pi-fold 4.2.7 → 4.3.0

package/README.md

@@ -2,156 +2,94 @@
 
 [![npm](https://img.shields.io/npm/v/pi-fold)](https://www.npmjs.com/package/pi-fold) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22142456.svg)](https://doi.org/10.5281/zenodo.22142456)
 
-**Rotate stale text out of the context window without losing it, and spend the prefix cache once per commit instead of continuously.** The oldest part of a session collapses into short briefs while the exact originals stay on disk, one tool call away. Folding is automatic and needs no agent participation. The shipped shape is deterministic briefs paired with a durable memory store, which is the cheapest configuration measured that kept recall intact.
+**Long sessions without forgetting.** pi-fold rotates stale context out of the window and into short briefs, while the exact originals stay on disk one tool call away. It runs automatically, keeps your prefix cache warm, and never throws anything away.
 
 ![pi-fold folding a session in place: marks outline completed spans as the session works, and the marks commit together at a fold event](https://raw.githubusercontent.com/shaneconner/fold/main/media/fold-demo.gif)
 
-*Marks outline spans as they complete and move nothing; the next commit applies every standing mark in one rewrite. Expanding a brief brings the exact messages back byte for byte. Illustrative animation drawn on the 2.x surface, where the agent laid the marks; since 3.0 the runtime lays them.*
-
 ## Install
 
 ```sh
 pi install npm:pi-fold
 ```
 
-Node 22 or later and Pi 0.83 or later. Pi 1.0 is supported and requires Node 22.19 or later. MIT licensed. Pi supplies the extension's runtime packages; they are declared as host-provided peers, not private dependencies.
+Requires Node 22+ and Pi 0.83+ (Pi 1.0 needs Node 22.19+). MIT licensed.
 
-Folding does not require a memory store, but every best result measured came from pairing it with one. The campaigns used [pi-canon](https://github.com/shaneconner/canon), installed separately. The two began as a single working setup and were split into separate extensions for modularity, and the experiments are what established that they work better as complements than either does alone. Only that pairing has been measured. Any durable long-term memory store is expected to compose the same way, though that is a suspicion rather than a result.
+For the best results, pair it with a long-term memory store such as [pi-canon](https://github.com/shaneconner/canon). Folding keeps the window lean; the store keeps what the session learned. Together they were the strongest setup in every benchmark.
 
-## What it does
+## Why fold instead of compact
 
-Compaction replaces the transcript with a summary and discards the originals. Folding replaces stale spans with briefs and keeps the originals retrievable.
+Compaction replaces the transcript with a summary and discards the originals. Folding replaces old spans with briefs and keeps the originals retrievable, so nothing is ever lost.
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/shaneconner/fold/main/media/fold-vs-compaction-dark.svg">
   <img alt="Compaction turns the transcript into a summary and discards the originals, so the session starts over. pi-fold turns it into a brief and keeps the exact originals on disk, one peek or expand away, so the session keeps going." src="https://raw.githubusercontent.com/shaneconner/fold/main/media/fold-vs-compaction-light.svg">
 </picture>
 
-A fold takes a contiguous span of session entries and replaces it, in the window only, with a short brief. The entries stay in Pi's session file byte for byte; the fold finds them by Pi's own entry ids and records each one's SHA-256 hash when it folds. The brief carries a handle, the handle resolves to the originals, and expansion restores them as Pi holds them. If an entry's bytes no longer match the recorded hash, the fold still stands and the change is logged as a `context.drift` event.
+On a 64-stage coding assignment over the curl codebase, followed by a 16-question recall test about the whole session:
+
+| Setup | Recall | Cost | Wall clock |
+| --- | ---: | ---: | ---: |
+| Compaction | 4 / 16 | $151 | 6.9h |
+| Compaction + memory store | 14 / 16 | $202 | 9.0h |
+| **pi-fold + memory store** | **14 / 16** | **$101** | **5.2h** |
+
+Same recall, half the cost, and hours faster. The savings come from the cache: folding batches its rewrites so the provider replays the cached prefix instead of rereading the session from scratch, and roughly 95% of input in the pi-fold run was served from cache.
 
-The package registers one tool, `pi_fold_context`, with nine actions over the transcript: `status`, `peek`, `brief`, `expand`, `refold`, `pin`, `unpin`, `reboundary` and `unmark`. A session that never calls the tool still folds; it degrades into lossless hierarchical compaction.
+Full write-ups, data and logs are on Zenodo ([design](https://doi.org/10.5281/zenodo.21856873), [working memory](https://doi.org/10.5281/zenodo.21980746), [retrieval](https://doi.org/10.5281/zenodo.22142454), [rotation and retention](https://doi.org/10.5281/zenodo.22142456)), with friendlier versions on [Medium](https://medium.com/@shane.conner/a-compaction-summary-is-one-record-doing-a-stores-job-3f46212ef059) and [shaneconner.com](https://shaneconner.com/projects/pi-fold/).
 
-### The fold bar
+## What you get
 
-In an interactive session one compact, full-height bar sits directly above Pi's footer.
+- **Automatic folding.** Completed work is marked as it finishes and folded when the window fills up. The agent doesn't have to do anything.
+- **Lossless recall.** Every brief links back to the original messages, verified by hash. The agent can `peek` at them or `expand` them back in place.
+- **A cache-friendly cadence.** Marks cost nothing. All of them land together in one commit, so the cache is spent once per commit instead of on every change.
+- **A clean chat.** Folded spans collapse into a single muted row in the chat, so your screen matches what the model actually sees.
+- **The fold bar.** A compact usage bar above Pi's footer shows how full the window is and what's in it, from deeply folded to still raw.
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/shaneconner/fold/main/media/fold-bar-dark.svg">
-  <img alt="A single full-height usage bar. Batlow colours group consolidated folds, span folds, tool folds, marked content, raw context and pinned content in that order. The suffix shows percentage, commit point, and fold, mark, and pin counts." src="https://raw.githubusercontent.com/shaneconner/fold/main/media/fold-bar-light.svg">
+  <img alt="A single full-height usage bar. Colours group consolidated folds, span folds, tool folds, marked content, raw context and pinned content in that order. The suffix shows percentage, commit point, and fold, mark, and pin counts." src="https://raw.githubusercontent.com/shaneconner/fold/main/media/fold-bar-light.svg">
 </picture>
 
-The forty-column bar uses full-height half-blocks for eighty steps of fill, reading Pi's `getContextUsage()` directly whenever the session moves, on the same key Pi's footer re-reads on (session, leaf entry, entry count, model), so a repaint never pays for a fresh reading. Its percentage uses Pi's full context window, the same scale as Pi's footer, including Pi's estimate of messages since the last provider response. Within that fill, colours show the estimated visible composition, grouped by distance from compression: **Consolidated Folds, Span Folds, Tool Folds, Marked, Raw, Pinned**. The first three are compressed now, deepest first; marked content folds at the next commit; raw content is eligible later; pinned content is held against every commit until released. The six shades, from consolidated to pinned, are read off a colour map, [Crameri's Batlow](https://www.fabiocrameri.ch/colourmaps/) end to end by default, so the bar reads as a gradient from most compressed to most settled. `/fold-settings` offers Batlow, viridis, plasma, magma and cividis, and where on the chosen map the two ends sit, so a slice of a map or a reversed one is a keypress away; the bar repaints on each step. Whatever the choice, each shade's lightness is moved away from the background, hue held, until it clears 4.5:1 on dark and light terminals, and label colours match the bar. Each nonempty category keeps at least one half-cell when the measured fill has room; remaining width follows relative mass. This visibility floor makes small compressed categories visible, so individual category widths are not token-exact. At very low occupancy, the largest shares take the available space. There are no individual fold edges, scores, or height differences.
-
-The suffix reads `34% · commit at 55% · N Folds (X Cons., Y Span, Z Tool, X Mark, Y Pin)`, naming only the kinds with something to count, in the bar's order; a fresh session reads `0 Folds`. `N Folds` counts visible compressed folds; `Mark` counts pending marks and `Pin` counts protected entries, not additional compressed folds. A tool fold is lossless compression of tool-result context, not a count of tool calls. `/fold-status` retains the detailed token and nesting figures. Its `Budget` row and the editor's `Budget` header report the separate serving budget and the tokens remaining before a commit.
-
-Two dotted marks stand in the band's edge cells: one where a commit aims to land and one where automatic folding is triggered. `minTarget` and `maxTarget` remain shares of the serving budget; the marks and displayed commit point are converted to Pi's full-window scale, so the trigger does not move. With a 272,000-token window and the default 255,616-token serving budget, the 80% trigger appears at about 75% of Pi's window. The usage label rounds down to a whole percentage, matching pi-cc's footer; bar fill and folding decisions keep the unrounded value. The displayed commit point rounds to the nearest whole percentage. Each is drawn over the fill's own colour in a deeper tone of that same hue, so the fill continues behind the mark; on the empty track they stand in muted ink. Neither takes a colour of its own or a warning colour. When Pi reports unknown usage, including immediately after native compaction, the row says `not measured yet`; no saved count or local estimate fills the gap. After a fold commit it identifies the old reading until the provider measures again. Crossing the target is routine runtime work, not a user action item. On reload, saved session context supplies the fold counts and composition without a new model message; the next real context event replaces that read-only view. Unavailable composition is stated as `mapping`; if folding stops, `FOLDING STOPPED` replaces the bar. Non-truecolor terminals use the theme's own colours.
-
-### The chat
-
-The chat shows the model's window. Pi paints its chat from every session entry and only native compaction clears it, so without this a long folded session would keep its whole transcript on screen. Each fold the model holds collapsed appears as one muted row, `▸ consolidation · 59 entries · <brief>`, in place of the messages it covers. When the model expands a fold, its messages return where they were. The view follows the model one way: it changes when a commit, an expansion or a refold changes what the model sees, or when Pi repaints the chat, and nothing done in the chat changes the model's context. `/fold-editor` remains the place to read inside a fold.
-
-## Results
-
-One 64-stage assignment over the curl C repository, run as a single agentic turn. Same model, same 251,520-token serving budget, every run. After all 64 stages landed, one withheld message asked sixteen questions about material from across the whole session.
+## Commands
 
-| Condition | Correct of 16 | Wrong | Cost | Fresh input | Cached input | Wall clock |
-| --- | ---: | ---: | ---: | ---: | ---: | ---: |
-| Compaction | 4 | 3 | $151.24 | 7.64M | 160.2M | 6.9h |
-| Compaction + memory store | 14 | 0 | $201.70 | 9.65M | 231.7M | 9.0h |
-| pi-fold, deterministic briefs | 11.3 avg | 3.5 avg | $93.65 | 5.74M | 91.2M | 4.6h |
-| **pi-fold + memory store** | **14** | **0** | **$100.85** | **5.57M** | **102.2M** | **5.2h** |
-| pi-fold, agent-written briefs | 3 | 9 | $111.96 | 7.12M | 108.8M | 5.4h |
+| Command | What it does |
+| --- | --- |
+| `/fold-status` | Detailed token and fold figures |
+| `/fold` | Commit every pending mark now |
+| `/fold-editor` | Interactive map of the window, for reading inside folds |
+| `/fold-settings` | Edit options live; saved to `~/.config/pi-fold/settings.json` |
 
-*Fresh input is what the provider had to read for the first time; cached input is what it replayed. The deterministic-briefs row averages four runs that scored 14, 14, 9 and 8.*
-
-Compare the two store-paired rows. Both scored 14 correct with none wrong, and folding cost half. That gap is request count rather than price: compaction needed roughly twice the provider requests for the same work, plus summarizer calls that never show up in its own ledger.
-
-Compaction alone abstained nine times and was wrong three, so its dominant failure was declining rather than inventing, but it did invent. And the fold's deterministic runs are bimodal rather than average: two answered 14 with nothing wrong, two lost old material, and cost did not predict which. The store was tried once on each arm and both came back with nothing wrong, which is suggestive, not a rate.
-
-Agent-written briefs scored worst of anything measured, which is why that invitation ships off.
-
-Four papers with figure sources, redacted per-request ledgers and campaign logs are on Zenodo: [design and trace evaluation](https://doi.org/10.5281/zenodo.21856873), [working memory under context shedding](https://doi.org/10.5281/zenodo.21980746), [ephemeral retrieval](https://doi.org/10.5281/zenodo.22142454), and [rotation and retention](https://doi.org/10.5281/zenodo.22142456), which is the campaign above. Narrative versions on [Medium](https://medium.com/@shane.conner/a-compaction-summary-is-one-record-doing-a-stores-job-3f46212ef059), interactive versions at [shaneconner.com](https://shaneconner.com/projects/pi-fold/), and the full chronology in [the experiment log](https://github.com/shaneconner/fold/blob/main/docs/fold_vs_compaction/experiment-log.md).
-
-## Limits
-
-- **Native compaction is strong and is the right default for most sessions.** It needs no installation and no tool surface. This is an alternative for workflows where the numbers above matter, not a replacement.
-- **The benchmark is narrow by construction.** It was built to reproduce specific things compaction handles badly, one to four runs per condition, and it says nothing about production behavior.
-- **Folding is not a memory store.** It rotates transcript source out of the window; durable placement of what a session learned is a separate job, and the pairing is where the measured value sat.
+The agent gets one tool, `pi_fold_context`, with actions to `status`, `peek`, `expand`, `refold`, `pin` and `unpin` content, plus `brief`, `reboundary` and `unmark` for curating pending folds. It's all optional; a session that never calls the tool still folds.
 
 ## Configuration
 
-`registerPiFold(pi)` works with no arguments, and the defaults are the configuration the campaign above actually ran: deterministic briefs, the invitation off, the tool-call diet at half the window, and a 0.80/0.20 band. Nothing here needs tuning.
-
-The one thing worth adding is a long-term memory store. Rotation and retention are different jobs: folding gets stale material out of the window, a store keeps what the session learned. A handoff summary tries to do both in one record, written once under time pressure, bounded by the window it has to fit in. Folding is the rotation half and only that half.
+The defaults are the benchmarked setup, so there's nothing you need to tune.
 
-Seven options, and every other name is refused.
-
-| Option | Default | Effect |
+| Option | Default | What it controls |
 | --- | --- | --- |
-| `thresholds` | `{ maxTarget: 0.80, minTarget: 0.20, consolidateAfter: 10, minFoldChars: 8000 }` | The band, set whole or not at all. The first two are proportions of the serving budget. `consolidateAfter` is how many visible roots a parent is owed. `minFoldChars` is the size a fold has to reach to be worth making, and the floor a gap between folds has to clear to stay raw. Validated atomically; an impossible policy is refused by name rather than clamped. |
-| `providerInputBudget` | derived from Pi's context window | The tokens this deployment may actually put in a request, already net of any output reservation when supplied. Without it, folding retains its default headroom of 16,384 tokens, capped at 10% of the window. This is a folding allowance, not a measured provider output reservation or a read of Pi's per-model compaction settings. Thresholds use this serving budget; the fold bar uses Pi's full-window scale. |
-| `blacklistAutoFoldTools` | `new Set()` | The exception list. Every completed tool batch is foldable without an agent mark; name a tool here and its results stay raw. |
-| `toolFoldThreshold` | `0.50` | The tool-call diet: a share in `[0, 1)` naming the oldest fraction of the window whose tool results are clipped in view. `0` turns it off. |
-| `preCommitNotice` | `false` | The notice switch. False is the shape that won the campaign above: no carrier reaches the projection and every fold ships the runtime's own words. `true` states the window's status to the agent once per approach to a commit: where the commit fires, how far away it is, what is staged, what that frees, what is pinned and what the pin costs, with the verbs listed and no argument made for using any of them. |
-| `noticeLeadShare` | `0.10` | How far below the commit trigger that notice speaks, as a share of the serving budget. A distance rather than a point, so it follows a band that moves. Read only when `preCommitNotice` is on. |
-| `palette` | `{ map: "batlow", start: 0, end: 1 }` | The fold bar's colours, and nothing about folding. `map` is one of `batlow`, `viridis`, `plasma`, `magma`, `cividis`; `start` and `end` are positions on it in `[0, 1]` for the most compressed and the pinned shade, which may not coincide and may run backwards. Set whole or not at all. |
-
-Four commands ship for the human: `/fold-status`, `/fold` (commit every staged mark now), `/fold-editor` (the interactive map of the window) and `/fold-settings` (edit the options above; each change is saved to `~/.config/pi-fold/settings.json` and takes effect in the running session).
+| `thresholds` | `{ maxTarget: 0.80, minTarget: 0.20, consolidateAfter: 10, minFoldChars: 8000 }` | When a commit fires (`maxTarget`), how far it folds down (`minTarget`), when folds consolidate, and the smallest span worth folding |
+| `providerInputBudget` | from Pi's context window | The token budget folding works within |
+| `blacklistAutoFoldTools` | `new Set()` | Tools whose results should never be auto-folded |
+| `toolFoldThreshold` | `0.50` | Oldest share of the window where tool results are clipped in view (`0` turns it off) |
+| `preCommitNotice` | `false` | Tell the agent when a commit is approaching |
+| `noticeLeadShare` | `0.10` | How early that notice arrives |
+| `palette` | `{ map: "batlow", start: 0, end: 1 }` | Fold bar colours: `batlow`, `viridis`, `plasma`, `magma` or `cividis` |
 
 ## How it works
 
-### The cache invariant
+**Prefix caches are positional.** A provider replays the longest byte-identical prefix of a prompt, so changing one early byte invalidates everything after it. pi-fold only rewrites the window at a commit; everything else is a pure append.
 
-**A provider prefix cache is positional.** It replays the longest byte-identical prefix of the prompt, so one changed byte at offset K discards everything cached after K. The cost of a mutation has nothing to do with its size.
-
-**So the runtime may move a byte in the window only at a moment it is already rewriting the window**, which is a commit or a fold. Everything else is a pure append, and an appended byte is never later altered, shortened, removed or repositioned. Never mutate the window, and never show something and then take it back. The second half is the one that costs features: anything that displays state and then updates it in place is out, because updating in place is a mid-prefix write with better manners.
-
-### Marks and commits
+**Marks, then commits.** As each tool batch or chapter finishes, the runtime marks it as a fold candidate. A mark lives outside the window, so it changes nothing and costs nothing. When the window reaches `maxTarget`, a single commit folds the stalest marks into briefs until it's back down to `minTarget`, leaving recent work raw.
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/shaneconner/fold/main/media/marks-and-commits-dark.svg">
-  <img alt="A completed unit becomes a pending mark that leaves the window and its cached prefix untouched. Marks repeat for free below maxTarget; at maxTarget one commit applies every standing mark in a single rewrite. From the brief, peek appends the exact bytes and expand restores them in place, both after verifying the SHA-256." src="https://raw.githubusercontent.com/shaneconner/fold/main/media/marks-and-commits-light.svg">
+  <img alt="A completed unit becomes a pending mark that leaves the window and its cached prefix untouched. Marks repeat for free below maxTarget; at maxTarget one commit applies every standing mark in a single rewrite. From the brief, peek appends verified history without thinking blocks and expand restores the original messages in place." src="https://raw.githubusercontent.com/shaneconner/fold/main/media/marks-and-commits-light.svg">
 </picture>
 
-A mark moves nothing. The moment a tool batch or chapter closes, the runtime cuts it into a pending mark, up to eight cuts per pass, stalest first. The mark lives in durable state outside the window, so the projection stays byte-identical and the cached prefix survives. Marks accumulate for free until one commit applies all of them in a single rewrite.
-
-What the agent owns is the words. `brief` writes its own sentence onto a pending fold for free, because that brief reaches the window only when the commit writes the placeholder for the first time. A supplied brief is kept verbatim; an unbriefed fold commits with the deterministic brief the runtime writes from the span itself, and the provenance records which happened. Curation stays correctable until the commit: `reboundary` re-cuts a span, `unmark` withdraws a pending mark, and a pending brief can be rewritten any number of times at no cost. A standing fold's brief is never rewritten, because that rewrites the projection at its placeholder.
-
-### The band
-
-A commit fires on one condition: occupancy reaching `maxTarget` of the serving budget. It applies marks stalest first and stops at `minTarget`, so the newest events stay raw and a mark past the bound waits for the next epoch. Below `maxTarget` the window is quiet, because a commit is an epoch transition that risks the whole prefix cache and the right cadence is the fewest commits that keep the window inside its budget.
-
-```
-272,000  Pi's full context window
-255,616  default serving budget, after folding headroom
-─────────────────────────────────────────────────────
-~250k    peak: inflow continues while the epoch computes
-204,493  maxTarget 0.80   ← about 75% on Pi's scale
-   ⋮                        marks accumulate, free, quiet
- 51,123  minTarget 0.20   ← about 19% on Pi's scale
-─────────────────────────────────────────────────────
-```
-
-Every commit re-reads roughly `minTarget` of the budget uncached, so a shallower cut buys less runway for nearly the same bill: the rewrite tax is `minTarget / (maxTarget - minTarget)`, 0.33 at 0.80/0.20 against 1.0 at 0.80/0.40.
+**Peek and expand.** `peek` appends a verified, plain-text view of a fold's originals (without thinking blocks or provider metadata) for one turn, then steps aside. `expand` restores the original messages in place until the fold is refolded.
 
-### Peek and expand
-
-`peek` returns a fold's exact SHA-256-verified source as a tool result at any depth, with the ancestors still collapsed. It appends and never edits the prefix, so checking what a fold holds costs nothing a commit has to pay for. It takes `offset` and `bytes` for a bounded slice and reads any child fold by id, so a large fold has a narrow read.
-
-A peek is ephemeral by default: the bytes ride the window until the model's next message, then their place holds a one-line placeholder and the reply that used them is the surviving trace. Peeking again is lossless and costs one append. The default follows what the agent chose: on the run measured for it, six of seven peeks asked for ephemeral at first exposure. `expand` is the commitment, restoring the source in place until the fold is refolded. Looking is not the same as taking.
-
-### Clipping, pins and the compaction path
-
-Tool results get a second, lighter treatment at the same commit. Results in the oldest `toolFoldThreshold` share of the projected window, half of it by default, are clipped in view: the identifying head stays, the rest becomes a marker naming the entry id that peeks it back, and the stored bytes are untouched, so a later fold of that span still encodes the full result.
-
-Briefs are bounded at 2,000 characters each, so the visible index normally costs a low single-digit share of the window. Folds nest rather than partially overlap, and collapsed folds double as a browsable index: `status` with `detail: "tree"` lists every fold in transcript order with its depth and parent. `pin` holds entries raw through every fold and frees nothing, so pinned mass makes the rest of the window fold sooner; a pinned-share cap stops that from becoming a window nothing can reclaim.
-
-Pi's automatic compaction stays enabled underneath and is intercepted by kind. A threshold pass is cancelled, because the fold commit fires first. An overflow pass becomes an automated recovery: the session branches back to the last message before the error, and the retried pass folds and commits before transmitting. Manual `/compact` passes through untouched as the escape hatch.
-
-Evidence ingestion writes read-only artifacts under the session directory's `pi-fold-evidence/` at mode `0444`, under a 512 MB session cap. It is always on: the artifacts are what an oversized result folds against, so a deployment that stopped writing them would keep its folds and lose what makes them lossless.
+**Plays well with Pi.** Pi's own compaction stays enabled underneath. Threshold compaction is skipped because folding gets there first, overflow is recovered by folding and retrying, and manual `/compact` still works as an escape hatch.
 
 ## Prior work
 
-Two recent lines inform this one. Lossless hierarchical compaction, exemplified by LCM ([arXiv:2605.04050](https://arxiv.org/abs/2605.04050)) with a walkthrough at [losslesscontext.ai](https://www.losslesscontext.ai/), builds a summary DAG over older messages with lossless pointers to every original. Agentic context management, exemplified by [Letta](https://github.com/letta-ai/letta) and by [arXiv:2510.11967](https://arxiv.org/abs/2510.11967), gives the agent tools over its own memory. See also [arXiv:2607.00692](https://arxiv.org/abs/2607.00692).
-
-What this one adds is an efficiency result, arrived at by running the mechanism repeatedly and following the bill. Rotation is the part every approach here shares. The cost sits in where the rewrites land, because a prefix cache charges by position rather than by size, so each fold is staged as a mark that moves nothing and one commit spends the cache for all of them at once. The same campaigns settled the recommended shape: deterministic briefs paired with a durable memory store, which held recall at the lowest cost and wall clock measured. Agent control over boundaries and brief text stays available, and the invitation to use it ships off.
+pi-fold builds on lossless hierarchical compaction ([LCM, arXiv:2605.04050](https://arxiv.org/abs/2605.04050)) and agentic context management ([Letta](https://github.com/letta-ai/letta), [arXiv:2510.11967](https://arxiv.org/abs/2510.11967)); see also [arXiv:2607.00692](https://arxiv.org/abs/2607.00692). Its contribution is the cache-aware commit: stage every fold as a free mark, then pay for the rewrite once.

package/extensions/evidence.js

@@ -11,7 +11,12 @@ import {
 } from "node:fs/promises";
 import { dirname, isAbsolute, join } from "node:path";
 import { denseOwnArrayValues, evidenceValue, isPlainRecord, ownDataProperty, stableStringify } from "./json.ts";
-import { DEFAULT_ACTIVE_CONTEXT_ENTRY_TYPE_PREFIX, entryTypeNamespace } from "./lib/policy.ts";
+import { contextWindowFor } from "./lib/measurement.ts";
+import {
+  DEFAULT_ACTIVE_CONTEXT_ENTRY_TYPE_PREFIX,
+  entryTypeNamespace,
+  oversizedToolResultBytes,
+} from "./lib/policy.ts";
 
 export const EVIDENCE_REFERENCE_VERSION = 1;
 export const TOOL_RESULT_PROJECTION_BYTES = 16 * 1024;
@@ -641,6 +646,22 @@ export function registerEvidenceIngestion(pi, {
         mcpServer: mcpServerForTool(toolName, evidenceNamespace),
       });
     }
+
+    // Any other tool: raw unless the one result would crowd the window by itself.
+    if (utf8Bytes(text) > oversizedToolResultBytes(contextWindowFor(ctx))) {
+      const descriptor = await writeEvidenceArtifact({
+        sessionFile,
+        ownerKind: "pi-session",
+        ownerId: sessionId,
+        bytes: Buffer.from(text, "utf8"),
+        mediaType: "text/plain",
+        encoding: "utf-8",
+        source: { toolName, toolCallId, artifactKind: "oversized-tool-result" },
+        evidenceDirectory,
+      });
+      const truncation = boundedTruncation(ownDataProperty(details, "truncation"));
+      return projectEvidenceText(text, descriptor, "utf8-head", truncation ? { truncation } : undefined);
+    }
   });
 }
 

package/extensions/lib/folding.ts

@@ -1427,14 +1427,23 @@ export function peekFoldSource(input: {
 }): Record<string, unknown> {
   const fold = input.state.folds.find((item) => item.id === input.foldId);
   if (!fold) throw new Error(`Unknown active-context fold ${input.foldId}`);
-  const messages = foldStoredSpan({
+  const storedMessages = foldStoredSpan({
     foldId: input.foldId,
     state: input.state,
     entries: input.entries,
     sessionId: input.sessionId,
     projectEntry: input.projectEntry,
   });
-  const source = stableStringify(messages);
+  // Verify the ORIGINAL messages first, then build the history read: plain text,
+  // not the stored message JSON (issues #10 and #12). A JSON array of assistant
+  // messages carrying model, provider, usage and response ids reads like exported
+  // model output, and native reasoning with its opaque signatures belongs to the
+  // provider's protocol, not to an ordinary tool result. The text keeps every
+  // visible word, tool call and tool result; stored refs, hashes and expand are intact.
+  const rendered = renderHistoryText(storedMessages);
+  const { omittedThinkingBlocks } = rendered;
+  const messages = storedMessages;
+  const source = rendered.text;
   const sourceBytes = bytes(source);
   const offset = Math.min(Math.max(0, input.offset ?? 0), sourceBytes);
   // The widest read anyone may ask for is the policy's own source cap, the same ceiling
@@ -1475,6 +1484,8 @@ export function peekFoldSource(input: {
     brief: foldBrief(fold, input.state),
     sourceCount: messages.length,
     sourceSha256: fold.sourceSha256,
+    sourceFormat: PEEK_SOURCE_FORMAT,
+    omittedThinkingBlocks,
     sourceBytes,
     offset,
     returnedBytes,
@@ -1493,16 +1504,20 @@ export function peekFoldSource(input: {
       ? { wider: { action: "peek", id: fold.id, bytes: Math.min(sourceBytes, ACTIVE_CONTEXT_POLICY.maxSourceChars) } }
       : {}),
     lifetime: "these bytes stay in the window exactly as returned, like any other tool result, and " +
-      `nothing rewrites this result in place. It is a COPY of fold ${fold.id}'s stored source, so the ` +
+      `nothing rewrites this result in place. It is a COPY of fold ${fold.id}'s source view, so the ` +
       `next commit reclaims it behind a placeholder naming ${fold.id}; peek ${fold.id} again for the ` +
       "same verbatim bytes, or pin this result to keep the copy raw.",
     note: (truncated
-      ? `Bounded read: ${returnedBytes} of ${sourceBytes} exact source bytes, ${view.omittedBytes} omitted ` +
+      ? `Bounded read: ${returnedBytes} of ${sourceBytes} history-text bytes, ${view.omittedBytes} omitted ` +
         `from the middle. Widen with bytes, page with offset, or expand ${fold.id} to restore it in place.`
       : children.length
-        ? `Complete stored span, one level: raw entries exactly, and ${children.length} child fold(s) still ` +
+        ? `Complete stored span, one level: raw entries as plain text, and ${children.length} child fold(s) still ` +
           "placeheld. Peek a child id to read its own span; the fold stayed collapsed and no projection changed."
-        : "Complete exact source; the fold stayed collapsed and no projection changed.") +
+        : "Complete history text; the fold stayed collapsed and no projection changed.") +
+      (omittedThinkingBlocks
+        ? ` ${omittedThinkingBlocks} thinking blocks omitted from this read, including their opaque ` +
+          "signatures. The original messages remain unchanged for exact in-place restoration."
+        : "") +
       (catalog.omitted
         ? ` The nested index seats the shallowest ${index.length} of ${index.length + catalog.omitted} ` +
           "descendant briefs inside the byte budget; the deeper rows are one hop away by peeking a child id, " +
@@ -1523,6 +1538,90 @@ export function peekFoldSource(input: {
   };
 }
 
+export const PEEK_SOURCE_FORMAT = "history-text";
+
+// Provider bookkeeping a history read never needs. It is what makes a message array
+// look like an exported model transcript, and none of it is work content.
+const HISTORY_METADATA_KEYS = new Set([
+  "role", "content", "provider", "model", "api", "usage", "responseId", "stopReason",
+  "timestamp", "toolCallId", "toolName", "isError",
+]);
+
+function historyBlock(block: unknown, counter: { thinking: number }): string | null {
+  if (typeof block === "string") return block;
+  const type = ownValue(block, "type");
+  if (type === "thinking" || type === "redacted_thinking") { counter.thinking += 1; return null; }
+  if (type === "text") {
+    const text = ownValue(block, "text");
+    return typeof text === "string" ? text : "";
+  }
+  if (type === "toolCall") {
+    const name = ownValue(block, "name");
+    const id = ownValue(block, "id");
+    const args = ownValue(block, "arguments");
+    return `[tool call: ${typeof name === "string" ? name : "unknown"}` +
+      `${typeof id === "string" ? ` (${id})` : ""}]\n` +
+      (args === undefined ? "" : stableStringify(args));
+  }
+  if (type === "image") {
+    const mime = ownValue(block, "mimeType");
+    return `[image${typeof mime === "string" ? `: ${mime}` : ""}; expand restores it]`;
+  }
+  return stableStringify(block);
+}
+
+function historyContent(content: unknown, counter: { thinking: number }): string {
+  if (content === undefined || content === null) return "";
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return stableStringify(content);
+  return content.map((block) => historyBlock(block, counter))
+    .filter((part): part is string => part !== null)
+    .join("\n\n");
+}
+
+// The peek view of a stored span: one labelled section per message, each holding the
+// visible text, tool calls with their arguments, and tool results verbatim. Thinking
+// blocks and provider metadata are left out; nested fold placeholders read as a line
+// with their brief and the id that peeks them. Deterministic, so offset paging is stable.
+export function renderHistoryText(messages: readonly unknown[]): {
+  text: string;
+  omittedThinkingBlocks: number;
+} {
+  const counter = { thinking: 0 };
+  const sections = messages.map((message) => {
+    if (!isPlainRecord(message)) return `### entry\n${stableStringify(message)}`;
+    if (ownValue(message, "placeholder") === "fold") {
+      const id = String(ownValue(message, "id"));
+      const children = Number(ownValue(message, "children") ?? 0);
+      return `### folded ${String(ownValue(message, "kind"))} ${id}` +
+        `${children ? `, ${children} child fold(s)` : ""}\n` +
+        `${String(ownValue(message, "brief") ?? "")}\n` +
+        `(peek it with {"action":"peek","id":"${id}"})`;
+    }
+    const role = messageRole(message) ?? "entry";
+    let header: string;
+    if (role === "toolResult") {
+      const name = ownValue(message, "toolName");
+      const id = ownValue(message, "toolCallId");
+      header = `### tool result: ${typeof name === "string" ? name : "unknown"}` +
+        `${typeof id === "string" ? ` (${id})` : ""}` +
+        `${ownValue(message, "isError") === true ? " [error]" : ""}`;
+    } else {
+      header = `### ${role}`;
+    }
+    const body = historyContent(ownValue(message, "content"), counter);
+    // Any other own field (a bash command, a summary, an error message) is content the
+    // reader may need; only the bookkeeping above is dropped.
+    const extras = Object.keys(message).filter((key) => !HISTORY_METADATA_KEYS.has(key))
+      .sort().map((key) => {
+        const value = (message as Record<string, unknown>)[key];
+        return `${key}: ${typeof value === "string" ? value : stableStringify(value)}`;
+      });
+    return [header, ...extras, ...(body ? [body] : [])].join("\n");
+  });
+  return { text: sections.join("\n\n"), omittedThinkingBlocks: counter.thinking };
+}
+
 export function headTailMarker(omittedBytes: number): string {
   return omittedBytes > 0 ? `\n... [${omittedBytes} exact source bytes omitted] ...\n` : "";
 }

package/extensions/lib/policy.ts

@@ -302,6 +302,28 @@ export const ESTIMATED_BYTES_PER_TOKEN = 4;
 export const IMAGE_ESTIMATED_TOKENS = 1_600;
 export const ESTIMATED_PLACEHOLDER_OVERHEAD_BYTES = 240;
 
+/**
+ * ONE TOOL RESULT MAY NOT FILL THE WINDOW BY ITSELF (issue #13, 2026-10-26).
+ *
+ * Folding rewrites the old end of the window and leaves the fresh end alone, so a single
+ * fresh tool result larger than the serving budget is out of its reach: the provider
+ * rejects the request, the rollback retries it with the same result inside, and every
+ * later prompt carries it again. The images in issue #13 are priced flat now, but the
+ * same megabyte returned as text by any tool other than read, bash or MCP still wedged
+ * the session. Above this share of the window a result is pinned as exact evidence and
+ * the window gets its head and a reference to the artifact, the way an oversized read
+ * already does. A share rather than a byte count, so a small window is protected
+ * without clipping results that a large one holds comfortably.
+ */
+export const OVERSIZED_TOOL_RESULT_WINDOW_SHARE = 0.25;
+
+export function oversizedToolResultBytes(window: number | null | undefined): number {
+  const resolved = typeof window === "number" && Number.isFinite(window) && window > 0
+    ? window
+    : DEFAULT_CONTEXT_WINDOW;
+  return Math.floor(resolved * OVERSIZED_TOOL_RESULT_WINDOW_SHARE) * ESTIMATED_BYTES_PER_TOKEN;
+}
+
 export const PEEK_MIN_SLICE_BYTES = 1_024;
 
 export const STATUS_DIET_INDEX_ROWS = 5;

package/extensions/lib/tool-surface.ts

@@ -29,7 +29,7 @@ export function buildActiveContextTool(input: {
   handler: ToolHandler;
 }) {
   const peekGuidance = input.allowedActions.includes("peek")
-    ? ` Peek is the point read: it returns one fold's index view -- nested folds' briefs seated shallowest first inside the byte budget with the omitted rows counted, plus the head and tail of that fold's own span with the omitted middle stated -- for any fold id, ancestors still collapsed, changing nothing. It serves ONE level: raw entries come back exactly, folds nested inside stay placeheld, and peeking a child id you see there returns that child's own bytes, so anything folded is one hop away at any depth. It returns at most ${input.defaultPeekBytes} bytes unless you widen it with bytes, and it is EPHEMERAL by default: the bytes ride only until your next message, your reply then the surviving trace, so extract what your current task needs from them in that reply. Peeking again is lossless and costs one append, so a read you turn out to need twice is cheap; pass ephemeral false when you need the bytes standing across several turns. Expand is the durable in-place restoration.`
+    ? ` Peek is the point read: it returns one fold's index view -- nested folds' briefs seated shallowest first inside the byte budget with the omitted rows counted, plus the head and tail of that fold's own span with the omitted middle stated -- for any fold id, ancestors still collapsed, changing nothing. It serves ONE level: raw entries come back as plain-text history -- visible text, tool calls with their arguments and tool results verbatim, with thinking blocks and provider metadata left out -- folds nested inside stay placeheld, and peeking a child id you see there returns that child's own bytes, so anything folded is one hop away at any depth. It returns at most ${input.defaultPeekBytes} bytes unless you widen it with bytes, and it is EPHEMERAL by default: the bytes ride only until your next message, your reply then the surviving trace, so extract what your current task needs from them in that reply. Peeking again is lossless and costs one append, so a read you turn out to need twice is cheap; pass ephemeral false when you need the bytes standing across several turns. Expand is the durable in-place restoration.`
     : "";
   const correctionGuidance = input.allowedActions.includes("reboundary")
     ? " Curation is correctable: reboundary with ids re-cuts a span into exactly one fold, which merges adjacent folds when the span covers several and splits one when the span sits inside it. Reboundary with a single id returns that fold's span to raw. A brief is written when you mark the span; a standing fold's brief is not rewritten, because rewriting it rewrites the projection at that fold's placeholder and costs the whole prefix cache from there on."
@@ -80,7 +80,7 @@ export function buildActiveContextTool(input: {
         bytes: {
           type: "integer",
           minimum: input.minPeekSliceBytes,
-          description: `Peek only: bytes of exact source to return, widening or narrowing the ${input.defaultPeekBytes}-byte default.`,
+          description: `Peek only: bytes of the plain-text history view to return, widening or narrowing the ${input.defaultPeekBytes}-byte default.`,
         },
         limit: { type: "integer", minimum: 1, maximum: 100 },
         detail: { type: "string", enum: [...input.statusDetails] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-fold",
-  "version": "4.2.7",
+  "version": "4.3.0",
   "description": "Lossless context folding for the Pi coding agent: only the oldest context changes; the fresh window stays untouched.",
   "keywords": [
     "pi-package",