pi-zip 0.2.8 → 0.3.0-rc.2

package/src/state.ts

@@ -0,0 +1,53 @@
+// Planner state that is a function of the session: rebuilt from the branch at session start (a restart, a resume, a fork), so a fresh
+// process plans exactly like one that never left (formal/TRIAGE.md (a) 1: growth g, "the newest response carried an edit", and
+// "a summary was made in this warm stretch" lived only in memory).
+import { COMMIT_CUSTOM, PRODUCT, type Any } from "./util.ts";
+
+/** A pi-zip summary that went in through Pi's compaction before a run (the run's first request is the first to carry it). */
+const nativeSummary = (e: Any): boolean => e?.type === "compaction" && e.details?.by === PRODUCT && e.details?.via === "native";
+
+/** For each assistant message of the branch (by branch index): was it the first response to carry a pi-zip edit? A run plan is sent from
+ *  the run's first request and persisted after its response (the commit entry says `carried`); a warm-valve plan, or a summary that went
+ *  in through Pi's compaction, is first carried by the next request. Errors and aborts count: the request was made. */
+export function carriedEdits(branch: Any[]): Set<number> {
+	const edited = new Set<number>();
+	let next = false, last = -1;
+	branch.forEach((e, i) => {
+		if (e?.type === "message" && e.message?.role === "assistant") {
+			if (next) edited.add(i);
+			next = false;
+			last = i;
+		} else if (nativeSummary(e)) next = true;
+		else if (e?.type === "custom" && e.customType === COMMIT_CUSTOM) {
+			if (e.data?.carried && last >= 0) edited.add(last);
+			else if (!e.data?.carried) next = true;
+		}
+	});
+	return edited;
+}
+
+/** Growth per request, as run.ts `learn` accumulates it: EWMA(0.1) of the growth between consecutive responses of one model that
+ *  carried no edit of ours, each capped at the p90 of the last 20 deltas; and whether the newest response was the first to carry an edit. */
+export function replayGrowth(branch: Any[], g0: number): { g: number; deltas: number[]; justEdited: boolean } {
+	const edited = carriedEdits(branch);
+	let g = g0, deltas: number[] = [], prevKey = "", prevTotal = 0, justEdited = false;
+	branch.forEach((e, i) => {
+		const m = e?.type === "message" ? e.message : null;
+		if (m?.role !== "assistant") return;
+		justEdited = edited.has(i);
+		const u = m.usage;
+		if (!u || m.stopReason === "error" || m.stopReason === "aborted") return;
+		const total = (u.input ?? 0) + (u.cacheRead ?? 0) + (u.cacheWrite ?? 0);
+		if (!(total > 0)) return;
+		const key = `${m.provider ?? ""}/${m.model ?? ""}`;
+		if (!edited.has(i) && prevKey === key && prevTotal > 0 && total >= prevTotal) {
+			const d = total - prevTotal;
+			deltas = [...deltas.slice(-19), d];
+			const sorted = [...deltas].sort((a, b) => a - b);
+			g = 0.9 * g + 0.1 * Math.min(d, sorted[Math.ceil(0.9 * sorted.length) - 1]);
+		}
+		prevTotal = total;
+		prevKey = key;
+	});
+	return { g, deltas, justEdited };
+}

package/src/summary.ts

@@ -3,6 +3,7 @@
 import { randomUUID } from "node:crypto";
 import { handleFor, outcomeHint, pickKeyLines, RECALL_TOOL, shortArgs } from "./placeholder.ts";
 import { type Block, type Cut, type PlanResult, settings, toolCallIndex } from "./plan.ts";
+import { type FileRecall, fileRecallHow } from "./recallfile.ts";
 import { type Any, clamp, clip, textOf, tok4 } from "./util.ts";
 
 export const SUMMARY_MARK = "[summary of earlier conversation by pi-zip]";
@@ -21,6 +22,8 @@ export interface HandleRow {
 }
 
 const TABLE_HEAD = "## Folded outputs (originals recallable with zip_recall; handles stay valid after later summaries or compaction)";
+/** The same heading when zip_recall is hidden and the originals are read from recall files (parseSummary keys on "## Folded outputs"). */
+const tableHead = (file?: FileRecall) => (file ? `## Folded outputs (originals in ${file.dir}/<handle>.txt; handles stay valid after later summaries or compaction)` : TABLE_HEAD);
 const TABLE_ROWS = 40;
 const tableLine = (r: HandleRow) => `- ${r.handle} · ${r.tool}${r.args ? " " + r.args : ""}${r.turn ? ` · turn ${r.turn}` : ""}${r.outcome ? ` · ${r.outcome}` : ""} · ${clip(r.hint, 90)}`;
 
