pi-condense 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -9,6 +9,10 @@ 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).

package/README.md

@@ -6,254 +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,
-    "recoveryGraceTurns": 3,
-    "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 |
-| `recoveryGraceTurns` | non-negative integer (user-turn-groups), `0` disables | `3` | After a `context_tree_query` recovery, render that tool's output verbatim for this many user-turn-groups before re-stubbing it. Enforced at render time (Phase 1 + chain-compression eligibility), not at capture time. See [PRUNING.md § What Pruning Does](PRUNING.md#what-pruning-does) |
-| `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 recovery-grace [n]` | Show or set the post-recovery verbatim grace window, in user-turn-groups (`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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-condense",
-  "version": "2.3.0",
+  "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/commands.ts

@@ -12,6 +12,8 @@ import {
   SUMMARIZER_THINKING_LEVELS,
   MIN_BATCH_CHARS_PRESETS,
   RECOVERY_GRACE_PRESETS,
+  SUMMARIZER_IDLE_TIMEOUT_PRESETS,
+  SUMMARIZER_MAX_TIMEOUT_PRESETS,
   AUTO_BUDGET_PRESETS,
   ROLLING_WINDOW_PRESETS,
   KEEP_LAST_TURNS_PRESETS,
@@ -199,6 +201,19 @@ function recoveryGraceDescription(config: ContextPruneConfig): string {
   return `context_tree_query (recovery) output stays verbatim for ${config.recoveryGraceTurns} user-turn-group(s) after recovery, then reverts to the stub. Bounds the recover->re-stub->re-query loop. Currently ${config.recoveryGraceTurns}. Set to 0 to disable.`;
 }
 
+function idleTimeoutDescription(config: ContextPruneConfig): string {
+  if (config.summarizerIdleTimeoutMs === 0) {
+    return "Summarizer idle timeout DISABLED - a stalled stream is only bounded by the ceiling (or not at all if that is 0 too).";
+  }
+  return `Abort a summarizer call after ${Math.round(config.summarizerIdleTimeoutMs / 1000)}s of silence (no stream event). Resets on every event, so it never aborts a flowing generation; a timeout feeds the same outage-fallback retry as a provider error. Set 0 to disable.`;
+}
+function maxTimeoutDescription(config: ContextPruneConfig): string {
+  if (config.summarizerMaxTimeoutMs === 0) {
+    return "Summarizer total-duration ceiling DISABLED - only the idle timeout bounds a call.";
+  }
+  return `Hard ceiling on total duration of a single summarizer call: ${Math.round(config.summarizerMaxTimeoutMs / 1000)}s. Backstop for a stream that dribbles forever without going idle. Set 0 to disable.`;
+}
+
 function autoBudgetThresholdDescription(config: ContextPruneConfig): string {
   if (config.autoBudgetThreshold == null) {
     return `Token-budget auto-flush: force a prune when context usage reaches this share of the window, regardless of prune-on mode. Currently off. Pick a percentage to enable.`;
@@ -566,6 +581,24 @@ export function registerCommands(
                 : RECOVERY_GRACE_PRESETS[2].value,
               description: recoveryGraceDescription(config),
             },
+            {
+              id: "summarizerIdleTimeoutMs",
+              label: "Summarizer idle timeout",
+              values: SUMMARIZER_IDLE_TIMEOUT_PRESETS.map((p) => p.value),
+              currentValue: SUMMARIZER_IDLE_TIMEOUT_PRESETS.some((p) => p.value === String(config.summarizerIdleTimeoutMs))
+                ? String(config.summarizerIdleTimeoutMs)
+                : (SUMMARIZER_IDLE_TIMEOUT_PRESETS.find((p) => p.value === String(DEFAULT_CONFIG.summarizerIdleTimeoutMs))?.value ?? SUMMARIZER_IDLE_TIMEOUT_PRESETS[0].value), // fall back to the default preset if a custom value isn't in the cycle
+              description: idleTimeoutDescription(config),
+            },
+            {
+              id: "summarizerMaxTimeoutMs",
+              label: "Summarizer max timeout",
+              values: SUMMARIZER_MAX_TIMEOUT_PRESETS.map((p) => p.value),
+              currentValue: SUMMARIZER_MAX_TIMEOUT_PRESETS.some((p) => p.value === String(config.summarizerMaxTimeoutMs))
+                ? String(config.summarizerMaxTimeoutMs)
+                : (SUMMARIZER_MAX_TIMEOUT_PRESETS.find((p) => p.value === String(DEFAULT_CONFIG.summarizerMaxTimeoutMs))?.value ?? SUMMARIZER_MAX_TIMEOUT_PRESETS[0].value), // fall back to the default preset if a custom value isn't in the cycle
+              description: maxTimeoutDescription(config),
+            },
             {
               id: "autoBudgetThreshold",
               label: "Auto-flush at context %",
@@ -732,6 +765,16 @@ export function registerCommands(
               if (rgItem) {
                 rgItem.description = recoveryGraceDescription(newConfig);
               }
+            } else if (id === "summarizerIdleTimeoutMs") {
+              const parsed = Number.parseInt(newValue, 10);
+              newConfig.summarizerIdleTimeoutMs = Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_CONFIG.summarizerIdleTimeoutMs;
+              const it = items.find((item) => item.id === "summarizerIdleTimeoutMs");
+              if (it) it.description = idleTimeoutDescription(newConfig);
+            } else if (id === "summarizerMaxTimeoutMs") {
+              const parsed = Number.parseInt(newValue, 10);
+              newConfig.summarizerMaxTimeoutMs = Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_CONFIG.summarizerMaxTimeoutMs;
+              const it = items.find((item) => item.id === "summarizerMaxTimeoutMs");
+              if (it) it.description = maxTimeoutDescription(newConfig);
             } else if (id === "autoBudgetThreshold") {
               const parsed = Number.parseFloat(newValue);
               newConfig.autoBudgetThreshold =
@@ -839,8 +882,9 @@ export function registerCommands(
           const statsLine = s.callCount > 0
             ? `\n  --- summarizer ---\n  calls:       ${s.callCount}\n  input:       ${formatTokens(s.totalInputTokens)} tokens\n  output:      ${formatTokens(s.totalOutputTokens)} tokens\n  cost:        ${formatCost(s.totalCost)}`
             : "\n  (no summarizer calls yet)";
+          const fmtTimeout = (ms: number) => (ms === 0 ? "disabled" : `${Math.round(ms / 1000)}s`);
           ctx.ui.notify(
-            `pruner status:\n  enabled:  ${cfg.enabled}\n  model:    ${cfg.summarizerModel}\n  thinking: ${summarizerThinkingLabel(cfg.summarizerThinking)} (${cfg.summarizerThinking})\n  trigger:  ${mode}\n  batching: ${batchingModeLabel(cfg.batchingMode)} (${cfg.batchingMode})\n  dedup:    ${cfg.dedupByContentHash ? "on" : "off"}\n  status:   ${cfg.showPruneStatusLine ? "on" : "off"}${statsLine}`,
+            `pruner status:\n  enabled:  ${cfg.enabled}\n  model:    ${cfg.summarizerModel}\n  thinking: ${summarizerThinkingLabel(cfg.summarizerThinking)} (${cfg.summarizerThinking})\n  idle to:  ${fmtTimeout(cfg.summarizerIdleTimeoutMs)}\n  max to:   ${fmtTimeout(cfg.summarizerMaxTimeoutMs)}\n  trigger:  ${mode}\n  batching: ${batchingModeLabel(cfg.batchingMode)} (${cfg.batchingMode})\n  dedup:    ${cfg.dedupByContentHash ? "on" : "off"}\n  status:   ${cfg.showPruneStatusLine ? "on" : "off"}${statsLine}`,
           );
           break;
         }

package/src/config.test.ts

@@ -5,22 +5,23 @@ import { join } from "node:path";
 import { DEFAULT_CONFIG } from "./types.js";
 
 /**
- * config.ts computes SETTINGS_PATH from getAgentDir() at module-load time, so
- * PI_CODING_AGENT_DIR must be set before the module is imported. normalize()
- * itself isn't exported; loadConfig() is the only public entry point that
- * exercises it, so these tests drive normalization indirectly by writing
- * settings.json into an isolated agent dir and reading it back.
+ * config.ts resolves the settings path from getAgentDir() lazily on each
+ * read/write, so PI_CODING_AGENT_DIR set here is honored regardless of import
+ * order (bun shares the module registry across test files). normalize() itself
+ * isn't exported; loadConfig() is the only public entry point that exercises
+ * it, so these tests drive normalization indirectly by writing settings.json
+ * into an isolated agent dir and reading it back.
  */
 let tmpDir: string;
 let loadConfig: typeof import("./config.js").loadConfig;
-let SETTINGS_PATH: string;
+let settingsPath: typeof import("./config.js").settingsPath;
 
 beforeAll(async () => {
   tmpDir = await mkdtemp(join(tmpdir(), "pi-condense-config-test-"));
   process.env.PI_CODING_AGENT_DIR = tmpDir;
   const mod = await import("./config.js");
   loadConfig = mod.loadConfig;
-  SETTINGS_PATH = mod.SETTINGS_PATH;
+  settingsPath = mod.settingsPath;
 });
 
 afterAll(async () => {
@@ -29,7 +30,7 @@ afterAll(async () => {
 });
 
 async function writeContextPrune(overrides: Record<string, unknown>): Promise<void> {
-  await writeFile(SETTINGS_PATH, JSON.stringify({ contextPrune: overrides }));
+  await writeFile(settingsPath(), JSON.stringify({ contextPrune: overrides }));
 }
 
 describe("loadConfig recoveryGraceTurns normalization", () => {
@@ -63,3 +64,38 @@ describe("loadConfig recoveryGraceTurns normalization", () => {
     expect(config.recoveryGraceTurns).toBe(DEFAULT_CONFIG.recoveryGraceTurns);
   });
 });
+
+describe("loadConfig summarizer timeout normalization", () => {
+  it("defaults both timeouts when absent", async () => {
+    await writeContextPrune({});
+    const config = await loadConfig();
+    expect(config.summarizerIdleTimeoutMs).toBe(DEFAULT_CONFIG.summarizerIdleTimeoutMs);
+    expect(config.summarizerMaxTimeoutMs).toBe(DEFAULT_CONFIG.summarizerMaxTimeoutMs);
+  });
+
+  it("preserves explicit 0 (disabled) for both", async () => {
+    await writeContextPrune({ summarizerIdleTimeoutMs: 0, summarizerMaxTimeoutMs: 0 });
+    const config = await loadConfig();
+    expect(config.summarizerIdleTimeoutMs).toBe(0);
+    expect(config.summarizerMaxTimeoutMs).toBe(0);
+  });
+
+  it("falls back to default for a negative idle timeout", async () => {
+    await writeContextPrune({ summarizerIdleTimeoutMs: -5 });
+    const config = await loadConfig();
+    expect(config.summarizerIdleTimeoutMs).toBe(DEFAULT_CONFIG.summarizerIdleTimeoutMs);
+  });
+
+  it("falls back to default for NaN max timeout", async () => {
+    // JSON.stringify serializes NaN to null; normalize's typeof-number guard rejects it.
+    await writeContextPrune({ summarizerMaxTimeoutMs: Number.NaN });
+    const config = await loadConfig();
+    expect(config.summarizerMaxTimeoutMs).toBe(DEFAULT_CONFIG.summarizerMaxTimeoutMs);
+  });
+
+  it("floors a fractional idle timeout", async () => {
+    await writeContextPrune({ summarizerIdleTimeoutMs: 1234.9 });
+    const config = await loadConfig();
+    expect(config.summarizerIdleTimeoutMs).toBe(1234);
+  });
+});

package/src/config.ts

@@ -15,8 +15,14 @@ import { DEFAULT_CONFIG, PRUNE_ON_MODES, SUMMARIZER_THINKING_LEVELS } from "./ty
  * Resolved against `getAgentDir()` so it honors `PI_CODING_AGENT_DIR`
  * (defaults to `~/.pi/agent`). Each pi preset directory therefore gets its
  * own context-prune config — including its own summarizer model.
+ *
+ * Computed lazily on each read/write rather than frozen at module load, so the
+ * resolved path always reflects the current `PI_CODING_AGENT_DIR` regardless of
+ * when the module was first imported.
  */
-export const SETTINGS_PATH = join(getAgentDir(), "settings.json");
+export function settingsPath(): string {
+  return join(getAgentDir(), "settings.json");
+}
 
 /** Top-level key under which context-prune state lives in `settings.json`. */
 export const SETTINGS_KEY = "contextPrune" as const;
@@ -52,6 +58,18 @@ function normalize(existing: Partial<ContextPruneConfig>): ContextPruneConfig {
       merged.minBatchChars >= 0
         ? Math.floor(merged.minBatchChars)
         : DEFAULT_CONFIG.minBatchChars,
+    summarizerIdleTimeoutMs:
+      typeof merged.summarizerIdleTimeoutMs === "number" &&
+      Number.isFinite(merged.summarizerIdleTimeoutMs) &&
+      merged.summarizerIdleTimeoutMs >= 0
+        ? Math.floor(merged.summarizerIdleTimeoutMs)
+        : DEFAULT_CONFIG.summarizerIdleTimeoutMs,
+    summarizerMaxTimeoutMs:
+      typeof merged.summarizerMaxTimeoutMs === "number" &&
+      Number.isFinite(merged.summarizerMaxTimeoutMs) &&
+      merged.summarizerMaxTimeoutMs >= 0
+        ? Math.floor(merged.summarizerMaxTimeoutMs)
+        : DEFAULT_CONFIG.summarizerMaxTimeoutMs,
     recoveryGraceTurns:
       typeof merged.recoveryGraceTurns === "number" &&
       Number.isFinite(merged.recoveryGraceTurns) &&
@@ -106,7 +124,7 @@ async function readJsonObject(path: string): Promise<Record<string, unknown> | u
 
 /** Reads `<agent-dir>/settings.json` and returns the `contextPrune` block, or defaults. */
 export async function loadConfig(): Promise<ContextPruneConfig> {
-  const main = await readJsonObject(SETTINGS_PATH);
+  const main = await readJsonObject(settingsPath());
   const namespaced = main?.[SETTINGS_KEY];
   if (namespaced && typeof namespaced === "object" && !Array.isArray(namespaced)) {
     return normalize(namespaced as Partial<ContextPruneConfig>);
@@ -123,10 +141,11 @@ export async function loadConfig(): Promise<ContextPruneConfig> {
  * last-write-wins race only loses a single change, never corrupts the file.
  */
 export async function saveConfig(config: ContextPruneConfig): Promise<void> {
-  const current = (await readJsonObject(SETTINGS_PATH)) ?? {};
+  const path = settingsPath();
+  const current = (await readJsonObject(path)) ?? {};
   const next = { ...current, [SETTINGS_KEY]: config };
-  await mkdir(dirname(SETTINGS_PATH), { recursive: true });
-  const tmpPath = `${SETTINGS_PATH}.${randomBytes(8).toString("hex")}.tmp`;
+  await mkdir(dirname(path), { recursive: true });
+  const tmpPath = `${path}.${randomBytes(8).toString("hex")}.tmp`;
   await writeFile(tmpPath, `${JSON.stringify(next, null, 2)}\n`);
-  await rename(tmpPath, SETTINGS_PATH);
+  await rename(tmpPath, path);
 }

package/src/summarizer-wiring.test.ts

@@ -2,11 +2,11 @@ import { describe, it, expect, mock } from "bun:test";
 
 // Stub pi-ai's `stream` so runSummarization can be exercised without a network
 // call. `streamImpl` is swapped per test to simulate primary/fallback outcomes.
-let streamImpl: (model: any) => any = () => {
+let streamImpl: (model: any, input?: any, opts?: any) => any = () => {
   throw new Error("streamImpl not set");
 };
 mock.module("@earendil-works/pi-ai", () => ({
-  stream: (model: any) => streamImpl(model),
+  stream: (...args: any[]) => streamImpl(...args),
 }));
 
 const { summarizeBatch } = await import("./summarizer.js");
@@ -45,6 +45,61 @@ function errStream(message: string) {
   };
 }
 
+// Hangs until `opts.signal` (the combined caller+timeout signal runOnce
+// passes to stream()) aborts. With no signal it never settles.
+function hangingStream(opts: any) {
+  const signal: AbortSignal | undefined = opts?.signal;
+  const untilAbort = () =>
+    new Promise<never>((_, reject) => {
+      if (!signal) return; // no signal => never settles
+      if (signal.aborted) return reject(new Error("aborted"));
+      signal.addEventListener("abort", () => reject(new Error("aborted")), { once: true });
+    });
+  return {
+    async *[Symbol.asyncIterator]() {
+      await untilAbort();
+    },
+    async result() {
+      return untilAbort();
+    },
+  };
+}
+
+// Emits `events` thinking_delta events spaced `gapMs` apart, then completes
+// successfully — UNLESS `opts.signal` aborts mid-drip, in which case the
+// current sleep rejects, exactly like a real provider stream cancelling on
+// abort. This is what gives the idle-reset test teeth: if runOnce's in-loop
+// bumpIdle() is ever removed, the idle timer fires at the configured window
+// and the combined signal aborts, so this stream rejects instead of
+// completing — the test then fails instead of passing vacuously.
+function drippingStream(opts: any, text: string, events: number, gapMs: number) {
+  const signal: AbortSignal | undefined = opts?.signal;
+  const sleepOrAbort = (ms: number) =>
+    new Promise<void>((resolve, reject) => {
+      if (signal?.aborted) return reject(new Error("aborted"));
+      const timer = setTimeout(resolve, ms);
+      signal?.addEventListener(
+        "abort",
+        () => {
+          clearTimeout(timer);
+          reject(new Error("aborted"));
+        },
+        { once: true }
+      );
+    });
+  return {
+    async *[Symbol.asyncIterator]() {
+      for (let i = 0; i < events; i++) {
+        await sleepOrAbort(gapMs);
+        yield { type: "thinking_delta" };
+      }
+    },
+    async result() {
+      return { stopReason: "stop", content: [{ type: "text", text }], usage: USAGE };
+    },
+  };
+}
+
 interface Note {
   msg: string;
   level: string;
@@ -163,3 +218,90 @@ describe("runSummarization wiring — abort", () => {
     ).rejects.toThrow();
   });
 });
+
+describe("runSummarization wiring — timeouts", () => {
+  it("idle timeout (default model): transient warning, returns null", async () => {
+    streamImpl = (_m, _i, opts) => hangingStream(opts);
+    const notes: Note[] = [];
+    const ctx = makeCtx(notes);
+    const cfg = { ...DEFAULT_CONFIG, summarizerModel: "default", summarizerIdleTimeoutMs: 20, summarizerMaxTimeoutMs: 0 };
+    const r = await summarizeBatch(makeBatch(), cfg, ctx, {});
+    expect(r).toBeNull();
+    const warnings = notes.filter((n) => n.level === "warning");
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0].msg).toMatch(/stalled/);
+    expect(notes.filter((n) => n.level === "error")).toHaveLength(0);
+  });
+
+  it("ceiling timeout (idle disabled): transient warning mentioning ceiling", async () => {
+    streamImpl = (_m, _i, opts) => hangingStream(opts);
+    const notes: Note[] = [];
+    const ctx = makeCtx(notes);
+    const cfg = { ...DEFAULT_CONFIG, summarizerModel: "default", summarizerIdleTimeoutMs: 0, summarizerMaxTimeoutMs: 20 };
+    const r = await summarizeBatch(makeBatch(), cfg, ctx, {});
+    expect(r).toBeNull();
+    const warnings = notes.filter((n) => n.level === "warning");
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0].msg).toMatch(/ceiling/);
+  });
+
+  it("option B: primary idle-times-out, session model rescues", async () => {
+    streamImpl = (model, _i, opts) => (model.id === PRIMARY.id ? hangingStream(opts) : okStream("- rescued"));
+    const notes: Note[] = [];
+    const ctx = makeCtx(notes);
+    const controller = new FallbackController();
+    const cfg = { ...distinctConfig, summarizerIdleTimeoutMs: 20 };
+    const r = await summarizeBatch(makeBatch(), cfg, ctx, { controller });
+    expect(r?.summaryText).toBe("- rescued");
+    expect(controller.inFallback).toBe(true);
+    expect(notes.filter((n) => n.level === "warning")).toHaveLength(1); // generic "enter" fallback warning
+    expect(notes.filter((n) => n.level === "error")).toHaveLength(0);
+  });
+
+  it("both time out: null, both-down notice at warning severity", async () => {
+    streamImpl = (_m, _i, opts) => hangingStream(opts);
+    const notes: Note[] = [];
+    const ctx = makeCtx(notes);
+    const controller = new FallbackController();
+    const cfg = { ...distinctConfig, summarizerIdleTimeoutMs: 20 };
+    const r = await summarizeBatch(makeBatch(), cfg, ctx, { controller });
+    expect(r).toBeNull();
+    expect(notes.filter((n) => n.level === "warning")).toHaveLength(1);
+    expect(notes.filter((n) => n.level === "error")).toHaveLength(0);
+  });
+
+  it("pre-aborted signal is not a timeout (throws, no warning)", async () => {
+    streamImpl = (_m, _i, opts) => hangingStream(opts);
+    const notes: Note[] = [];
+    const ctx = makeCtx(notes);
+    const ac = new AbortController();
+    ac.abort();
+    const cfg = { ...distinctConfig, summarizerIdleTimeoutMs: 20 };
+    await expect(summarizeBatch(makeBatch(), cfg, ctx, { signal: ac.signal })).rejects.toThrow();
+    expect(notes.filter((n) => n.level === "warning")).toHaveLength(0);
+  });
+
+  it("both timeouts disabled: okStream succeeds unchanged", async () => {
+    streamImpl = () => okStream("- ok");
+    const notes: Note[] = [];
+    const ctx = makeCtx(notes);
+    const cfg = { ...DEFAULT_CONFIG, summarizerModel: "default", summarizerIdleTimeoutMs: 0, summarizerMaxTimeoutMs: 0 };
+    const r = await summarizeBatch(makeBatch(), cfg, ctx, {});
+    expect(r?.summaryText).toBe("- ok");
+    expect(notes).toHaveLength(0);
+  });
+});
+
+describe("runSummarization wiring — idle reset keeps a flowing stream alive", () => {
+  it("does not time out while events keep arriving within the idle window", async () => {
+    // 6 events, 10ms apart = 60ms total > 25ms idle window; only survives if
+    // the idle timer resets on every event (bumpIdle() inside the loop).
+    streamImpl = (_m, _i, opts) => drippingStream(opts, "- flowing summary", 6, 10);
+    const notes: Note[] = [];
+    const ctx = makeCtx(notes);
+    const cfg = { ...DEFAULT_CONFIG, summarizerModel: "default", summarizerIdleTimeoutMs: 25, summarizerMaxTimeoutMs: 0 };
+    const r = await summarizeBatch(makeBatch(), cfg, ctx, {});
+    expect(r?.summaryText).toBe("- flowing summary");
+    expect(notes.filter((n) => n.level === "warning")).toHaveLength(0);
+  });
+});

package/src/summarizer.ts

@@ -90,7 +90,7 @@ type RunOutcome =
   | { kind: "ok"; result: SummarizeResult }
   | { kind: "auth"; message: string }
   | { kind: "unusable" }
-  | { kind: "transient"; message: string };
+  | { kind: "transient"; message: string; timedOut?: boolean };
 
 /** Human label for a model in notify text: prefer name, fall back to provider/id. */
 function modelLabel(model: any): string {
@@ -98,6 +98,14 @@ function modelLabel(model: any): string {
   return model.name || `${model.provider}/${model.id}`;
 }
 
+/** Combines any present abort signals into one; undefined if none are given. */
+function combineSignals(...signals: (AbortSignal | undefined)[]): AbortSignal | undefined {
+  const present = signals.filter((s): s is AbortSignal => !!s);
+  if (present.length === 0) return undefined;
+  if (present.length === 1) return present[0];
+  return AbortSignal.any(present); // Node 20+; host runtime is node 24.5.0
+}
+
 /**
  * One summarization attempt against a specific model. Returns a classified
  * outcome instead of throwing (except aborts, which propagate so flushPending
@@ -113,6 +121,29 @@ async function runOnce(
   ctx: ExtensionContext,
   options: SummarizeBatchOptions
 ): Promise<RunOutcome> {
+  const idleMs = config.summarizerIdleTimeoutMs;
+  const maxMs = config.summarizerMaxTimeoutMs;
+  const timeoutController = new AbortController();
+  let timedOut = false;
+  let timeoutKind: "idle" | "ceiling" | null = null;
+  let idleTimerId: ReturnType<typeof setTimeout> | null = null;
+  let ceilingTimerId: ReturnType<typeof setTimeout> | null = null;
+
+  const bumpIdle = () => {
+    if (idleTimerId !== null) clearTimeout(idleTimerId);
+    if (idleMs > 0) {
+      idleTimerId = setTimeout(() => {
+        timedOut = true;
+        timeoutKind = "idle";
+        timeoutController.abort();
+      }, idleMs);
+    }
+  };
+  const timeoutMessage = () =>
+    timeoutKind === "ceiling"
+      ? `summarizer ${modelLabel(model)} exceeded ${Math.round(maxMs / 1000)}s ceiling`
+      : `summarizer ${modelLabel(model)} stalled (no output for ${Math.round(idleMs / 1000)}s)`;
+
   try {
     const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
     if (!auth.ok) {
@@ -120,8 +151,8 @@ async function runOnce(
       return { kind: "auth", message: authMessage };
     }
 
-    // Pass the abort signal so the underlying fetch is cancelled immediately
-    // when the user presses Esc while the tool is running.
+    // Pass the combined signal so the underlying fetch is cancelled immediately
+    // either when the user presses Esc, or when an idle/ceiling timeout fires.
     const responseStream = stream(
       model,
       {
@@ -133,9 +164,25 @@ async function runOnce(
           },
         ],
       },
-      { apiKey: auth.apiKey, headers: auth.headers, signal: options.signal, ...summarizerThinkingOptions(config) }
+      {
+        apiKey: auth.apiKey,
+        headers: auth.headers,
+        signal: combineSignals(options.signal, timeoutController.signal),
+        ...summarizerThinkingOptions(config),
+      }
     );
 
+    // Ceiling arms once at call start; idle arms/resets on every stream event
+    // (including before the first one, so it also bounds time-to-first-token).
+    if (maxMs > 0) {
+      ceilingTimerId = setTimeout(() => {
+        timedOut = true;
+        timeoutKind ??= "ceiling";
+        timeoutController.abort();
+      }, maxMs);
+    }
+    bumpIdle();
+
     let lastReportedChars = -1;
     options.onTextProgress?.(0);
     const reportTextProgress = (message: AssistantMessage) => {
@@ -147,6 +194,10 @@ async function runOnce(
     };
 
     for await (const event of responseStream) {
+      // Reset idle on ANY event (text_* and thinking_*), not just text — a
+      // reasoning-heavy model stays alive via thinking_delta and is never
+      // false-aborted for being quiet on text while it reasons.
+      bumpIdle();
       // Belt-and-suspenders: break early when signal fires mid-stream.
       if (options.signal?.aborted) break;
       if (event.type === "text_start" || event.type === "text_delta" || event.type === "text_end") {
@@ -167,6 +218,7 @@ async function runOnce(
       throw new Error("summarize: stream stopped with reason aborted");
     }
     if (response.stopReason === "error") {
+      if (timedOut) return { kind: "transient", message: timeoutMessage(), timedOut: true };
       return { kind: "transient", message: response.errorMessage ?? "Summarizer stopped with reason: error" };
     }
 
@@ -182,7 +234,11 @@ async function runOnce(
     // Propagate abort errors upward so flushPending can check signal.aborted
     // and return { ok: false, reason: "aborted" } without showing a UI error.
     if (options.signal?.aborted) throw err;
+    if (timedOut) return { kind: "transient", message: timeoutMessage(), timedOut: true };
     return { kind: "transient", message: err.message };
+  } finally {
+    if (idleTimerId !== null) clearTimeout(idleTimerId);
+    if (ceilingTimerId !== null) clearTimeout(ceilingTimerId);
   }
 }
 
@@ -211,8 +267,13 @@ async function runSummarization(
   const controller = options.controller;
   const sessionModel = ctx.model;
 
-  const notifyError = (msg: string) =>
-    ctx.ui.notify(`pruner: summarization failed: ${msg}`, "error");
+  const notifyFailure = (o: { message: string; timedOut?: boolean }) =>
+    ctx.ui.notify(
+      o.timedOut
+        ? `pi-condense: ${o.message}; summarizer call abandoned`
+        : `pruner: summarization failed: ${o.message}`,
+      o.timedOut ? "warning" : "error",
+    );
 
   // No controller or no distinct fallback: single attempt, legacy behavior.
   if (!controller || !FallbackController.hasDistinctFallback(primary, sessionModel)) {
@@ -222,7 +283,7 @@ async function runSummarization(
         return r.result;
       case "auth":
       case "transient":
-        notifyError(r.message);
+        notifyFailure(r);
         return null;
       case "unusable":
         return null;
@@ -250,14 +311,14 @@ async function runSummarization(
       else emit(controller.onFallbackSuccess());
       return r.result;
     case "auth":
-      notifyError(r.message); // auth never trips the controller
+      notifyFailure(r); // auth never trips the controller
       return null;
     case "unusable":
       return null; // probe unusable => stay (no state change)
     case "transient": {
       if (decision.target === "fallback") {
         controller.onFallbackOnlyFail();
-        notifyError(r.message);
+        notifyFailure(r);
         return null;
       }
       // target was primary (initial detection or probe): retry once on the session model.
@@ -267,7 +328,7 @@ async function runSummarization(
         return r2.result; // suppress the legacy error notify — fallback rescued the call
       }
       controller.onBothDown();
-      notifyError(r2.kind === "transient" || r2.kind === "auth" ? r2.message : r.message);
+      notifyFailure(r2.kind === "transient" || r2.kind === "auth" ? r2 : r);
       return null;
     }
   }

package/src/types.ts

@@ -202,6 +202,30 @@ export const RECOVERY_GRACE_PRESETS: { value: string; label: string }[] = [
   { value: "8", label: "8" },
 ];
 
+/**
+ * Cycling presets for `summarizerIdleTimeoutMs` (stored as strings; the
+ * settings UI cycles string values). "0" is the disabling sentinel.
+ */
+export const SUMMARIZER_IDLE_TIMEOUT_PRESETS: { value: string; label: string }[] = [
+  { value: "0", label: "0 (disabled)" },
+  { value: "10000", label: "10s" },
+  { value: "20000", label: "20s (default)" },
+  { value: "45000", label: "45s" },
+  { value: "90000", label: "90s" },
+];
+
+/**
+ * Cycling presets for `summarizerMaxTimeoutMs` (stored as strings). "0" is
+ * the disabling sentinel - no total-duration ceiling.
+ */
+export const SUMMARIZER_MAX_TIMEOUT_PRESETS: { value: string; label: string }[] = [
+  { value: "0", label: "0 (disabled)" },
+  { value: "120000", label: "120s" },
+  { value: "180000", label: "180s (default)" },
+  { value: "300000", label: "300s" },
+  { value: "600000", label: "600s" },
+];
+
 /**
  * Cycling presets for the `autoBudgetThreshold` setting (stored as strings;
  * the settings UI cycles string values). "0" is the disabled sentinel → null.
@@ -281,6 +305,21 @@ export interface ContextPruneConfig {
    * (Phase 1) and chain-compressor.ts (eligibility), not at capture.
    */
   recoveryGraceTurns: number;
+  /**
+   * Idle (inactivity) timeout for a single summarizer stream call, in ms.
+   * Reset on every received stream event; armed before the first event so it
+   * also bounds time-to-first-token. If no event arrives within this window
+   * the call is aborted and classified transient (feeds the outage-fallback
+   * retry). 0 disables the idle timer. Default 20000.
+   */
+  summarizerIdleTimeoutMs: number;
+  /**
+   * Total-duration ceiling for a single summarizer stream call, in ms. Armed
+   * once at call start, never reset - a hard upper bound catching a stream
+   * that keeps dribbling events but never completes. Same transient/warning
+   * handling as the idle timeout. 0 disables the ceiling. Default 180000.
+   */
+  summarizerMaxTimeoutMs: number;
   /**
    * Tool names whose outputs must NEVER be pruned or summarized. Tool calls
    * with matching `toolName` are filtered out of the pruning capture path so
@@ -480,6 +519,8 @@ export const DEFAULT_CONFIG: ContextPruneConfig = {
   quietOversizedSkips: false,
   minBatchChars: 1000,
   recoveryGraceTurns: 3,
+  summarizerIdleTimeoutMs: 20000,
+  summarizerMaxTimeoutMs: 180000,
   protectedTools: [],
   protectedPaths: ["**/skills/**/*.md"],
   chainCompression: {