pi-repl-py 0.6.12 → 0.6.13

package/docs/ARCHITECTURE.md

@@ -205,6 +205,14 @@ global one and both sides are guaranteed to agree. The venv is built automatical
 interpreter follows the order above. No setting is needed. The per-cell silence watchdog is
 off by default (`PI_REPL_TIMEOUT_MS=0`: a silent but working cell may run on).
 
+The boot itself is bounded regardless: kernel start, helpers preload, and snapshot restore are
+kernel cells with no deadline of their own, and `acquire()` dedupes, so one wedged boot (an npm
+update swapping the venv under a live kernel, a snapshot value whose unpickling never returns)
+would hang the first cell and every cell after it. The lifecycle races each boot attempt against
+`PI_REPL_BOOT_TIMEOUT_MS` (default 90s): a wedged attempt is killed and retried once with the
+snapshot deliberately skipped, landing on an honest "wedged while reviving; skipped" notice; a
+second wedge fails the cell loudly instead of hanging.
+
 ## Reference documentation
 
 - Design rationale: [design.md](design.md)

package/index.ts

@@ -58,6 +58,11 @@ export default function (pi: ExtensionAPI) {
 	const pendingErrorResults = new Map<string, { details: ExecuteDetails }>();
 
 	const lifecycle = new EngineLifecycle<EngineManager>({
+		// --- boot deadline: bounds kernel start + helpers preload + snapshot restore. An npm
+		// --- update swaps the venv and helpers under a live kernel, and the first boot after
+		// --- it can wedge (poisoned pickle, half-built venv); without this the first cell
+		// --- hangs forever, because acquire() dedupes onto the same hung boot. ---
+		bootTimeoutMs: Number(process.env.PI_REPL_BOOT_TIMEOUT_MS ?? 90_000) || 90_000,
 		create() {
 			const { cwd, sessionFile } = location;
 			const sessionKey = sessionFile ? basename(sessionFile).replace(/\.jsonl$/, "") : undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-repl-py",
-	"version": "0.6.12",
+	"version": "0.6.13",
 	"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

@@ -387,11 +387,15 @@ export class EngineManager {
 		}
 	}
 
-	async restoreState(): Promise<RestoreResult | null> {
+	async restoreState(skip = false): Promise<RestoreResult | null> {
+		// --- start unconditionally: the boot deadline in the lifecycle bounds this call, so
+		// --- booting eagerly here (even with nothing to revive) is what makes a wedged boot
+		// --- detectable instead of deferring the wedge to the first cell. ---
+		await this.start();
+		if (skip) return null;
 		const config = this.options.snapshot;
 		if (!config) return null;
 		if (!existsSync(config.path)) return null;
-		await this.start();
 		try {
 			const payload = JSON.parse(readFileSync(config.path, "utf8")) as {
 				version?: number;

package/src/extension/prompt.ts

@@ -14,7 +14,7 @@ export function buildPromptGuidelines(preloaded: string[]): string[] {
 	return [
 		"Write modern idiomatic Python.",
 		"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.",
+		"Make surgical, precise changes over rewrites or whole-file dumps: 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

@@ -517,6 +517,9 @@ function renderOutput(
 	}
 
 	if (details?.errorStack && details.errorStack.length > 0) {
+		// --- a traceback IS output: without this flag a pure-traceback error cell (no
+		// --- stdout/stderr/result, the common error shape) also rendered "no output" below it ---
+		renderedText = true;
 		output.push(` ${OUTPUT_INDENT}${deps.fg("dim", "traceback:")}`);
 		for (const line of details.errorStack) {
 			const safe = sanitizeTuiOutput(line || " ");
@@ -529,6 +532,13 @@ function renderOutput(
 		addWrapped(output, OUTPUT_INDENT, deps.fg("muted", message), width, deps, { sanitize: false });
 	}
 
+	// --- bottom cushion: streams end with a newline, so blobs already render a trailing blank
+	// --- row; traceback and the placeholder have no such newline and would sit flush against
+	// --- the panel's bottom edge. Normalize: the panel always ends with one blank painted row.
+	// --- (SGR stripped before the blank test; the colored rows themselves stay untouched.) ---
+	const lastRow = output[output.length - 1];
+	if (lastRow !== undefined && lastRow.replace(SGR_PATTERN, "").trim() !== "") output.push("");
+
 	// --- expanded cells render the whole output: the data cap bounds it ---
 	if (output.length > 0 && hasCode) lines.push("");
 	lines.push(...output);

package/src/extension/session-engine.ts

@@ -10,7 +10,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>;
+	/** Boot the engine and revive the snapshot; `skip` boots fresh, deliberately not reviving. */
+	restoreState(skip?: boolean): Promise<RestoreResult | null>;
 	/** True when this conversation's state dir already exists, so the engine was resumed. */
 	hasSnapshotHistory(): boolean;
 }
@@ -22,11 +23,27 @@ export interface EngineLifecycleDeps<E extends RevivableEngine> {
 	dispose(engine: E): Promise<void>;
 	/** Kill-then-rebuild when a wedged engine cannot serve the snapshot flush. */
 	discard?(engine: E): Promise<void>;
+	/** Boot deadline in ms; a boot (kernel start, helpers preload, snapshot restore) that
+	 * outlives it is killed and retried fresh. Default 90s. */
+	bootTimeoutMs?: number;
 }
 
+/** Sentinel: the boot outlived its deadline. Distinct from null, which means "booted, nothing revived". */
+const BOOT_WEDGED = Symbol("boot wedged");
+
 /** `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";
 
+const DEFAULT_BOOT_TIMEOUT_MS = 90_000;
+
+/** Model-facing body for a boot whose snapshot revive wedged and was skipped. */
+function revivedNoticeBody(origin: AcquireOrigin): string {
+	const resumed = origin === "startup";
+	return resumed
+		? "This session's evaluator wedged while reviving the saved namespace, so the snapshot was skipped and the namespace is empty."
+		: "The evaluator wedged while reviving its saved namespace, so the snapshot was skipped and the namespace is empty.";
+}
+
 // --- Terse TUI toast for the human, separate from the model-facing cell marker: the user
 // --- asked for the classic subtle notification instead of a showy in-cell message. Counts
 // --- come from the same restore the marker describes, so the two never disagree. ---
@@ -112,6 +129,23 @@ export class EngineLifecycle<E extends RevivableEngine> {
 
 	constructor(private readonly deps: EngineLifecycleDeps<E>) {}
 
+	/** Race one boot attempt against the deadline. The losing attempt is abandoned (and the
+	 * engine killed by the caller): its promise gets a no-op catch so killing the kernel
+	 * cannot surface an unhandled rejection later. */
+	private bootOnce(
+		engine: E,
+		deadlineMs: number,
+		skipRestore: boolean,
+	): Promise<RestoreResult | null | typeof BOOT_WEDGED> {
+		const work = engine.restoreState(skipRestore).catch(() => null);
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		const guard = new Promise<typeof BOOT_WEDGED>((resolve) => {
+			timer = setTimeout(() => resolve(BOOT_WEDGED), deadlineMs);
+			timer.unref?.();
+		});
+		return Promise.race([work, guard]).finally(() => clearTimeout(timer));
+	}
+
 	/** Built and revived on demand; awaited so callers never see an un-revived namespace. */
 	async acquire(origin: AcquireOrigin): Promise<{ engine: E; restore: RestoreResult | null; created: boolean }> {
 		if (this.engine) {
@@ -124,10 +158,41 @@ export class EngineLifecycle<E extends RevivableEngine> {
 				const held: E = this.engine;
 				return { engine: held, restore: await this.revival!, created: false };
 			}
-			const engine = this.deps.create();
+			let engine = this.deps.create();
 			this.engine = engine;
-			this.revival = engine.restoreState().catch(() => null);
-			const restore = await this.revival;
+			// --- the boot is bounded: kernel start, helpers preload, and snapshot restore all
+			// --- run as kernel cells with no deadline of their own, and acquire() dedupes, so
+			// --- one wedged boot (venv swapped mid-update, a poisoned pickle) would otherwise
+			// --- hang the first cell and every cell after it. ---
+			const deadline = this.deps.bootTimeoutMs ?? DEFAULT_BOOT_TIMEOUT_MS;
+			let restore = await this.bootOnce(engine, deadline, false);
+			if (restore === BOOT_WEDGED) {
+				// --- the kernel is alive but stuck; only a kill frees it. Retry once WITHOUT the
+				// --- snapshot, so a poisoned pickle cannot wedge the session twice in a row. ---
+				await (this.deps.discard ?? this.deps.dispose)(engine);
+				engine = this.deps.create();
+				this.engine = engine;
+				restore = await this.bootOnce(engine, deadline, true);
+				if (restore === BOOT_WEDGED) {
+					await (this.deps.discard ?? this.deps.dispose)(engine);
+					this.engine = undefined;
+					throw new Error("evaluator boot timed out twice (kernel/helpers wedged); no session was started");
+				}
+				// --- the snapshot existed but reviving it is what wedged: say exactly that, not
+				// --- "no snapshot available", so the model doesn't go hunting for a missing file ---
+				if (origin === "cell" || (origin === "startup" && engine.hasSnapshotHistory())) {
+					this.pendingNotice = [
+						"<repl_engine_reset>",
+						revivedNoticeBody(origin),
+						"Re-verify a variable before reusing it, especially inside shell interpolation.",
+						"</repl_engine_reset>",
+					].join("\n");
+					this.pendingReset = { origin, restore: null };
+				}
+				this.revival = Promise.resolve(null);
+				return { engine, restore: null, created: true };
+			}
+			this.revival = Promise.resolve(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())) {