pi-zip 0.2.7 → 0.3.0-rc.1

package/src/recall.ts

@@ -1,10 +1,12 @@
 // 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, shortArgs } from "./placeholder.ts";
+import { commandRecallHandles, parseRecallPath } from "./recallfile.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
+const SEARCH_PAGE_CHARS = 8_000; // default page of grep without a handle: a broad pattern over every output stays small (search results are never folded)
 const RECALL_MAX_PAGE_CHARS = 50_000;
 const RECALL_MAX_HITS = 400;
 const GREP_MAX_PATTERN = 256;
@@ -55,7 +57,7 @@ const isLow = (c: number) => c >= 0xdc00 && c <= 0xdfff;
  * Full text, a line range or grep matches of an original, then one page of it by CHARACTERS (offset, limit): a single
  * 45,000-character line is reachable too. Pages never split a surrogate pair, so concatenated pages are the selection byte for byte.
  */
-export function sliceRecall(text: string, opts: { grep?: string; range?: string; offset?: unknown; limit?: unknown }): RecallSlice {
+export function sliceRecall(text: string, opts: { grep?: string; range?: string; offset?: unknown; limit?: unknown; pageChars?: number; narrow?: string }): RecallSlice {
 	const lines = text.split("\n");
 	const totalLines = lines.length;
 	let sel: string;
@@ -83,7 +85,7 @@ export function sliceRecall(text: string, opts: { grep?: string; range?: string;
 		sel = text;
 	}
 	const limitIn = int(opts.limit);
-	const limit = clamp(limitIn ?? RECALL_PAGE_CHARS, 1, RECALL_MAX_PAGE_CHARS);
+	const limit = clamp(limitIn ?? opts.pageChars ?? RECALL_PAGE_CHARS, 1, RECALL_MAX_PAGE_CHARS);
 	let offset = clamp(int(opts.offset) ?? 0, 0, sel.length);
 	if (offset > 0 && offset < sel.length && isLow(sel.charCodeAt(offset))) offset--; // never start inside a surrogate pair
 	let end = Math.min(sel.length, offset + limit);
@@ -93,7 +95,7 @@ export function sliceRecall(text: string, opts: { grep?: string; range?: string;
 	const paged = more || offset > 0;
 	const pageHeader = paged ? `[chars ${offset}-${end} of ${sel.length}${header ? " of the selection" : ""}]\n` : "";
 	const hint = more
-		? `\n[… ${sel.length - end} more chars: call ${RECALL_TOOL} again with offset=${end} for the next page (limit up to ${RECALL_MAX_PAGE_CHARS}), or narrow it with grep or range]`
+		? `\n[… ${sel.length - end} more chars: call ${RECALL_TOOL} again with offset=${end} for the next page (limit up to ${RECALL_MAX_PAGE_CHARS}), or ${opts.narrow ?? "narrow it with grep or range"}]`
 		: "";
 	return { text: header + pageHeader + body + hint, body, totalLines, matched, clipped: more, offset, nextOffset: more ? end : null, selectionChars: sel.length };
 }
@@ -106,6 +108,9 @@ export interface RecallItem {
 	turn?: number;
 }
 
+/** "[handle h · bash npm test · 812 chars · 40 lines]": the call that produced an output, so the model can tell look-alike outputs apart. */
+const sectionHead = (it: RecallItem & { text: string }) => `[handle ${it.handle}${it.label || it.tool ? " · " + (it.label ?? it.tool) : ""} · ${it.text.length} chars · ${it.text.split("\n").length} lines]`;
+
 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[] = [];
@@ -124,33 +129,92 @@ export function recallSections(items: RecallItem[], opts: { grep?: string; range
 		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}`);
+		parts.push(`${sectionHead({ ...it, text: it.text })}\n${slice.text}`);
 	}
 	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);
+/** Every tool output of the session branch (which spans entries before any compaction), oldest first, with the call that produced it. */
+export function branchOutputs(branch: Any[]): Array<RecallItem & { text: string; entryId: string }> {
+	const out: Array<RecallItem & { text: string; entryId: string }> = [];
 	const calls = new Map<string, Any>();
 	let turn = 0;
 	for (const en of branch) {
 		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;
+		if (msg?.role !== "toolResult" || !en.id) continue;
 		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;
+		out.push({ entryId: en.id, handle: handleFor(en.id), text: textOf(msg.content), tool, label: tool ? `${tool}${args ? " " + args : ""}` : undefined, turn: turn || undefined });
+	}
+	return out;
+}
+
+/** Resolve handles against the session branch: 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);
+	for (const o of branchOutputs(branch)) {
+		const k = handles.indexOf(o.handle);
+		if (k < 0) continue;
+		const { entryId, ...it } = o;
+		items[k] = it;
+		entryIds[k] = entryId;
 	}
 	return { items, entryIds };
 }
 
+/**
+ * grep without a handle: every earlier tool output of the branch (zip_recall results excepted), newest output first, each match
+ * under its output's handle and call, then one page by characters (default SEARCH_PAGE_CHARS). For outputs whose handle the model
+ * cannot see any more (a long summary lists only the newest) and for questions that name the content rather than the output.
+ * `upTo` pins the pool to its first n outputs (branch order, oldest first; new outputs only append): a later page of the same search
+ * passes the pool size of its first page, so an output that arrived in between cannot shift the character offsets.
+ */
+export function searchOutputs(outputs: Array<RecallItem & { text: string }>, grep: string, opts: { offset?: unknown; limit?: unknown; upTo?: number } = {}): { text: string; matched: number; hits: number; chars: number; pool: number; sections: RecallSectionInfo[] } {
+	const { re, literal } = grepMatcher(grep);
+	const all = outputs.filter((o) => o.tool !== RECALL_TOOL);
+	const pool = opts.upTo !== undefined && opts.upTo >= 0 && opts.upTo < all.length ? all.slice(0, opts.upTo) : all;
+	const parts: string[] = [];
+	const sections: RecallSectionInfo[] = [];
+	let hits = 0;
+	let stopped = false;
+	const t0 = Date.now();
+	for (let k = pool.length - 1; k >= 0 && !stopped; k--) {
+		const it = pool[k];
+		const lines = it.text.split("\n");
+		const got: string[] = [];
+		for (let i = 0; i < lines.length; i++) {
+			if (hits >= RECALL_MAX_HITS || Date.now() - t0 > GREP_BUDGET_MS) {
+				stopped = true;
+				break;
+			}
+			if (re.test(lines[i])) {
+				got.push(`${i + 1}: ${lines[i]}`);
+				hits++;
+			}
+		}
+		if (!got.length) continue;
+		parts.push(`${sectionHead(it)}\n${got.join("\n")}`);
+		sections.push({ handle: it.handle, label: it.label ?? it.tool ?? undefined, turn: it.turn, totalLines: lines.length, shownLines: got.length, how: "grep" });
+	}
+	const head = `[grep${literal ? " (searched as literal text: the pattern is not a safe regular expression)" : ""} over all ${pool.length} earlier tool outputs (no handle given): ${hits} matching line(s) in ${sections.length} output(s), newest output first${stopped ? "; stopped early (time or hit cap), narrow the pattern or pass a handle" : ""}]\n`;
+	if (!hits) return { text: head + "Nothing matched. Try a shorter or different pattern, or pass the handle shown in a folded block or a summary.", matched: 0, hits, chars: 0, pool: pool.length, sections };
+	const page = sliceRecall(parts.join("\n\n"), { offset: opts.offset, limit: opts.limit, pageChars: SEARCH_PAGE_CHARS, narrow: "narrow the pattern, or pass one of the handles above with grep" });
+	return { text: head + page.text, matched: sections.length, hits, chars: page.body.length, pool: pool.length, sections };
+}
+
+/** The pool size recorded by the newest earlier search with this same pattern (its first page), for a later page of it. */
+export function searchPoolOf(branch: Any[], grep: string): number | undefined {
+	for (let i = branch.length - 1; i >= 0; i--) {
+		const m = branch[i]?.type === "message" ? branch[i].message : null;
+		if (m?.role === "toolResult" && m.toolName === RECALL_TOOL && m.details?.search === grep && typeof m.details.pool === "number") return m.details.pool;
+	}
+	return undefined;
+}
+
 /** Handles the model already recalled in this branch (F4: never refold them). */
 export function recalledHandlesFromBranch(branch: Any[]): Set<string> {
 	const out = new Set<string>();
@@ -158,10 +222,17 @@ export function recalledHandlesFromBranch(branch: Any[]): Set<string> {
 		const m = en?.type === "message" ? en.message : null;
 		if (m?.role !== "assistant" || !Array.isArray(m.content)) continue;
 		for (const c of m.content) {
-			if (c?.type !== "toolCall" || c.name !== RECALL_TOOL) continue;
+			if (c?.type !== "toolCall") continue;
 			const a: Any = c.arguments ?? {};
-			if (typeof a.handle === "string" && a.handle.trim()) out.add(a.handle.trim());
-			if (Array.isArray(a.handles)) for (const h of a.handles) if (typeof h === "string" && h.trim()) out.add(h.trim());
+			if (c.name === RECALL_TOOL) {
+				if (typeof a.handle === "string" && a.handle.trim()) out.add(a.handle.trim());
+				if (Array.isArray(a.handles)) for (const h of a.handles) if (typeof h === "string" && h.trim()) out.add(h.trim());
+			} else if (c.name === "bash") {
+				for (const h of commandRecallHandles(a.command)) out.add(h); // file recall: a shell reading a recall file
+			} else if (c.name === "read" || c.name === "grep") {
+				const h = parseRecallPath(a.path)?.handle; // file recall: read or grep of a recall file
+				if (h) out.add(h);
+			}
 		}
 	}
 	return out;
@@ -169,6 +240,7 @@ export function recalledHandlesFromBranch(branch: Any[]): Set<string> {
 
 export interface RecallHooks {
 	onRecall(handles: string[], chars: number, entryIds: (string | null)[]): void;
+	labelOf?(handle: string): string | undefined; // "read src/learn.ts" for a handle folded in this branch
 }
 
 export function registerRecallTool(pi: ExtensionAPI, hooks: RecallHooks) {
@@ -176,26 +248,27 @@ export function registerRecallTool(pi: ExtensionAPI, hooks: RecallHooks) {
 		name: RECALL_TOOL,
 		label: "Recall folded output",
 		description:
-			"Get back the EXACT original content of tool outputs that pi-zip folded earlier in this session. It is instant, free and has no side effects: " +
-			"prefer it over re-running a command or re-reading a file when you need the exact earlier output (a re-run may give different results). " +
-			"Every folded block shows a handle (10 characters) in its marker line, and summaries carry a handle table; handles stay valid " +
-			"after later summaries or compaction. Pass one handle, or several at once with handles for a batch. " +
-			"The text may be large and comes in pages of characters: prefer grep (case-insensitive regular expression; returns matching lines with their line numbers) " +
-			'or range (e.g. "120-240" for that line range); when a page says more is left, call again with offset to continue. Never guess the content of a folded block.',
+			"Get back the EXACT original of earlier tool outputs of this session that are no longer shown in full: a [folded by pi-zip …] block, or an output " +
+			"listed with a handle in a pi-zip summary. Whenever you need what such an output said, recall it first: it is instant, free and has no side effects, " +
+			"while re-running a command or re-reading a file costs a step and may give a different result. Never guess the content of a folded output. " +
+			"Pass its handle (10 characters, from the block's marker line or the summary; handles stay valid after later summaries or compaction), or several with handles. " +
+			'For a part, add grep (case-insensitive regular expression; matching lines with line numbers) or range (e.g. "120-240"). ' +
+			"No handle at hand? grep alone searches every earlier tool output of the session and labels each match with its output's handle and command. " +
+			"Large results come in pages of characters: when a page says more is left, call again with offset.",
 		parameters: {
 			type: "object",
 			properties: {
-				handle: { type: "string", description: "A single handle from a folded block's marker line or the summary's handle table" },
+				handle: { type: "string", description: "A handle from a folded block's marker line or a summary" },
 				handles: { type: "array", items: { type: "string" }, description: "Optional batch: several handles at once; each is returned as its own labelled section" },
-				grep: { type: "string", description: "Optional: only lines matching this case-insensitive regular expression, with line numbers (applied to every handle)" },
+				grep: { type: "string", description: "Optional: only lines matching this case-insensitive regular expression, with line numbers (applied to every handle). Without any handle: searches every earlier tool output of the session" },
 				range: { type: "string", description: 'Optional: only this line range, e.g. "120-240" (applied to every handle)' },
 				offset: { type: "number", description: "Optional: start this many characters into the (selected) text, for the next page of a large output or a very long single line (applied to every handle)" },
-				limit: { type: "number", description: `Optional: page size in characters (default ${RECALL_PAGE_CHARS}, at most ${RECALL_MAX_PAGE_CHARS})` },
+				limit: { type: "number", description: `Optional: page size in characters (default ${RECALL_PAGE_CHARS}; ${SEARCH_PAGE_CHARS} for grep without a handle; at most ${RECALL_MAX_PAGE_CHARS})` },
 			},
 			required: [],
 		} as Any,
 		renderCall(args: Any, theme: Any) {
-			return lines((w) => recallCallLine(args ?? {}, w, theme, measure));
+			return lines((w) => recallCallLine(args ?? {}, w, theme, measure, (h) => hooks.labelOf?.(h)));
 		},
 		renderResult(result: Any, options: Any, theme: Any) {
 			const text = textOf(result?.content);
@@ -210,7 +283,18 @@ export function registerRecallTool(pi: ExtensionAPI, hooks: RecallHooks) {
 			const handles: string[] = [];
 			if (typeof params?.handle === "string" && params.handle.trim()) handles.push(params.handle.trim());
 			if (Array.isArray(params?.handles)) for (const h of params.handles) if (typeof h === "string" && h.trim() && !handles.includes(h.trim())) handles.push(h.trim());
-			if (!handles.length) return { content: [{ type: "text", text: "Pass handle (one string) or handles (array), copied exactly from the folded block marker lines or the summary handle table." }], details: {}, isError: true };
+			if (!handles.length && grep !== undefined && grep.trim() !== "") {
+				try {
+					const branch = ctx.sessionManager.getBranch() as Any[];
+					const later = (int(offset) ?? 0) > 0; // a later page: search the pool its first page saw
+					const out = searchOutputs(branchOutputs(branch), grep, { offset, limit, upTo: later ? searchPoolOf(branch, grep) : undefined });
+					hooks.onRecall([], out.chars, []); // a search marks nothing as recalled: only what the model asks for by handle is kept unfolded
+					return { content: [{ type: "text", text: out.text }], details: { handles: [], search: grep, pool: out.pool, resolved: out.matched, missing: 0, sections: out.sections }, isError: false };
+				} catch (err) {
+					return { content: [{ type: "text", text: `${RECALL_TOOL} failed: ${err instanceof Error ? err.message : String(err)}` }], details: {}, isError: true };
+				}
+			}
+			if (!handles.length) return { content: [{ type: "text", text: "Pass handle (one string) or handles (array), copied exactly from a folded block's marker line or a summary; or grep alone to search every earlier tool output." }], details: {}, isError: true };
 			try {
 				const { items, entryIds } = resolveHandlesInBranch(ctx.sessionManager.getBranch() as Any[], handles);
 				const out = recallSections(items, { grep, range, offset, limit });

package/src/recallfile.ts

@@ -0,0 +1,165 @@
+// Recall through files (research pi-tricks §2). A tool allowlist (`pi --tools read,grep,bash`, sub-agent launchers) hides zip_recall,
+// but read, grep or bash may still be there: a folded output then names a file those tools can read, and the file is written on
+// demand, from the session, the moment a tool call names it. Placeholders say ~/.cache/pi-zip/recall/<session id>/<handle>.txt;
+// a tool_call hook points any such path (any prefix: another machine, another user, a forked session) at this machine's copy.
+import { chmodSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, sep } from "node:path";
+
+/** What placeholders and summaries name: portable, `~` is expanded by read, grep, find and ls, and by the shell. */
+export const RECALL_DIR = "~/.cache/pi-zip/recall";
+/** Copies older than this are deleted at session start; they can be written again from the session at any time. */
+export const RECALL_MAX_AGE_MS = 14 * 24 * 3600_000;
+
+/** Where the copies live on this machine: $XDG_CACHE_HOME/pi-zip/recall, else ~/.cache/pi-zip/recall. A relative XDG_CACHE_HOME is
+ *  ignored, as the XDG spec says (it would put the copies in the project folder, where they could be committed). */
+export const recallRoot = (): string => {
+	const xdg = process.env.XDG_CACHE_HOME;
+	return join(xdg && isAbsolute(xdg) ? xdg : join(homedir(), ".cache"), "pi-zip", "recall");
+};
+/** recallRoot() as the user is shown it (state line, /zip card): the home directory as ~. */
+export const recallRootShown = (): string => {
+	const r = recallRoot(), h = homedir();
+	return h && h !== sep && r.startsWith(h + sep) ? `~${r.slice(h.length)}` : r;
+};
+
+/** A session id as a directory name (Pi's ids are UUIDs; anything else is reduced to safe characters). */
+export const sidDir = (sid: string): string => sid.replace(/[^0-9A-Za-z_-]/g, "_").slice(0, 80);
+
+/** The tools that can read a recall file, as they are active in this session. */
+export interface FileRecall {
+	dir: string; // what the model is told: RECALL_DIR/<session id>
+	read: boolean;
+	grep: boolean;
+	bash: boolean;
+}
+
+export const fileRecallFor = (sid: string, active: { read: boolean; grep: boolean; bash: boolean }): FileRecall => ({ dir: `${RECALL_DIR}/${sidDir(sid)}`, ...active });
+
+/** How to read a recall file, naming only the tools that are active ("read it (offset/limit for pages) or grep it"). */
+export function fileRecallHow(f: FileRecall): string {
+	const ways: string[] = [];
+	if (f.read) ways.push("read it (offset/limit for pages)");
+	else if (f.bash) ways.push("read it with bash (sed -n for pages)");
+	if (f.grep) ways.push("grep it");
+	else if (f.bash) ways.push("grep -n it with bash");
+	return ways.join(" or ");
+}
+
+const SID = "[0-9A-Za-z][0-9A-Za-z_-]{0,79}";
+const SID_RE = new RegExp(`^${SID}$`);
+/** What materialize writes in a session directory: <handle>.txt, and <handle>.txt.<pid>.tmp while writing. Cleanup deletes nothing else. */
+const COPY_RE = /^[0-9a-z]{10}\.txt(\.\d+\.tmp)?$/;
+const FILE_RE = new RegExp(`(?:^|/)pi-zip/recall/${SID}/([0-9a-z]{10})\\.txt$`);
+const DIR_RE = new RegExp(`(?:^|/)pi-zip/recall/${SID}/?$`);
+
+/** A path that names a recall file ({ handle }) or a session's recall directory ({}); null for anything else. */
+export function parseRecallPath(p: unknown): { handle?: string } | null {
+	if (typeof p !== "string") return null;
+	const f = FILE_RE.exec(p);
+	if (f) return { handle: f[1] };
+	return DIR_RE.test(p) ? {} : null;
+}
+
+/** Recall paths in a shell command: a word that runs into pi-zip/recall/<session>, with /<handle>.txt or not (the directory, a glob in it).
+ *  The path starts after any quote, operator, `=` (`X=<path>`, `--file=<path>`), `,`, `{` or `}` (brace expansion); `${HOME}` and the
+ *  like are part of it. */
+const CMD_RE = new RegExp(`(?:\\$\\{[A-Za-z_][A-Za-z0-9_]*\\}|[^\\s'"\`<>|;&(){},=])*pi-zip/recall/${SID}(/[0-9a-z]{10}\\.txt\\b)?`, "g");
+export const commandNamesRecall = (cmd: unknown): boolean => typeof cmd === "string" && new RegExp(CMD_RE.source).test(cmd);
+/** The handles of the recall files a shell command names. */
+export const commandRecallHandles = (cmd: unknown): string[] => (typeof cmd === "string" ? [...cmd.matchAll(CMD_RE)].filter((m) => m[1]).map((m) => m[1].slice(1, 11)) : []);
+
+/** The command with every recall path pointed at `localDir`, the handles it names, and whether it names the directory itself.
+ *  A local directory that would need shell quoting is not written in (the shell then reads ~/.cache, where the copies are when
+ *  XDG_CACHE_HOME is unset). */
+export function rewriteCommand(cmd: string, localDir: string): { command: string; handles: string[]; dir: boolean } {
+	const handles: string[] = [];
+	let dir = false;
+	const safe = /^[\w@%+=:,./-]+$/.test(localDir);
+	const command = cmd.replace(CMD_RE, (m: string, file?: string) => {
+		if (file) handles.push(file.slice(1, 11));
+		else dir = true;
+		return safe ? `${localDir}${file ?? ""}` : m;
+	});
+	return { command, handles, dir };
+}
+
+/** A copy on disk is the original only when it is a plain file holding exactly its bytes: a bash command may append to it or edit it
+ *  in place (the rewrite points writes at it too), and write and edit are not hooked. */
+function intact(file: string, bytes: Buffer): boolean {
+	try {
+		const st = lstatSync(file);
+		return st.isFile() && st.size === bytes.length && readFileSync(file).equals(bytes);
+	} catch {
+		return false;
+	}
+}
+
+/** Write each original that is not on disk as it is (directory 0700, file 0600, written whole then renamed over anything there, a
+ *  symlink included); this machine's path per handle. */
+export function materialize(root: string, sid: string, items: { handle: string; text: string }[]): Map<string, string> {
+	const dir = join(root, sidDir(sid));
+	mkdirSync(dir, { recursive: true, mode: 0o700 });
+	try {
+		chmodSync(dir, 0o700);
+	} catch {}
+	const out = new Map<string, string>();
+	for (const it of items) {
+		if (!/^[0-9a-z]{10}$/.test(it.handle)) continue;
+		const file = join(dir, `${it.handle}.txt`);
+		const bytes = Buffer.from(it.text, "utf8");
+		if (!intact(file, bytes)) {
+			const tmp = `${file}.${process.pid}.tmp`;
+			try {
+				unlinkSync(tmp); // a leftover (or a planted symlink): never written through
+			} catch {}
+			writeFileSync(tmp, bytes, { mode: 0o600, flag: "wx" });
+			renameSync(tmp, file);
+		}
+		out.set(it.handle, file);
+	}
+	return out;
+}
+
+/** Delete copies older than maxAgeMs and the session directories they leave empty. Returns how many files went. Only what materialize
+ *  writes is touched: plain files named <handle>.txt (or its .tmp) in real directories named like a session id; a symlink, as a
+ *  session directory or as a file, is never followed nor deleted. */
+export function cleanupRecall(root: string = recallRoot(), now = Date.now(), maxAgeMs = RECALL_MAX_AGE_MS): number {
+	let removed = 0;
+	let sids: string[];
+	try {
+		sids = readdirSync(root);
+	} catch {
+		return 0;
+	}
+	for (const sid of sids) {
+		if (!SID_RE.test(sid)) continue;
+		const dir = join(root, sid);
+		let names: string[];
+		try {
+			if (!lstatSync(dir).isDirectory()) continue; // lstat: a symlinked directory is not a directory here
+			names = readdirSync(dir);
+		} catch {
+			continue;
+		}
+		let left = names.length;
+		for (const n of names) {
+			if (!COPY_RE.test(n)) continue;
+			try {
+				const f = join(dir, n);
+				const st = lstatSync(f);
+				if (st.isFile() && now - st.mtimeMs > maxAgeMs) {
+					unlinkSync(f);
+					removed++;
+					left--;
+				}
+			} catch {}
+		}
+		if (left === 0) {
+			try {
+				rmdirSync(dir);
+			} catch {}
+		}
+	}
+	return removed;
+}