@@ -28,12 +31,12 @@ const tableLine = (r: HandleRow) => `- ${r.handle} · ${r.tool}${r.args ? " " +
  * Compact table appended to every summary so handles survive it: this prefix's rows merged with the rows of the previous summary's
  * table(s) (hints and outcomes kept), newest TABLE_ROWS rows, each handle once, and a count of the older rows left out.
  */
-export function handleTable(rows: HandleRow[], previous: string | null = null): string | null {
+export function handleTable(rows: HandleRow[], previous: string | null = null, file?: FileRecall): string | null {
 	const prev = parseSummary(previous);
 	const merged = mergeItems(prev.table.items, rows.map(tableLine), prev.table.omitted, TABLE_ROWS, Infinity, (l) => TABLE_ROW.exec(l)?.[1]);
 	if (!merged.kept.length) return null;
 	const lines = merged.omitted ? [`[… ${merged.omitted} older folded outputs omitted from this table …]`, ...merged.kept] : merged.kept;
-	return TABLE_HEAD + "\n" + lines.join("\n");
+	return tableHead(file) + "\n" + lines.join("\n");
 }
 
 /** Keep the newest `n` lines and say how many older ones were left out (never a silent drop). */
@@ -93,7 +96,7 @@ export function handleRowsOf(text: string | null): IndexRow[] {
  * Handles of the tool results the summary would otherwise lose: this prefix's results and the earlier summary's rows, newest first,
  * minus handles already written elsewhere in the summary, under a token budget. Says how many rows did not fit.
  */
-function handleIndex(now: IndexRow[], previous: string | null, listed: string, budgetTokens: number): string | null {
+function handleIndex(now: IndexRow[], previous: string | null, listed: string, budgetTokens: number, file?: FileRecall): string | null {
 	const seen = new Set<string>(listed.match(new RegExp(`\\b${H}\\b`, "g")) ?? []);
 	const rows: IndexRow[] = [];
 	for (const r of [...now].reverse().concat(handleRowsOf(previous).reverse())) {
@@ -102,7 +105,7 @@ function handleIndex(now: IndexRow[], previous: string | null, listed: string, b
 		rows.push({ ...r, args: clip(r.args, 60) });
 	}
 	if (!rows.length) return null;
-	const head = `${INDEX_HEAD} (older outputs, newest first; zip_recall with a handle returns the original)`;
+	const head = `${INDEX_HEAD} (older outputs, newest first; ${file ? `${file.dir}/<handle>.txt holds the original` : "zip_recall with a handle returns the original"})`;
 	let used = tok4(head) + 12; // 12: the "not listed" line
 	const lines: string[] = [];
 	for (const r of rows) {
@@ -321,7 +324,7 @@ const list = (title: string, m: { kept: string[]; omitted: number }, marker: str
  * merged from the previous summary `previous` (any format) and this prefix. `tableText` = the folded-outputs table the caller will
  * append, so the index does not repeat its handles.
  */
-export function skeleton(prefix: Block[], previous: string | null, tableText = ""): { text: string; users: number } {
+export function skeleton(prefix: Block[], previous: string | null, tableText = "", file?: FileRecall): { text: string; users: number } {
 	const calls = toolCallIndex(prefix);
 	const results = new Map<string, Block>();
 	for (const b of prefix) if (b.kind === "toolResult") results.set(b.msg.toolCallId, b);
@@ -377,7 +380,13 @@ export function skeleton(prefix: Block[], previous: string | null, tableText = "
 	const mo = mergeItems(prev.others.items, others, prev.others.omitted, BUDGET.lines, BUDGET.others);
 	const me = mergeItems(prev.errors.items, errors, prev.errors.omitted, BUDGET.errorLines, BUDGET.errors);
 	const out: string[] = [SUMMARY_MARK];
-	out.push(`Covers ${prefix.length} earlier messages. Tool outputs in the kept part of the conversation may have been folded; call zip_recall with a handle to get one back exactly.`);
+	out.push(
+		file
+			? `Covers ${prefix.length} earlier messages. Their tool outputs are no longer in your context but are kept exactly: the 10-character code next to a command, file or call below is its handle, and ${file.dir}/<handle>.txt holds that output. ` +
+					`To use what an output said, ${fileRecallHow(file)}${file.grep || file.bash ? ` (grep over ${file.dir} searches every earlier output)` : ""} rather than re-running or re-reading (results may differ). Folded blocks later in the conversation work the same way.`
+			: `Covers ${prefix.length} earlier messages. Their tool outputs are no longer in your context but are kept exactly: the 10-character code next to a command, file or call below is its handle. ` +
+					`To use what an output said, ${RECALL_TOOL} it (grep/range for a part; grep alone searches every earlier output) rather than re-running or re-reading (results may differ). Folded blocks later in the conversation work the same way.`,
+	);
 	out.push(USERS_HEAD);
 	if (mu.omitted) out.push(`[… ${mu.omitted} older requests omitted …]`);
 	out.push(...(userLines.length ? userLines : [NONE_ROW]));
@@ -385,7 +394,7 @@ export function skeleton(prefix: Block[], previous: string | null, tableText = "
 	out.push(...list("## Commands run (with exit status)", mc, "older omitted"));
 	if (mo.kept.length) out.push(...list("## Other tool calls (turn, handle)", mo, "older omitted"));
 	out.push(...list("## Errors", me, "older omitted"));
-	const index = handleIndex(now, previous, out.join("\n") + "\n" + tableText, INDEX_TOKENS);
+	const index = handleIndex(now, previous, out.join("\n") + "\n" + tableText, INDEX_TOKENS, file);
 	if (index) out.push(index);
 	const foreign = !prev.structured;
 	const narr = prev.narrative.join("\n\n");
@@ -477,12 +486,14 @@ export async function buildCut(p: PlanResult, ctx: Any, signal?: AbortSignal): P
 			const tool = call?.name ?? b.msg.toolName ?? "tool";
 			return { handle: handleFor(b.entryId!), tool, args: call ? shortArgs(call.args) : "", turn: b.userTurn, outcome: outcomeHint(textOf((b.raw ?? b.msg).content), tool, !!b.msg.isError), hint: (keys.find((k) => k.why === "error" || k.why === "id") ?? keys[0])?.text ?? "" };
 		});
-	const table = handleTable(rows, prev);
-	const sk = skeleton(prefix.filter((b) => b.kind !== "summary"), prev, table ?? "");
+	const file = p.fileRecall; // zip_recall hidden by an allowlist: the summary names the recall files instead
+	const table = handleTable(rows, prev, file);
+	const sk = skeleton(prefix.filter((b) => b.kind !== "summary"), prev, table ?? "", file);
 	const nb = clamp(p.summaryTokensPlanned - tok4(sk.text), 300, 4000);
 	const nar = await narrative(prefix, ctx, nb, signal);
 	let text = sk.text;
-	text += nar.ok && nar.text ? `\n## Narrative (model-written)\n${nar.text.slice(0, nb * 6)}` : `\n## Narrative\n(unavailable: ${nar.error ?? "n/a"}; rely on the sections above and re-read files as needed)`;
+	const how = file ? `read an output's file by its handle (${file.dir}/<handle>.txt)` : `${RECALL_TOOL} an output by its handle`;
+	text += nar.ok && nar.text ? `\n## Narrative (model-written)\n${nar.text.slice(0, nb * 6)}` : `\n## Narrative\n(unavailable: ${nar.error ?? "n/a"}; rely on the sections above and ${how} rather than re-running or re-reading)`;
 	if (table) text += "\n" + table;
 	return {
 		firstKeptEntryId: p.blocks[p.cutIdx!].entryId!,
@@ -496,5 +507,6 @@ export async function buildCut(p: PlanResult, ctx: Any, signal?: AbortSignal): P
 		costUsd: nar.costUsd,
 		usage: nar.usage,
 		ms: Math.round(performance.now() - t0),
+		...(p.ahead ? { ahead: true } : {}),
 	};
 }

