pi-smart-compact 10.0.1 → 10.1.1

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.1`. 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
@@ -226,10 +228,10 @@ compaction is on.
 
 ### Automatic runs cap
 
-Automatic runs (native-hook, settled and background) are capped at **60
-seconds** and **four model calls**. `autoTriggerTimeoutMs` defaults to 120,000
-ms and accepts up to 300,000 ms, but the effective automatic deadline is
-`min(autoTriggerTimeoutMs × provider timeout multiplier, 60 s)`. The call cap is
+Automatic runs (native-hook, settled and background) are capped at **300
+seconds** and **four model calls**. `autoTriggerTimeoutMs` defaults to 300,000
+ms and accepts up to 300,000 ms; the effective automatic deadline is
+`min(autoTriggerTimeoutMs × provider timeout multiplier, 300 s)`. The call cap is
 `min(mode call budget, 4)`. When an automatic run times out or fails, it unwinds
 so Pi's own compactor can run.
 
@@ -267,7 +269,7 @@ For calls (`maxLlmCalls`) and prompt tokens (`maxLlmInputTokens`):
 | Per-run option (`--max-calls`, `max_calls`, ...) | Used as given, even above the mode limit |
 | Config value `0` | The mode limit |
 | Config value above `0` | `min(config value, mode limit)` |
-| Automatic run | Additionally capped at 4 calls and 60 s |
+| Automatic run | Additionally capped at 4 calls and 300 s |
 
 With the default `maxLlmCalls: 8`, every mode keeps its own limit, because 8 is
 not below any mode's call limit. A config value can only lower the limit.
@@ -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,13 +511,13 @@ 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 |
+| `autoTriggerTimeoutMs` | integer 1,000–300,000 | `300000` | `Automatic run time limit (ms)`; capped at 300 s |
 | `compactionEngines` | ordered list of `eesv`, `native` | `["eesv"]` | `Engine` |
 | `requireApproval` | boolean | `true` | `Ask before applying` |
 | `showStatus` | boolean | `true` | `Footer status` |
@@ -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

@@ -133,9 +133,8 @@ receives the same three bounded coding-continuity scenarios (`implementation`,
 `debugging`, `continuity`) sequentially, with a 1,500-token output cap and a
 60-second timeout per call, scored by the deterministic verifier. It reports
 score, latency and reported usage. Apply a route manually, and only after
-representative evidence; one probe is not that evidence. The dated
-[2026-08-06 baseline](https://github.com/alpertarhan/pi-smart-compact/blob/main/docs/reports/provider-evaluation-2026-08-06.md)
-(repository only) is an example of this output, not a current ranking.
+representative evidence; one probe is not that evidence. Historical probe
+results are not a current model ranking.
 
 ## Paired continuation and memory evaluation
 
@@ -160,8 +159,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`
@@ -387,22 +399,15 @@ no provider request.
 | `PSC_HINDSIGHT_LIVE=1 … bun run test/hindsight-live.canary.ts` | Not run by `bun test` | Live Hindsight contract with a hard call budget; see [Hindsight memory](./hindsight-memory.md#tests) |
 
 Dated reports record what was measured on their date, with the code and host
-versions stated inside. They are kept for provenance and are not updated
-retroactively; later findings are added as dated addenda. Current behavior is
-described in the [guide](./guide.md), [configuration](./configuration.md) and
-[architecture](../ARCHITECTURE.md). Reports live in the repository only; the
-npm package does not include `docs/reports/` or `docs/findings/`. Pilot
-reports have a machine-readable `.json` companion beside them.
-
-| Report | Scope |
-| --- | --- |
-| [Provider evaluation baseline, 2026-08-06](https://github.com/alpertarhan/pi-smart-compact/blob/main/docs/reports/provider-evaluation-2026-08-06.md) | Live three-scenario probe across five models; advisory; 2026-09-25 addendum on route-report token semantics |
-| [Context hygiene and continuity, 2026-09-24](https://github.com/alpertarhan/pi-smart-compact/blob/main/docs/reports/context-hygiene-2026-09-24.md) | Hygiene design and offline experiments |
-| [Hindsight and provider-native compaction research, 2026-09-24](https://github.com/alpertarhan/pi-smart-compact/blob/main/docs/reports/hindsight-native-compaction-research-2026-09-24.md) | Pre-implementation research plus later measured results |
-| [Full AgentSession offline pilot, 2026-09-24](https://github.com/alpertarhan/pi-smart-compact/blob/main/docs/reports/session-pilot-2026-09-24.md) | Scripted-transport lifecycle pilot; 2026-09-25 candidate and `9.8.0-canary.1` follow-ups |
-| [Visual evidence pilot, 2026-09-24](https://github.com/alpertarhan/pi-smart-compact/blob/main/docs/reports/visual-pilot-2026-09-24.md) | Live synthetic bitmap-versus-text reading pilot on one model |
-
-External review findings, one folder per reviewer, are indexed in
-[`docs/findings/`](https://github.com/alpertarhan/pi-smart-compact/blob/main/docs/findings/README.md).
-They are advisory analyses of a specific revision range, not release gates or
-evidence of current behavior.
+versions stated inside. Preserve their provenance; add dated addenda rather
+than updating measurements retroactively. Current behavior is described in the
+[guide](./guide.md), [configuration](./configuration.md) and
+[architecture](../ARCHITECTURE.md).
+
+Research reports in `docs/reports/` and review findings in `docs/findings/`
+are local, ignored artifacts, not tracked repository or npm content. Pilot
+reports can keep machine-readable `.json` companions beside them. Earlier
+copies may remain in Git history; this policy does not erase that history.
+
+External review findings are advisory analyses of a specific revision range,
+not release gates or evidence of current behavior.

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.1`,
-> 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.
@@ -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,20 +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.1`, 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.
+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).
 
@@ -207,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
@@ -290,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 |
@@ -298,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)`
@@ -312,12 +314,17 @@ model (Home warns above 400k tokens), set `Context cap for start % (tokens)`
 and safety headroom still use the real window.
 
 Turning `Automatic compaction` off disables both Smart Compact strategies. It
-does not turn off Pi's own compactor. Automatic runs are capped at 60 seconds
+does not turn off Pi's own compactor. Automatic runs are capped at 300 seconds
 and four model calls, whatever the configured limits are. When they fail, Pi
 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
@@ -393,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.
@@ -414,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`:
 
@@ -488,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
@@ -508,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
@@ -795,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`. |
@@ -810,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.1",
+	"version": "10.1.1",
 	"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",