pi-zip 0.2.4 → 0.2.7

package/README.md

@@ -16,12 +16,13 @@ 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.
+Live A/B runs on the same coding tasks (4 task templates × 4 seeds, the user away between prompts as stated), 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 |
+| Claude Sonnet 5.5, away 6 min | **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, away 6 min | 1.00× [0.92, 1.08] | median task 209 s vs 305 s | 16/16 and 1.00 vs 15/16 |
+| GPT-6.1-sol, away 2 or 6 min | 1.07× [0.91, 1.22] | median task 271 s vs 389 s | 16/16 and 1.00 vs 14/16 |
 
 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.
 
@@ -34,14 +35,59 @@ Known limits:
 
 ## What you see
 
-At most one line per turn, only when something was folded:
+At most one line per turn in the transcript, only when the context was folded or summarized. The numbers come first, and the bar shows how much is left:
 
 ```
-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)
+▸ pi-zip  74K → 43K  ▰▰▰▰▰▰▱▱▱▱  folded 12 old outputs
+          originals are kept; the model can recall any of them with zip_recall
+▸ pi-zip  182K → 41K  ▰▰▱▱▱▱▱▱▱▱  summarized 64 requests · ready 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 second line appears once per session. Expand tool output (ctrl+o) to see why it happened now and what was folded:
+
+```
+▸ pi-zip  74K → 43K  ▰▰▰▰▰▰▱▱▱▱  folded 12 old outputs
+          cache cold (away 47 min): this request rewrites it anyway, so editing is free
+          bash npm test        turn 1     14K  k3x9q2m7ab
+          read src/payment.ts  turn 1      9K  p8d2x1qa0m
+          … 10 more
+```
+
+These lines are saved in the session, so they are still there after a restart, but they are never sent to the model. On narrow terminals the words go first, then the bar; the numbers always stay. A summary still shows up as Pi's own `[compaction]` block as well; the pi-zip line next to it tells you who made it.
+
+Everything else pi-zip shows uses the same one-line grammar, and only when something changed:
+
+```
+▸ pi-zip  on  folds old tool output after the prompt cache expires (5 min here) · nothing to set up · /zip for status
+▸ pi-zip  reread-only  a tool allowlist hides zip_recall · only re-readable outputs fold · allow zip_recall to fold more
+▸ pi-zip  paused  billion-context also manages context, so pi-zip only guards requests · to use pi-zip: pi remove the other one
+```
+
+The first one appears once per machine. A folded output keeps its place in the transcript; its tool row gets a dim mark on the right, so you can see what the model no longer sees in full:
+
+```
+ $ npm test                                                              ▸ folded · k3x9q2m7ab
+```
+
+A recall is one quiet row (ctrl+o shows the recalled text):
+
+```
+ ↺ recall k3x9q2m7ab  grep "Expected"
+ bash npm test · turn 1  3 of 812 lines
+```
+
+While a summary started in the background is being finished, Pi's working line says so (Esc skips the wait). `/zip` prints a small card into the transcript:
+
+```
+▸ pi-zip  on
+  cache    anthropic/claude-sonnet-5-5 · explicit · lives ~5 min (declared)
+  alive    ██████▁▁▁▁▁▁▁▁▁▁  30 s → 2 h
+  session  56 folds ~310K  ·  2 summaries $0.41  ·  3 recalls
+  last     10:50  folded 12 old outputs · cache cold (away 47 min): this request rewrites it anyway, so editing is free
+  mode     full (zip_recall available)
+```
+
+`alive` is what pi-zip currently believes about the cache: how likely it is to be still warm after 30 s, 1 min, … 2 h away, learned from the provider's replies (see below).
 
 ## The three rules
 
@@ -49,11 +95,11 @@ The line goes to the UI only; it never enters the model's context. Nothing else
 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.
+**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, the lifetime it currently believes, and the learned survival as the `alive` row.
 
 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.
+**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 status` 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.
 
@@ -61,13 +107,12 @@ The cold cap is kept below Pi's own compaction trigger (window minus `compaction
 
 | Command | Effect |
 |---|---|
-| `/zip status` | on / off / paused, cache TTL, what this session has folded, summarised and recalled, learned cache survival |
-| `/zip stats` | this session's folds (with tokens removed), summaries and recalls; persisted in the session, so a restart does not reset them |
+| `/zip` or `/zip status` | the card above: state, cache class and lifetime, learned survival, this session's folds, summaries and recalls (counted from the session, so a restart does not reset them) |
 | `/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.
+`off` and `quiet` are remembered per session; each change is one line in the transcript. In `-p` / json mode `/zip status` prints plain text to stderr.
 
 ## Recall
 
@@ -109,9 +154,9 @@ The guard has two parts. Before saving a fold or a summary it checks that the ed
 
 ## 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 what this session has folded (and roughly how many tokens that removed), its summaries with what their model calls cost, and its recalls. The numbers live in the session file, so a restart does not reset them.
+**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 status` shows what this session has folded (and roughly how many tokens that removed), its summaries with what their model calls cost, and its recalls. The numbers live in the session file, so a restart does not reset them.
 
