pi-smart-compact 10.0.0 → 10.1.0

package/docs/configuration.md

@@ -7,9 +7,9 @@ Pi Continuity is the product name only. Settings keep their technical names:
 everything lives under the `smartCompact` key, and the settings screen is opened
 with `/smart-compact settings`.
 
-Defaults on this page were checked against Pi Continuity `10.0.0`. For an older
-installation, use [the changelog](../CHANGELOG.md) and the
-[upgrade notes](./guide.md#upgrade-from-9x) before adopting these settings.
+Defaults describe the shipped `10.1.0` working tree, including the pressure-first
+changes. See [the changelog](../CHANGELOG.md) for the release scope and
+evidence limits before adopting these settings.
 
 ## Contents
 
@@ -75,8 +75,8 @@ means all defaults are used.
 | Hand edits to `settings.json` | Next operation (the file's modification time is checked). Active tools and footer refresh on `/reload` or session restore; no file watcher runs. |
 
 Changing agent-tool settings from the TUI re-applies the tool list at once.
-Groups the agent loaded through `smart_tools` are forgotten at session start,
-on a branch change and after a compaction; see
+In optional lazy mode, loaded groups are forgotten at session start and branch
+changes, but retained across compaction to preserve the tool prefix; see
 [agent tools](./guide.md#agent-tools).
 
 ## How settings combine
@@ -114,14 +114,14 @@ nothing new is stored.
 
 | Preset | `autoTrigger` | `autoTriggerStrategy` | `contextHygieneEnabled` | `agentToolAccess` |
 | --- | --- | --- | --- | --- |
-| `With Pi (default)` | `true` | `native-hook` | `false` | `inherit` |
+| `Pressure-first (default)` | `true` | `settled` | `true` | `inherit` |
 | `Manual only` | `false` | unchanged | `false` | `disabled` |
 | `Manual + agent` | `false` | unchanged | `false` | `enabled` |
 | `Cleanup only` | `false` | unchanged | `true` | `disabled` |
 | `Fully automatic` | `true` | `settled` | `true` | `disabled` |
 
-`With Pi (default)` is the unchanged built-in default, not a preset you pick.
-Any other combination is shown as `Custom` with a one-line description. Existing
+`Pressure-first (default)` is the built-in default, not a preset you pick.
+Cleanup timing defaults to pressure-only. Other combinations are shown as `Custom`. Existing
 `native-hook` configurations are not migrated to `settled`.
 
 ### Summary format
@@ -151,8 +151,8 @@ compaction. `autoTriggerStrategy` chooses how it starts.
 
 | `autoTriggerStrategy` | TUI label (`Start when`) | Who decides when | Needs Pi auto-compaction |
 | --- | --- | --- | --- |
-| `native-hook` (default) | `Before Pi's compaction` | Pi | Yes |
-| `settled` | `When idle` | Smart Compact, at an idle boundary | No |
+| `native-hook` | `Before Pi's compaction` | Pi | Yes |
+| `settled` (default) | `When idle` | Smart Compact, at an idle boundary | No |
 | `background` | `Prepare in background` | Smart Compact; also prepares early | No |
 
 Rules that hold for all strategies:
@@ -176,9 +176,11 @@ not as on. If it is off, nothing compacts automatically.
 
 At the next idle, queue-empty boundary where context is at least
 `minContextPercent` of the active model's window (and at least 5,000 tokens),
-Smart Compact asks Pi to compact. A running tool loop is not interrupted. After
-any confirmed compaction there is a 10-minute cooldown. Pi's own threshold and
-overflow triggers stay active.
+Smart Compact asks Pi to compact. A running tool loop is not interrupted. Every
+finished attempt starts a 10-minute cooldown, including errors, synchronous
+host failures and missing-callback timeouts, so repeated idle events do not
+spend another compaction budget. Confirmed compactions also start the cooldown.
+Manual requests and Pi's own threshold and overflow triggers stay available.
 
 ### background: early preparation
 
@@ -192,15 +194,15 @@ hides latency, not cost: an unused summary still spends its model budget.
 | `prepareContextPercent: null` (Auto) | Starts 12.5% of the apply-token threshold earlier, bounded to 8,192–32,000 tokens |
 | Concurrency | One speculative task per extension |
 | Retry cooldown | 10 minutes |
-| Ready result lifetime | 5 minutes |
-| Context hygiene | Pressure-gated trims run under this strategy even if `contextHygieneEnabled` is off (needs active `smart_context`); break-even and cold-cache trims need `contextHygieneEnabled` |
+| Ready result lifetime | `pendingTtlMs` (default 5 minutes) |
+| Context hygiene | Pressure-gated trims run even if `contextHygieneEnabled` is off; economic/cold-cache timing additionally requires `contextPressureOnly: false` |
 
 Example: with `prepareContextPercent: 60` and `minContextPercent: 70` in a 200k
 window, preparation starts at 120k and applies at 140k. With Auto and an 80%
 apply gate in a 200k window, preparation starts at 140k (160k minus a 20k lead).
 
 At apply, the prepared summary is revalidated against session, branch,
-projected content, model, configuration, target and response headroom. A
+projected content, model, effective system/tool definitions, configuration, target and response headroom. A
 changed, expired or unfinished preparation is discarded, and Smart Compact
 falls back to a normal run or Pi's own compactor. New messages after the
 snapshot stay verbatim. When cleanup changes the context first, preparation
@@ -280,6 +282,11 @@ Per-run options accept narrower ranges than the settings:
 | Prompt tokens | `--max-input-tokens` / `max_input_tokens`: 10,000–1,000,000 | `maxLlmInputTokens`: 0–1,000,000 |
 | Deadline (ms) | `--max-latency` / `max_latency_ms`: 5,000–600,000 | `maxLatencyMs`: 0 or 5,000–7,200,000 |
 
+Optional exploration leaves two calls for batch synthesis and final assembly;
+with two or fewer calls remaining it is skipped. Batch retries and queued work
+also preserve the final assembly call. This does not raise call, token or time
+limits, and cannot guarantee provider success.
+
 Running out of calls or tokens falls back to a deterministic summary. A deadline
 or cancellation stops the run: no staged summary, no apply, and a manual
 timeout does not start Pi's compactor.
@@ -353,7 +360,8 @@ choice because a rejected provider request falls back to the smart summary.
 
 ## Context hygiene and archives
 
-All three switches are off by default. Automatic trimming and offload run only
+Pressure-gated automatic trimming is on by default; offload and image snapshots
+remain opt-in. Automatic trimming and offload run only
 while the model can reach `smart_context`: active, or loadable through
 `smart_tools` in On demand mode. With agent tools `off`, or `smart_context`
 hidden with `/tools`, new automatic trims and offloads stop; existing archives
@@ -361,7 +369,8 @@ stay on disk and manual `/smart-compact trim` still works.
 
 | Key | TUI label | Default | Effect |
 | --- | --- | --- | --- |
-| `contextHygieneEnabled` | `Automatic cleanup` | `false` | Batched, recoverable trimming. Needs 16,384 characters of net savings and eight assistant turns since the last trim, rewind or compaction; commits under pressure, at break-even, or once the prompt cache is cold (below). Works with `autoTrigger: false`. |
+| `contextHygieneEnabled` | `Automatic cleanup` | `true` | Batched, recoverable trimming. Needs 16,384 characters of net savings and eight assistant turns since the last trim, rewind or compaction. Works with `autoTrigger: false`. |
+| `contextPressureOnly` | `Cleanup timing` | `true` | Automatic cleanup and agent trim/rewind/anchor requests require the early pressure gate. `false` opts into the legacy economic/cold-cache timing below. Human commands bypass pressure, never safety checks. |
 | `artifactOffloadEnabled` | `Offload huge outputs` | `false` | Saves eligible read-only text results of 16,384+ characters before the model sees them. Independent of pressure gates. |
 | `visualArchiveEnabled` | `Image snapshots` | `false` | Experimental image snapshots beside the verified text. Adds image tokens; needs a vision model with a validated cost rule and the optional `@resvg/resvg-js` component (not installed with the extension; `Readiness & details` shows the install command). Without it, output falls back to text. |
 | `pinPaths` | `Always-kept files` | `[]` | Paths every summary must keep |
@@ -386,6 +395,13 @@ These limits are not configurable. Behavior and examples are in the guide's
 
 ### Automatic trim timing
 
+Default: only `pressure` can trigger automatic cleanup. The shared early gate is
+`prepareContextPercent`, or the adaptive lead when null. A 400k policy window
+with the default 80% apply gate cleans from 288k and compacts from 320k.
+Unknown usage does not authorize cleanup. First-delivery offload and metadata
+checkpoints do not rewrite cached history and remain independent of pressure.
+
+The following economics apply **only with `contextPressureOnly: false`**.
 Let `X` be the estimated tokens a batch removes (net of its markers) and `T`
 the estimated tokens of every message from the first trimmed output to the
 end, the part of the prompt cache a trim rewrites. With the active model's
@@ -405,8 +421,8 @@ At a completed turn boundary a ready batch commits with cause:
   requests keep them, and the edits commit at the next completed, uncontested
   turn.
 
-An unknown price only allows `pressure` and `cold`. Manual and agent trims
-commit at the next boundary as before (causes `manual`, `agent`).
+An unknown price only allows `pressure` and `cold`. Manual and permitted agent trims
+commit at the next boundary (causes `manual`, `agent`).
 
 A Pi cache-warming refresh counts as a response for this expiry. While a
 batch is held, warming stops once
@@ -415,8 +431,16 @@ miss cost net of the removed output's cache write; `w'` is the cache-write
 price per million tokens, or the input price when none is listed).
 
 A newer compaction, context edit, session change, queued manual/agent request,
-or turning `contextHygieneEnabled` off drops the held batch. Prices are
-catalog ratios, not measured cache behavior.
+or turning `contextHygieneEnabled` off drops the held batch. Re-enabling
+pressure-only cancels unconsumed economic plans. Prices and cache lifetimes
+here are heuristics, not measured provider cache behavior.
+
+Trim/rewind refuse edits that would invalidate retained signed Anthropic
+thinking. Keeping thinking bytes unchanged alone is insufficient. Use a
+supported provider-native compaction route instead; native support remains opt-in.
+A new anchor can request one safe cleanup of its new region before first replay;
+previous anchor prefixes and recent turns remain protected. Anchor creation alone
+does not invalidate an append-only background snapshot.
 
 ## Agent tools and session navigation
 
@@ -424,7 +448,7 @@ Settings → **Agent tools & navigation**.
 
 | Key | TUI label | Default | Effect |
 | --- | --- | --- | --- |
-| `toolLoading` | `Agent tools` | `lazy` | `lazy` (On demand): the agent sees the `smart_tools` loader and loads the `navigation`, `history`, `memory` or `compaction` group when needed; loaded groups reset at session start, branch change and compaction. `eager` (Always available): every permitted tool is active from the start. `off`: no context tools; Home, `/smart-compact` and the navigation panel keep working. |
+| `toolLoading` | `Agent tools` | `eager` | `eager` (Always available): permitted tools are present from the start, keeping their prefix stable. `lazy` (On demand): load groups through `smart_tools`; late loading can rebuild the cache. Loaded groups reset at session start/branch change, not compaction. `off`: no agent context tools; human commands and navigation keep working. |
 | `contextNavigationEnabled` | `Session navigation` | `true` | Anchors, search and returning to an anchor. Off hides the panel and `smart_navigation`; recorded anchors and the keys below are kept. |
 | `contextRecallEnabled` | `Search other sessions` | `true` | Read-only search of anchors saved by earlier sessions, this project by default. |
 | `contextPivotEnabled` | `Return to an anchor` | `true` | Returning to an anchor on a new branch with a required carryover. |
@@ -487,11 +511,11 @@ Hindsight setup, data flow and troubleshooting:
 | `summaryThinkingLevel` | level \| `null` | `minimal` | `Summary thinking` |
 | `segmentationThinkingLevel` | level \| `null` | `minimal` | `Topic split thinking` |
 | `agentToolAccess` | `inherit` \| `enabled` \| `disabled` | `inherit` | `Agent can compact` |
-| `toolLoading` | `lazy` \| `eager` \| `off` | `lazy` | `Agent tools` |
+| `toolLoading` | `lazy` \| `eager` \| `off` | `eager` | `Agent tools` |
 | `autoTrigger` | boolean | `true` | `Automatic compaction` |
-| `autoTriggerStrategy` | `native-hook` \| `settled` \| `background` | `native-hook` | `Start when` |
-| `minContextPercent` | 0–100 | `60` | `Start at context %` |
-| `prepareContextPercent` | `null` or 0–100, below `minContextPercent` | `null` | `Prepare at context %` |
+| `autoTriggerStrategy` | `native-hook` \| `settled` \| `background` | `settled` | `Start when` |
+| `minContextPercent` | 0–100 | `80` | `Start at context %` |
+| `prepareContextPercent` | `null` or 0–100, below `minContextPercent` | `null` | `Cleanup / prepare at context %` |
 | `maxContextTokens` | `0` (off) or integer 16,384–2,000,000 | `0` | `Context cap for start % (tokens)` |
 | `autoTriggerTimeoutMs` | integer 1,000–300,000 | `120000` | `Automatic run time limit (ms)`; capped at 60 s |
 | `compactionEngines` | ordered list of `eesv`, `native` | `["eesv"]` | `Engine` |
@@ -502,7 +526,8 @@ Hindsight setup, data flow and troubleshooting:
 | `maxLatencyMs` | `0` or integer 5,000–7,200,000 | `0` (no limit) | `Run time limit (ms)` |
 | `codexMaxCallMs` | `0` or integer 5,000–3,600,000 | `0` (auto 15–90 s) | `Stuck-call timeout (ms)` |
 | `pendingTtlMs` | integer 1,000–3,600,000 | `300000` | `Prepared summary lifetime (ms)` |
-| `contextHygieneEnabled` | boolean | `false` | `Automatic cleanup` |
+| `contextHygieneEnabled` | boolean | `true` | `Automatic cleanup` |
+| `contextPressureOnly` | boolean | `true` | `Cleanup timing` |
 | `artifactOffloadEnabled` | boolean | `false` | `Offload huge outputs` |
 | `visualArchiveEnabled` | boolean | `false` | `Image snapshots` |
 | `pinPaths` | string array | `[]` | `Always-kept files` |
@@ -537,10 +562,9 @@ Notes on specific keys:
   apply gate for automatic and agent runs and the replacement gate for
   `native-hook`. Manual `/smart-compact` shows a warning and ignores it. A
   5,000-token floor always applies.
-- `pendingTtlMs` is how long a summary returned to Pi waits for Pi's matching
-  compaction confirmation. It does not change the fixed 5-minute window in
-  which a summary staged by the `smart_compact` tool must be applied with
-  `/compact`, or the 5-minute lifetime of a background preparation.
+- `pendingTtlMs` governs staged and ready background summaries (default five
+  minutes), as well as the host-confirmation retention budget. Changing it
+  never permits reuse of a changed prefix or an unsafe retained tail.
 - `showStatus` adds a footer note only when compaction is manual-only or
   disabled. Nothing is shown while healthy, and background preparation is not
   shown in the footer.
@@ -570,6 +594,45 @@ Notes on specific keys:
 
 ## Examples
 
+### Cache-first automatic compaction
+
+Keep roomy cached history stable, clean under pressure, and avoid paying for
+speculative summaries that may expire unused:
+
+```json
+{
+  "smartCompact": {
+    "autoTrigger": true,
+    "autoTriggerStrategy": "settled",
+    "toolLoading": "eager",
+    "contextHygieneEnabled": true,
+    "contextPressureOnly": true,
+    "minContextPercent": 80,
+    "maxContextTokens": 0,
+    "artifactOffloadEnabled": true
+  }
+}
+```
+
+With the optional cap off, thresholds follow Pi's active model `contextWindow`,
+including `models.json` overrides: a 400k window cleans at 288k and compacts at
+320k; a 1M window cleans at 768k and compacts at 800k. The adaptive lead is bounded,
+not a fixed 72% cleanup threshold. After editing model metadata, reselect the
+model through Pi so its active model reflects the override. Overrides are scoped
+to a provider/model pair and cannot enlarge the backend's actual capacity.
+
+Existing summary budgets remain unchanged. Compaction waits
+for an idle, queue-empty boundary; long tool loops can still grow before that
+boundary, and preparing the summary adds latency when it is needed. Offload
+shortens eligible large search/web results before their first model request,
+not cached history; file reads and shell output stay inline. Bound those at
+the tool call with ranges, symbols or concise command output. Retrieval can
+spend tokens too, so smaller context alone is not proof of lower billed cost.
+For a lower automatic trigger threshold on large-window models, set
+`maxContextTokens`; it is not a hard per-request token limit.
+
+### Other configurations
+
 Cleanup and offload without automatic compaction, with every permitted tool
 visible to the agent from the start:
 

package/docs/evaluation.md

@@ -160,8 +160,21 @@ Options (from `--help`): `--arms`, `--repeats=1..8` (default five rounds, probes
 after rounds two and five), `--out` (absolute directory; defaults to
 `./task-eval-reports/<timestamp>`), `--json`, and two offline-only
 cost-accounting fixtures, `--cache-warming=off|streaming|idle` and
-`--background-prep`. Every arm runs with `toolLoading: "eager"`, so the arms
-differ only in hygiene/offload knobs, not in on-demand tool discovery. With
+`--background-prep`. `--tool-loading=eager|lazy` selects the same exposure mode
+for every arm (default eager). Offline lazy frames explicitly load missing groups;
+this measures host/discovery mechanics, not autonomous tool choice. Prefix
+comparisons include active tool schemas and the SDK-collapsed system prompt,
+not just conversation text. They model providers without in-place additions,
+not an exact provider wire payload or billed cache-hit rate.
+
+For a paired exposure comparison:
+
+```bash
+bun run task-eval --arms=hybrid --repeats=2 --tool-loading=eager --out=/tmp/psc-eager
+bun run task-eval --arms=hybrid --repeats=2 --tool-loading=lazy --out=/tmp/psc-lazy
+```
+
+With
 `--cache-warming=idle`, arms that have automatic cleanup on may commit a
 break-even trim at an idle boundary; the rebuilt context ends Pi's warming for
 that entry, so zero warm replays there is expected, while the `no-compaction`
@@ -381,7 +394,6 @@ no provider request.
 | Command | Default | Purpose |
 | --- | --- | --- |
 | `bun scripts/session-pilot.ts` | Offline | Real `AgentSession` with scripted model transport, Pi Continuity only: tools, anchor and pivot with carryover, trimming/retrieval, rewind, compaction and reopen |
-| `NODE_PATH="$PWD/node_modules" bun scripts/context-compat-pilot.ts /path/to/pi-lens` | Offline | Real Pi dispatch with an explicit local pi-lens path in both load orders: read-guard coverage and the anchor cached prefix across trim |
 | `PSC_CLAUDE_OAUTH_EXTENSION=<pi-claude-oauth-adapter>/extensions/index.ts bun scripts/native-host-pilot.ts` | Offline fake provider | Provider-native compaction on stock Pi; the Anthropic OAuth route needs the standalone adapter (patched final-payload build for billing on nested requests). `PSC_NATIVE_ROUTES=codex-oauth,openai-api-key` runs without it and `PSC_PILOT_SHORT=1` shortens each route. `PSC_NATIVE_LIVE=1` sends real, ledger-capped requests and needs explicit approval |
 | `bun run scripts/rtk-pilot.ts /absolute/path/to/rtk` | Local only | Synthetic RTK rewrite contract; characters, not provider tokens |
 | `bun run scripts/visual-pilot.ts --model=provider/id` | Offline planning | Bitmap versus text evidence; `--live` authorizes at most 9 sequential requests and needs explicit approval |

package/docs/guide.md

@@ -15,8 +15,8 @@ This guide is task oriented. For every setting, default and range, see the
 release evidence, see [evaluation](./evaluation.md).
 
 > [!NOTE]
-> **Which version this describes.** This guide targets Pi Continuity `10.0.0`,
-> the stable release of the context-hygiene and continuity rework. The earlier
+> **Which version this describes.** This guide describes the `10.1.0` shipped
+> defaults, including the pressure-first changes and native tool rows. The earlier
 > `9.8.0-canary.*` entries in the changelog are historical local candidates,
 > not npm releases. See [upgrade notes](#upgrade-from-9x) when coming from 9.x
 > and [the changelog](../CHANGELOG.md) for the release scope and evidence limits.
@@ -35,7 +35,7 @@ release evidence, see [evaluation](./evaluation.md).
 - [Session navigation](#session-navigation)
 - [Agent tools](#agent-tools)
 - [Memory: what is stored where](#memory-what-is-stored-where)
-- [Working with other extensions and features](#working-with-other-extensions-and-features)
+- [Pi host integration](#pi-host-integration)
 - [Experimental features](#experimental-features)
 - [Recovery](#recovery)
 - [Storage and privacy](#storage-and-privacy)
@@ -65,8 +65,8 @@ default.
 
 | Status | Features |
 | --- | --- |
-| On by default | Replacing Pi's summary when Pi compacts, **Compact now**, `/smart-compact trim`, session navigation, agent tools on demand, local project memory, backups, secret scrubbing |
-| Optional, off until selected | **Automatic cleanup**, **Offload huge outputs**, the `When idle` and `Prepare in background` strategies, the Hindsight and Mnemopi memory stores, personal-data scrubbing |
+| On by default | Pressure-gated batched cleanup, idle compaction at 80%, stable permitted agent tools, **Compact now**, `/smart-compact trim`, session navigation, local project memory, backups, secret scrubbing |
+| Optional, off until selected | **Offload huge outputs**, economic/cold-cache cleanup, `Prepare in background`, the Hindsight and Mnemopi memory stores, personal-data scrubbing |
 | Experimental | [Provider compaction, image snapshots](#summary-format-provider-compaction-and-images) and the [RTK companion](#rtk-companion-optional-experimental) |
 
 Settings and defaults are listed in the
@@ -86,9 +86,10 @@ Then, inside Pi:
 /smart-compact
 ```
 
-Opening Home changes nothing. With the built-in defaults, automatic compaction
-depends on Pi starting it. Automatic local cleanup, early output offload and
-speculative background preparation are off until selected.
+Opening Home changes nothing. With the new defaults, batched cleanup starts
+under early pressure and compaction starts at an idle 80% boundary. A 400k
+policy window means 288k cleanup / 320k compaction. Offload and speculative
+background preparation remain optional; no extra model calls run while roomy.
 
 ## Upgrade from 9.x
 
@@ -97,23 +98,20 @@ speculative background preparation are off until selected.
 and stored paths keep their names; do not rename existing data directories.
 
 1. Update Pi to **0.87.1+** and use **Node.js 22.19+**. Install the release with
-   `pi install npm:pi-smart-compact@10.0.0`, then reload or restart Pi.
+   `pi install npm:pi-smart-compact@10.1.0`, then reload or restart Pi.
 2. Open `/smart-compact` in the TUI. The bare command now opens Home; **Compact
    now** starts the interactive compaction flow. Print/RPC/SDK use still runs
    compaction directly. Review requires **A** to apply, not Enter.
-3. Expect the agent to see `smart_tools` first. It loads navigation, history,
-   memory and compaction tools on demand. Choose **Always available** only if
-   you want all permitted tools exposed from the start.
-4. Keep one context-editing owner. Disable pi-toolkit auto-context or another
-   overlapping cleanup/compaction extension before using these features; see
-   [extension compatibility](#working-with-other-extensions-and-features).
-5. Review **Memory store** if you use project memory. Exactly one backend is
+3. 10.1.0 uses the pressure-first default: **Always available** tool exposure
+   to keep tool definitions stable. Existing explicit `toolLoading: "lazy"`
+   settings remain respected.
+4. Review **Memory store** if you use project memory. Exactly one backend is
    used, with no silent fallback. Mnemopi and image snapshots now require
    [separately installed optional components](../README.md#optional-components);
    the default local memory store does not.
 
-Automatic cleanup, early offload, background preparation, provider-native
-compaction and image snapshots remain opt-in. Existing compaction permissions
+In the 10.1.0 defaults, cleanup is pressure-gated and enabled. Early
+offload, background preparation, provider-native compaction and images remain opt-in. Existing compaction permissions
 are preserved. Claude subscription routes still need the compatible separate
 adapter described under [provider compaction](#summary-format-provider-compaction-and-images).
 
@@ -210,15 +208,16 @@ changes only the order and the note, never which outputs are eligible.
 
 ### Automatic cleanup (optional)
 
-Automatic trimming is separate and off by default: turn on
-**Automatic cleanup** (`contextHygieneEnabled`), or pick the `Cleanup only` or
-`Fully automatic` preset. It uses the same eligibility rules as the manual
+Automatic trimming is separate and enabled under pressure by default. Control
+it with **Automatic cleanup** (`contextHygieneEnabled`); **Cleanup timing**
+(`contextPressureOnly`) defaults to pressure-only. It uses the same eligibility rules as the manual
 command and needs `smart_context` reachable by the model, since the digest
 points it there (any **Agent tools** choice except **Off**).
 
 A batch needs at least 16,384 characters of net savings and eight assistant
 turns after the last trim, rewind or compaction. It then commits at the turn
-boundary for one of three causes, recorded on the trim entry:
+boundary under pressure. The other two causes below require the explicit
+**Economic (opt-in)** timing choice (`contextPressureOnly: false`):
 
 - `pressure`: context usage reached the early pressure gate.
 - `break-even`: the model's catalog prices say the trim pays back its prompt
@@ -293,7 +292,7 @@ to existing settings.
 
 | Preset | Automatic compaction | Automatic cleanup | Agent can call `smart_compact` |
 | --- | --- | --- | --- |
-| `With Pi (default)` | Only when Pi's own auto-compaction fires | Off | Follows Pi's tool settings |
+| `Pressure-first (default)` | Starts when idle at the 80% apply gate | Under early pressure | Follows Pi's tool settings |
 | `Manual only` | Off | Off | No |
 | `Manual + agent` | Off | Off | Yes |
 | `Cleanup only` | Off | On | No |
@@ -301,13 +300,13 @@ to existing settings.
 
 Two points matter most:
 
-- **`With Pi (default)` is passive.** It replaces the summary only when Pi
-  starts a compaction. If Pi's auto-compaction is off, nothing compacts
-  automatically. Extensions cannot read Pi's setting, so readiness reports it
-  as `unknown`.
+- **The default is pressure-first.** Roomy history stays unchanged; cleanup
+  and compaction share one policy window. The optional `native-hook` strategy
+  remains passive and requires Pi's auto-compaction to be enabled.
 - **`Fully automatic` works with Pi's auto-compaction off.** It asks Pi to
   compact at the next idle, queue-empty boundary once context reaches
-  `Start at context %`, with a 10-minute cooldown after a compaction.
+  `Start at context %`, with a 10-minute cooldown after every completed
+  attempt, including failures and missing-callback timeouts.
 
 `Start at context %` counts against the model's full window. On a large-window
 model (Home warns above 400k tokens), set `Context cap for start % (tokens)`
@@ -321,6 +320,11 @@ may still use its own compactor. See
 [automatic strategies](./configuration.md#automatic-strategies) for the
 background strategy and the gate arithmetic.
 
+For cost-sensitive sessions, use the [cache-first configuration](./configuration.md#cache-first-automatic-compaction):
+stable tools, idle compaction, pressure-only cleanup, no speculative preparation,
+and first-delivery offload for eligible large outputs. Existing mode budgets and
+summary quality checks remain in place.
+
 ## Retrieve archived output
 
 The agent retrieves trimmed, rewound, offloaded or image-archived output with
@@ -374,7 +378,7 @@ size, an `artifact-<hash>` ID and short first/last excerpts.
 - Not offloaded: errors, images, shell commands, writes, unknown tools,
   `read`/`read_symbol`/`read_enclosing` deliveries, instruction/skill-file
   reads and `smart_context` itself. File reads stay inline on first delivery,
-  so read-before-edit guards such as pi-lens see what was actually read.
+  so read-before-edit guards see what was actually read.
 - This is not a summary. The agent has to search or read the omitted parts
   when it needs them. Total savings depend on how much it reads back.
 - Each file is at most 2 MiB. A session holds at most 256 files or 32 MiB; at
@@ -396,6 +400,11 @@ Example inputs (one JSON object per call; explore between checkpoint and rewind)
 {"action":"trim"}
 ```
 
+- Check `status` for actual usage and gates. Checkpoints are permitted below
+  pressure; agent rewind/trim/anchor requests are not, by default. Human
+  commands can request early work. Unsafe edits before retained signed
+  Anthropic thinking are refused, even when thinking bytes themselves would
+  stay unchanged.
 - `checkpoint`, `rewind` and `trim` return **queued**. Pi commits them at the
   end of the current tool batch.
 - One checkpoint is active at a time; a new one replaces it. It survives reload.
@@ -417,7 +426,11 @@ Example inputs (one JSON object per call; explore between checkpoint and rewind)
 An anchor is a named point in this conversation with a summary of what was
 true there: the goal, decisions and the state of the work. Anchors are stored
 as messages in the session, so the agent sees them too. Use them to find the
-way back after a long detour.
+way back after a long detour. Under pressure, an agent anchor also queues one
+safe cleanup of its new region through the shared trim controller. Previous
+anchor prefixes stay protected. It is not a full compaction; the response says
+whether cleanup was queued, blocked or unnecessary. A human may mark a milestone
+earlier. Append-only anchors do not discard an already prepared summary.
 
 Home → **History & recovery** → **Session navigation**, or `/smart-compact context`:
 
@@ -449,8 +462,8 @@ other switches are kept), **Search other sessions**, **Return to an anchor**,
 newest anchor, so the context before it is read from cache while later turns
 change), **Anchor status** (footer, display only) and **Navigation guide**.
 
-Anchors recorded by pi-toolkit's `context` tool in earlier sessions stay
-readable in browse and search.
+Legacy `context` tool anchors recorded in earlier sessions stay readable in
+browse and search.
 
 ### Hand off to a new session
 
@@ -491,8 +504,8 @@ decides what the agent sees:
 
 | Choice | What the agent sees |
 | --- | --- |
-| **On demand** (default) | One small loader, `smart_tools`. The agent loads a group when it needs it: `navigation`, `history`, `memory` or `compaction`. Loaded groups are forgotten at the next session start, branch change or compaction. |
-| **Always available** | Every permitted tool from the start. |
+| **Always available** (default) | Every permitted tool from the start, keeping tool definitions stable. |
+| **On demand** | `smart_tools` loads a missing group. Late loading can rebuild the provider cache. Loaded groups reset at session start/branch change, not compaction. |
 | **Off** | No context tools. The human UI keeps working. |
 
 `smart_tools` also answers `status`, `unload` and `guide`. The guide is the
@@ -511,11 +524,19 @@ earlier request bytes disappear.
 | `smart_context` | `history` | Status, search, read, plan, trim, checkpoint, rewind | Queued edits apply at the end of the current tool batch |
 | `smart_recall` | `memory` | Searches this project's memory in the selected store | Immediately; read-only |
 | `smart_save_memory` | `memory` | Saves or resolves one durable fact | Only after **you** approve the host confirmation dialog |
-| `smart_compact` | `compaction` | Prepares a verified summary and stages it | Never mid-turn. Staged for 5 minutes; applied by the next `/compact` or a compaction Pi starts. |
+| `smart_compact` | `compaction` | Prepares a verified summary and stages it | Never mid-turn. Staged for `pendingTtlMs` (default 5 minutes); applied by the next `/compact` or a compaction Pi starts. |
+
+**Tool rows.** Every Smart Compact tool renders a native, compact status row:
+queued, staged, dry-run, skipped, pending, failed and cancelled states are
+labeled as such and never displayed as done, applied or saved. Collapsed rows
+show bounded previews and hide long identifiers behind the native expansion
+key (the configured keybinding, shown as a hint); expanding shows the full
+original result text. Rows are call-time snapshots — they never poll or refresh
+on their own.
 
 Approval and gates:
 
-- `smart_compact` refuses below `Start at context %` (default 60%) or below
+- `smart_compact` refuses below `Start at context %` (default 80%) or below
   5,000 tokens. `tool=XX%` in Pi's footer is the tool-output share, not
   context fullness. If a summary is already staged, it reports that and makes
   no calls. With automatic compaction off, nothing consumes the staged summary
@@ -595,25 +616,9 @@ memory**) needs the TUI and applies only to the local store. It offers:
 It shows counts and asks for confirmation. Mnemopi, Hindsight, continuity
 state, backups and artifacts are not affected.
 
-## Working with other extensions and features
-
-At session start Pi Continuity checks the loaded commands and tools for known
-compaction or context-editing extensions (pi-openai-toolkit, context-fold,
-pi-fold, pi-context-prune, pi-dcp, pi-toolkit's `context` tool) and shows one
-notice naming them. The check is name-based evidence, not proof, and finds
-nothing for unknown extensions; the runtime notices below (foreign compaction
-applied, foreign cache rebuilds) still cover those.
-
-### pi-toolkit
-
-Session navigation replaces the anchor, recall and pivot features of
-pi-toolkit's `context` tool, and Pi Continuity is the only owner of trimming.
-Do not load pi-toolkit's context-management extension together with Pi
-Continuity: two extensions recording anchors and pruning the same branch are
-not safe in any load order. The `piToolkit.context.thinningEnabled` key is not
-read by Pi Continuity. Anchors recorded earlier by pi-toolkit stay readable.
+## Pi host integration
 
-### Other compaction extensions and Pi's built-in compaction
+### Pi compaction lifecycle
 
 Pi applies one compaction per request: the last extension to answer
 `session_before_compact` wins, and with no answer Pi's built-in summarizer
@@ -625,7 +630,7 @@ runs. When something other than Pi Continuity applies the compaction:
   the winner and the model calls that were wasted.
 - Another extension's compaction shows a once-per-session notice even when
   nothing was prepared, because Pi Continuity recorded no state or metrics
-  for it. Keep only one compaction extension loaded.
+  for it.
 - Pi's built-in compaction shows a notice only while automatic compaction is
   on (nothing was ready when Pi asked); earlier continuity state still carries
   over through the capsule.
@@ -814,9 +819,9 @@ What is not covered:
 | Symptom | Cause and action |
 | --- | --- |
 | Agent reports "Compaction skipped: context 38% (…) below the 60% agent-tool threshold" | `smart_compact` waits for `Start at context %` of the **active model's** window (`tool=XX%` in the footer is the tool-output share, not context fullness). Use **Compact now** for early compaction. |
-| Nothing compacts automatically | With the default `With Pi`, Pi's auto-compaction must be on (readiness shows `unknown`). Choose `Fully automatic` to start without it. Check `Automatic compaction` and `This branch only`. On a large-window model, see `Context cap for start % (tokens)` in [Let it run automatically](#let-it-run-automatically). |
+| Nothing compacts automatically | Check the idle boundary and pressure gates. Only the optional `native-hook` strategy requires Pi's auto-compaction (readiness shows `unknown`). Check `Automatic compaction` and `This branch only`. On a large-window model, see `Context cap for start % (tokens)` in [Let it run automatically](#let-it-run-automatically). |
 | Cleanup did nothing on the next reply | Expected: the next request is sent untrimmed; cleanup applies at the next completed turn. |
-| **Clean up tool output** shows `held for a cold cache` | Expected with **Automatic cleanup**: the batch waits for the prompt cache to expire; see [automatic cleanup](#automatic-cleanup-optional). Select the row to apply it at the next completed turn instead. |
+| **Clean up tool output** shows `held for a cold cache` | Expected only with **Economic (opt-in)** cleanup timing: the batch waits for the prompt cache to expire; see [automatic cleanup](#automatic-cleanup-optional). Select the row to apply it at the next completed turn instead. |
 | Automatic cleanup or offload never happens | Both need `smart_context` reachable: **Agent tools** must not be **Off**, and `smart_context` must not be hidden with `/tools`. Offload also needs **Offload huge outputs** on and applies only to read-only text results of 16,384+ characters. |
 | Agent says a summary is staged, but context did not shrink | Run `/compact` within 5 minutes. With automatic compaction off, nothing else consumes it. |
 | `smart_context`, `smart_recall`, `smart_save_memory` or `smart_navigation` missing | With **On demand**, the agent loads a group through `smart_tools`; with **Off**, no context tool is shown; see [agent tools](#agent-tools). Check `/tools`. |
@@ -829,7 +834,9 @@ What is not covered:
 | Warning line at the top of Settings | Some `settings.json` values were invalid or converted and are being ignored; the line names them. |
 | Provider compaction was skipped | The chat model's API is not a supported native route; verified text was used. In sessions smaller than Pi's `compaction.keepRecentTokens`, Pi refuses the result and the conversation stays unchanged. |
 | `Text + images` produced text only | Expected unless the chat model is direct Anthropic `claude-sonnet-5` and the optional `@resvg/resvg-js` component is installed; see [image snapshots](#summary-format-provider-compaction-and-images). |
-| Timeout or verification failure | A single `Smart Compact: ...` line explains the effect and next step. Details: `/smart-compact metrics`. Stack traces: `DEBUG=smart-compact`. |
+| Synthesis fallback in progress or metrics | Intermediate recovery, not an apply result. The final `Smart compact applied` notice discloses fallback use. Generation error details remain in `/smart-compact metrics` and verbose output. |
+| Timeout or verification failure | No Smart Compact summary was applied. During host-triggered compaction, Pi may then produce its own summary; that is a separate outcome. A single `Smart Compact: ...` line explains the failure. Details: `/smart-compact metrics`. Stack traces: `DEBUG=smart-compact`. |
+| `Cache miss: … tokens re-billed (~$…)` | Pi's own notice, not a compaction failure. The amount is a token-price estimate, not a verified invoice. Smart Compact records rebuild attribution in Home → Readiness & details and metrics without a duplicate toast. |
 
 Without a UI, warnings and errors go to stderr.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-smart-compact",
-	"version": "10.0.0",
+	"version": "10.1.0",
 	"description": "Pi Continuity — context hygiene and session continuity for Pi Coding Agent: recoverable cleanup, checkpoints, memory and verified compaction.",
 	"type": "module",
 	"packageManager": "bun@1.4.2",

package/dist/app/extension-conflicts.d.ts

@@ -1,15 +0,0 @@
-import type { SlashCommandInfo, ToolInfo } from "@earendil-works/pi-coding-agent";
-export interface ConflictingExtension {
-    name: string;
-    kind: "compaction" | "context-editing";
-    evidence: string;
-}
-export interface ExtensionRegistry {
-    commands: SlashCommandInfo[];
-    tools: ToolInfo[];
-}
-/** Known compaction or context-editing extensions visible in the live command/tool registry. Name-based evidence, not proof. */
-export declare function detectExtensionConflicts(registry: ExtensionRegistry): ConflictingExtension[];
-/** One notice naming every conflicting extension. */
-export declare function conflictNotice(conflicts: ConflictingExtension[]): string;
-//# sourceMappingURL=extension-conflicts.d.ts.map

package/dist/app/extension-conflicts.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"extension-conflicts.d.ts","sourceRoot":"","sources":["../../src/app/extension-conflicts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAElF,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,YAAY,GAAG,iBAAiB,CAAC;IACvC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AAmCD,gIAAgI;AAChI,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,oBAAoB,EAAE,CA0B5F;AAED,qDAAqD;AACrD,wBAAgB,cAAc,CAAC,SAAS,EAAE,oBAAoB,EAAE,GAAG,MAAM,CAMxE"}