package/src/ui.ts

@@ -1,10 +1,13 @@
 // 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.
+// One visual grammar everywhere: the monogram ƶ (bold, accent) says whose line it is, the words zip / zipped / unzip say what
+// happened, the one bright thing is the size now; everything else is dim, no boxes, no other symbols.
+// Collapsed = the conclusion, click or ctrl+o = the detail. Every returned line fits the given width.
+// ƶ (U+01B6) is a Latin letter: East Asian width N, so one column in every terminal and locale; fonts without it fall back.
 import { PRODUCT } from "./util.ts";
 
 export interface Th {
 	fg(color: string, text: string): string;
+	bold?(text: string): string;
 }
 /** Display width and truncation: Pi's visibleWidth / truncateToWidth in the renderer, string length in tests. */
 export interface Measure {
@@ -21,8 +24,9 @@ export function setMeasure(m: Measure) {
 	measure = m;
 }
 
-export const MARK = "▸ ";
-const HEAD = MARK + PRODUCT;
+/** The pi-zip monogram: z for zip, the stroke is the slider. */
+export const SYM = "ƶ";
+export const brand = (th: Th): string => th.fg("accent", th.bold ? th.bold(SYM) : SYM);
 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. */
@@ -33,25 +37,31 @@ export const clean = (s: string): string => s.replace(/\t/g, "  ").replace(/\x1b
 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" */
+/** "ƶ 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}`;
+	const wordC = th.fg(WARN.has(word) ? "warning" : word === "on" ? "success" : "muted", word);
+	const base = `${SYM} ${PRODUCT}  ${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) : ""}`];
+	return [`${brand(th)} ${th.fg("muted", PRODUCT)}  ${wordC}${r ? "  " + th.fg("dim", r) : ""}`];
 }
 
 // ---- status card ------------------------------------------------------------------------------------------------------
 
+/** One learned gap bin of the cache chart: how many times you came back after a gap in [lo, hi) s and the cache was still there / gone.
+ *  Counts are rounded decayed weights (learn.ts keeps no raw per-bin count: old evidence halves after HALF_LIFE newer ones of the bin). */
+export interface ChartBin { lo: number; hi: number; alive: number; gone: number }
+
 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
+	life?: string; // "~5 min" | "~1 h" | "2 h+": how long the cache outlives the last reply (the declared TTL until something is learned)
+	bins?: ChartBin[]; // learned bins that round to at least one return; none = nothing learned yet: one line, no chart
+	s1?: number; // seconds: the cache is (nearly) always still there under this (learned curve, never the prior)
+	s2?: number; // seconds: it is mostly gone from here on; between s1 and s2 it is not sure yet
+	usually?: boolean; // some bin under s1 has P(still there) < 0.95: "usually still there" instead of "still there"
 	folds: number;
 	foldedTokens: string; // "310K"
 	summaries: number;
@@ -59,41 +69,191 @@ export interface CardData {
 	recalls: number;
 	last?: string; // "10:50  folded 12 old outputs · cache cold (away 47 min)"
 	quiet: boolean;
+	unzip?: string; // how the model gets folded outputs back, when it is not zip_recall (file recall under a tool allowlist)
 }
 
-/** 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`;
+	if (Math.round(s / 60) < 60) return `~${Math.round(s / 60)} min`;
 	return `~${+(s / 3600).toFixed(1)} h`;
 }
 
+// ---- the cache chart: one dot per time you came back ----------------------------------------------------------------------
+// Across: how long you were away, 30 s to 2 h on a log scale. Above the axis (accent): the times the cache was still there, below
+// (dim): the times it was gone. The axis itself says what to expect: solid while it is (nearly) always there, dashed while not sure,
+// thin after it is gone. A column shows at most STACK_CAP marks; beyond that STACK_CAP - 1 dots and then the count.
+
+export const CHART_W = 60; // columns 0..CHART_W
+const CT0 = 30, CT1 = 7200;
+export const STACK_CAP = 4;
+const IND = 11; // the values column of the card: "  " + the 9-wide label
+export const colW = (s: number): number => Math.round((CHART_W * Math.log(s / CT0)) / Math.log(CT1 / CT0));
+const gapW = (c: number): number => CT0 * (CT1 / CT0) ** (c / CHART_W);
+const AXIS_TICKS: [number, string][] = [[30, "30s"], [60, "1m"], [120, "2m"], [300, "5m"], [600, "10m"], [1800, "30m"], [3600, "1h"], [7200, "2h"]];
+const fmtGap = (s: number): string => (s < 60 ? `${Math.round(s)} s` : s < 3600 ? `${+(s / 60).toFixed(1)} min` : `${+(s / 3600).toFixed(1)} h`);
+
+/** What the marks of one side of the axis look like, as rows from the axis outwards: row r (1-based) holds, per column, a dot, a digit of
+ *  the count or a blank. `items` are (column, times); items on the same column merge. A count is drawn on the row of the stack's end,
+ *  centred on its column; when that would touch another mark in its row (neighbouring columns, other counts) it moves, the nearest free
+ *  place first, right before left, and keeps one blank on each side, so two counts never read as one number. Deterministic. */
+export function stackRows(items: { col: number; n: number }[], dot: string = "\u25cf", cap: number = STACK_CAP, width: number = CHART_W + 1): { rows: string[][]; height: number } {
+	const merged = new Map<number, number>();
+	for (const it of items) {
+		const col = Math.max(0, Math.min(width - 1, it.col));
+		if (it.n > 0) merged.set(col, (merged.get(col) ?? 0) + it.n);
+	}
+	const cols = [...merged.entries()].sort((a, b) => a[0] - b[0]);
+	const height = Math.max(1, ...cols.map(([, n]) => Math.min(n, cap)));
+	const rows = Array.from({ length: height }, () => Array<string>(width).fill(" "));
+	const counts: { col: number; text: string; row: number }[] = [];
+	for (const [col, n] of cols) {
+		const dots = n <= cap ? n : cap - 1;
+		for (let r = 0; r < dots; r++) rows[r][col] = dot;
+		if (n > cap) counts.push({ col, text: String(n), row: cap - 1 });
+	}
+	for (const { col, text, row } of counts) {
+		const len = text.length, want = col - Math.floor((len - 1) / 2), line = rows[row];
+		const free = (st: number, gap: boolean) => {
+			if (st < 0 || st + len > width) return false;
+			for (let x = st - (gap ? 1 : 0); x < st + len + (gap ? 1 : 0); x++) if (x >= 0 && x < width && line[x] !== " ") return false;
+			return true;
+		};
+		let at = -1;
+		for (const gap of [true, false]) {
+			for (let d = 0; d < width && at < 0; d++) for (const st of d ? [want + d, want - d] : [want]) if (at < 0 && free(st, gap)) at = st;
+			if (at >= 0) break;
+		}
+		if (at >= 0) for (let k = 0; k < len; k++) line[at + k] = text[k];
+	}
+	return { rows, height };
+}
+
+/** Colours the cells of a row (one string per column, null = blank) with as few runs as possible. */
+function paint(cells: { ch: string; color: string }[], th: Th): string {
+	let out = "", run = "", color = "";
+	const flush = () => { if (run) out += color ? th.fg(color, run) : run; run = ""; };
+	for (const c of cells) {
+		if (c.color !== color) flush(), (color = c.color);
+		run += c.ch;
+	}
+	flush();
+	return out.trimEnd();
+}
+
+interface Seg { lead: string; word: string; color: string }
+/** "under 5 min: usually still there · 5–10 min: not sure yet · over 10 min: gone", as segments that wrap whole. */
+function captionSegs(c: CardData): Seg[] {
+	const s1 = c.s1 ?? CT0, s2 = c.s2 ?? CT1;
+	const range = s1 >= 60 && s2 < 3600 ? `${+(s1 / 60).toFixed(1)}–${fmtGap(s2)}` : `${fmtGap(s1)}–${fmtGap(s2)}`; // "5–10 min"
+	return [
+		{ lead: `under ${fmtGap(s1)}: `, word: c.usually ? "usually still there" : "still there", color: "accent" },
+		...(s2 > s1 ? [{ lead: `${range}: `, word: "not sure yet", color: "warning" }] : []),
+		{ lead: `over ${fmtGap(s2)}: `, word: "gone", color: "muted" },
+	];
+}
+const SEP = "  \u00b7  ";
+const segW = (g: Seg) => g.lead.length + g.word.length;
+/** The caption as lines of at most `room` columns, wrapped between segments (a segment wider than the room is cut). */
+function captionLines(segs: Seg[], room: number, th: Th, m: Measure): string[] {
+	if (room < 2) return []; // no room for even a cut sentence
+	const lines: Seg[][] = [[]];
+	for (const g of segs) {
+		const cur = lines[lines.length - 1], w = cur.reduce((a, x) => a + segW(x), 0) + SEP.length * cur.length + segW(g);
+		if (cur.length && w > room) lines.push([g]);
+		else cur.push(g);
+	}
+	return lines.map((l) => {
+		const plain = l.map((g) => g.lead + g.word).join(SEP);
+		if (plain.length > room) return th.fg("dim", m.cut(plain, room));
+		return l.map((g) => th.fg("dim", g.lead) + th.fg(g.color, g.word)).join(th.fg("dim", SEP));
+	});
+}
+const captionPlain = (c: CardData) => captionSegs(c).map((g) => g.lead + g.word).join(SEP);
+
+const idle = (c: CardData): string => (c.life ? `expires after ${c.life} idle` : "");
+const NO_DATA = "a chart appears once you come back after a break";
+const hasChart = (c: CardData): boolean => !!c.model && !!c.bins?.length;
+
 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`]);
+	if (c.model) rows.push(["model", c.model]);
+	if (c.model) rows.push(["cache", hasChart(c) ? `each dot is one time you came back · ${captionPlain(c)}` : `${idle(c) || "expires after ~5 min idle"} · ${NO_DATA}`]);
 	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")}`]);