-**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 there too. Recalled content re-enters the context at normal prices.
+**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 status`. A background summary you never use (you came back while the cache was warm) is counted there 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-zip",
-  "version": "0.2.4",
+  "version": "0.2.7",
   "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",

package/src/index.ts

@@ -1,31 +1,92 @@
 // 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 type { Any } from "./util.ts";
+import { type NoticeData, registerZipCommand, renderNotice } from "./notice.ts";
 import { RECALL_TOOL } from "./placeholder.ts";
 import { registerRecallTool } from "./recall.ts";
-import { Zip } from "./run.ts";
+import { NOTICE_CUSTOM, Zip } from "./run.ts";
+import { markFirstLine, measure, renderCard, renderState, setMeasure } from "./ui.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);
+	try {
+		// Everything pi-zip shows lives in the transcript as custom entries (never part of the model's context): fold/summary
+		// notices, state lines and the /zip status card. Widths are measured with Pi's own pi-tui once it has loaded.
+		import("@earendil-works/pi-tui").then((m: Any) => {
+			if (typeof m?.visibleWidth === "function" && typeof m?.truncateToWidth === "function")
+				setMeasure({ vw: m.visibleWidth, cut: (s: string, w: number) => (m.visibleWidth(s) <= w ? s : w <= 0 ? "" : m.truncateToWidth(s, w, "…")) });
+		}, () => {});
+		pi.registerEntryRenderer?.(NOTICE_CUSTOM, (entry: Any, o: Any, theme: Any) => {
+			const d = entry?.data;
+			if (!d?.text) return undefined;
+			return {
+				render: (width: number) => {
+					try {
+						if (d.v !== 2) return [theme.fg("dim", measure.cut(d.text, width))];
+						if (d.kind === "state") return renderState(d.word, d.reason ?? "", width, theme, measure);
+						if (d.kind === "card" && d.card) return renderCard(d.card, width, theme, measure);
+						return renderNotice(d as NoticeData, !!o?.expanded, width, theme, measure.vw);
+					} catch {
+						return [];
+					}
+				},
+				invalidate: () => {},
+			};
+		});
+		zip.entryRenderer = typeof pi.registerEntryRenderer === "function";
+		// a folded output keeps its place in the transcript; its call row gets a dim "▸ folded · <handle>" on the right
+		pi.registerToolRenderer?.((toolName: string, next: () => Any) => {
+			const base = next();
+			if (toolName === RECALL_TOOL || typeof base?.renderCall !== "function") return base;
+			return {
+				...base,
+				renderCall: (args: Any, theme: Any, c: Any) => {
+					const comp = base.renderCall(args, theme, c);
+					const id = c?.toolCallId;
+					if (!comp || typeof comp.render !== "function" || typeof id !== "string") return comp;
+					return new Proxy(comp, {
+						get(t, p, r) {
+							if (p !== "render") return Reflect.get(t, p, r);
+							return (width: number) => {
+								const lines = t.render(width);
+								const h = zip.foldedHandle(id);
+								try {
+									return h ? markFirstLine(lines, h, width, theme, measure) : lines;
+								} catch {
+									return lines;
+								}
+							};
+						},
+					});
+				},
+			};
+		});
+	} catch {
+		/* older Pi: notices fall back to the status line */
+	}
 	// A tool allowlist (`pi --tools read,bash`, sub-agent launchers) replaces the whole selection and Pi then does not even register
 	// zip_recall; folds of outputs the model could not get back would be lost, so only rereadable outputs fold then (plan rereadOnly).
-	const checkRecall = () => {
+	const checkRecall = (ctx: Any) => {
 		try {
 			const active = pi.getActiveTools?.();
-			if (Array.isArray(active)) zip.setRecallOk(active.includes(RECALL_TOOL));
+			if (Array.isArray(active)) zip.setRecallOk(active.includes(RECALL_TOOL), ctx);
 		} catch {
 			/* never in the way */
 		}
 	};
 	pi.on("session_start", (_e, ctx) => {
-		checkRecall();
-		return zip.sessionStart(ctx);
+		const r = zip.sessionStart(ctx);
+		checkRecall(ctx);
+		zip.refreshFolded(ctx);
+		zip.welcome(ctx);
+		return r;
 	});
 	pi.on("before_agent_start", (_e, ctx) => {
-		checkRecall();
+		checkRecall(ctx);
+		zip.refreshFolded(ctx); // the branch may have changed (/tree, fork)
 		return zip.beforeAgentStart(ctx);
 	});
 	pi.on("context_with_system", (e, ctx) => zip.context(e, ctx)); // the complete transcript: system messages stay where Pi put them

package/src/notice.ts

@@ -1,6 +1,7 @@
 // User-facing text (F15, F16): one notice line per turn, honest stats, the /zip command. Notices never enter model context.
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { type Any, PRODUCT } from "./util.ts";
+import type { CardData, StateWord } from "./ui.ts";
 
 export interface NoticeAction {
 	kind: "fold" | "summary";
@@ -12,19 +13,94 @@ export interface NoticeAction {
 	pressure?: boolean; // done by the warm valve (the law fired while the cache is still warm), not because the cache was cold
 }
 
+/** One folded output, for the expanded (ctrl+o) view of a notice. */
+export interface NoticeItem {
+	label: string; // tool + short args
+	turn?: number;
+	tokens: number;
+	handle: string;
+}
+
+/** What a transcript notice stores (custom entry data; never sent to the model). `text` is the plain one-line form (status-line fallback, ledger). */
+export interface NoticeData {
+	v: 2;
+	kind?: "state" | "card"; // absent: a fold/summary notice
+	word?: StateWord;
+	reason?: string;
+	card?: CardData;
+	text: string;
+	before: number;
+	after: number;
+	desc: string; // "folded 12 old outputs · summarized 64 requests · ready while you were away"
+	why?: string; // expanded view: why now
+	items?: NoticeItem[];
+	more?: number; // folded outputs not listed
+	first?: boolean; // the session's first notice: say once that originals are kept
+}
+
 export const fmtK = (tokens: number): string => `${tokens >= 99_500 ? Math.round(tokens / 1000) : Math.round(tokens / 100) / 10}K`;
 
+const plural = (n: number, w: string) => `${n} ${w}${n === 1 ? "" : "s"}`;
+const secs = (ms: number) => `${(Math.round(ms / 100) / 10).toFixed(1)} s`;
+
+/** The words after the numbers: what happened, plus how long the user waited for a summary (if at all). */
+export function noticeDesc(actions: NoticeAction[]): string {
+	return actions
+		.map((a) => {
+			if (a.kind === "fold") return `folded ${plural(a.count, "old output")}`;
+			return `summarized ${plural(a.count, "request")} · ${a.prepared ? "ready while you were away" : `waited ${secs(a.ms)}`}`;
+		})
+		.join(" · ");
+}
+
 export function noticeText(actions: NoticeAction[]): string {
-	const segs = actions.map((a) => {
-		const sizes = `${fmtK(a.tokensBefore)} → ${fmtK(a.tokensAfter)} tokens`;
-		if (a.kind === "fold") {
-			const ms = a.ms < 10 ? (Math.round(a.ms * 10) / 10).toFixed(1) : String(Math.round(a.ms));
-			return `folded ${a.count} old output${a.count === 1 ? "" : "s"} · ${sizes} · ${ms} ms · originals recallable${a.pressure ? " · context over the warm-cache limit" : ""}`;
-		}
-		const s = (Math.round(a.ms / 100) / 10).toFixed(1);
-		return `summarized ${a.count} request${a.count === 1 ? "" : "s"} · ${sizes} · ${a.prepared ? `${s} s (done while you were away)` : `waited ${s} s`}`;
-	});
-	return `${PRODUCT} · ${segs.join(" · ")}`;
+	const first = actions[0], last = actions[actions.length - 1];
+	return `${PRODUCT}  ${fmtK(first.tokensBefore)} → ${fmtK(last.tokensAfter)}  ${noticeDesc(actions)}`;
+}
+
+/** Ten cells, filled in proportion to what is left: length is read before any digit is. */
+export function ratioBar(before: number, after: number, cells = 10): string {
+	const f = before > 0 ? Math.min(cells, Math.max(1, Math.round((cells * after) / before))) : cells;
+	return "▰".repeat(f) + "▱".repeat(cells - f);
+}
+
+export interface NoticeTheme {
+	fg(color: string, text: string): string;
+}
+
+const MARK = "▸ ";
+const INDENT = " ".repeat(MARK.length + PRODUCT.length + 2);
+
+/** Lines for the transcript. Narrow terminals drop whole segments in order (description, then bar); the numbers always stay.
+ *  `w` measures display width (Pi's visibleWidth in the renderer; string length in tests). Every line fits `width`. */
+export function renderNotice(d: NoticeData, expanded: boolean, width: number, th: NoticeTheme, w: (s: string) => number = (s) => s.length): string[] {
+	const nums = `${fmtK(d.before)} → ${fmtK(d.after)}`;
+	const bar = ratioBar(d.before, d.after);
+	const tries: [string, string][] = [
+		[`${MARK}${PRODUCT}  ${nums}  ${bar}  ${d.desc}`, `${th.fg("accent", MARK + PRODUCT)}  ${th.fg("text", nums)}  ${th.fg("dim", bar)}  ${th.fg("dim", d.desc)}`],
+		[`${MARK}${PRODUCT}  ${nums}  ${bar}`, `${th.fg("accent", MARK + PRODUCT)}  ${th.fg("text", nums)}  ${th.fg("dim", bar)}`],
+		[`${MARK}${PRODUCT}  ${nums}`, `${th.fg("accent", MARK + PRODUCT)}  ${th.fg("text", nums)}`],
+		[nums, th.fg("text", nums)],
+	];
+	const head = tries.find(([plain]) => w(plain) <= width);
+	if (!head) return [];
+	const out = [head[1]];
+	const sub = (plain: string) => {
+		const line = INDENT + plain;
+		if (w(line) <= width) out.push(th.fg("dim", line));
+		else if (w(plain) <= width) out.push(th.fg("dim", plain));
+	};
+	if (d.first) sub("originals are kept; the model can recall any of them with zip_recall");
+	if (!expanded) return out;
+	if (d.why) sub(d.why);
+	const items = d.items ?? [];
+	const lw = Math.min(28, Math.max(0, ...items.map((i) => i.label.length)));
+	for (const i of items) {
+		const label = i.label.length > lw ? i.label.slice(0, lw - 1) + "…" : i.label.padEnd(lw);
+		sub(`${label}  ${(i.turn ? `turn ${i.turn}` : "").padEnd(8)}${fmtK(i.tokens).padStart(6)}  ${i.handle}`);
+	}
+	if (d.more) sub(`… ${d.more} more`);
+	return out;
 }
 
 export class Stats {
@@ -47,6 +123,9 @@ export class Stats {
 
 export interface ZipControl {
 	status(ctx?: Any): string;
+	card?(ctx?: Any): CardData;
+	/** Show a /zip result in the transcript; false = no transcript surface here (print/json/rpc or an older Pi). */
+	show?(ctx: Any, data: NoticeData): boolean;
 	statsLine(ctx?: Any): string;
 	setOff(off: boolean): string;
 	toggleQuiet(): string;
@@ -54,16 +133,25 @@ export interface ZipControl {
 
 export function registerZipCommand(pi: ExtensionAPI, zip: ZipControl) {
 	pi.registerCommand("zip", {
-		description: `${PRODUCT}: status | stats | off | on | quiet`,
+		description: `${PRODUCT}: status | off | on | quiet`,
 		handler: async (args: string, cctx: Any) => {
 			const sub = (args ?? "").trim().toLowerCase() || "status";
+			if ((sub === "status" || sub === "stats") && zip.card && zip.show) {
+				const card = zip.card(cctx);
+				if (zip.show(cctx, { v: 2, kind: "card", card, text: zip.status(cctx), before: 0, after: 0, desc: "" })) return;
+			}
 			const text =
 				sub === "status" ? zip.status(cctx)
 				: sub === "stats" ? zip.statsLine(cctx)
 				: sub === "off" ? zip.setOff(true)
 				: sub === "on" ? zip.setOff(false)
 				: sub === "quiet" ? zip.toggleQuiet()
-				: `${PRODUCT}: unknown subcommand "${sub}" (use status | stats | off | on | quiet)`;
+				: `${PRODUCT}: unknown subcommand "${sub}" (use status | off | on | quiet)`;
+			if (zip.show && (sub === "off" || sub === "on" || sub === "quiet")) {
+				const word: StateWord = sub === "quiet" ? (/notices off/.test(text) ? "quiet" : "notices on") : sub;
+				const reason = text.replace(/^pi-zip: (off|on)\.? ?/, "").replace(/^pi-zip: /, "");
+				if (zip.show(cctx, { v: 2, kind: "state", word, reason: reason || "folding resumes", text, before: 0, after: 0, desc: "" })) return;
+			}
 			if (cctx?.ui?.notify && (cctx.mode === "tui" || cctx.mode === "rpc")) {
 				try {
 					cctx.ui.notify(text);

package/src/recall.ts

@@ -1,6 +1,7 @@
 // zip_recall (F3): exact, batched retrieval of folded originals from the session file (I2).
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { handleFor, RECALL_TOOL } from "./placeholder.ts";
+import { handleFor, RECALL_TOOL, shortArgs } from "./placeholder.ts";
+import { measure, recallCallLine, recallResultLines, type RecallSectionInfo } from "./ui.ts";
 import { type Any, clamp, textOf } from "./util.ts";
 
 const RECALL_PAGE_CHARS = 20_000; // default page
@@ -101,34 +102,50 @@ export interface RecallItem {
 	handle: string;
 	text: string | null;
 	tool: string | null;
+	label?: string; // tool + short args of the call that produced it (transcript only)
+	turn?: number;
 }
 
-export function recallSections(items: RecallItem[], opts: { grep?: string; range?: string; offset?: unknown; limit?: unknown }): { text: string; ok: number; missing: number } {
+export function recallSections(items: RecallItem[], opts: { grep?: string; range?: string; offset?: unknown; limit?: unknown }): { text: string; ok: number; missing: number; sections: RecallSectionInfo[] } {
 	const parts: string[] = [];
+	const sections: RecallSectionInfo[] = [];
 	let ok = 0;
 	let missing = 0;
 	for (const it of items) {
 		if (it.text === null) {
 			missing++;
+			sections.push({ handle: it.handle, missing: true });
 			parts.push(`[handle ${it.handle}] not found. Copy the handle exactly from the folded block's marker line or the summary's handle table.`);
 			continue;
 		}
 		ok++;
 		const slice = sliceRecall(it.text, opts);
+		const grep = opts.grep !== undefined && String(opts.grep).trim() !== "", range = opts.range !== undefined && String(opts.range).trim() !== "";
+		const how = grep ? "grep" : range ? "range" : slice.clipped || slice.offset > 0 ? "page" : "all";
+		const shown = grep ? (slice.matched ?? 0) : slice.body ? slice.body.split("\n").length : 0;
+		sections.push({ handle: it.handle, label: it.label ?? it.tool ?? undefined, turn: it.turn, totalLines: slice.totalLines, shownLines: shown, how });
 		parts.push(`[handle ${it.handle}${it.tool ? " · " + it.tool : ""} · ${it.text.length} chars · ${slice.totalLines} lines]\n${slice.text}`);
 	}
-	return { text: parts.join("\n\n"), ok, missing };
+	return { text: parts.join("\n\n"), ok, missing, sections };
 }
 
 /** Resolve handles against the session branch (which spans entries before any compaction): exact originals. */
 export function resolveHandlesInBranch(branch: Any[], handles: string[]): { items: RecallItem[]; entryIds: (string | null)[] } {
 	const items: RecallItem[] = handles.map((h) => ({ handle: h, text: null, tool: null }));
 	const entryIds: (string | null)[] = handles.map(() => null);
+	const calls = new Map<string, Any>();
+	let turn = 0;
 	for (const en of branch) {
-		if (en?.type !== "message" || en.message?.role !== "toolResult") continue;
+		const msg = en?.type === "message" ? en.message : null;
+		if (msg?.role === "user") turn++;
+		if (msg?.role === "assistant" && Array.isArray(msg.content)) for (const c of msg.content) if (c?.type === "toolCall" && c.id) calls.set(c.id, c);
+		if (msg?.role !== "toolResult") continue;
 		const k = handles.indexOf(handleFor(en.id));
 		if (k < 0) continue;
-		items[k] = { handle: handles[k], text: textOf(en.message.content), tool: en.message.toolName ?? null };
+		const call = calls.get(msg.toolCallId);
+		const tool = msg.toolName ?? call?.name ?? null;
+		const args = call ? shortArgs(call.arguments) : "";
+		items[k] = { handle: handles[k], text: textOf(msg.content), tool, label: tool ? `${tool}${args ? " " + args : ""}` : undefined, turn: turn || undefined };
 		entryIds[k] = en.id;
 	}
 	return { items, entryIds };
@@ -177,6 +194,14 @@ export function registerRecallTool(pi: ExtensionAPI, hooks: RecallHooks) {
 			},
 			required: [],
 		} as Any,
+		renderCall(args: Any, theme: Any) {
+			return lines((w) => recallCallLine(args ?? {}, w, theme, measure));
+		},
+		renderResult(result: Any, options: Any, theme: Any) {
+			const text = textOf(result?.content);
+			const secs: RecallSectionInfo[] = Array.isArray(result?.details?.sections) ? result.details.sections : [];
+			return lines((w) => recallResultLines(secs, text, !!options?.expanded, w, theme, measure));
+		},
 		async execute(_id: string, params: Any, _signal: Any, _onUpdate: Any, ctx: Any): Promise<Any> {
 			const grep = params?.grep !== undefined ? String(params.grep) : undefined;
 			const range = params?.range !== undefined ? String(params.range) : undefined;
@@ -190,10 +215,15 @@ export function registerRecallTool(pi: ExtensionAPI, hooks: RecallHooks) {
 				const { items, entryIds } = resolveHandlesInBranch(ctx.sessionManager.getBranch() as Any[], handles);
 				const out = recallSections(items, { grep, range, offset, limit });
 				hooks.onRecall(handles, items.reduce((a, it) => a + (it.text?.length ?? 0), 0), entryIds);
-				return { content: [{ type: "text", text: out.text }], details: { handles, resolved: out.ok, missing: out.missing }, isError: out.ok === 0 };
+				return { content: [{ type: "text", text: out.text }], details: { handles, resolved: out.ok, missing: out.missing, sections: out.sections }, isError: out.ok === 0 };
 			} catch (err) {
 				return { content: [{ type: "text", text: `${RECALL_TOOL} failed: ${err instanceof Error ? err.message : String(err)}` }], details: {}, isError: true };
 			}
 		},
 	});
 }
+
+/** A minimal pi-tui Component: lines computed for the width at render time. */
+function lines(fn: (width: number) => string[]): Any {
+	return { render: (width: number) => fn(Math.max(1, width)), invalidate: () => {} };
+}

package/src/run.ts

@@ -1,21 +1,24 @@
 // The per-session state machine behind index.ts: cold detection, the run plan (F8), the warm valve (F10), persistence at turn_end,
 // settle preparation and the away-timer for the summary (F12).
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { appendFileSync, mkdirSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { detectCold, lastMessageMs, lastPrompt, modelKey, resolveTtl, ttlFor } from "./cache.ts";
-import { describe, lawPrices, loadStats, pWarm, record, sample, GAP_EDGES, type Entry } from "./learn.ts";
+import { describe, lawPrices, loadStats, pWarm, record, sample, statsPath, GAP_EDGES, type Entry } from "./learn.ts";
 import { validateEdits, repairPayload } from "./guard.ts";
-import { fmtK, Stats, noticeText, type NoticeAction, type ZipControl } from "./notice.ts";
+import { fmtK, Stats, noticeDesc, noticeText, type NoticeAction, type NoticeData, type ZipControl } from "./notice.ts";
 import { applyPlanToMessages, buildBlocks, calibrate, countUserTurns, G0, planContext, reserveTokensFor, untouchedEst, type Block, type Calibration, type Cut, type FoldTarget, type Law, type PlanOpts, type PlanResult, type RunPlan } from "./plan.ts";
 import { handleFor, PH_MARK, RECALL_TOOL } from "./placeholder.ts";
 import { recalledHandlesFromBranch } from "./recall.ts";
 import { buildCut } from "./summary.ts";
 import { type Any, PRODUCT, textOf, tok4 } from "./util.ts";
+import { fmtLife, SPARK_GAPS, type CardData, type StateWord } from "./ui.ts";
 
 export const PLAN_CUSTOM = "pi-zip/plan";
 export const STATE_CUSTOM = "pi-zip/state";
 export const STEER_CUSTOM = "pi-zip/steer";
+const fmtAway = (s: number) => (s < 90 ? `${Math.round(s)} s` : s < 5400 ? `${Math.round(s / 60)} min` : `${(Math.round(s / 360) / 10).toFixed(1)} h`);
+export const NOTICE_CUSTOM = "pi-zip/notice"; // a fold/summary notice kept in the transcript (rendered by index.ts, never sent to the model)
 export const UNUSED_SUMMARY_CUSTOM = "pi-zip/unused-summary"; // a background summary nobody adopted: its cost, so the session totals stay honest
 export const AWAY_FRACTION = 0.8; // the away-timer fires this far into the cache lifetime
 // Other context managers rewrite the view too (F14); two writers give unpredictable results, so we pause and keep only the Guard.
@@ -95,11 +98,68 @@ export class Zip implements ZipControl {
 
 	/** zip_recall declared to the model? Checked at session start and before every run (index.ts); a `--tools` allowlist hides it. */
 	recallOk = true;
+	/** index.ts registered the transcript renderer for NOTICE_CUSTOM (Pi versions without registerEntryRenderer fall back to a status line). */
+	entryRenderer = false;
+	private coldWhy = ""; // the expanded notice's "why now" for this run
+	private noticed = false; // a transcript notice was written in this process (the branch may not show it yet)
 	/** A summary was persisted since the last cold run start: later warm plans make none unless at the compaction room. */
 	summarizedWarm = false;
-	setRecallOk(ok: boolean) {
+	setRecallOk(ok: boolean, ctx?: Any) {
 		if (ok !== this.recallOk) this.ledger({ type: "recall_available", ok });
 		this.recallOk = ok;
+		if (!ok && ctx) this.stateLine(ctx, "reread-only", "a tool allowlist hides zip_recall · only re-readable outputs fold · allow zip_recall to fold more");
+	}
+
+	/** Folded tool outputs of the current branch by toolCallId -> handle (the transcript marks them). */
+	readonly foldedCalls = new Map<string, string>();
+	foldedHandle = (toolCallId: string): string | undefined => this.foldedCalls.get(toolCallId);
+	refreshFolded(ctx: Any) {
+		const branch = this.branch(ctx);
+		const byId = new Map(branch.map((e: Any) => [e?.id, e]));
+		this.foldedCalls.clear();
+		for (const e of branch) {
+			if (e?.type !== "context_edit" || !String(e?.replacement?.content?.[0]?.text ?? "").startsWith(PH_MARK)) continue;
+			const id = byId.get(e.targetId)?.message?.toolCallId;
+			if (typeof id === "string") this.foldedCalls.set(id, handleFor(e.targetId));
+		}
+	}
+
+	/** /zip output in the transcript (custom entry, never sent to the model). */
+	show(ctx: Any, data: NoticeData): boolean {
+		if (ctx?.mode !== "tui" || !this.entryRenderer) return false;
+		try {
+			this.pi.appendEntry(NOTICE_CUSTOM, data);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
+	/** A state change as one transcript line ("▸ pi-zip  paused  …"); each word once per session unless always. */
+	stateLine(ctx: Any, word: StateWord, reason: string, once = true) {
+		const text = `${PRODUCT}  ${word}  ${reason}`;
+		if (ctx?.mode !== "tui" && word !== "paused") return; // print/json/rpc (sub-agents): no transcript to keep it in
+		if (once && (this.statesShown.has(word) || this.branch(ctx).some((e: Any) => e?.type === "custom" && e.customType === NOTICE_CUSTOM && e.data?.kind === "state" && e.data?.word === word))) return;
+		this.statesShown.add(word);
+		this.ledger({ type: "state", word, reason });
+		// a state is not tied to this turn's edits: append now, so it sits where it happened
+		if (!this.show(ctx, { v: 2, kind: "state", word, reason, text, before: 0, after: 0, desc: "" })) this.notify(ctx, text);
+	}
+	private statesShown = new Set<string>();
+
+	/** First pi-zip session on this machine: one line that sets the expectation (nothing visible happens until the cache expires). */
+	welcome(ctx: Any) {
+		if (ctx?.mode !== "tui" || !this.entryRenderer || this.off || this.conflict) return;
+		const flag = `${dirname(process.env.PI_ZIP_CACHE_STATS || statsPath())}/welcomed`;
+		try {
+			if (existsSync(flag)) return;
+			mkdirSync(dirname(flag), { recursive: true });
+			writeFileSync(flag, new Date().toISOString() + "\n");
+		} catch {
+			return;
+		}
+		const ttl = ttlFor(ctx.model ?? this.model);
+		this.stateLine(ctx, "on", `folds old tool output after the prompt cache expires (${fmtLife(ttl / 1000).slice(1)} here) · nothing to set up · /zip for status`);
 	}
 
 	ledger(rec: Record<string, unknown>) {
@@ -111,9 +171,19 @@ export class Zip implements ZipControl {
 		} catch {}
 	}
 
-	private notify(ctx: Any, text: string) {
+	/** keep = a fold/summary notice: written to the session as a custom entry, so it stays in the transcript (also after a restart)
+	 *  next to Pi's own "[compaction]" block instead of a status line the next status overwrites. Custom entries never reach the model. */
+	private notify(ctx: Any, text: string, keep?: NoticeData) {
 		this.stats.notices++;
 		this.ledger({ type: "notice", text });
+		if (keep && ctx?.mode === "tui" && this.entryRenderer) {
+			setTimeout(() => { // after Pi has appended this turn's edits
+				try {
+					this.pi.appendEntry(NOTICE_CUSTOM, keep);
+				} catch {}
+			}, 0);
+			return;
+		}
 		if (ctx?.ui?.notify && (ctx.mode === "tui" || ctx.mode === "rpc")) {
 			try {
 				ctx.ui.notify(text, "info");
@@ -186,7 +256,7 @@ export class Zip implements ZipControl {
 		this.conflict = found;
 		if (found && !this.conflictNoticed) {
 			this.conflictNoticed = true;
-			this.notify(ctx, `${PRODUCT} · "${found}" also manages context, so folding is paused (only the request guard stays on)`);
+			this.stateLine(ctx, "paused", `${found} also manages context, so pi-zip only guards requests · to use pi-zip: pi remove the other one`, true);
 		}
 	}
 
@@ -243,6 +313,7 @@ export class Zip implements ZipControl {
 		this.survSrc = src;
 		this.runChecked = false; // the first request decides (cold: the cold plan; warm: only above the cap, if the law fires)
 		this.coldReason = reason;
+		this.coldWhy = src === "model switch" ? "model switched: its cache starts empty, so this request rewrites it anyway" : cold && gapS !== null ? `cache cold (away ${fmtAway(gapS)}): this request rewrites it anyway, so editing is free` : "";
 		for (const h of recalledHandlesFromBranch(branch)) this.recalled.add(h);
 		for (let i = branch.length - 1; i >= 0; i--) {
 			const en = branch[i];
@@ -255,7 +326,7 @@ export class Zip implements ZipControl {
 		this.ledger({ type: "prompt", cold, reason, ttlMs: ttl.ms, ttlSource: ttl.source, settleTargets: this.settleIds.length, gapS: gapS === null ? null : Math.round(gapS), pWarm: Math.round(p * 1000) / 1000, survSrc: src, cls: this.ent?.cls ?? null });
 		if (ttl.note && !this.ttlNoticed) {
 			this.ttlNoticed = true; // once per session
-			if (!this.quiet) this.notify(ctx, ttl.note);
+			if (!this.quiet) this.stateLine(ctx, "cache", ttl.note.replace(`${PRODUCT} · `, ""));
 		}
 	}
 
@@ -306,14 +377,29 @@ export class Zip implements ZipControl {
 	}
 
 	/** A prepared summary for this cut, or null. A summary still being written is waited for (only the remainder); Esc stops the waiting, not the work. */
-	private async takeBg(key: string | null, signal?: AbortSignal): Promise<{ cut: Cut | null; adopted: boolean }> {
+	/** While the user waits for a summary, Pi's working line says what for (and that Esc skips a prepared one). */
+	private async working<T>(ctx: Any, text: string, p: Promise<T>): Promise<T> {
+		const ui = ctx?.mode === "tui" ? ctx?.ui : null;
+		try {
+			ui?.setWorkingMessage?.(text);
+		} catch {}
+		try {
+			return await p;
+		} finally {
+			try {
+				ui?.setWorkingMessage?.(undefined);
+			} catch {}
+		}
+	}
+
+	private async takeBg(key: string | null, signal?: AbortSignal, ctx?: Any): Promise<{ cut: Cut | null; adopted: boolean }> {
 		const b = this.bg;
 		if (!b || key === null || b.key !== key) {
 			this.discardBg();
 			return { cut: null, adopted: false };
 		}
 		const w0 = performance.now();
-		const cut = b.done ?? (await waitFor(b.promise, signal));
+		const cut = b.done ?? (await this.working(ctx, `${PRODUCT}: finishing the summary it started while you were away · Esc skips it`, waitFor(b.promise, signal)));
 		this.bgWaitMs = performance.now() - w0;
 		if (cut) {
 			this.bg = null;
@@ -347,7 +433,7 @@ export class Zip implements ZipControl {
 		let cut: Cut | null = null;
 		let adopted = false;
 		if (p && p.cutIdx !== null) {
-			const got = await this.takeBg(p.firstKeptEntryId, ctx.signal);
+			const got = await this.takeBg(p.firstKeptEntryId, ctx.signal, ctx);
 			cut = got.cut;
 			adopted = got.adopted;
 		} else {
@@ -356,7 +442,7 @@ export class Zip implements ZipControl {
 		const sameSet = this.settleIds.length === folds.length && this.settleIds.every((id) => folds.some((u) => u.entryId === id));
 		const source: RunPlan["source"] = !this.cold ? "valve" : adopted || (this.settleIds.length > 0 && sameSet) ? "settle" : "runstart";
 		const foldMs = performance.now() - t0;
-		if (!cut && p && p.cutIdx !== null && !ctx.signal?.aborted) cut = await buildCut(p, ctx); // produced now, before the first request: the user waits
+		if (!cut && p && p.cutIdx !== null && !ctx.signal?.aborted) cut = await this.working(ctx, `${PRODUCT}: writing a summary (folding alone cannot make the context small enough)`, buildCut(p, ctx)); // produced now, before the first request: the user waits
 		// a plan that cannot be persisted must never be sent: the request view would differ from what turn_end can write (I1)
 		if (p) {
 			const invalid = checkEdits(p.blocks, p.userTurns, folds, cut);
@@ -501,8 +587,8 @@ export class Zip implements ZipControl {
 		if (!p || (!p.folds.length && p.cutIdx === null)) return undefined;
 		let cut: Cut | null = null;
 		if (p.cutIdx !== null) {
-			const got = await this.takeBg(p.firstKeptEntryId, ctx.signal);
-			cut = got.cut ?? (await buildCut(p, ctx)); // the user is here and the cache is warm; the alternative is Pi's lossy compaction
+			const got = await this.takeBg(p.firstKeptEntryId, ctx.signal, ctx);
+			cut = got.cut ?? (await this.working(ctx, `${PRODUCT}: writing a summary (the context is close to the window)`, buildCut(p, ctx))); // the user is here and the cache is warm; the alternative is Pi's lossy compaction
 		} else this.discardBg();
 		const plan: RunPlan = { source: "valve", folds: p.folds, cut, ctxBefore: p.ctxTokens, ctxAfter: p.ctxAfterFolds, ms: performance.now() - t0, k: p.k, persisted: false, untouched: p.k * untouchedEst(p.blocks, p.folds, !!cut, popts.sys) };
 		return this.commit(e, ctx, plan, o);
@@ -530,6 +616,7 @@ export class Zip implements ZipControl {
 		}
 		if (!plan.sent) this.nextEdit = plan.untouched ?? 0; // persisted now, first sent with the next request
 		const ours: Any[] = live.map((t) => ({ type: "context_edit", targetId: t.entryId, replacement: { content: [{ type: "text", text: t.ph }] } }));
+		for (const t of live) if (t.toolCallId) this.foldedCalls.set(t.toolCallId, handleFor(t.entryId));
 		if (cut) ours.push({ type: "compaction", summary: cut.text, firstKeptEntryId: cut.firstKeptEntryId, details: { by: PRODUCT, trigger: cut.trigger }, usage: cut.usage });
 		const before = Math.round(k * live.reduce((a, t) => a + t.entryTokens, 0));
 		const after = Math.round(k * live.reduce((a, t) => a + t.phTokens, 0));
@@ -565,7 +652,14 @@ export class Zip implements ZipControl {
 			const prepared = plan.source === "settle" && waitMs < 500; // finished while the user was away: report the real production time, not the zero wait
 			notices.push({ kind: "summary", count: cut.count, tokensBefore: ctxTokens - (before - after), tokensAfter: ctxTokens - (before - after) - cutSaved, ms: prepared ? cut.ms : waitMs, prepared, pressure: valve });
 		}
-		if (notices.length && !this.quiet) this.notify(ctx, noticeText(notices));
+		if (notices.length && !this.quiet) {
+			const ITEMS = 8;
+			const items = live.slice(0, ITEMS).map((t) => ({ label: `${t.tool}${t.args ? " " + t.args : ""}`, turn: byId.get(t.entryId)?.userTurn, tokens: Math.round(k * t.entryTokens), handle: handleFor(t.entryId) }));
+			const why = valve ? "cache still warm, but the context passed the warm-cache limit" : this.cold ? this.coldWhy : "cache warm: the reads saved pay for the rewrite";
+			const data: NoticeData = { v: 2, text: noticeText(notices), before: Math.round(notices[0].tokensBefore), after: Math.round(notices[notices.length - 1].tokensAfter), desc: noticeDesc(notices), why: why || undefined, items, more: Math.max(0, live.length - ITEMS) || undefined, first: !this.noticed && !this.branch(ctx).some((en: Any) => en?.type === "custom" && en.customType === NOTICE_CUSTOM) };
+			this.noticed = true;
+			this.notify(ctx, data.text, data);
+		}
 		return { entries: [...e.entries, ...ours] }; // append, never overwrite other extensions' drafts
 	}
 
@@ -644,10 +738,11 @@ export class Zip implements ZipControl {
 		} catch {}
 	}
 	/** What this session carries: folds and summaries persisted in its file (they survive restarts) and the recalls in its branch. */
-	private sessionTotals(ctx: Any): string {
+	private totals(ctx: Any) {
 		const branch = ctx ? this.branch(ctx) : [];
 		const byId = new Map(branch.map((e: Any) => [e?.id, e]));
 		let folds = 0, folded = 0, summaries = 0, recalls = 0, usd = 0;
+		let last: Any = null;
 		for (const e of branch) {
 			const ph = String(e?.replacement?.content?.[0]?.text ?? "");
 			if (e?.type === "context_edit" && ph.startsWith(PH_MARK)) {
@@ -657,11 +752,36 @@ export class Zip implements ZipControl {
 				summaries++;
 				usd += Number(e.usage?.cost?.total) || 0;
 			} else if (e?.type === "custom" && e.customType === UNUSED_SUMMARY_CUSTOM) usd += Number(e.data?.usd) || 0;
+			else if (e?.type === "custom" && e.customType === NOTICE_CUSTOM && e.data?.v === 2 && !e.data?.kind) last = e;
 			else if (e?.type === "message" && e.message?.role === "toolResult" && e.message?.toolName === RECALL_TOOL) recalls++;
 		}
+		return { folds, folded, summaries, recalls, usd, last };
+	}
+	/** What this session carries: folds and summaries persisted in its file (they survive restarts) and the recalls in its branch. */
+	private sessionTotals(ctx: Any): string {
+		const { folds, folded, summaries, recalls, usd } = this.totals(ctx);
 		const n = (x: number, one: string, many: string) => `${x} ${x === 1 ? one : many}`;
 		return `this session: ${n(folds, "folded output", "folded outputs")} (~${fmtK(folded)} tokens), ${n(summaries, "summary", "summaries")}${usd > 0 ? ` (summary calls $${usd.toFixed(4)})` : ""}, ${n(recalls, "recall", "recalls")}`;
 	}
+	/** The /zip status card (rendered by ui.ts renderCard). */
+	card(ctx?: Any): CardData {
+		const t = this.totals(ctx);
+		const model = ctx?.model ?? this.model;
+		const key = modelKey(model), ttlS = ttlFor(model) / 1000, ent = key ? loadStats().models[key] : undefined;
+		const alive = key ? SPARK_GAPS.map((g) => pWarm(ent, g, ttlS).p) : undefined;
+		let lifeS = 0;
+		for (let g = 30; g <= 7200; g += 30) if (pWarm(ent, g, ttlS).p >= 0.5) lifeS = g;
+		const learned = !!ent && ent.n > 0 && pWarm(ent, Math.max(30, lifeS), ttlS).src === "learned";
+		const life = key ? `${lifeS >= 7200 ? "over 2 h" : fmtLife(lifeS || ttlS)} (${learned ? `learned from ${Math.round(ent!.n)} ${Math.round(ent!.n) === 1 ? "reply" : "replies"}` : "declared"})` : undefined;
+		const ts = t.last?.timestamp ? new Date(t.last.timestamp) : null;
+		const hhmm = ts && !Number.isNaN(ts.getTime()) ? `${String(ts.getHours()).padStart(2, "0")}:${String(ts.getMinutes()).padStart(2, "0")}  ` : "";
+		const last = t.last ? `${hhmm}${t.last.data.desc}${t.last.data.why ? " · " + t.last.data.why : ""}` : undefined;
+		const state = this.off ? "off" : this.conflict ? "paused" : this.recallOk ? "on" : "reread-only";
+		return {
+			state, stateNote: state === "paused" ? `${this.conflict} also manages context` : state === "off" ? "/zip on to resume" : undefined,
+			model: key || undefined, cls: ent?.cls, life, alive, folds: t.folds, foldedTokens: fmtK(t.folded), summaries: t.summaries, summaryUsd: t.usd, recalls: t.recalls, last, quiet: this.quiet,
+		};
+	}
 	status(ctx?: Any): string {
 		const state = this.off ? "off" : this.conflict ? `paused ("${this.conflict}" also manages context; only the request guard is on)` : "on";
 		const key = modelKey(this.model), ttl = ttlFor(this.model), ent = loadStats().models[key];

package/src/ui.ts

@@ -0,0 +1,158 @@
+// Transcript surfaces (pure, testable): the status card, state lines, the zip_recall row and the fold mark on a folded output.
+// One visual grammar everywhere: "▸ pi-zip" in the accent colour, numbers in the text colour, everything else dim, no boxes;
+// collapsed = the conclusion, ctrl+o = the detail. Every returned line fits the given width.
+import { PRODUCT } from "./util.ts";
+
+export interface Th {
+	fg(color: string, text: string): string;
+}
+/** Display width and truncation: Pi's visibleWidth / truncateToWidth in the renderer, string length in tests. */
+export interface Measure {
+	vw(s: string): number;
+	cut(s: string, width: number): string; // plain text, at most width columns, with "…" when cut
+}
+export const plainMeasure: Measure = {
+	vw: (s) => s.length,
+	cut: (s, w) => (s.length <= w ? s : w <= 0 ? "" : s.slice(0, w - 1) + "…"),
+};
+/** The measure renderers use: index.ts swaps in Pi's own (pi-tui) when it loads. */
+export let measure: Measure = plainMeasure;
+export function setMeasure(m: Measure) {
+	measure = m;
+}
+
+export const MARK = "▸ ";
+const HEAD = MARK + PRODUCT;
+const LABEL_W = 9;
+
+/** Plain text without control characters (tabs become two spaces): recalled output goes into the TUI as text, never as escape codes. */
+export const clean = (s: string): string => s.replace(/\t/g, "  ").replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "").replace(/[\x00-\x08\x0b-\x1f\x7f]/g, "");
+
+// ---- state lines -------------------------------------------------------------------------------------------------------
+
+export type StateWord = "on" | "off" | "paused" | "reread-only" | "quiet" | "notices on" | "cache";
+const WARN = new Set<StateWord>(["off", "paused", "reread-only"]);
+
+/** "▸ pi-zip  paused  billion-context also manages context · run: pi remove npm:billion-context" */
+export function renderState(word: StateWord, reason: string, width: number, th: Th, m: Measure = plainMeasure): string[] {
+	const wordC = th.fg(WARN.has(word) ? "warning" : "accent", word);
+	const base = `${HEAD}  ${word}`;
+	if (m.vw(base) > width) return m.vw(word) <= width ? [wordC] : [];
+	const room = width - m.vw(base) - 2;
+	const r = reason && room >= 12 ? m.cut(reason, room) : "";
+	return [`${th.fg("accent", HEAD)}  ${wordC}${r ? "  " + th.fg("dim", r) : ""}`];
+}
+
+// ---- status card ------------------------------------------------------------------------------------------------------
+
+export interface CardData {
+	state: "on" | "off" | "paused" | "reread-only";
+	stateNote?: string; // why paused / reread-only
+	model?: string; // provider/id
+	cls?: string; // explicit | automatic
+	life?: string; // "~5 min (declared)" | "~1 h (learned from 42 returns)"
+	alive?: number[]; // P(warm) at SPARK_GAPS
+	folds: number;
+	foldedTokens: string; // "310K"
+	summaries: number;
+	summaryUsd: number;
+	recalls: number;
+	last?: string; // "10:50  folded 12 old outputs · cache cold (away 47 min)"
+	quiet: boolean;
+}
+
+/** Gaps (seconds) the "alive" sparkline samples: 30 s to 2 h, denser where caches usually expire. */
+export const SPARK_GAPS = [30, 60, 120, 180, 240, 300, 360, 420, 600, 900, 1200, 1800, 2700, 3600, 5400, 7200];
+const SPARK = "▁▂▃▄▅▆▇█";
+export const sparkline = (ps: number[]): string => ps.map((p) => SPARK[Math.max(0, Math.min(7, Math.round(p * 7)))]).join("");
+
+/** "~5 min", "~1 h", "~2.5 h" */
+export function fmtLife(s: number): string {
+	if (s < 90) return `~${Math.round(s)} s`;
+	if (s < 5400) return `~${Math.round(s / 60)} min`;
+	return `~${+(s / 3600).toFixed(1)} h`;
+}
+
+export function cardText(c: CardData): string[] {
+	const rows: [string, string][] = [];
+	if (c.model) rows.push(["cache", [c.model, c.cls ?? "class unknown until the first reply", c.life ? `lives ${c.life}` : ""].filter(Boolean).join(" · ")]);
+	if (c.alive?.length) rows.push(["alive", `${sparkline(c.alive)}  30 s → 2 h`]);
+	const n = (x: number, one: string, many = one + "s") => `${x} ${x === 1 ? one : many}`;
+	rows.push(["session", `${n(c.folds, "fold")} ~${c.foldedTokens}  ·  ${n(c.summaries, "summary", "summaries")}${c.summaryUsd > 0 ? ` $${c.summaryUsd.toFixed(2)}` : ""}  ·  ${n(c.recalls, "recall")}`]);
+	if (c.last) rows.push(["last", c.last]);
+	const mode = c.state === "reread-only" ? "reread-only (zip_recall hidden by a tool allowlist)" : "full (zip_recall available)";
+	rows.push(["mode", `${mode}${c.quiet ? " · notices off" : ""}`]);
+	return rows.map(([k, v]) => `${k.padEnd(LABEL_W)}${v}`);
+}
+
+export function renderCard(c: CardData, width: number, th: Th, m: Measure = plainMeasure): string[] {
+	const out = renderState(c.state, c.stateNote ?? "", width, th, m);
+	const indent = "  ";
+	for (const row of cardText(c)) {
+		const line = m.cut(indent + row, width);
+		if (!line) continue;
+		const warn = row.startsWith("mode") && c.state === "reread-only";
+		const k = line.slice(0, indent.length + LABEL_W), v = line.slice(indent.length + LABEL_W);
+		out.push(th.fg("dim", k) + (row.startsWith("session") ? th.fg("text", v) : th.fg(warn ? "warning" : "dim", v)));
+	}
+	return out;
+}
+
+// ---- zip_recall row ------------------------------------------------------------------------------------------------------
+
+export interface RecallSectionInfo {
+	handle: string;
+	label?: string; // "bash npm test"
+	turn?: number;
+	totalLines?: number;
+	shownLines?: number;
+	how?: "all" | "grep" | "range" | "page";
+	missing?: boolean;
+}
+
+/** "↺ recall k3x9q2m7ab  grep "Expected"" */
+export function recallCallLine(args: { handle?: string; handles?: string[]; grep?: string; range?: string; offset?: number }, width: number, th: Th, m: Measure = plainMeasure): string[] {
+	const hs = [...(typeof args?.handle === "string" ? [args.handle] : []), ...(Array.isArray(args?.handles) ? args.handles.filter((h) => typeof h === "string") : [])];
+	const what = hs.length > 1 ? `${hs.length} handles` : (hs[0] ?? "");
+	const opt = [args?.grep ? `grep "${args.grep}"` : "", args?.range ? `lines ${args.range}` : "", args?.offset ? `from char ${args.offset}` : ""].filter(Boolean).join(" · ");
+	const plain = m.cut(`↺ recall ${what}${opt ? "  " + opt : ""}`, width);
+	const head = "↺ recall";
+	if (!plain.startsWith(head)) return [th.fg("toolTitle", plain)];
+	return [th.fg("toolTitle", head) + th.fg("accent", plain.slice(head.length, head.length + 1 + what.length)) + th.fg("dim", plain.slice(head.length + 1 + what.length))];
+}
+
+export function sectionLine(s: RecallSectionInfo): string {
+	if (s.missing) return `${s.handle} not found`;
+	const where = [s.label, s.turn ? `turn ${s.turn}` : ""].filter(Boolean).join(" · ");
+	const total = s.totalLines ?? 0;
+	const got = s.how === "all" ? `all ${total} lines` : `${s.shownLines ?? 0} of ${total} lines`;
+	return `${where || s.handle}  ${got}`;
+}
+
+/** Collapsed: one line per handle ("bash npm test · turn 1  3 of 812 lines"). Expanded: the recalled text, at most maxLines. */
+export function recallResultLines(sections: RecallSectionInfo[], text: string, expanded: boolean, width: number, th: Th, m: Measure = plainMeasure, maxLines = 40): string[] {
+	const out: string[] = [];
+	for (const s of sections) {
+		const l = m.cut(sectionLine(s), width);
+		if (l) out.push(s.missing ? th.fg("error", l) : th.fg("dim", l));
+	}
+	if (!sections.length && text) out.push(th.fg("dim", m.cut(clean(text.split("\n")[0]), width)));
+	if (!expanded || !text) return out;
+	const lines = clean(text).split("\n");
+	for (const l of lines.slice(0, maxLines)) out.push(th.fg("toolOutput", m.cut(l, width)));
+	if (lines.length > maxLines) out.push(th.fg("dim", m.cut(`… ${lines.length - maxLines} more lines (the model got them all)`, width)));
+	return out;
+}
+
+// ---- the mark on a folded output ---------------------------------------------------------------------------------------
+
+/** Right-aligns "▸ folded · <handle>" on the first line of a tool call row, if it fits; otherwise leaves the row alone. */
+export function markFirstLine(lines: string[], handle: string, width: number, th: Th, m: Measure = plainMeasure): string[] {
+	if (!lines.length) return lines;
+	const mark = `${MARK}folded · ${handle}`;
+	// renderers often pad a row to the full width (and may close styles after the padding): drop the padding, keep the codes
+	const first = lines[0].replace(/ +((?:\x1b\[[0-9;]*m)*)$/, "$1");
+	const gap = width - m.vw(first) - m.vw(mark);
+	if (gap < 2) return lines;
+	return [first + " ".repeat(gap) + th.fg("dim", mark), ...lines.slice(1)];
+}