pi-repl-py 0.6.9 → 0.6.11

package/docs/ARCHITECTURE.md

@@ -138,10 +138,17 @@ only itself) and publishes the result back over a private MIME payload. The host
 `namespace.snapshot`, keyed to the session file under
 `~/.pi/agent/pi-repl/state/<session>/`.
 
-When a fresh engine is built, it restores that snapshot. It reports the names of values that
-could not be pickled, such as live handles and some runtime objects. If the evaluator was rebuilt mid-session,
-the result is prefixed with a `<repl_engine_reset>` block that names what was revived and
-what was lost, so the model re-verifies before reusing state that may be gone.
+When a fresh engine is built, it restores that snapshot. Values are pickled entry by entry, and
+functions and classes defined in cells are captured by source and re-executed on restore (plain
+pickle cannot revive them, since they live in `__main__`). Bindings that still fail — live
+handles, open resources, source-less functions — are reported by name, never dropped silently.
+Entries are capped per-binding and in total (128 MiB default), and the snapshot file is written
+via temp-file-and-rename so a crash cannot corrupt the last good copy; old session snapshot
+directories are pruned to the newest 25. If the evaluator was rebuilt mid-session, the next
+cell's result is prefixed with a `<repl_engine_reset>` block that names what was revived and
+what was lost, so the model re-verifies before reusing state that may be gone. A resumed
+conversation announces the same block on its first cell, but only when the conversation has a
+saved past; a first-ever session starts quiet.
 
 ## Failure modes
 

package/docs/design.md

@@ -47,6 +47,7 @@ that failed. A cell that wedges the *whole* kernel instead stops cells from runn
 the next call notices the dead kernel and rebuilds it from the last completed snapshot.
 Either way the result carries a `<repl_engine_reset>` notice that names what the rebuild
 revived and what it lost, so the model re-verifies before trusting state that may be gone.
+A resumed conversation gets the same notice on its first cell when it has a saved past.
 (How that machinery works is in `ARCHITECTURE.md`.)
 
 ## The venv as part of the design

package/index.ts

@@ -5,7 +5,7 @@ import { homedir } from "node:os";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Type } from "typebox";
 import { withSkillsBlock } from "./src/extension/skill-hook.js";
-import { EngineManager } from "./src/engine/index.js";
+import { EngineManager, pruneSnapshotDirs } from "./src/engine/index.js";
 import { ExecuteCellComponent, type ExecuteDetails, type ExecuteRenderState } from "./src/extension/render.js";
 import { EngineLifecycle } from "./src/extension/session-engine.js";
 import { EXECUTE_DESCRIPTION, buildExecutePromptGuidelines, EXECUTE_PROMPT_SNIPPET } from "./src/extension/tool-meta.js";
