pi-zip 0.2.7 → 0.3.0-rc.1

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,14 +37,14 @@ 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 ------------------------------------------------------------------------------------------------------
@@ -49,9 +53,9 @@ 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
+	measured?: boolean; // life comes from this provider's own replies, not the declared TTL
+	alive?: number[]; // P(cache still there) after being away chartGap(i), one per chart column
 	folds: number;
 	foldedTokens: string; // "310K"
 	summaries: number;
@@ -59,42 +63,93 @@ 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 column per time away, log-spaced from 30 s to 2 h. The row labels are the axes ("cache" up, "away" across),
+ *  so it reads like any chart; the bars still there are in the accent colour, the dead ones dim. */
+export const CHART_COLS = 32;
+const CHART_T0 = 30, CHART_T1 = 7200;
+export const chartGap = (i: number): number => CHART_T0 * (CHART_T1 / CHART_T0) ** (i / (CHART_COLS - 1));
+const chartCol = (s: number): number => Math.round(((CHART_COLS - 1) * Math.log(s / CHART_T0)) / Math.log(CHART_T1 / CHART_T0));
+const BARS = "▁▂▃▄▅▆▇█";
+const TICKS: [number, string][] = [[60, "1m"], [300, "5m"], [900, "15m"], [3600, "1h"], [7200, "2h"]];
+const bar = (p: number): string => BARS[Math.max(0, Math.min(7, Math.round(p * 7)))];
+const ALIVE = 0.5; // a bar at or above this is drawn as still there
+
+/** "1m      5m      15m      1h  2h": tick labels start at their column. */
+export function chartAxis(): string {
+	const s = Array<string>(CHART_COLS + 2).fill(" ");
+	for (const [t, lab] of TICKS) {
+		const c = Math.min(chartCol(t), CHART_COLS - lab.length + 1);
+		if (s.slice(Math.max(0, c - 1), c + lab.length + 1).every((x) => x === " ")) s.splice(c, lab.length, ...lab);
+	}
+	return s.join("").trimEnd();
+}
+
+const lifeText = (c: CardData): string => (c.life ? `expires after ${c.life} idle${c.measured ? " (measured)" : ""}` : "");
+
 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`]);
+	// One fact the user can act on ("come back within ~5 min and nothing is touched"), drawn and said: no classes, no jargon.
+	if (c.model && c.alive?.length) rows.push(["model", c.model], ["cache", `${c.alive.map(bar).join("")}  ${lifeText(c)}`.trimEnd()], ["away", chartAxis()]);
+	else if (c.model) rows.push(["cache", `${c.model}${c.life ? ` · ${lifeText(c)}` : ""}`]);
 	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}`);
 }
 
 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 = "  ";
+	const indent = "  "; // under the words after the monogram
+	// Too narrow for the chart and its axis: the sentence alone says the same thing.
+	if (c.alive?.length && width < indent.length + LABEL_W + Math.max(c.alive.length, chartAxis().length)) c = { ...c, alive: undefined };
+	let under = "";
 	for (const row of cardText(c)) {
+		if (under && !row.startsWith("away ")) out.push(under), (under = "");
+		if (c.alive?.length && row.startsWith("cache ")) {
+			const runs: string[] = [];
+			for (let i = 0; i < c.alive.length; ) {
+				const on = c.alive[i] >= ALIVE;
+				let j = i;
+				while (j < c.alive.length && c.alive[j] >= ALIVE === on) j++;
+				runs.push(th.fg(on ? "accent" : "dim", c.alive.slice(i, j).map(bar).join("")));
+				i = j;
+			}
+			// The sentence goes beside the bars when it fits there whole, else on its own line under the axis: never cut mid-fact.
+			const say = lifeText(c), beside = m.vw(say) <= width - indent.length - LABEL_W - c.alive.length - 2;
+			out.push(th.fg("dim", (indent + "cache").padEnd(indent.length + LABEL_W)) + runs.join("") + (say && beside ? "  " + th.fg("dim", say) : ""));
+			if (say && !beside) under = th.fg("dim", m.cut(" ".repeat(indent.length + LABEL_W) + say, width));
+			continue;
+		}
+		if (!c.alive?.length && c.model && c.life && row.startsWith("cache ")) {
+			// Narrow: keep the fact whole, dropping the model name first, then "(measured)".
+			const head = (indent + "cache").padEnd(indent.length + LABEL_W), room = width - m.vw(head);
+			const v = [row.slice(LABEL_W), lifeText(c), lifeText({ ...c, measured: false })].find((x) => m.vw(x) <= room);
+			if (v) { out.push(th.fg("dim", head + v)); continue; }
+		}
+		if (row.startsWith("unzip ")) {
+			// Narrow: the bracketed reason goes first, so where the files are stays whole.
+			const head = (indent + "unzip").padEnd(indent.length + LABEL_W), room = width - m.vw(head);
+			const v = [row.slice(LABEL_W), row.slice(LABEL_W).replace(/ \([^()]*\)$/, "")].find((x) => m.vw(x) <= room);
+			if (v) { out.push(th.fg("dim", head + v)); continue; }
+		}
 		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)));
+		out.push(th.fg("dim", k) + (row.startsWith("session") ? th.fg("text", v) : th.fg("dim", v)));
 	}
+	if (under) out.push(under);
 	return out;
 }
 
@@ -110,35 +165,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 +208,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;