+	rows.push(["session", `${c.folds} zipped ~${c.foldedTokens}  ·  ${n(c.summaries, "summary", "summaries")}${c.summaryUsd > 0 ? ` $${c.summaryUsd.toFixed(2)}` : ""}  ·  ${n(c.recalls, "unzip")}`]);
 	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" : ""}`]);
+	if (c.unzip) rows.push(["unzip", c.unzip]);
+	if (c.quiet) rows.push(["notices", "off  (/zip quiet turns them back on)"]); // the default says nothing, so it is not shown
 	return rows.map(([k, v]) => `${k.padEnd(LABEL_W)}${v}`);
 }
 
+/** The chart rows (without the model row): header, marks above, axis, marks below, axis labels, [legend], caption. */
+function chartRows(c: CardData, width: number, th: Th, m: Measure): string[] {
+	const indent = "  ", label = (k: string) => th.fg("dim", (indent + k).padEnd(indent.length + LABEL_W)), pad = " ".repeat(IND);
+	const bins = c.bins ?? [];
+	const na = bins.reduce((a, b) => a + b.alive, 0), nd = bins.reduce((a, b) => a + b.gone, 0);
+	const up = stackRows(bins.map((b) => ({ col: colW(Math.sqrt(b.lo * b.hi)), n: b.alive })));
+	const down = stackRows(bins.map((b) => ({ col: colW(Math.sqrt(b.lo * b.hi)), n: b.gone })), "\u25cb");
+	const legUp = ["\u25cf", ` still there  ${na}`], legDown = ["\u25cb", ` gone  ${nd}`];
+	const legW = (l: string[]) => l[0].length + l[1].length;
+	const beside = width >= IND + CHART_W + 1 + 3 + Math.max(legW(legUp), legW(legDown));
+	const s1 = c.s1 ?? CT0, s2 = c.s2 ?? CT1;
+	const out: string[] = [label("cache") + th.fg("dim", "each dot is one time you came back")];
+	const side = (rows: string[][], color: string, leg: string[], first: number) =>
+		rows.map((cells, r) => {
+			const line = paint(cells.map((ch) => ({ ch, color: ch === " " ? "" : color })), th);
+			return pad + line + (beside && r === first ? "   " + th.fg(color, leg[0]) + th.fg("muted", leg[1]) : "");
+		});
+	out.push(...side(up.rows.slice().reverse(), "accent", legUp, up.height - 1)); // outermost row first; the legend sits on the row next to the axis
+	out.push(pad + paint(Array.from({ length: CHART_W + 1 }, (_, i) => ({ ch: gapW(i) < s1 ? "\u2501" : gapW(i) < s2 ? "\u2505" : "\u2500", color: gapW(i) < s1 ? "accent" : gapW(i) < s2 ? "warning" : "dim" })), th));
+	out.push(...side(down.rows, "dim", legDown, 0));
+	const ax = Array<string>(CHART_W + 3).fill(" ");
+	for (const [t, lab] of AXIS_TICKS) {
+		const col = Math.min(colW(t), CHART_W - lab.length + 1);
+		for (let k = 0; k < lab.length; k++) ax[col + k] = lab[k];
+	}
+	out.push(label("away") + th.fg("dim", ax.join("").trimEnd()));
+	if (!beside) out.push(pad + th.fg("accent", legUp[0]) + th.fg("muted", legUp[1]) + "   " + th.fg("dim", legDown[0]) + th.fg("muted", legDown[1]));
+	for (const l of captionLines(captionSegs(c), width - IND, th, m)) out.push(pad + l);
+	return out;
+}
+
 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);
