pi-zip 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-zip contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,140 @@
-# Temporary Holding Version
+# pi-zip
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Keeps long [Pi](https://github.com/earendil-works/pi) sessions cheap without losing anything.
+
+pi-zip folds old tool output out of the context **only when the prompt cache has already gone cold**, so the edit costs nothing extra, and every folded output can be fetched back byte for byte. No configuration, no proxy process, no footer.
+
+## Install
+
+```bash
+pi install npm:pi-zip
+# or
+pi install git:github.com/purboo/pi-zip
+```
+
+Try it for one run without installing: `pi -e npm:pi-zip`.
+
+## Measured results (v0.2.0)
+
+Live A/B runs on the same coding tasks (4 task templates × 4 seeds, the user away 6 minutes between prompts), paired by task, 95% bootstrap intervals. BC = [billion-context](https://github.com/ranxianglei/billion-context) with its defaults.
+
+| Model | Cost vs BC | Speed | Quality (task done / planted facts recalled) |
+|---|---|---|---|
+| Claude Sonnet 5.5 | **0.79×** [0.72, 0.86] | p90 wait per prompt 53 s vs 85 s; same as plain Pi | 16/16 and 1.00, same as BC |
+| GPT-6.1-sol (14 tasks so far) | 1.00× [0.91, 1.09] | median task 197 s vs 293 s | 14/14 and 1.00 vs 13/14 and 0.96 |
+
+Against plain Pi on the same Claude runs: same speed, 0.45× the cost. Hidden-question probes on real long sessions (questions whose answer had been folded): 45–52% answered from the original via `zip_recall` vs 5% for BC's reconstruction, same number of wrong answers.
+
+Known limits:
+
+- **GLM** (automatic prefix cache that outlives its declared 5 minutes): v0.1 cost about 1.2× BC live. v0.2 learns the real cache lifetime and folds the previous turn after the declared TTL (offline 0.95–0.97× v0.1), but this was not verified live.
+- **Long autonomous runs** (one prompt, hundreds of tool calls, e.g. sub-agents): roughly on par with BC, not better. Outputs are only folded inside a running turn once they are 60 requests old.
+- If you always answer within the cache lifetime, there is little to save, by design.
+
+## What you see
+
+At most one line per turn, only when something was folded:
+
+```
+pi-zip · folded 12 old outputs · 84.2K → 31.5K tokens · 0.9 ms · originals recallable
+pi-zip · summarized 64 requests · 182K → 41K tokens · 8.4 s (done while you were away)
+```
+
+The line goes to the UI only; it never enters the model's context. Nothing else is added to the screen.
+
+## The three rules
+
+1. **Nothing is lost.** The session file stays the single source of truth. pi-zip only changes the view sent to the model, never deletes anything. User messages, tool-call arguments, the system prompt, tool definitions and thinking are never rewritten. Every folded block carries a handle and shows its key lines (errors, ids, first and last line).
+2. **Edit only when the cache is already gone.** Provider prompt caches expire (the model's declared TTL, usually minutes). Changing the context while the cache is warm means paying to rewrite it; changing it after it expired is free, because the whole context is rewritten anyway, and a smaller context makes that rewrite cheaper. So when you come back after the TTL (or after switching model, or when the session was last touched longer ago than the TTL), pi-zip folds old outputs down to about 40K real tokens in one step, and every request of that turn sends the same bytes. While the cache is warm it does nothing, with one exception, the warm valve: above the 40K target it applies that plan, minus the previous user turn (a warm edit never folds the turn you just finished, except when you come back after the declared TTL: there the previous turn is eligible exactly as at a cold return, so a provider whose cache outlives its TTL does not keep it at every return), when the edit pays for the rewrite it causes, and never on the request right after an edited one (no back-to-back warm rewrites). That is one inequality, r Δ²/(2g) + η Δ ≥ K with K = (w − r)(P T − (1 − P) Δ): the reads the removed Δ tokens would cost while the context grows back at g tokens per request (measured in the session), plus, near Pi's compaction trigger, what Pi would charge for the same room (η), against the rewrite of the T = A tokens left after the edit (pricing only the suffix after the earliest edit fires warm edits earlier and lost quality in the offline evaluation; the suffix is logged as `Tsuf` for measurement). r and w are the read and rewrite price ratios of the cache class, never the model's price table: explicit write premium 0.1 / 1.25 x input (2 x on the 1-hour tier), automatic prefix cache 0.2 / 1 x input; the class is read from the provider's usage reports, and until the first response the old fixed rule applies. P is the probability that the cache is still warm. A cold return is P = 0, so K < 0 and it always fires; a single small fold never pays at a warm cache, a large one does.
+3. **Never in the way.** Planning is local and takes milliseconds. Anything that needs a model call (a summary, only when folding is not enough and the same inequality prices the extra model call in) is prepared while you are away: if the cache is about to expire (0.8 x its lifetime after your last request) and you have not come back, a background timer writes the summary with a separate, uncached call. The timer is cancelled the moment you send a prompt. If you return before the summary finishes, only the remaining time is waited, Esc stops the waiting, and the notice says so. If you return while the cache is still warm and the valve does not fire, the prepared summary is discarded (its cost is still counted). In non-interactive modes (`-p`, `--mode json`) nothing is ever started in the background: a cold return that needs a summary computes it right then.
+
+**The cache lifetime is learned, not configured.** Every response says how much of the prompt came from the cache. pi-zip compares that read with what the request re-sent unchanged (the previous prompt, or the untouched prefix before one of its own edits: on an automatic prefix cache every edit leaves the first 8K tokens alone, so even the response right after a fold says whether the cache survived) and so learns, per provider and model, whether the cache survived a gap of that length: a few counts per gap bin (30 s to 90 min, with bin edges on the 5-minute and 1-hour tiers), monotone in the gap, older evidence halved after 16 newer observations of the same bin, stored without any content in `~/.pi/agent/pi-zip/cache-survival.json`. Before any evidence the model's declared TTL decides, exactly as before (300 s when it declares none; too short a guess is cheaper than too long); beyond it one clean read overrides it, inside it a lone miss counts as noise (warm caches do miss now and then) and only repeated misses do. A GLM cache read in full after 365 s makes the next 365 s return warm; a Claude 5-minute cache that read nothing after 360 s stays dead. Whether the provider bills cache writes (explicit cache) or not (automatic prefix cache) is read from the first response too. `/zip status` shows the class, its price ratios, and the learned survival per bin with its sample count.
+
+Protected from folding: the current user turn and the previous one. When the context is above the target, re-readable outputs of the previous turn (an unchanged file, a read-only command) can still be folded at a cold return or at any return after the declared TTL (never on a warm request inside it), and any output in either turn can be folded once it is 60 assistant requests old (so a long agent run that is a single user turn with hundreds of tool calls is not exempt from folding; the newest 59 requests' outputs always stay, and every fold stays recallable). Messages you type while the agent is running (steering, follow-up) belong to that turn and do not start a new one. Outputs you have already recalled, and `zip_recall` results themselves, are never folded again. "Read-only" is a conservative whitelist: `find -delete` or `-exec`, command substitution, redirects, background jobs, `git diff --output` and the like are not.
+
+**Token counts are calibrated, not guessed.** Sizes are estimated as chars/4, which undercounts real tokens (typically by about 1.7x in coding sessions). So the cold cap, the compaction room and the law's token counts are all compared against `k` x the estimate, where `k` = real tokens / estimated tokens for the newest assistant message that reports usage (input + cache read + cache write, over the estimate of the context that request carried; clamped to 1 to 2.5). `k` is read from the session itself on every decision, so a restart, `pi -p` or a resumed session calibrates exactly like a long-lived one, and nothing extra is stored. With no usage to read (a brand-new session, or a provider that reports none) `k` is 1.7. Sizes in the notices, `/zip stats` and the ledger use the same scale.
+
+The cold cap is kept below Pi's own compaction trigger (window minus `compaction.reserveTokens`), so on small windows Pi's lossy compaction does not get there first.
+
+## Commands
+
+| Command | Effect |
+|---|---|
+| `/zip status` | on / off / paused, cache TTL, totals |
+| `/zip stats` | tokens folded, estimated $ saved versus doing nothing, summaries, recalls |
+| `/zip off` | strict no-op: no folds, no summaries, requests left untouched (earlier folds stay recallable) |
+| `/zip on` | resume |
+| `/zip quiet` | toggle the per-turn notice (folding continues) |
+
+`off` and `quiet` are remembered per session.
+
+## Recall
+
+A folded block says what produced it (tool, command or path with offset/limit, user turn, exit status and test counts for commands), its size, a handle and its key lines, so look-alike runs stay apart. It also tells the model to prefer `zip_recall` (original bytes, instant, free, no side effects) over re-running or re-reading, because a re-run may give a different result:
+
+```
+[folded by pi-zip · bash bun test test/api.test.ts · turn 12 · exit 1, 79 passed, 2 failed · 5637 chars, 109 lines · handle k3f9a0x1qz]
+key lines kept (original line numbers; up to 8):
+1: (pass) suite 0 > case parse config ...
+106: 2 fail
+109: Command exited with code 1
+Original kept byte for byte, recallable even after summaries or compaction: zip_recall("k3f9a0x1qz") (optional grep/range) is instant, free, no side effects; prefer it to re-running or re-reading (output may differ). Do not guess its content.
+```
+
+Placeholders are written once, when the fold is saved: sessions folded by an earlier version keep their old placeholder text unchanged. Summaries list each folded output with its handle, turn and outcome in the same way. A summary of an earlier summary merges it section by section (requests, files, commands, other calls, errors, handle table, handle index) instead of clipping its text: items are deduplicated, the oldest are dropped first under a per-section budget with a count of what was left out, and the previous narrative survives as a short tail excerpt. Pi's own free-text compaction summaries are carried as a head-and-tail excerpt.
+
+The model recalls by itself when it needs the content:
+
+```
+zip_recall({ handles: ["k3f9a0x1qz", "m2b7c4d8ww"] })
+zip_recall({ handle: "k3f9a0x1qz", grep: "ERROR|FAIL" })
+zip_recall({ handle: "k3f9a0x1qz", range: "120-240" })
+```
+
+Recall is batched, exact, and also works for outputs from before a compaction or a pi-zip summary (summaries carry a handle table and a budgeted index of older handles). Output comes back in pages of 20,000 characters; the page says how to continue:
+
+```
+zip_recall({ handle: "k3f9a0x1qz", offset: 20000 })               // next page, by characters
+zip_recall({ handle: "k3f9a0x1qz", offset: 20000, limit: 50000 }) // up to 50,000 characters per page
+```
+
+Paging is by characters, so even one 45,000-character line can be read in full, and the pages add up to the original byte for byte. `offset` and `limit` also page a `grep` or `range` selection. `grep` is a case-insensitive regular expression; patterns that could backtrack badly (nested quantifiers, quantified alternation, back-references, very long patterns) are searched as literal text instead.
+
+## Coexistence
+
+If another extension that manages context is loaded (for example billion-context, magic-context, pi-smart-compact, pi-hot-compact, pi-context-prune), pi-zip pauses folding, says so once, and keeps only its request guard. Two writers on the same view give unpredictable results. `/zip status` shows `paused`.
+
+The guard has two parts. Before saving a fold or a summary it checks that the edit itself would not leave a tool result without its tool call (failed or aborted assistant turns, which the provider layer drops anyway, are ignored, as is any oddity the session already had). And before a request is sent it repairs a tool result that lost its tool call, instead of letting the provider reject the request and brick the session. The repair understands the request shapes of Pi's Anthropic, OpenAI chat completions (and Mistral), OpenAI Responses (Azure, Codex), Google Gemini/Vertex and Bedrock Converse providers; a request of any other shape is passed through untouched.
+
+## FAQ
+
+**Will it save money?** Mostly on cold returns, which is where a long session pays for a full cache rewrite. While the cache is warm it edits only when the inequality above says the rewrite pays back (large contexts, near Pi's compaction trigger, outputs 60+ requests old). `/zip stats` shows an estimate based on the model's declared prices: avoided cache writes and reads, minus summary calls, minus the cost of content you recalled. It is an estimate (token counts are chars/4, scaled by the calibration above), and it can be negative.
+
+**Does it cost extra?** Planning is free. A summary is one extra model call (the current model, no tools, no prompt cache), shown in `/zip stats`. A background summary you never use (you came back while the cache was warm) is counted too. Recalled content re-enters the context at normal prices.
+
+**Can the model lose information?** Folded outputs are replaced by a placeholder with key lines and a handle, and the placeholder tells the model not to guess. Summaries quote your requests verbatim and never paraphrase the model's reasoning. If the model ignores the handle and guesses, that is a model failure pi-zip cannot catch; this is why only re-readable outputs of the previous turn are folded at a cold return; other outputs of the protected turns wait until they are 60 requests old.
+
+**Does it work with `/tree`, fork, resume and model switches?** Yes. Folds are ordinary `context_edit` entries, projected per branch by Pi; the originals stay in the session file.
+
+**Which providers?** Anything Pi supports. The cache TTL comes from the model's `promptCache` declaration (seconds) for the tier Pi uses (`short`, or `long` when `PI_CACHE_RETENTION=long`), falling back to 5 minutes. Pi's own idle cache refreshes count as a cache touch, and a different provider or model than the last request counts as cold. Providers that do not report cache usage still work; the stats are then estimates only.
+
+Some relays rewrite `cache_control`, so the TTL actually written can differ from the one requested. pi-zip checks `usage.cacheWrite1h` (reported by the Anthropic messages API and Bedrock) on the newest few assistant messages of the current model: if you requested 1h but the provider wrote 5m, it uses the 5m TTL (and the reverse, when the model declares a 1h tier), and says so once per session unless `/zip quiet` is on. Without that field it keeps the declared TTL. `PI_ZIP_TTL_SECS` still wins.
+
+Some relays reject `PI_CACHE_RETENTION=long` with 400 `a ttl='1h' cache_control block must not come after a ttl='5m' cache_control block`, because they inject their own 5m `cache_control`. That is a provider issue: unset the variable.
+
+## Testing
+
+```bash
+bun test                                                                   # unit + invariant tests + integration with Pi itself
+bun run build-check                                                        # bundles src/index.ts with Pi's packages external
+```
+
+`test/pi-integration.test.ts` runs the extension through Pi's real session manager, extension loader and `emitContext`, with a mid-conversation system update and an aborted tool-call turn in the session, and checks that the request is byte-identical before and after turn_end persists the edits.
+
+Environment overrides exist for tests only and are not part of the product surface: `PI_ZIP_TTL_SECS` (cache TTL), `PI_ZIP_COLD_CAP` (fold target in tokens, default 40000), `PI_ZIP_FOLD_MIN` (smallest output worth folding, default 500 tokens), `PI_ZIP_KEEP_LINES`, `PI_ZIP_MIN_GAIN` (summary gain floor of the legacy rule used only when nothing is known about prices, default 10000), `PI_ZIP_INTURN_AGE` (age in assistant requests from which any output of the protected turns may fold, default 60; 0 = never), `PI_ZIP_CACHE_STATS=<path>` (where the learned cache survival lives; benches isolate it), `PI_ZIP_OFF=1` (register nothing), `PI_ZIP_LEDGER=<path>` (append a JSON line per decision; `prompt` records `ttlMs` and `ttlSource`, `declared` or `observed`; including the summary call's token usage; `cold_plan` records the calibration as `k`, `calReal`, `calEst`, `calSource`, next to the scaled `ctxBefore` and `ctxAfter`; `prompt` also records `gapS`, `pWarm`, `survSrc` and `cls`; `law` records every evaluation with `g`, `wr` (w/r), `pWarm`, `survSrc`, `prSrc` and per step `B`, `A`, `T` (= A), `Tsuf` (the suffix after the earliest edit, measurement only), `phi`, `K`, `eta`; `b2b_skip` marks a warm edit skipped right after an edited request; `cache_sample` records each learned survival observation).
+
+Internally, `RELAX_PREV_TURN` in `src/plan.ts` selects whether re-readable outputs of the previous user turn may be folded on a cold return or a return after the declared TTL (default `true`; other warm plans never fold them).
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "pi-zip",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Keeps long Pi sessions cheap without losing anything: folds old tool output only when the prompt cache has already gone cold, and every fold can be recalled byte for byte. Zero config.",
+  "type": "module",
+  "license": "MIT",
+  "author": "purboo",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/purboo/pi-zip.git"
+  },
+  "homepage": "https://github.com/purboo/pi-zip#readme",
+  "bugs": {
+    "url": "https://github.com/purboo/pi-zip/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "context",
+    "cache",
+    "compaction"
+  ],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "bun test",
+    "build-check": "bun build src/index.ts --target=node --external '@earendil-works/*' --outfile /dev/null"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  }
+}

package/src/cache.ts

@@ -0,0 +1,116 @@
+// Cache temperature (F7): "cold" is a fact about real time, never a guess.
+import { type Any, PRODUCT, envInt } from "./util.ts";
+
+export const DEFAULT_TTL_MS = 300_000;
+
+export type CacheRetention = "none" | "short" | "long";
+
+/**
+ * Lifetime of the prompt cache entry a request writes, mirroring Pi's getPromptCacheTtlMs (core/cache-warmer.js): the tier is the
+ * request's cacheRetention, else "long" when PI_CACHE_RETENTION=long, else "short"; the model's promptCache holds SECONDS for
+ * that tier only. Pi sends no explicit cacheRetention, so in practice the environment decides. "none" = no cache at all = 0.
+ * A model that declares no lifetime for the tier gets fallbackMs. An explicit PI_ZIP_TTL_SECS (tests) wins in ttlFor.
+ */
+export function cacheTtlMs(
+	pc: { short?: number; long?: number } | undefined,
+	fallbackMs: number = DEFAULT_TTL_MS,
+	opts: { cacheRetention?: CacheRetention; env?: Record<string, string | undefined> } = {},
+): number {
+	const env = opts.env ?? process.env;
+	const retention: CacheRetention = opts.cacheRetention ?? (env.PI_CACHE_RETENTION === "long" ? "long" : "short");
+	if (retention === "none") return 0;
+	const secs = pc?.[retention];
+	return typeof secs === "number" && secs > 0 ? secs * 1000 : fallbackMs;
+}
+
+/**
+ * TTL tier the provider really wrote, from the newest <=3 usable assistant messages of this model (real run, cacheWrite >= MIN_WRITE):
+ * `usage.cacheWrite1h` (Anthropic, Bedrock) is the 1h share of `cacheWrite`. >= 50% -> "1h", ~0 -> "5m". The field absent (the API
+ * does not report it) or a split in between = no evidence (undefined): the declared TTL stands. Relays may rewrite cache_control.
+ */
+const MIN_WRITE = 1024;
+export function observedTier(branch: Any[], key: string): "1h" | "5m" | undefined {
+	let w = 0, w1h = 0, seen = 0;
+	for (let i = branch.length - 1; i >= 0 && seen < 3; i--) {
+		const m = branch[i]?.type === "message" ? branch[i].message : null;
+		if (m?.role !== "assistant" || m.stopReason === "error" || m.stopReason === "aborted" || `${m.provider}/${m.model ?? ""}` !== key) continue;
+		const u = m.usage;
+		if (!(u?.cacheWrite >= MIN_WRITE)) continue;
+		seen++;
+		if (typeof u.cacheWrite1h === "number") (w += u.cacheWrite), (w1h += u.cacheWrite1h);
+	}
+	return !w ? undefined : w1h >= w / 2 ? "1h" : w1h < w * 0.05 ? "5m" : undefined;
+}
+
+export interface TtlInfo { ms: number; source: "declared" | "observed"; note?: string }
+
+/** Declared TTL, corrected by what the provider was seen to write. PI_ZIP_TTL_SECS wins. `note` = the one-time mismatch notice text. */
+export function resolveTtl(model: Any, branch: Any[] = []): TtlInfo {
+	if (process.env.PI_ZIP_TTL_SECS) return { ms: envInt("TTL_SECS", 300) * 1000, source: "declared" };
+	const pc = model?.promptCache;
+	const declared = cacheTtlMs(pc);
+	const long = process.env.PI_CACHE_RETENTION === "long";
+	const seen = declared > 0 ? observedTier(branch, modelKey(model)) : undefined;
+	const mismatch = (req: string, got: string, ms: number): TtlInfo => ({ ms, source: "observed", note: `${PRODUCT} · requested ${req} prompt cache, provider wrote ${got} · using ${got}` });
+	if (long && seen === "5m") return mismatch("1h", "5m", cacheTtlMs(pc, DEFAULT_TTL_MS, { cacheRetention: "short" }));
+	if (!long && seen === "1h" && pc?.long > 0) return mismatch("5m", "1h", pc.long * 1000);
+	return { ms: declared, source: "declared" };
+}
+
+export const ttlFor = (model: Any, branch: Any[] = []): number => resolveTtl(model, branch).ms;
+
+/** Cold = a prior request exists and nothing touched the cache for longer than the TTL. No prior request counts as warm. */
+export const isColdByTtl = (lastActivityMs: number, nowMs: number, ttlMs: number): boolean => lastActivityMs > 0 && nowMs - lastActivityMs > ttlMs;
+
+export const modelKey = (m: Any): string => (m ? `${m.provider ?? ""}/${m.id ?? m.model ?? ""}` : "");
+
+const tsOf = (en: Any, inner?: Any): number => {
+	const t = typeof inner?.timestamp === "number" ? inner.timestamp : Date.parse(en?.timestamp ?? "");
+	return Number.isFinite(t) ? t : 0;
+};
+
+/**
+ * Last time anything touched the cache, according to the branch: the newest message, or the newest cache-warm usage entry
+ * (Pi's own idle refresh persists `{ type: "usage", kind: "cache_warm" }`, and a refresh keeps the entry alive for another TTL).
+ * Fresh process: err on the warm side (0 = unknown).
+ */
+export function lastMessageMs(branch: Any[]): number {
+	let last = 0;
+	for (const en of branch) {
+		if (en?.type === "message" && en.message) last = Math.max(last, tsOf(en, en.message));
+		else if (en?.type === "usage" && en.kind === "cache_warm") last = Math.max(last, tsOf(en));
+	}
+	return last;
+}
+
+/** The newest assistant message that really ran (errors and aborts may never have reached a cache): its provider/model and prompt size. */
+export function lastPrompt(branch: Any[]): { key: string; total: number } {
+	for (let i = branch.length - 1; i >= 0; i--) {
+		const m = branch[i]?.type === "message" ? branch[i].message : null;
+		if (m?.role === "assistant" && m.stopReason !== "error" && m.stopReason !== "aborted" && m.provider) {
+			const u = m.usage;
+			return { key: `${m.provider}/${m.model ?? ""}`, total: u ? (u.input ?? 0) + (u.cacheRead ?? 0) + (u.cacheWrite ?? 0) : 0 };
+		}
+	}
+	return { key: "", total: 0 };
+}
+export const lastModelInBranch = (branch: Any[]): string => lastPrompt(branch).key;
+
+export type Survival = (gapS: number, priorS: number) => { p: number; src: string };
+/** pastTtl: the idle gap exceeds the declared TTL (the shipped rule's "cold"), whatever the learned P(warm) says. */
+export interface ColdInfo { cold: boolean; reason: string; ttl: TtlInfo; pWarm: number; src: string; gapS: number | null; pastTtl: boolean }
+
+/** Cold by time, or because the model changed: a cache entry belongs to one provider and model. `learned` = P(warm) after a gap from the
+ *  survival the provider was seen to have (learn.ts); without it, or under PI_ZIP_TTL_SECS (tests), the TTL decides. cold = P(warm) < 0.5. */
+export function detectCold(model: Any, lastReqMs: number, branch: Any[], nowMs = Date.now(), lastModel = "", learned?: Survival): ColdInfo {
+	const ttl = resolveTtl(model, branch);
+	const last = Math.max(lastReqMs, lastMessageMs(branch));
+	const prev = lastModel || lastModelInBranch(branch);
+	if (last && prev && modelKey(model) && prev !== modelKey(model)) return { cold: true, reason: `model switch ${prev} -> ${modelKey(model)}`, ttl, pWarm: 0, src: "model switch", gapS: null, pastTtl: false };
+	if (!last) return { cold: false, reason: "no prior request", ttl, pWarm: 1, src: "no prior request", gapS: null, pastTtl: false };
+	const gapS = (nowMs - last) / 1000;
+	const byTtl = isColdByTtl(last, nowMs, ttl.ms);
+	const s = learned && !process.env.PI_ZIP_TTL_SECS ? learned(gapS, ttl.ms / 1000) : { p: byTtl ? 0 : 1, src: "prior" };
+	const reason = `ttl gap ${Math.round(gapS)}s ${byTtl ? ">" : "<="} ${Math.round(ttl.ms / 1000)}s${s.src === "prior" ? "" : `, learned P(warm) ${s.p.toFixed(2)}`}`;
+	return { cold: s.p < 0.5, reason, ttl, pWarm: s.p, src: s.src, gapS, pastTtl: byTtl };
+}

package/src/classify.ts

@@ -0,0 +1,77 @@
+// Retrievability classification (F5): can the model get this output back by simply re-running the call?
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import type { Any } from "./util.ts";
+
+export type Recover = "rereadable" | "nonrereadable";
+
+const READ_ONLY_CMDS = new Set(["ls", "cat", "head", "tail", "wc", "grep", "rg", "find", "file", "stat", "du", "pwd", "echo"]);
+const READ_ONLY_GIT = new Set(["log", "show", "diff", "status", "blame", "shortlog"]);
+
+// Options that make an otherwise read-only command write files or run other programs.
+const FIND_UNSAFE = /^-(delete|exec|execdir|ok|okdir|fprint|fprint0|fprintf|fls)$/;
+const GIT_UNSAFE = /^--(output(=.*)?|ext-diff|textconv|open-files-in-pager.*|exec-path.*)$/;
+const RG_UNSAFE = /^--(pre|pre-glob)(=.*)?$/;
+
+/** Read-only bash whitelist: every pipe/;/&& segment must be a whitelisted command with no write or exec option; substitutions, redirections and background jobs are never read-only. */
+export function isReadOnlyBash(cmd: string): boolean {
+	const c = String(cmd ?? "").replace(/2>(\/dev\/null|&1)/g, " ").trim();
+	if (!c || /[<>`]|\$\(/.test(c)) return false; // any remaining redirection can write; $(...) and backticks run arbitrary commands
+	if (/&/.test(c.replace(/&&/g, ";"))) return false; // a lone & backgrounds a job (and `&>` redirects)
+	const segments = c.split(/[|;\n]|&&/).map((s) => s.trim()).filter(Boolean);
+	if (!segments.length) return false;
+	for (const seg of segments) {
+		let toks = seg.split(/\s+/).filter(Boolean);
+		while (toks.length > 1 && /^[A-Za-z_][A-Za-z0-9_]*=/.test(toks[0])) toks = toks.slice(1);
+		const head = (toks[0] ?? "").toLowerCase();
+		const rest = toks.slice(1);
+		if (head === "find") {
+			if (rest.some((t) => FIND_UNSAFE.test(t))) return false;
+			continue;
+		}
+		if (head === "rg") {
+			if (rest.some((t) => RG_UNSAFE.test(t))) return false;
+			continue;
+		}
+		if (head === "file") {
+			if (rest.some((t) => /^-[A-Za-z]*C/.test(t) || t === "--compile")) return false; // file -C writes a magic database
+			continue;
+		}
+		if (READ_ONLY_CMDS.has(head)) continue;
+		if (head === "git" && READ_ONLY_GIT.has((toks[1] ?? "").toLowerCase())) {
+			if (rest.some((t) => GIT_UNSAFE.test(t))) return false;
+			continue;
+		}
+		return false;
+	}
+	return true;
+}
+
+/**
+ * read: rereadable iff the file still exists and its bytes equal what the tool returned (unchanged since).
+ * bash: rereadable iff read-only. grep/find/ls/glob: re-runnable queries. Everything else: not rereadable.
+ */
+export function classifyRecoverability(tool: string, args: Any, rawText: string, cwd: string): Recover {
+	tool = String(tool ?? "").toLowerCase();
+	const a: Any = args ?? {};
+	if (tool === "read") {
+		const p = typeof a.path === "string" ? a.path : typeof a.file_path === "string" ? a.file_path : null;
+		if (!p) return "nonrereadable";
+		try {
+			const full = isAbsolute(p) ? p : join(cwd, p);
+			const st = statSync(full);
+			if (!st.isFile()) return "nonrereadable";
+			if (st.size > 2_000_000) return "rereadable"; // too big to hash cheaply; existence is the test
+			const onDisk = readFileSync(full);
+			const out = rawText.replace(/\n*\[Showing lines [^\]]*\]\s*$/, ""); // strip the continuation notice before comparing
+			const h = (t: string) => createHash("sha1").update(t.trimEnd()).digest("hex"); // trailing whitespace may differ around the notice
+			return h(onDisk.toString("utf8")) === h(out) ? "rereadable" : "nonrereadable";
+		} catch {
+			return "nonrereadable";
+		}
+	}
+	if (tool === "bash") return typeof a.command === "string" && isReadOnlyBash(a.command) ? "rereadable" : "nonrereadable";
+	if (tool === "grep" || tool === "find" || tool === "ls" || tool === "glob") return "rereadable";
+	return "nonrereadable";
+}

package/src/guard.ts

@@ -0,0 +1,192 @@
+// Guard (F13, I5): validate an edit set before committing it, and repair orphan tool results in the outgoing payload.
+import { RELAX_PREV_TURN, settings, type Block } from "./plan.ts";
+import type { Any } from "./util.ts";
+
+const PROTECT_USER_TURNS = 2;
+
+export interface EditSet {
+	folds: Map<number, string>; // block idx -> placeholder text
+	cut: number | null; // summarise blocks[0..cut-1]; blocks[cut] becomes firstKeptEntryId
+	recover?: Map<number, string | undefined>; // block idx -> "rereadable" | "nonrereadable" (needed for folds in the previous user turn)
+	relax?: boolean; // default RELAX_PREV_TURN
+	inturnAge?: number; // default settings().inturnAge: an output (any class) at least this many assistant requests old may fold in a protected turn (0 = never)
+}
+
+/**
+ * Tool-call pairing problems of a block list, the way the provider layer sees it (pi-ai transform-messages): errored or
+ * aborted assistant messages are dropped, so their calls never count; a toolResult must follow a call of the nearest
+ * assistant message; calls without results are synthesised by the provider but still reported (the caller decides).
+ */
+function pairingIssues(blocks: Block[], from: number): Set<string> {
+	const issues = new Set<string>();
+	let pending: Set<string> | null = null;
+	const closePending = (at: number) => {
+		if (pending) for (const id of pending) issues.add(`noResult:${id}@${at}`);
+		pending = null;
+	};
+	for (let i = from; i < blocks.length; i++) {
+		const b = blocks[i];
+		if (b.kind === "summary" && from > 0) continue; // replaced by our summary
+		const m = b.msg;
+		if (m.role === "toolResult") {
+			if (!pending || !pending.has(m.toolCallId)) issues.add(`orphanResult:${m.toolCallId}@${b.entryId ?? i}`);
+			else pending.delete(m.toolCallId);
+			continue;
+		}
+		if (m.role === "system") continue; // transparent: the provider layer holds it back
+		closePending(i);
+		if (m.role === "assistant") {
+			if (m.stopReason === "error" || m.stopReason === "aborted") continue; // dropped by the provider layer
+			const ids = (m.content ?? []).filter((c: Any) => c?.type === "toolCall").map((c: Any) => c.id);
+			if (ids.length) pending = new Set(ids);
+		}
+	}
+	closePending(blocks.length);
+	return issues;
+}
+
+/** null = legal. Otherwise the reason: bad targets, edits inside the protected user turns, or a tool_use/tool_result pairing the edits themselves would break. */
+export function validateEdits(blocks: Block[], plan: EditSet, userTurns: number): string | null {
+	const relax = plan.relax ?? RELAX_PREV_TURN;
+	const inturnAge = plan.inturnAge ?? settings().inturnAge;
+	const limit = blocks.findIndex((b) => b.userTurn >= userTurns - PROTECT_USER_TURNS + 1);
+	for (const [i, text] of plan.folds) {
+		const b = blocks[i];
+		if (!b || b.kind !== "toolResult") return `fold target ${i} is not a toolResult`;
+		if (b.edited) return `fold target ${i} already edited`;
+		const rereadable = plan.recover?.get(i) === "rereadable";
+		const aged = inturnAge > 0 && b.age >= inturnAge; // old enough: allowed anywhere, any class (same rule as the planner)
+		if (b.userTurn >= userTurns && !aged) return `fold target ${i} is inside the latest user turn`;
+		if (b.userTurn === userTurns - 1 && !aged && (!relax || !rereadable)) return `fold target ${i} is in the previous user turn and not re-readable`;
+		if (!b.entryId) return `fold target ${i} has no entry id`;
+		if (typeof text !== "string" || !text.trim()) return `empty placeholder for ${i}`;
+	}
+	if (plan.cut !== null) {
+		if (plan.cut < 1 || plan.cut >= blocks.length) return `bad cut ${plan.cut}`;
+		if (limit >= 0 && plan.cut > limit) return `cut ${plan.cut} inside the last ${PROTECT_USER_TURNS} user turns`;
+		const kb = blocks[plan.cut];
+		if (!kb.entryId || (kb.kind !== "user" && kb.kind !== "assistant")) return `cut ${plan.cut} is not at a user/assistant message`;
+		// only what the cut itself would create is our problem; a session that was already odd stays as odd as it was
+		const before = pairingIssues(blocks, 0);
+		for (const issue of pairingIssues(blocks, plan.cut)) if (!before.has(issue) && issue.startsWith("orphanResult")) return `the cut would orphan a tool result: ${issue}`;
+		for (const issue of pairingIssues(blocks, plan.cut)) if (!before.has(issue)) return `the cut would break tool-call pairing: ${issue}`;
+	}
+	const kept = plan.cut ?? 0;
+	return blocks.slice(kept).some((b) => b.kind !== "summary") ? null : "empty context after edits";
+}
+
+const toText = (c: Any): string => (typeof c === "string" ? c : Array.isArray(c) ? c.map((x: Any) => (typeof x === "string" ? x : (x?.text ?? ""))).join("\n") : c === undefined || c === null ? "" : JSON.stringify(c));
+const FOLDED = "[tool result, call folded]\n";
+const hasType = (b: Any, t: string) => b?.type === t;
+
+/** Index of the nearest earlier message that is not one of `skip` roles. */
+function prevIndex(list: Any[], i: number, skip: (m: Any) => boolean): number {
+	let j = i - 1;
+	while (j >= 0 && skip(list[j])) j--;
+	return j;
+}
+
+/** Anthropic messages: tool_result blocks inside a user message must answer tool_use blocks of the assistant message right before it. */
+function repairAnthropic(list: Any[], edit: () => Any): number {
+	let repaired = 0;
+	for (let i = 0; i < list.length; i++) {
+		const m = list[i];
+		if (m?.role !== "user" || !Array.isArray(m.content) || !m.content.some((b: Any) => hasType(b, "tool_result"))) continue;
+		const prev = list[prevIndex(list, i, (x) => x?.role === "system")];
+		const ids = new Set((prev?.role === "assistant" && Array.isArray(prev.content) ? prev.content : []).filter((b: Any) => hasType(b, "tool_use")).map((b: Any) => b.id));
+		const content = m.content.map((b: Any) => {
+			if (!hasType(b, "tool_result") || ids.has(b.tool_use_id)) return b;
+			repaired++;
+			return { type: "text", text: FOLDED + toText(b.content) };
+		});
+		if (content.some((b: Any, k: number) => b !== m.content[k])) edit().messages[i].content = content;
+	}
+	return repaired;
+}
+
+/** Bedrock Converse: { toolResult: { toolUseId } } blocks answer { toolUse: { toolUseId } } blocks of the assistant message before. */
+function repairBedrock(list: Any[], edit: () => Any): number {
+	let repaired = 0;
+	for (let i = 0; i < list.length; i++) {
+		const m = list[i];
+		if (m?.role !== "user" || !Array.isArray(m.content) || !m.content.some((b: Any) => b?.toolResult)) continue;
+		const prev = list[i - 1];
+		const ids = new Set((prev?.role === "assistant" && Array.isArray(prev.content) ? prev.content : []).filter((b: Any) => b?.toolUse).map((b: Any) => b.toolUse.toolUseId));
+		const content = m.content.map((b: Any) => {
+			if (!b?.toolResult || ids.has(b.toolResult.toolUseId)) return b;
+			repaired++;
+			return { text: FOLDED + toText(b.toolResult.content) };
+		});
+		if (content.some((b: Any, k: number) => b !== m.content[k])) edit().messages[i].content = content;
+	}
+	return repaired;
+}
+
+/** OpenAI chat completions and Mistral: a `tool` message must follow the assistant message whose tool_calls it answers. */
+function repairChat(list: Any[], edit: () => Any): number {
+	let repaired = 0;
+	for (let i = 0; i < list.length; i++) {
+		const m = list[i];
+		if (m?.role !== "tool" || m.tool_call_id === undefined) continue;
+		const prev = list[prevIndex(list, i, (x) => x?.role === "tool")];
+		if (!(prev?.role === "assistant" && (prev.tool_calls ?? []).some((c: Any) => c.id === m.tool_call_id))) {
+			repaired++;
+			edit().messages[i] = { role: "user", content: FOLDED + toText(m.content) };
+		}
+	}
+	return repaired;
+}
+
+/** OpenAI Responses (also Azure and Codex): a function_call_output needs a function_call with the same call_id earlier in the input. */
+function repairResponses(list: Any[], edit: () => Any): number {
+	let repaired = 0;
+	const calls = new Set<string>();
+	for (let i = 0; i < list.length; i++) {
+		const it = list[i];
+		if (it?.type === "function_call" || it?.type === "custom_tool_call") calls.add(it.call_id);
+		else if ((it?.type === "function_call_output" || it?.type === "custom_tool_call_output") && !calls.has(it.call_id)) {
+			repaired++;
+			edit().input[i] = { role: "user", content: [{ type: "input_text", text: FOLDED + toText(it.output) }] };
+		}
+	}
+	return repaired;
+}
+
+/** Gemini / Vertex: a functionResponse part answers a functionCall part of the model turn right before (by id when present, else by name). */
+function repairGoogle(list: Any[], edit: () => Any, path: (q: Any) => Any[]): number {
+	let repaired = 0;
+	for (let i = 0; i < list.length; i++) {
+		const c = list[i];
+		if (c?.role !== "user" || !Array.isArray(c.parts) || !c.parts.some((x: Any) => x?.functionResponse)) continue;
+		const prev = list[i - 1];
+		const open: Any[] = prev?.role === "model" && Array.isArray(prev.parts) ? prev.parts.filter((x: Any) => x?.functionCall).map((x: Any) => x.functionCall) : [];
+		const parts = c.parts.map((x: Any) => {
+			const r = x?.functionResponse;
+			if (!r) return x;
+			const k = open.findIndex((f) => (r.id !== undefined && f.id !== undefined ? f.id === r.id : f.name === r.name));
+			if (k >= 0) { open.splice(k, 1); return x; }
+			repaired++;
+			const out = r.response?.output ?? r.response?.error ?? r.response;
+			return { text: FOLDED + toText(out) };
+		});
+		if (parts.some((x: Any, k: number) => x !== c.parts[k])) path(edit())[i].parts = parts;
+	}
+	return repaired;
+}
+
+/**
+ * Turn tool results that no longer follow their tool call into plain text, in the request shapes Pi's providers produce:
+ * Anthropic messages, OpenAI chat completions (and Mistral), OpenAI Responses (Azure, Codex), Google Gemini/Vertex and
+ * Bedrock Converse. Any other shape is left alone. Returns the repaired payload, or null if nothing was wrong.
+ */
+export function repairPayload(p: Any): { payload: Any; repaired: number } | null {
+	if (!p || typeof p !== "object") return null;
+	let q: Any = null;
+	const edit = () => (q ??= structuredClone(p));
+	let repaired = 0;
+	if (Array.isArray(p.messages)) repaired += repairAnthropic(p.messages, edit) + repairBedrock(p.messages, edit) + repairChat(p.messages, edit);
+	if (Array.isArray(p.input)) repaired += repairResponses(p.input, edit);
+	if (Array.isArray(p.contents)) repaired += repairGoogle(p.contents, edit, (x) => x.contents);
+	else if (Array.isArray(p.request?.contents)) repaired += repairGoogle(p.request.contents, edit, (x) => x.request.contents);
+	return repaired ? { payload: q, repaired } : null;
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+// pi-zip: keeps long Pi sessions cheap without losing anything. Wiring only; the logic lives in the sibling modules.
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerZipCommand } from "./notice.ts";
+import { registerRecallTool } from "./recall.ts";
+import { Zip } from "./run.ts";
+
+export default function piZip(pi: ExtensionAPI) {
+	if (process.env.PI_ZIP_OFF === "1") return; // test only: behave exactly as if not installed (registers nothing)
+	const zip = new Zip(pi);
+	registerRecallTool(pi, zip); // stays registered even when off: earlier folds must stay recallable, and a tool-list change would bust the cache
+	registerZipCommand(pi, zip);
+	pi.on("session_start", (_e, ctx) => zip.sessionStart(ctx));
+	pi.on("before_agent_start", (_e, ctx) => zip.beforeAgentStart(ctx));
+	pi.on("context_with_system", (e, ctx) => zip.context(e, ctx)); // the complete transcript: system messages stay where Pi put them
+	pi.on("turn_end", (e, ctx) => zip.turnEnd(e, ctx));
+	pi.on("agent_before_settle", (e, ctx) => zip.settle(e, ctx));
+	pi.on("before_provider_request", (e) => zip.providerRequest(e));
+	pi.on("message_end", (e) => zip.messageEnd(e.message));
+	pi.on("session_shutdown", () => zip.shutdown());
+}