@@ -63,6 +63,12 @@ export default function (pi: ExtensionAPI) {
 			const sessionKey = sessionFile ? basename(sessionFile).replace(/\.jsonl$/, "") : undefined;
 			// --- kernel namespace state lives under ~/.pi/agent/pi-repl, keyed by session, so it never clutters the project ---
 			const stateDir = join(homedir(), ".pi", "agent", "pi-repl", "state", sessionKey ?? "ephemeral");
+			// --- keep the state root from growing one dir per session forever; the live dir is exempt ---
+			if (sessionKey) {
+				try {
+					pruneSnapshotDirs(join(stateDir, ".."), 25, sessionKey);
+				} catch {}
+			}
 			return new EngineManager({
 				cwd,
 				// --- snapshots are keyed to a session file; ephemeral sessions get none ---
@@ -93,7 +99,7 @@ export default function (pi: ExtensionAPI) {
 		location = { cwd: ctx.cwd, sessionFile: ctx.sessionManager.getSessionFile() ?? undefined };
 		void lifecycle.acquire("startup").catch(() => {
 			// --- boot/revive handled on the execute path; swallow so a background warm can never
-			// --- surface an unhandled rejection and the model never needs the restore notice ---
+			// --- surface an unhandled rejection. A resume's notice lands on the first cell. ---
 		});
 	});
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-repl-py",
-	"version": "0.6.9",
+	"version": "0.6.11",
 	"type": "module",
 	"description": "A pi extension with a single tool: execute, running a TypeScript host with a persistent Python (ipykernel) evaluator and a user-configurable toolbox of functions.",
 	"keywords": [

package/src/engine/index.ts

@@ -2,10 +2,10 @@
 // --- ZMTP directly (no guest.py middleman). Owns venv resolution, spawn, queue,   ---
 // --- snapshots, abort grace, and teardown — the wire lives in kernel.ts.         ---
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { KernelClient } from "./kernel.js";
+import { KernelClient, type SnapshotEntry } from "./kernel.js";
 
 function installVenvPython(): string {
 	return join(homedir(), ".pi", "agent", "pi-repl", "venv", "bin", "python3");
@@ -27,6 +27,9 @@ const DEFAULT_MAX_OUTPUT_CHARS = 46080;
 export const MAX_OUTPUT_LINE_CHARS = 4096;
 const ABORT_GRACE_MS = 20_000;
 const DEFAULT_SNAPSHOT_DEBOUNCE_MS = 1500;
+/** Total snapshot size cap (base64 payload). Per-entry entries are capped at the same
+ * bound; larger bindings are reported as skipped names. Mirrors the pi-codex scheme. */
+const DEFAULT_SNAPSHOT_MAX_BYTES = 128 * 1024 * 1024;
 
 interface EngineExecuteError {
 	/** Error class name, e.g. "TypeError". */
@@ -76,6 +79,8 @@ export interface EngineOptions {
 		path: string;
 		/** Debounce for the auto-snapshot after each ok cell. Default 1500 ms. */
 		debounceMs?: number;
+		/** Total base64 payload cap; also the per-entry cap. Oversized entries are skipped with a reason. Default 128 MiB. */
+		maxBytes?: number;
 	};
 }
 
@@ -109,6 +114,33 @@ export function capLinesForContext(text: string): { text: string; trimmed: boole
 	return { text: mapped.join("\n"), trimmed };
 }
 
+const DEFAULT_KEEP_SNAPSHOTS = 25;
+
+/** Scan the state root for per-session snapshot dirs and delete all but the newest `keep`,
+ * so a long-lived machine does not accumulate one directory per session forever. The
+ * current session's dir is exempt; a snapshot dir without a usable manifest is ignored. */
+export function pruneSnapshotDirs(stateRoot: string, keep: number = DEFAULT_KEEP_SNAPSHOTS, currentDir?: string): void {
+	const entries: { dir: string; mtimeMs: number }[] = [];
+	try {
+		for (const name of readdirSync(stateRoot, { withFileTypes: true })) {
+			if (!name.isDirectory() || name.name === currentDir) continue;
+			try {
+				const manifest = join(stateRoot, name.name, "namespace.snapshot");
+				if (!existsSync(manifest)) continue;
+				entries.push({ dir: join(stateRoot, name.name), mtimeMs: statSync(manifest).mtimeMs });
+			} catch {}
+		}
+	} catch {
+		return;
+	}
+	entries.sort((a, b) => b.mtimeMs - a.mtimeMs);
+	for (const { dir } of entries.slice(keep)) {
+		try {
+			rmSync(dir, { recursive: true, force: true });
+		} catch {}
+	}
+}
+
 export class EngineManager {
 	private readonly options: EngineOptions;
 	private kernel?: KernelClient;
@@ -302,12 +334,16 @@ export class EngineManager {
 		const config = this.options.snapshot;
 		if (!config || this.state !== "running" || !this.kernel) return null;
 		try {
-			const reply = await this.kernel.snapshot();
+			const reply = await this.kernel.snapshot(config.maxBytes ?? DEFAULT_SNAPSHOT_MAX_BYTES);
 			// --- an incomplete snapshot must not overwrite the last good file ---
 			if (reply.complete === false) return null;
 			mkdirSync(dirname(config.path), { recursive: true });
-			writeFileSync(config.path, JSON.stringify({ version: 1, vars: reply.vars, failed: reply.failed }));
-			return { path: config.path, saved: Object.keys(reply.vars), failed: reply.failed };
+			// --- write to a temp file then rename so a crash mid-write can never corrupt
+			// --- the last good snapshot (the restore side parses or returns null) ---
+			const tmp = `${config.path}.tmp`;
+			writeFileSync(tmp, JSON.stringify({ version: 2, entries: reply.entries, failed: reply.failed }));
+			renameSync(tmp, config.path);
+			return { path: config.path, saved: reply.entries.map((e) => e.name), failed: reply.failed };
 		} catch {
 			return null;
 		}
@@ -319,15 +355,29 @@ export class EngineManager {
 		if (!existsSync(config.path)) return null;
 		await this.start();
 		try {
-			const payload = JSON.parse(readFileSync(config.path, "utf8")) as { vars?: Record<string, string> };
-			const vars = payload.vars ?? {};
-			const reply = await this.kernel!.restore(vars);
+			const payload = JSON.parse(readFileSync(config.path, "utf8")) as {
+				version?: number;
+				entries?: SnapshotEntry[];
+				vars?: Record<string, string>;
+			};
+			// --- version 1 files (pre-source-capture) are still restorable: their vars are plain pickles ---
+			const entries: SnapshotEntry[] =
+				payload.version === 2
+					? (payload.entries ?? [])
+					: Object.entries(payload.vars ?? {}).map(([name, b64]) => ({ name, kind: "value", payload: b64 }));
+			const reply = await this.kernel!.restore(entries);
 			return { path: config.path, restored: reply.restored, failed: reply.failed };
 		} catch {
 			return null;
 		}
 	}
 
+	/** The conversation's state dir exists, so this engine is a resume, not a first run. */
+	hasSnapshotHistory(): boolean {
+		const config = this.options.snapshot;
+		return config ? existsSync(dirname(config.path)) : false;
+	}
+
 	async listNamespaceNames(): Promise<string[] | null> {
 		if (this.state !== "running" || !this.kernel) return null;
 		try {

package/src/engine/kernel.ts

@@ -47,8 +47,15 @@ export interface CellOptions {
 	maxOutputChars?: number;
 }
 
+export interface SnapshotEntry {
+	name: string;
+	/** "value" pickles the object; "def" re-executes captured source (functions and classes). */
+	kind: "value" | "def";
+	payload: string;
+}
+
 export interface SnapshotReply {
-	vars: Record<string, string>;
+	entries: SnapshotEntry[];
 	failed: { name: string; reason: string }[];
 	complete: boolean;
 }
@@ -88,39 +95,130 @@ function buildSkipList(helperNames: string[]): string {
 	return JSON.stringify([...names]);
 }
 
-function snapshotCode(helperNames: string[]): string {
+function snapshotCode(helperNames: string[], maxBytes: number): string {
 	const skip = buildSkipList(helperNames);
-	return (
-		"import pickle as _pk, base64 as _b64, json as _js\n" +
-		`__repl_skip = set(${skip})\n` +
-		"__repl_v = {}\n__repl_f = []\n" +
-		"for _k, _v in list(globals().items()):\n" +
-		"    if _k.startswith('_') or _k in __repl_skip:\n" +
-		"        continue\n" +
-		"    try:\n" +
-		"        __repl_v[_k] = _b64.b64encode(_pk.dumps(_v)).decode()\n" +
-		"    except Exception as _e:\n" +
-		"        __repl_f.append({'name': _k, 'reason': str(_e)})\n" +
-		`get_ipython().display_pub.publish({${JSON.stringify(SNAPSHOT_MIME)}: _js.dumps({'vars': __repl_v, 'failed': __repl_f})})\n`
-	);
+	// --- functions and classes defined in cells cannot be pickled by reference, so their
+	// --- source is captured instead and re-executed on restore. getsource works for
+	// --- functions because the code object carries the cell's filename in linecache; for
+	// --- classes inspect's module-file lookup misses, so a class is captured by locating
+	// --- its header from a member method's co_firstlineno and dedent-scanning the block.
+	// --- fallback pickles the value and reports it if that also fails; per-entry and total
+	// --- byte caps mirror the pi-codex scheme: oversized bindings become skipped names.
+	return `import pickle as _pk, base64 as _b64, json as _js, inspect as _in, linecache as _lc
+def _repl_class_source(_c):
+    _m = getattr(_c, '__init__', None)
+    if _m is None or not _in.isfunction(_m):
+        for _v in vars(_c).values():
+            if _in.isfunction(_v):
+                _m = _v
+                break
+    if _m is None:
+        raise ValueError('class has no member methods')
+    _start = _m.__code__.co_firstlineno
+    _all = _lc.getlines(_m.__code__.co_filename)
+    if not _all:
+        raise ValueError('source not in linecache')
+    _ln = _start - 1
+    while _ln > 0:
+        _prev = _all[_ln - 1].lstrip()
+        if _prev.startswith('class ') and _c.__name__ in _prev:
+            break
+        _ln -= 1
+    if _ln == 0:
+        raise ValueError('class header not found')
+    _head = _ln - 1
+    while _head > 0:
+        _p = _all[_head - 1].lstrip()
+        if _p == '' or _p.startswith('@'):
+            _head -= 1
+        else:
+            break
+    _indent = len(_all[_head]) - len(_all[_head].lstrip())
+    _block = [_all[_head]]
+    _j = _head + 1
+    while _j < len(_all):
+        _line = _all[_j]
+        if _line.strip() == '':
+            _block.append(_line)
+            _j += 1
+            continue
+        if len(_line) - len(_line.lstrip()) > _indent:
+            _block.append(_line)
+            _j += 1
+        else:
+            break
+    return ''.join(_block)
+__repl_skip = set(${skip})
+__repl_max = ${maxBytes}
+__repl_e = []
+__repl_f = []
+__repl_total = 0
+for _k, _v in list(globals().items()):
+    if _k.startswith('_') or _k in __repl_skip:
+        continue
+    __repl_p = None
+    __repl_kind = 'value'
+    try:
+        if _in.isfunction(_v):
+            __repl_src = _in.getsource(_v)
+            if __repl_src:
+                __repl_p = _b64.b64encode(__repl_src.encode()).decode()
+                __repl_kind = 'def'
+        elif _in.isclass(_v):
+            __repl_src = _repl_class_source(_v)
+            if __repl_src:
+                __repl_p = _b64.b64encode(__repl_src.encode()).decode()
+                __repl_kind = 'def'
+    except Exception:
+        __repl_p = None
+        __repl_kind = 'value'
+    try:
+        if __repl_p is None:
+            __repl_p = _b64.b64encode(_pk.dumps(_v)).decode()
+        __repl_b = len(__repl_p)
+        if __repl_b > __repl_max:
+            __repl_f.append({'name': _k, 'reason': 'exceeds per-entry snapshot cap'})
+        elif __repl_total + __repl_b > __repl_max:
+            __repl_f.append({'name': _k, 'reason': 'exceeds total snapshot cap'})
+        else:
+            __repl_e.append({'name': _k, 'kind': __repl_kind, 'payload': __repl_p})
+            __repl_total += __repl_b
+    except Exception as _e:
+        __repl_f.append({'name': _k, 'reason': str(_e)})
+get_ipython().display_pub.publish({${JSON.stringify(SNAPSHOT_MIME)}: _js.dumps({'version': 2, 'entries': __repl_e, 'failed': __repl_f})})`;
 }
 
-function restoreCode(vars_: Record<string, string>): string {
-	const entries = Object.entries(vars_)
-		.map(([name, b64]) => {
+function restoreCode(entries: SnapshotEntry[]): string {
+	const per = entries
+		.map(({ name, kind, payload }) => {
 			const n = JSON.stringify(name);
-			return (
-				`try:\n    globals()[${n}] = _pk.loads(_b64.b64decode(${JSON.stringify(b64)}))\n    __repl_r['restored'].append(${n})\n` +
-				`except Exception as _e:\n    __repl_r['failed'].append({'name': ${n}, 'reason': str(_e)})`
-			);
+			const body =
+				kind === "def"
+					? // re-execute captured source and register it in linecache under the code
+						// object's filename so a later snapshot can capture it as source again;
+						// exec also binds the name the source defines.
+						`__repl_src = _b64.b64decode(${JSON.stringify(payload)}).decode()
+    exec(__repl_src, globals())
+    __repl_obj = globals().get(${n})
+    if __repl_obj is not None:
+        __repl_fname = getattr(getattr(__repl_obj, '__code__', None), 'co_filename', None)
+        if __repl_fname is None:
+            __repl_init = getattr(__repl_obj, '__init__', None)
+            __repl_fname = getattr(getattr(__repl_init, '__code__', None), 'co_filename', None)
+        if __repl_fname:
+            _lc.cache[__repl_fname] = (len(__repl_src.splitlines()), None, __repl_src.splitlines(True), __repl_fname)`
+					: `globals()[${n}] = _pk.loads(_b64.b64decode(${JSON.stringify(payload)}))`;
+			return `try:
+    ${body}
+    __repl_r['restored'].append(${n})
+except Exception as _e:
+    __repl_r['failed'].append({'name': ${n}, 'reason': str(_e)})`;
 		})
 		.join("\n");
-	return (
-		"import pickle as _pk, base64 as _b64, json as _js\n" +
-		"__repl_r = {'restored': [], 'failed': []}\n" +
-		entries +
-		`\nget_ipython().display_pub.publish({${JSON.stringify(RESTORE_MIME)}: _js.dumps(__repl_r)})\n`
-	);
+	return `import pickle as _pk, base64 as _b64, json as _js, linecache as _lc
+__repl_r = {'restored': [], 'failed': []}
+${per}
+get_ipython().display_pub.publish({${JSON.stringify(RESTORE_MIME)}: _js.dumps(__repl_r)})`;
 }
 
 function namesCode(helperNames: string[]): string {
@@ -547,29 +645,35 @@ export class KernelClient {
 		this.control?.send(this.session.buildFrames("interrupt_request", {}, null));
 	}
 
-	snapshot(): Promise<SnapshotReply> {
+	snapshot(maxBytes: number): Promise<SnapshotReply> {
 		return this.enqueue(async () => {
-			const res = await this.executeCellNow(snapshotCode(this.helperSources.map((h) => h.name)), {
-				maxOutputChars: 8_000_000,
-			});
+			const res = await this.executeCellNow(
+				snapshotCode(
+					this.helperSources.map((h) => h.name),
+					maxBytes,
+				),
+				{
+					maxOutputChars: 8_000_000,
+				},
+			);
 			const payload = res.payloads[SNAPSHOT_MIME];
-			if (payload === undefined) return { vars: {}, failed: [], complete: false };
+			if (payload === undefined) return { entries: [], failed: [], complete: false };
 			try {
 				const obj = JSON.parse(payload) as {
-					vars?: Record<string, string>;
+					entries?: SnapshotEntry[];
 					failed?: { name: string; reason: string }[];
 				};
-				return { vars: obj.vars ?? {}, failed: obj.failed ?? [], complete: true };
+				return { entries: obj.entries ?? [], failed: obj.failed ?? [], complete: true };
 			} catch {
-				return { vars: {}, failed: [], complete: false };
+				return { entries: [], failed: [], complete: false };
 			}
 		});
 	}
 
-	restore(vars_: Record<string, string>): Promise<{ restored: string[]; failed: { name: string; reason: string }[] }> {
-		if (Object.keys(vars_).length === 0) return Promise.resolve({ restored: [], failed: [] });
+	restore(entries: SnapshotEntry[]): Promise<{ restored: string[]; failed: { name: string; reason: string }[] }> {
+		if (entries.length === 0) return Promise.resolve({ restored: [], failed: [] });
 		return this.enqueue(async () => {
-			const res = await this.executeCellNow(restoreCode(vars_), { maxOutputChars: 8_000_000 });
+			const res = await this.executeCellNow(restoreCode(entries), { maxOutputChars: 8_000_000 });
 			const payload = res.payloads[RESTORE_MIME];
 			if (payload === undefined) return { restored: [], failed: [] };
 			try {

package/src/extension/prompt.ts

@@ -2,21 +2,21 @@
 // description = rich short behavior; promptSnippet = one-liner; guidelines = flat bullets.
 
 export const executeToolDescription =
-	"Execute Python cells in a persistent Python shell that is your entire workspace: it is where you read, " +
-	"write, run, and move, all in one instrument. The state you build, files, and subprocesses survive " +
-	"from one call to the next. Returns stdout, stderr, and the value of the last expression. Output is " +
-	"truncated to 45K with a marker.";
+	"Execute Python in a Jupyter notebook. Your workspace is one notebook where every cell runs in a " +
+	"shared Python environment: variables, functions, imports, classes, and data defined in one cell " +
+	"stay available to later cells for the life of the notebook. Cells return their last expression " +
+	"(auto-displayed) plus stdout/stderr; output is truncated to 45K with a marker.";
 
-export const executePromptSnippet = "Execute Python in a persistent shell (read, write, run, search, and more)";
+export const executePromptSnippet = "Run Python cells in a Jupyter notebook (read, write, run, search, and more)";
 
 // --- the model-facing guidelines, flat bullets like pi's own tool contributions ---
 export function buildPromptGuidelines(preloaded: string[]): string[] {
 	return [
-		"Find, filter, fetch, sample: narrow the output in Python, then print only the exact slice you need.",
-		"Make surgical, precise changes over rewrites or whole-file dumps: a small unique anchor, replace, verify, read the file back before trusting it.",
-		"Reference what the persistent shell already holds, don't redefine it.",
 		"Write modern idiomatic Python.",
-		"If output begins with <repl_engine_reset>, the kernel rebuilt; re-verify a revived variable.",
+		"Find, filter, fetch, sample: narrow the output in Python, then print only the window that decides the next step (a head, a shape, a slice), not the whole.",
+		"Make surgical, precise changes over rewrites or whole-file dumps: a small unique anchor, replace, verify, read the file back before trusting it.",
+		"Prefer to reuse existing variables, functions, imports, classes, and data from prior cells/namespaces over recomputing.",
+		"If output begins with <repl_engine_reset>, the runtime rebuilt and the notebook was restored from the last snapshot; reverify surviving names before building on them.",
 		...(preloaded.length
 			? [
 					[

package/src/extension/render-core.ts

@@ -278,17 +278,31 @@ function renderCode(state: ExecuteRenderState, lines: string[], width: number, d
 	const code = state.code.trimEnd();
 	if (!code) return false;
 	lines.push("");
+	let perWidth = codeWrapCache.get(state);
+	if (!perWidth) {
+		perWidth = new Map();
+		codeWrapCache.set(state, perWidth);
+	}
+	const cached = perWidth.get(width);
+	if (cached?.code === code) {
+		lines.push(...cached.lines);
+		return true;
+	}
+	const fresh: string[] = [];
 	const highlighted = highlightLines(code, deps);
 	for (const [index, rawLine] of code.split("\n").entries()) {
 		const prefix = index === 0 ? deps.fg("dim", "› ") : deps.fg("dim", "  ");
 		const paint = (id: string) => deps.fg("syntaxVariable", id);
 		const hlLine = colorBareIdentifiers(highlighted[index] ?? rawLine, paint);
 		const indent = /^[ \t]*/.exec(rawLine)?.[0] ?? "";
-		addWrapped(lines, prefix, hlLine, width, deps, {
+		addWrapped(fresh, prefix, hlLine, width, deps, {
 			sanitize: false,
 			indentAfter: deps.visibleWidth(indent),
 		});
 	}
+	boundWidthCache(perWidth);
+	perWidth.set(width, { code, lines: fresh });
+	lines.push(...fresh);
 	return true;
 }
 
@@ -307,6 +321,28 @@ interface BlobWrapEntry {
 }
 
 const blobWrapCache = new WeakMap<ExecuteRenderState, Map<number, BlobWrapEntry>>();
+/** Wrapped+highlighted rows rebuild only when their inputs (text/width) change; the
+ * TUI re-renders bodies on every frame, so these caches turn per-frame work into
+ * one build per change. They live on the persistent per-call state, which the host
+ * keeps for the session, so a small bound per state keeps resize churn bounded. */
+interface CodeEntry {
+	code: string;
+	lines: string[];
+}
+const codeWrapCache = new WeakMap<ExecuteRenderState, Map<number, CodeEntry>>();
+
+/** Window resizes add a per-width entry per cell; keep a small bound so a long
+ * session with resize churn cannot grow the wrap caches without limit. Map
+ * iteration order is insertion order, so evicting the first key drops the oldest
+ * width rather than the one in use. */
+const MAX_CACHED_WIDTHS_PER_STATE = 3;
+function boundWidthCache(perWidth: Map<number, unknown>): void {
+	while (perWidth.size >= MAX_CACHED_WIDTHS_PER_STATE) {
+		const oldest = perWidth.keys().next().value as number | undefined;
+		if (oldest === undefined) return;
+		perWidth.delete(oldest);
+	}
+}
 
 const CJK_WIDE_RE =
 	/[\p{Script_Extensions=Han}\p{Script_Extensions=Hiragana}\p{Script_Extensions=Katakana}\p{Script_Extensions=Hangul}\p{Script_Extensions=Bopomofo}]/u;
@@ -425,6 +461,7 @@ function wrapBlob(state: ExecuteRenderState, width: number, text: string, color:
 			}
 		}
 		const entry: BlobWrapEntry = { text, color, lines, partial };
+		boundWidthCache(perWidth);
 		perWidth.set(width, entry);
 		return entry;
 	};

package/src/extension/session-engine.ts

@@ -11,6 +11,8 @@ function summarizeNames(names: readonly string[], limit: number): string {
 /** The part of EngineManager this lifecycle needs; narrowed so tests can fake it. */
 export interface RevivableEngine {
 	restoreState(): Promise<RestoreResult | null>;
+	/** True when this conversation's state dir already exists, so the engine was resumed. */
+	hasSnapshotHistory(): boolean;
 }
 
 export interface EngineLifecycleDeps<E extends RevivableEngine> {
@@ -22,32 +24,43 @@ export interface EngineLifecycleDeps<E extends RevivableEngine> {
 	discard?(engine: E): Promise<void>;
 }
 
-/** `startup` is announced in the transcript; `cell` means an engine was rebuilt mid-session and needs an in-band notice. */
+/** `startup` restores then announces on the first cell when the conversation has a saved past; `cell` means an engine was rebuilt mid-session and announces immediately. */
 export type AcquireOrigin = "startup" | "cell";
 
-function formatEngineResetNotice(restore: RestoreResult | null): string {
+function formatEngineResetNotice(restore: RestoreResult | null, origin: AcquireOrigin): string {
+	const resumed = origin === "startup";
 	const lines = ["<repl_engine_reset>"];
 	if (!restore) {
 		// --- no snapshot at all: namespace is genuinely empty ---
 		lines.push(
-			"The evaluator restarted and its namespace is empty; no snapshot was available to revive.",
-			"Every variable from earlier in this session is gone. Rebuild what you need before using it.",
+			resumed
+				? "This session's evaluator started fresh, and no saved snapshot was available to revive; the namespace is empty."
+				: "The evaluator restarted and its namespace is empty; no snapshot was available to revive.",
+			resumed
+				? "Names from earlier in this conversation are gone. Rebuild what you need before using it."
+				: "Every variable from earlier in this session is gone. Rebuild what you need before using it.",
 		);
 	} else if (restore.restored.length === 0) {
 		// --- a snapshot existed but restored nothing; say why, don't claim "no snapshot" ---
 		lines.push(
-			"The evaluator restarted and a snapshot was found, but nothing in it could be revived.",
+			resumed
+				? "This session's evaluator started fresh. A saved snapshot was found, but nothing in it could be revived."
+				: "The evaluator restarted and a snapshot was found, but nothing in it could be revived.",
 			restore.failed.length > 0
 				? `Failed to revive (${restore.failed.length}): ${summarizeNames(
 						restore.failed.map((f) => f.name),
 						20,
 					)}`
 				: "The snapshot was empty.",
-			"Every variable from earlier in this session is gone. Rebuild what you need before using it.",
+			resumed
+				? "Names from earlier in this conversation are gone. Rebuild what you need before using it."
+				: "Every variable from earlier in this session is gone. Rebuild what you need before using it.",
 		);
 	} else {
 		lines.push(
-			"The evaluator restarted. Its namespace was rebuilt from the last snapshot, so it may be behind.",
+			resumed
+				? "This session's evaluator started fresh and restored the namespace saved by this conversation's last run, so it may be empty or behind."
+				: "The evaluator restarted. Its namespace was rebuilt from the last snapshot, so it may be behind.",
 			`Revived (${restore.restored.length}): ${summarizeNames(restore.restored, 20)}`,
 		);
 		if (restore.failed.length > 0) {
@@ -56,7 +69,7 @@ function formatEngineResetNotice(restore: RestoreResult | null): string {
 					restore.failed.map((f) => f.name),
 					20,
 				)}`,
-				"Functions, classes, and live handles cannot be snapshotted; redefine them.",
+				"Live handles, open resources, and source-less functions cannot be snapshotted; redefine them.",
 			);
 		}
 		lines.push("Anything defined after the last snapshot is also gone.");
@@ -91,7 +104,11 @@ export class EngineLifecycle<E extends RevivableEngine> {
 			this.engine = engine;
 			this.revival = engine.restoreState().catch(() => null);
 			const restore = await this.revival;
-			if (origin === "cell") this.pendingNotice = formatEngineResetNotice(restore);
+			// --- mid-session rebuilds always announce; startup announces only when the
+			// --- conversation has a saved past, so a first-ever session stays quiet ---
+			if (origin === "cell" || (origin === "startup" && engine.hasSnapshotHistory())) {
+				this.pendingNotice = formatEngineResetNotice(restore, origin);
+			}
 			return { engine, restore, created: true };
 		})();
 		this.acquiring = build;