+	const indent = "  "; // under the words after the monogram
+	const head = (k: string) => th.fg("dim", (indent + k).padEnd(indent.length + LABEL_W));
+	const row = (k: string, v: string) => {
+		const line = m.cut(indent + k.padEnd(LABEL_W) + v, width);
+		if (!line) return;
+		const kk = line.slice(0, indent.length + LABEL_W);
+		out.push(th.fg("dim", kk) + th.fg("dim", line.slice(kk.length)));
+	};
+	if (c.model) {
+		row("model", c.model);
+		if (!hasChart(c)) {
+			// nothing learned yet: one line, the chart appears with the first return after a break
+			const room = width - indent.length - LABEL_W;
+			const v = [`${idle(c) || "expires after ~5 min idle"} \u00b7 ${NO_DATA}`, idle(c) || "expires after ~5 min idle"].find((x) => m.vw(x) <= room);
+			if (v) out.push(head("cache") + th.fg("dim", v));
+			else row("cache", idle(c) || "expires after ~5 min idle");
+		} else if (width >= IND + CHART_W + 1) out.push(...chartRows(c, width, th, m));
+		else {
+			// too narrow for the chart: the caption sentence alone says the same thing
+			const lines = captionLines(captionSegs(c), width - IND, th, m);
+			lines.forEach((l, i) => out.push((i ? " ".repeat(IND) : head("cache")) + l));
+		}
+	}
+	for (const r of cardText({ ...c, model: undefined })) {
+		if (r.startsWith("unzip ")) {
+			// Narrow: the bracketed reason goes first, so where the files are stays whole.
+			const h = head("unzip"), room = width - m.vw(h);
+			const v = [r.slice(LABEL_W), r.slice(LABEL_W).replace(/ \([^()]*\)$/, "")].find((x) => m.vw(x) <= room);
+			if (v) { out.push(th.fg("dim", h + v)); continue; }
+		}
+		const line = m.cut(indent + r, 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)));
+		out.push(th.fg("dim", k) + (r.startsWith("session") ? th.fg("text", v) : th.fg("dim", v)));
 	}
 	return out;
 }
@@ -110,35 +270,42 @@ export interface RecallSectionInfo {
 	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[] {
+/** "ƶ unzip src/learn.ts:1-2000  /HALF_LIFE/": the same shape as Pi's own tool rows (bold name, accent argument) after the monogram;
+ *  the argument says WHAT comes back (the folded output's label), not its handle. `labelOf` maps a handle to that label when known. */
+export function recallCallLine(args: { handle?: string; handles?: string[]; grep?: string; range?: string; offset?: number }, width: number, th: Th, m: Measure = plainMeasure, labelOf: (h: string) => string | undefined = () => undefined): 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))];
+	const label = (h: string) => (labelOf(h.trim()) ?? h).replace(/^read /, ""); // "read src/a.ts" reads as "unzip src/a.ts"
+	const what = hs.length > 1 ? `${hs.length} outputs` : hs[0] ? label(hs[0]) : args?.grep ? "all outputs" : ""; // grep without a handle searches every output
+	const opt = [args?.grep ? `/${args.grep}/` : "", args?.range ? `lines ${args.range}` : "", args?.offset ? `from char ${args.offset}` : ""].filter(Boolean).join(" · ");
+	const head = `${SYM} unzip`;
+	const plain = m.cut(`${head} ${what}${opt ? "  " + opt : ""}`, width);
+	const bold = (t: string) => (th.bold ? th.bold(t) : t);
+	if (!plain.startsWith(head + " ")) return [th.fg("dim", plain)];
+	const w = plain.slice(head.length + 1, head.length + 1 + what.length);
+	return [brand(th) + " " + th.fg("toolTitle", bold("unzip")) + " " + th.fg("accent", w) + th.fg("dim", plain.slice(head.length + 1 + w.length))];
 }
 
-export function sectionLine(s: RecallSectionInfo): string {
+export function sectionLine(s: RecallSectionInfo, many = false): 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}`;
+	return many ? `${s.label || s.handle}  ${got}` : got;
 }
 
-/** Collapsed: one line per handle ("bash npm test · turn 1  3 of 812 lines"). Expanded: the recalled text, at most maxLines. */
+const RECALL_FRAME = /^\[(handle \S+( · |\]| not found)|grep( \(|: | over )|range: lines |chars \d+-\d+ of |… \d+ more chars: )/;
+
+/** Collapsed: what came back ("2 of 142 lines"; one line per output for a batch). 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);
+		const l = m.cut(sectionLine(s, sections.length > 1), 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");
+	// the model's framing lines ("[handle … · 117 lines]", "[grep: 0 matching line(s) of 117]", page notes) repeat the row above: the user sees only the text
+	const lines = clean(text).split("\n").filter((l) => !RECALL_FRAME.test(l));
+	if (!lines.some((l) => l.trim())) return out;
 	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;
@@ -146,13 +313,14 @@ export function recallResultLines(sections: RecallSectionInfo[], text: string, e
 
 // ---- 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. */
+/** "$ npm test  ƶ zipped": the mark follows the call row's own text, if it fits; otherwise the row is left 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}`;
+	// the handle is in the notice (click / ctrl+o) and in the model's view; here it would only be noise
 	// 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)];
+	const markW = 2 + m.vw(`${SYM} zipped`);
+	if (m.vw(first) + markW > width) return lines;
+	const pad = width - m.vw(first) - markW; // keep the row as wide as it was (Pi pads rows to the full width)
+	return [first + "  " + brand(th) + th.fg("dim", " zipped") + " ".repeat(pad), ...lines.slice(1)];
 }

package/src/util.ts

@@ -3,6 +3,13 @@ export type Any = any;
 
 export const PRODUCT = "pi-zip";
 
+/** Custom session entry pi-zip appends after the edits (context_edit / compaction) it persists at a turn_end: `{ carried }` says whether
+ *  the request(s) of the run had already sent them (a run plan: persisted after the response that first carried it) or whether the next
+ *  request is the first to carry them (a warm-valve plan). The edits alone do not say which, and the planner's state (growth, "the
+ *  newest response carried an edit", the size scale) is read from the branch, so a restart plans like a process that never left.
+ *  Custom entries never reach the model. */
+export const COMMIT_CUSTOM = "pi-zip/commit";
+
 export const textOf = (c: Any): string =>
 	typeof c === "string" ? c : Array.isArray(c) ? c.filter((b: Any) => b?.type === "text").map((b: Any) => b.text ?? "").join("\n") : "";
 
@@ -25,17 +32,65 @@ const IMAGE_CHARS = 4800;
 const contentChars = (c: Any): number =>
 	typeof c === "string" ? c.length : Array.isArray(c) ? c.reduce((a: number, b: Any) => a + (b?.type === "text" ? (b.text?.length ?? 0) : b?.type === "image" ? IMAGE_CHARS : 0), 0) : 0;
 
-/** chars/4 estimate, same rules as Pi's estimateTokens (kept local so plan.ts has no runtime Pi dependency). */
+/** Pi's own estimateTokens (core/compaction/compaction.js), rule for rule: no tool framing, system messages counted. Used only to predict
+ *  what Pi's compaction will decide (plan.ts piCanCompact); every pi-zip size uses tokensOf. */
+export function piTokensOf(m: Any): number {
+	let chars = 0;
+	switch (m?.role) {
+		case "system":
+			chars = contentChars(m.content);
+			for (const s of Object.values(m.sections ?? {})) if (typeof s === "string" && s) chars += s.length;
+			if (m.toolsAdded) chars += JSON.stringify(m.toolsAdded).length;
+			break;
+		case "user":
+		case "custom":
+		case "toolResult":
+			chars = contentChars(m.content);
+			break;
+		case "assistant":
+			for (const b of m.content ?? []) {
+				if (b?.type === "text") chars += b.text?.length ?? 0;
+				else if (b?.type === "thinking") chars += b.thinking?.length ?? 0;
+				else if (b?.type === "toolCall") chars += (b.name?.length ?? 0) + (JSON.stringify(b.arguments ?? {}) ?? "").length;
+			}
+			break;
+		case "bashExecution":
+			chars = (m.command?.length ?? 0) + (m.output?.length ?? 0);
+			break;
+		case "branchSummary":
+		case "compactionSummary":
+			chars = m.summary?.length ?? 0;
+			break;
+		default:
+			return 0;
+	}
+	return Math.ceil(chars / 4);
+}
+
+/** What every tool call puts on the wire that Pi's chars/4 rule does not see, in chars: the call id (in the call and again in its
+ *  result) and this much framing per block (the provider's tool-use / tool-result markup). It does not shrink when the output is
+ *  folded, so without it the size after a deep fold came out low: Tier1 fold plans that removed over half the content, median
+ *  -9.5% / -7.0% / -10.9% (Claude / GLM / GPT) -> -0.2% / -2.7% / -2.0% with 120 (research round5/affine.md section 8). */
+export const TOOL_FRAME_CHARS = 120;
+
+/** chars/4 estimate of a message's CONTENT as the wire carries it: Pi's estimateTokens rules (kept local so plan.ts has no runtime
+ *  Pi dependency) plus each tool block's id and framing (TOOL_FRAME_CHARS). A system message counts 0: the system prompt and the tools
+ *  are the fixed prefix O of plan.ts, never content. */
 export function tokensOf(m: Any): number {
 	let chars = 0;
 	switch (m?.role) {
+		case "system":
+			return 0;
 		case "assistant":
 			for (const b of m.content ?? []) {
 				if (b?.type === "text") chars += b.text?.length ?? 0;
 				else if (b?.type === "thinking") chars += b.thinking?.length ?? 0;
-				else if (b?.type === "toolCall") chars += (b.name?.length ?? 0) + JSON.stringify(b.arguments ?? {}).length;
+				else if (b?.type === "toolCall") chars += (b.name?.length ?? 0) + JSON.stringify(b.arguments ?? {}).length + String(b.id ?? "").length + TOOL_FRAME_CHARS;
 			}
 			break;
+		case "toolResult":
+			chars = contentChars(m.content) + String(m.toolCallId ?? "").length + TOOL_FRAME_CHARS;
+			break;
 		case "bashExecution":
 			chars = (m.command?.length ?? 0) + (m.output?.length ?? 0);
 			break;
@@ -48,3 +103,8 @@ export function tokensOf(m: Any): number {
 	}
 	return Math.ceil(chars / 4);
 }
+
+/** Custom session entry pi-zip appends right before the prompt of a cold return. A warm plan holds back what that return protected
+ *  (plan.ts FOLD_HOLD); the entry makes the return a fact of the session, so a restart reads it instead of guessing from timestamps at
+ *  the TTL's edge. Custom entries never reach the model. */
+export const COLD_CUSTOM = "pi-zip/cold";