pi-repl-py 0.6.12 → 0.6.14

package/docs/ARCHITECTURE.md

@@ -1,8 +1,9 @@
 # Architecture
 
-pi-repl runs in **two processes**. pi hosts the TypeScript extension, and the extension manages a
-separate Python `ipykernel` process where user code runs. The host talks to that kernel using the
-standard Jupyter protocol. There is no Python middleman and no private framing layer between them.
+pi-repl runs in **two processes**: pi hosts the TypeScript extension, which manages a separate
+Python `ipykernel` process where user code runs, speaking the standard Jupyter protocol directly
+(no Python middleman, no private framing). A cell can raise or wedge the kernel without taking pi
+down; the host stays answerable.
 
 ```
 pi
@@ -16,150 +17,109 @@ pi
              └─ python -m ipykernel -f <connection-file>   the evaluator
 ```
 
-The host is TypeScript, and the evaluator is Python in a separate process. This means a cell can
-raise an exception or make the kernel unusable without taking pi down. The host can still report
-what happened.
-
 ## Why the host speaks ZMTP itself
 
-The obvious way for a TypeScript host to drive an `ipykernel` is to load a ZMQ client
-library. That does not work here: libzmq's native Node bindings crash `bun`. So an earlier
-design put a Python middleman (`guest.py`) between the host and the kernel, translating a
-private JSON protocol over a file descriptor into the real Jupyter protocol.
-
-The current design removes the middleman. Instead of working around the missing library, the
-host implements the small slice of ZMTP 3.0 that a Jupyter client needs. ZMTP is the socket
-protocol used by Jupyter's channels: the host uses a DEALER socket for shell and control, and a
-SUB socket for iopub (`src/engine/zmtp.ts`).
-The payoff:
+A TypeScript host cannot load libzmq's native Node bindings (they crash `bun`), and the earlier
+Python middleman (`guest.py`) that translated a private JSON protocol is gone. The host instead
+implements the small slice of ZMTP 3.0 a Jupyter client needs — DEALER for shell/control, SUB for
+iopub (`src/engine/zmtp.ts`). The payoff:
 
 - **one process boundary** instead of two;
 - **one standard protocol** (Jupyter) instead of a private one on top of it;
 - **no invented framing** to maintain;
-- **Messages are authenticated with HMAC.** The host signs and verifies Jupyter messages with
-  the kernel's HMAC key. The earlier design used a nonce to prevent false completion messages;
-  the standard message signature now provides that check.
+- **messages are authenticated with HMAC** — the host signs and verifies every message with the
+  kernel's HMAC key, replacing the old nonce that guarded against false completion messages.
 
 ## The Python environment (the venv)
 
-The evaluator is a real `ipykernel` kernel, so it needs a Python environment with
-`ipykernel` installed. This is a hard runtime dependency. A script cannot replace it.
-(`jupyter_client` is *not* needed: the host is the client.)
+The evaluator is a real ipykernel, so it needs Python with `ipykernel` installed — a hard runtime
+dependency (`jupyter_client` is *not* needed: the host is the client). A package install runs
+`postinstall` (`scripts/setup-venv.mjs`), which builds a stable per-user venv at
+`~/.pi/agent/pi-repl/venv/bin/python3` — stable because it sits outside the package dir that npm
+replaces on each update. If `python3` or the network is missing at install time, it prints a
+notice and the host falls back at runtime.
 
-When installed as a pi package, `npm install` runs `postinstall`
-(`scripts/setup-venv.mjs`), which builds a stable per-user venv:
+At spawn, `resolvePythonPath` uses exactly one interpreter: the install venv, else `$PYTHON` /
+`python3`. It never auto-picks a repo or cwd `.venv` — such a venv may lack ipykernel, which
+killed the kernel whenever cwd happened to contain one. The kernel starts in the session's cwd
+and falls back to the host cwd if that directory is gone, so a stale cwd never prevents boot.
 
-```
-~/.pi/agent/pi-repl/venv/bin/python3
-```
+## The kernel client
 
-That path is stable across updates because it sits outside the package's own directory,
-which npm replaces on each update. If `python3` or the network is missing at install time,
-`postinstall` prints a clear notice and the host falls back at runtime.
+`KernelClient.start` spawns `python -m ipykernel -f <connection-file>` (a per-run connection file
+in the temp dir), connects the three channels over ZMTP, and waits for `kernel_info_reply` before
+declaring the kernel ready. Cells run as standard `execute_request`s, routed by `msg_id`:
 
-At spawn, `resolvePythonPath` uses exactly one interpreter, the install venv:
+- **iopub** — output: `stream`, `execute_result`, `display_data`, `error`, plus private-MIME
+  payloads for snapshot/restore/namespace data;
+- **shell** — the authoritative `execute_reply` (status, ename, evalue);
+- **control** — interrupts (`interrupt_request`) and shutdown.
 
-1. `~/.pi/agent/pi-repl/venv` (the package install)
-2. `$PYTHON`, then `python3` (only if the install venv is missing)
+Four protocol details have contract tests.
 
-It deliberately does NOT auto-pick the repo's or current directory's `.venv`: a per-project
-venv is not guaranteed to have `ipykernel`, so preferring it (as earlier versions did) made
-the kernel die from a `ModuleNotFoundError` whenever cwd happened to contain such a venv. The
-kernel therefore always runs in the stable install environment. The kernel starts in the
-session's cwd, falling back to the host's own cwd if that directory no longer exists (a
-deleted project dir), so a stale cwd can never prevent the kernel from coming up.
+**A cell settles only on two messages.** The shell reply and the iopub stream travel on different
+connections, so a tiny reply can beat a large output. A cell completes only when **both** the
+`execute_reply` and the matching iopub `status idle` (published after every byte) arrive;
+settling on the reply alone would drop output still in flight.
 
-## The kernel client
+**Output is capped per channel and per line**, both announced with markers: channels accumulate
+against `maxOutputChars` (checked within each message), and each line is capped at 4096 chars, so
+one oversized line cannot own the budget while long JSON/reprs/errors pass whole.
 
-`KernelClient.start` spawns `python -m ipykernel -f <connection-file>` with a per-run
-connection file in the temp directory, connects the three channels as ZMTP sockets, and
-waits for a `kernel_info_reply` before declaring the kernel ready. Cells run as standard
-Jupyter `execute_request`s, routed by `msg_id`:
-
-- **iopub** carries output messages such as `stream`, `execute_result`, `display_data`, and
-  `error`. It also carries private-MIME payloads for snapshot, restore, and namespace data.
-- **shell** carries the authoritative `execute_reply` (status, ename, evalue).
-- **control** carries interrupts (`interrupt_request`) and shutdown.
-
-Two details of this protocol are important enough to have dedicated contract tests.
-
-**A cell is not complete until two messages arrive.** The shell reply and the iopub output stream
-travel on different connections, so a tiny reply can arrive before a large output has
-finished draining on iopub. A cell settles only when **both** the `execute_reply` and the
-matching iopub `status idle` (published after every byte of output) have arrived. Settling
-on the reply alone would drop output that was still in flight.
-
-**Output is capped per channel and per line.** Each channel accumulates output against a character
-budget (`maxOutputChars`), checked within each message, so overflow trips the moment a message
-exceeds the budget rather than when it churns on. Each individual line is also capped at a generous
-length (4096 chars), so a single genuinely oversized line cannot own the whole budget — while
-legitimately long REPL output (JSON, reprs, errors) still passes through whole. Both truncations
-are announced with explicit markers so the model knows output was cut.
-
-**Cancellation is real.** An abort sends an `interrupt_request` on the control channel,
-which raises a genuine `KeyboardInterrupt` in the running cell; the namespace survives. As a
-backstop for cells wedged in C code (which ignore interrupts), the engine gives an aborted
-cell up to 20 seconds to settle and keeps the kernel if it does; only a cell that is still
-running after that grace is killed, and the next call rebuilds from the last snapshot.
-
-**History is off.** Every execute goes out with `store_history: false`. IPython's `In`/`Out`
-retention keeps every last-expression result object alive in the kernel, and that retention
-cannot be reclaimed from a user cell — deleting `Out` and `_`/`__`/`___` from `user_ns`
-followed by `gc.collect()` leaves the objects alive (measured: 62 MB idle grows past 400 MB
-after two bare big results and never comes back). Disabling history bounds the kernel to at
-most the latest result. The transcript is the record instead, and results still publish over
-iopub: single-mode execution calls `sys.displayhook` regardless of `store_history`.
+**Cancellation is real.** An abort sends `interrupt_request`, raising a genuine
+`KeyboardInterrupt`; the namespace survives. Cells wedged in C code (which ignore interrupts)
+get a 20-second grace, then the kernel is killed and the next call rebuilds from the last
+snapshot.
 
-## Helpers loading
+**History is off.** IPython's `In`/`Out` retention pins every last-expression result and cannot be
+reclaimed from a user cell (measured: 62 MB → 400+ MB after two bare big results, unrecoverable),
+so every execute goes out with `store_history: false`, bounding the kernel to the latest result.
+Results still publish over iopub: single-mode execution calls `sys.displayhook` regardless.
 
-At boot, the kernel and the host both read the same merged helper list (project
-`.pi/helpers/` directories plus the global `~/.pi/agent/pi-repl/helpers/`), so what the
-prompt advertises is what the kernel holds. Both directories are optional; nothing ships
-with the package. The exact merge order is under "The fixed layout" below.
+## Helpers loading
 
-- **The kernel** executes each eligible `*.py` file in its namespace, so the file's definitions
-  and imports become available.
-- **The host** reads the same files to build the helper list shown in the `execute` tool's
-  prompt, so the model sees each `helper_description` verbatim.
+At boot, the kernel and the host both read the same merged helper list (project `.pi/helpers/` up
+to the git root, then the global `~/.pi/agent/pi-repl/helpers/`), so what the prompt advertises is
+what the kernel holds: the kernel execs each eligible `*.py` into its namespace; the host reads
+the same files' `helper_description` verbatim into the tool prompt. `_`-prefixed files are
+skipped by both. Merge order and shadowing are under "The fixed layout" below.
 
-Both sides read the same list, so the names described to the model come from files the
-kernel also loads. A file renamed with a `_` prefix is skipped by both sides. The
-`promptGuidelines` are built once, when the `execute` tool is registered, so a helpers
-change needs a **session restart or `/reload`** to reach the prompt. The kernel also loads
-helpers only at boot.
+The `promptGuidelines` are built once, when `execute` is registered, and the kernel loads helpers
+only at boot, so a helpers change needs a **session restart or `/reload`**.
 
-There are no custom discovery intrinsics (`ls()` / `help()`) injected into a bare kernel.
-The model discovers what is loaded by listing the namespace with ordinary Python:
+No discovery intrinsics (`ls()` / `help()`) are injected; list the namespace with ordinary Python:
 
 ```python
 [k for k in globals() if not k.startswith('_')]
 ```
 
-For the full helper contract, including descriptions, docstrings, and disabling, see
-[helpers.md](helpers.md).
+Full contract: [helpers.md](helpers.md).
 
 ## Snapshots & honest resets
 
-After each successful cell, the host schedules a debounced snapshot. A private kernel cell
-pickles the kernel's `globals` (entry by entry, so one value that cannot be pickled costs
-only itself) and publishes the result back over a private MIME payload. The host stores it as
-`namespace.snapshot`, keyed to the session file under
-`~/.pi/agent/pi-repl/state/<session>/`.
-
-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, and snapshot dirs whose owning conversation file no
-longer exists in any project session root are swept entirely (deleting a conversation deletes
-its snapshots with it). "ephemeral" and the live session are always exempt. 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. The human gets
-only a terse `ui.notify` toast ("repl kernel rebuilt, 3 names revived") instead of the marker;
-the two are derived from the same restore result, so they never disagree. A resumed
-conversation announces the same pair on its first cell, but only when the conversation has a
+After each successful cell, a debounced snapshot pickles the kernel's `globals` entry by entry
+(one un-picklable value costs only itself) and publishes it back over a private MIME payload; the
+host stores it as `namespace.snapshot` under `~/.pi/agent/pi-repl/state/<session>/`.
+
+A fresh engine restores that snapshot **in the background**: recovery is a quiet-gap job that
+never runs ahead of a user cell, so a large revive does not delay the first cell; only a
+mid-session rebuild (kernel death) forces the restore before the cell that found the kernel dead.
+Functions and classes defined in cells are captured by source and re-executed on restore (plain
+pickle cannot revive them in `__main__`); bindings that still fail are reported by name, never
+dropped silently. Entries are capped per-binding and in total (128 MiB default); the file is
+written via temp-file-and-rename so a crash cannot corrupt the last good copy; session dirs are
+pruned to the newest 25, and dirs whose conversation file no longer exists are swept entirely —
+deleting a conversation deletes its snapshots. "ephemeral" and the live session are exempt.
+
+A revive that never completes (a poisoned pickle) is bounded by an engine restore-cell watchdog
+(`PI_REPL_BOOT_TIMEOUT_MS`, default 90s): the kernel is killed and the restore marked skipped —
+"wedged while reviving; skipped" — instead of hanging the queue.
+
+The first cell's result after a revive carries a `<repl_engine_reset>` block naming what was
+revived and lost, so the model re-verifies before trusting state that may be gone; because
+recovery is async, that is the first cell **after the restore completes** (usually the first cell
+of a resumed conversation). The human gets only a terse `ui.notify` toast, derived from the same
+restore result so the two never disagree. A resumed conversation announces only when it has a
 saved past; a first-ever session stays quiet.
 
 ## Failure modes
@@ -168,7 +128,7 @@ saved past; a first-ever session stays quiet.
 | --- | --- |
 | Cell throws | `error` status with traceback; kernel namespace intact |
 | Cell silent or wedged | the watchdog sends an `interrupt_request`; a caller abort kills the kernel only if it is still running after a 20-second grace |
-| Kernel dies | the running cell settles with an error; the next call builds a fresh kernel and restores the last snapshot |
+| Kernel dies | the running cell settles with an error; the next call builds a fresh kernel and restores the last snapshot **before** the triggering cell |
 | Host exits | `process.on("exit")` SIGKILLs live kernels (a child does not die with its parent) |
 | Output flood | capped per channel, truncation announced |
 
@@ -181,14 +141,14 @@ saved past; a first-ever session stays quiet.
   snapshot/restore round-trips, output caps, silence timeout, abort, and rebuilding from a
   snapshot after the kernel dies.
 
-The gate is `just check`. It runs Biome formatting and linting, dead-code checks, and host tests.
-`just integration` adds the real-kernel suite.
+The gate is `just check` (Biome formatting/lint, dead-code checks, host tests); `just integration`
+adds the real-kernel suite.
 
 ## The fixed layout
 
-There is no configuration file. Most state lives under one directory in the user's home. A
-small number of environment variables can still change runtime behavior, such as the silence
-watchdog timeout.
+There is no configuration file. Most state lives under one directory in the user's home. A small
+number of environment variables can still change runtime behavior, such as the silence watchdog
+timeout.
 
 ```
 ~/.pi/agent/pi-repl/
@@ -197,13 +157,24 @@ watchdog timeout.
   state/        per-session namespace snapshots
 ```
 
-Helpers merge project and global dirs: `resolveHelperDirs` walks from the working
-directory up to the git root collecting `.pi/helpers/`, then appends
-`~/.pi/agent/pi-repl/helpers`. Both the prompt loader and the kernel's `readHelperSources`
-walk the same ordered list with first-seen-wins, so a project helper shadows the same-named
-global one and both sides are guaranteed to agree. The venv is built automatically, and the
-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).
+State dirs are keyed `<project-slug>__<conversation>` so two conversations that share a filename
+can never share a snapshot (a pre-slug dir migrates on the owning conversation's next start), and
+`EngineLifecycle.acquire` binds each engine to its conversation, tearing a foreign engine down
+before building a new one — sessions cannot bleed into each other.
+
+Helpers merge project and global dirs: `resolveHelperDirs` walks up to the git root collecting
+`.pi/helpers/`, then appends the global dir; the prompt loader and the kernel's `readHelperSources`
+walk the same ordered list first-seen-wins, so a project helper shadows a same-named global one
+and both sides agree. No setting is needed. The per-cell silence watchdog is off by default
+(`PI_REPL_TIMEOUT_MS=0`).
+
+Boot is bounded regardless: kernel start and helpers preload 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 hanging helper import) would hang the first cell and every cell after. 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 — "wedged while
+reviving; skipped" — and a second wedge fails loudly. The same deadline bounds a restore whose
+unpickling never returns.
 
 ## Reference documentation
 

package/index.ts

@@ -8,6 +8,7 @@ import { withSkillsBlock } from "./src/extension/skill-hook.js";
 import { EngineManager, pruneOrphanedSnapshotDirs, pruneSnapshotDirs } from "./src/engine/index.js";
 import { ExecuteCellComponent, type ExecuteDetails, type ExecuteRenderState } from "./src/extension/render.js";
 import { EngineLifecycle, formatResetToast } from "./src/extension/session-engine.js";
+import { conversationName, resolveStateDir } from "./src/extension/state-layout.js";
 import { EXECUTE_DESCRIPTION, buildExecutePromptGuidelines, EXECUTE_PROMPT_SNIPPET } from "./src/extension/tool-meta.js";
 
 const executeSchema = Type.Object({
@@ -58,28 +59,44 @@ export default function (pi: ExtensionAPI) {
 	const pendingErrorResults = new Map<string, { details: ExecuteDetails }>();
 
 	const lifecycle = new EngineLifecycle<EngineManager>({
-		create() {
+		// --- boot deadline: bounds kernel start + helpers preload (recovery is a background
+		// --- quiet-gap job, bounded by the engine's own restore-cell watchdog). An npm update
+		// --- swaps the venv and helpers under a live kernel, and the first boot after it can
+		// --- wedge; 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(skipRestore = false) {
 			const { cwd, sessionFile } = location;
-			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) {
+			// --- kernel namespace state lives under ~/.pi/agent/pi-repl/state, keyed by
+			// --- <project-slug>__<conversation>, so it never clutters the project and two
+			// --- conversations can never share a snapshot dir (resolveStateDir migrates any
+			// --- pre-slug legacy dir on start). Ephemeral sessions get no snapshot at all. ---
+			const stateRoot = join(homedir(), ".pi", "agent", "pi-repl", "state");
+			let snapshot: { path: string } | undefined;
+			let currentDir: string | undefined;
+			if (sessionFile) {
+				const { dir, snapshotPath } = resolveStateDir(stateRoot, sessionFile);
+				currentDir = basename(dir);
+				snapshot = { path: snapshotPath };
+				// --- keep the state root from growing one dir per session forever; the live dir is exempt ---
 				try {
-					pruneSnapshotDirs(join(stateDir, ".."), 25, sessionKey);
+					pruneSnapshotDirs(stateRoot, 25, currentDir);
 				} catch {}
 				// --- cascade deletions: if a conversation is deleted, its snapshots die with it.
 				// --- sessionFile is sessions/<project-root>/<name>.jsonl, so the sessions root is
 				// --- two parent hops up; dirs whose conversation file exists in no project root
-				// --- (and that aren't this session or the ephemeral fallback) are swept. ---
+				// --- (and that aren't this session or the ephemeral fallback) are swept, in both
+				// --- the legacy bare-name and slug-keyed formats. ---
 				try {
-					pruneOrphanedSnapshotDirs(join(stateDir, ".."), sessionFile ? dirname(dirname(sessionFile)) : undefined, sessionKey);
+					pruneOrphanedSnapshotDirs(stateRoot, sessionFile ? dirname(dirname(sessionFile)) : undefined, currentDir);
 				} catch {}
 			}
 			return new EngineManager({
 				cwd,
-				// --- snapshots are keyed to a session file; ephemeral sessions get none ---
-				snapshot: sessionKey ? { path: join(stateDir, "namespace.snapshot") } : undefined,
+				// --- snapshots are keyed to the conversation; ephemeral sessions get none.
+				// --- skipRestore is true on the lifecycle's retry after a wedged boot. ---
+				snapshot,
+				skipRestore,
 			});
 		},
 		async dispose(engine) {
@@ -104,7 +121,8 @@ export default function (pi: ExtensionAPI) {
 		// --- warm the engine (and its revive) in the background; no popup. ---
 		// --- acquire() dedupes, so the first execute awaits this same in-flight boot ---
 		location = { cwd: ctx.cwd, sessionFile: ctx.sessionManager.getSessionFile() ?? undefined };
-		void lifecycle.acquire("startup").catch(() => {
+		const sessionKey = location.sessionFile ? conversationName(location.sessionFile) : undefined;
+		void lifecycle.acquire("startup", sessionKey).catch(() => {
 			// --- boot/revive handled on the execute path; swallow so a background warm can never
 			// --- surface an unhandled rejection. A resume's notice lands on the first cell. ---
 		});
@@ -170,7 +188,8 @@ export default function (pi: ExtensionAPI) {
 			// --- without this the host only renders the result once the first partial or the final result lands ---
 			onUpdate?.({ content: [], details: {} });
 			// --- previous engine died mid-session; acquire revives it ---
-			const { engine: m } = await lifecycle.acquire("cell");
+			const sessionKey = location.sessionFile ? conversationName(location.sessionFile) : undefined;
+			const { engine: m } = await lifecycle.acquire("cell", sessionKey);
 			try {
 				// --- accumulate partial updates so the row height doesn't oscillate ---
 				let streamed = "";
@@ -184,7 +203,7 @@ export default function (pi: ExtensionAPI) {
 				// --- reset notice leads so the model reads that its namespace was rebuilt; the
 				// --- human gets a terse notification instead of the marker, fire and forget ---
 				const reset = lifecycle.takeResetNotice();
-				if (reset?.notice) ctx?.ui?.notify?.(formatResetToast(reset.origin, reset.restore), "info");
+				if (reset?.notice) ctx?.ui?.notify?.(formatResetToast(reset.origin, reset.restore, reset.wedged), "info");
 				const sections = [reset?.notice, r.stdout, r.stderr, r.result];
 				const errorLines = r.error ? composeErrorLines(r.error) : undefined;
 				if (r.status === "error" && errorLines) sections.push(errorLines.join("\n"));

package/package.json

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

@@ -30,6 +30,12 @@ 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;
+/** Quiet-gap window before the background restore fires after boot; never ahead of a user cell. */
+const RESTORE_QUIET_MS = 250;
+/** Deadline for one restore cell (a poisoned pickle can wedge the kernel's single queue for
+ * ever). The reaper kills the kernel and marks the restore skipped so the next call rebuilds
+ * honestly. Mirrors the boot deadline in the lifecycle; also settable per engine via env. */
+const DEFAULT_RESTORE_DEADLINE_MS = 90_000;
 
 interface EngineExecuteError {
 	/** Error class name, e.g. "TypeError". */
@@ -82,6 +88,8 @@ export interface EngineOptions {
 		/** Total base64 payload cap; also the per-entry cap. Oversized entries are skipped with a reason. Default 128 MiB. */
 		maxBytes?: number;
 	};
+	/** Do not revive the snapshot on this engine (used after a wedged restore was detected once). */
+	skipRestore?: boolean;
 }
 
 // --- process-wide cleanup: a child does not die with its parent, so SIGKILL live kernels on exit ---
@@ -158,7 +166,12 @@ export function pruneOrphanedSnapshotDirs(
 		for (const proj of readdirSync(sessionsRoot, { withFileTypes: true })) {
 			if (!proj.isDirectory()) continue;
 			for (const f of readdirSync(join(sessionsRoot, proj.name))) {
-				if (f.endsWith(".jsonl")) liveNames.add(f.slice(0, -".jsonl".length));
+				if (!f.endsWith(".jsonl")) continue;
+				const name = f.slice(0, -".jsonl".length);
+				// --- both state-dir formats are live while their conversation lives: the legacy
+				// --- bare-name dir (pre-slug upgrade) and the slug-keyed dir (see state-layout) ---
+				liveNames.add(name);
+				liveNames.add(`${proj.name}__${name}`);
 			}
 		}
 	} catch {
@@ -191,9 +204,20 @@ export class EngineManager {
 	/** Last-seen top-level namespace names; snapshots are gated on this set changing. */
 	private lastNamespaceNames?: string[];
 	private pythonPath?: string;
+	/** The kernel whose namespace has (or is being) revived from the last snapshot. */
+	private restoredKernel?: KernelClient;
+	/** A wedged revive marks the engine: later kernels on this engine boot without restoring. */
+	private restoreSkipped: boolean;
+	private restoreTimer?: ReturnType<typeof setTimeout>;
+	private restoreResolve?: (result: RestoreResult | null) => void;
+	private restorePromise?: Promise<RestoreResult | null>;
+	private restoreSettledResult?: RestoreResult | null;
 
 	constructor(options: EngineOptions = {}) {
 		this.options = options;
+		this.restoreSkipped = options.skipRestore ?? false;
+		// no snapshot capability: recovery is trivially "nothing to revive"
+		if (!options.snapshot) this.settleRestore(null);
 	}
 
 	get isRunning(): boolean {
@@ -255,6 +279,9 @@ export class EngineManager {
 			throw new Error("Engine has been shut down");
 		}
 		this.state = "running";
+		// recovery is not on the first call's critical path: revive this kernel in the
+		// first quiet gap (never ahead of a user cell) and settle restoreResult().
+		this.maybeScheduleRestore();
 	}
 
 	/** Abrupt teardown: SIGKILL the kernel; safe from process.on("exit"). */
@@ -302,6 +329,19 @@ export class EngineManager {
 				this.kernel = undefined;
 				this.startPromise = undefined;
 				await this.start();
+				// --- a mid-session rebuild must revive the last snapshot BEFORE the cell that
+				// --- triggered it (unlike a session-start boot, where recovery runs in the
+				// --- background quiet gap and the first cell is served immediately). A wedged
+				// --- revive kills the new kernel too; boot a fresh one — the restore is now
+				// --- marked skipped, so the cell proceeds on live state instead of wedging. ---
+				await this.restoreWithReap().catch(() => null);
+				// read health through the getter: TS narrows this.kernel to undefined after the
+				// assignment above, but start() may have replaced it with a live kernel
+				if (!this.isRunning) {
+					this.kernel = undefined;
+					this.startPromise = undefined;
+					await this.start();
+				}
 			}
 			if (this.isShutdown()) {
 				throw new Error("Engine has been shut down");
@@ -387,11 +427,123 @@ export class EngineManager {
 		}
 	}
 
-	async restoreState(): Promise<RestoreResult | null> {
+	/** Resolves with this engine's recovery outcome: the revived names, or null when there was
+	 * nothing to restore, restore was skipped, or restore failed. Never rejects. The restore runs
+	 * as a background quiet-gap job, so this promise is the ONLY hook the lifecycle needs to
+	 * announce a resume or rebuild — acquire() never awaits it. */
+	restoreResult(): Promise<RestoreResult | null> {
+		if (this.restoreSettledResult !== undefined) return Promise.resolve(this.restoreSettledResult);
+		if (!this.restorePromise) {
+			this.restorePromise = new Promise<RestoreResult | null>((resolve) => {
+				this.restoreResolve = resolve;
+			});
+		}
+		return this.restorePromise;
+	}
+
+	/** True when restoring was deliberately skipped (a prior revive wedged or the engine was
+	 * built with skipRestore). Lets the lifecycle say exactly why a revival did not happen. */
+	restoreWasSkipped(): boolean {
+		return this.restoreSkipped;
+	}
+
+	private settleRestore(result: RestoreResult | null): void {
+		if (this.restoreSettledResult !== undefined) return;
+		this.restoreSettledResult = result;
+		this.restoreResolve?.(result);
+		this.restoreResolve = undefined;
+	}
+
+	/** Arm the background revive for the freshly booted kernel. It fires in the first quiet gap
+	 * (the same rule as the debounced snapshot: never ahead of a user cell) and settles
+	 * restoreResult(). A fresh engine therefore serves its first cell without waiting for the
+	 * restore, while a mid-session rebuild (execute's zombie path) forces it synchronously. */
+	private maybeScheduleRestore(): void {
+		const config = this.options.snapshot;
+		if (!config) return;
+		if (this.restoreSkipped) {
+			this.settleRestore(null);
+			return;
+		}
+		if (this.kernel && this.kernel === this.restoredKernel) return; // this kernel already revived
+		if (!existsSync(config.path)) {
+			this.settleRestore(null);
+			return;
+		}
+		if (this.restoreTimer) return; // already armed
+		const arm = () => {
+			this.restoreTimer = setTimeout(() => {
+				this.restoreTimer = undefined;
+				// --- quiet-gap rule, mirroring scheduleSnapshot: a pickling restore must not
+				// --- queue ahead of the user's next cell on the kernel's single queue ---
+				if (this.inFlightCells > 0 || !this.kernel?.isRunning) {
+					arm();
+					return;
+				}
+				void this.runRestore();
+			}, RESTORE_QUIET_MS);
+			this.restoreTimer.unref?.();
+		};
+		arm();
+	}
+
+	/** Run the restore cell with a watchdog. A snapshot value whose unpickling never returns
+	 * wedges the kernel's single queue forever; the reaper SIGKILLs the kernel and marks the
+	 * restore skipped, so the next call rebuilds honestly ("wedged while reviving; skipped")
+	 * instead of hanging every later cell behind the restore. */
+	private async restoreWithReap(): Promise<RestoreResult | null> {
 		const config = this.options.snapshot;
-		if (!config) return null;
-		if (!existsSync(config.path)) return null;
+		if (!config || !this.kernel || this.restoreSkipped) {
+			this.settleRestore(null);
+			return null;
+		}
+		if (this.kernel === this.restoredKernel) return this.restoreResult();
+		const deadlineMs =
+			Number(process.env.PI_REPL_BOOT_TIMEOUT_MS ?? this.options.env?.PI_REPL_BOOT_TIMEOUT_MS ?? 0) ||
+			DEFAULT_RESTORE_DEADLINE_MS;
+		const reaper = setTimeout(() => {
+			this.restoreSkipped = true;
+			this.settleRestore(null);
+			this.kernel?.kill();
+		}, deadlineMs);
+		reaper.unref?.();
+		try {
+			return await this.restoreState(false).catch(() => null);
+		} finally {
+			clearTimeout(reaper);
+		}
+	}
+
+	private async runRestore(): Promise<void> {
+		await this.restoreWithReap();
+	}
+
+	/** Revive this engine's kernel from the snapshot file. Idempotent per kernel: a second call
+	 * shares the outcome of an in-flight restore instead of double-running the restore cell. */
+	async restoreState(skip = false): Promise<RestoreResult | null> {
+		// --- start unconditionally: direct callers may not have started the engine, and a
+		// --- wedged boot is detectable only while a boot attempt is actually under way ---
 		await this.start();
+		if (skip) {
+			this.settleRestore(null);
+			return null;
+		}
+		const config = this.options.snapshot;
+		const kernel = this.kernel;
+		if (!config || !kernel || this.restoreSkipped) {
+			this.settleRestore(null);
+			return null;
+		}
+		if (kernel === this.restoredKernel) {
+			// already revived or reviving on this kernel: share the outcome, never double-run
+			return this.restoreResult();
+		}
+		// claim the kernel now so the quiet-gap scheduler cannot start a second restore cell
+		this.restoredKernel = kernel;
+		if (!existsSync(config.path)) {
+			this.settleRestore(null);
+			return null;
+		}
 		try {
 			const payload = JSON.parse(readFileSync(config.path, "utf8")) as {
 				version?: number;
@@ -403,9 +555,12 @@ export class EngineManager {
 				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 };
+			const reply = await kernel.restore(entries);
+			const result: RestoreResult = { path: config.path, restored: reply.restored, failed: reply.failed };
+			this.settleRestore(result);
+			return result;
 		} catch {
+			this.settleRestore(null);
 			return null;
 		}
 	}

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

@@ -1,4 +1,6 @@
-// revival is part of create() so a session that gets teardown without a session_start reload still revives
+// The lifecycle owns boot, session binding, and the reset announcements. Recovery is a
+// background engine job (the quiet-gap restore): the first tool call waits only for the
+// kernel to come up, and the reset notice lands on the first cell AFTER the restore lands.
 
 import type { RestoreResult } from "../engine/index.js";
 
@@ -10,44 +12,59 @@ 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 kernel (and preload helpers), independent of snapshot recovery. */
+	start(skipRestore?: boolean): Promise<void>;
+	/** Resolves once this engine's recovery has settled: revived names, or null when there was
+	 * nothing to revive, recovery was skipped, or recovery failed. Never rejects. */
+	restoreResult(): Promise<RestoreResult | null>;
+	/** True when recovery was deliberately skipped (a prior revive wedged). */
+	restoreWasSkipped(): boolean;
 	/** True when this conversation's state dir already exists, so the engine was resumed. */
 	hasSnapshotHistory(): boolean;
 }
 
 export interface EngineLifecycleDeps<E extends RevivableEngine> {
-	/** Builds a fresh engine. Called at most once per lifecycle generation. */
-	create(): E;
+	/** Builds a fresh engine. Called at most once per lifecycle generation; `skipRestore` is
+	 * true on the retry after a wedged boot, so the poisoned snapshot cannot wedge twice. */
+	create(skipRestore?: boolean): E;
 	/** Tears the current engine down, flushing its final snapshot. */
 	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) that outlives it is killed
+	 * and retried fresh. Default 90s. Recovery is NOT inside this deadline: it runs in the
+	 * background and is bounded by the engine's own restore-cell watchdog. */
+	bootTimeoutMs?: number;
 }
 
-/** `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. */
+/** `startup` restores then announces 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. ---
-export function formatResetToast(origin: AcquireOrigin, restore: RestoreResult | null): string {
+export function formatResetToast(origin: AcquireOrigin, restore: RestoreResult | null, wedged = false): string {
 	const resumed = origin === "startup";
+	const verb = resumed ? "repl session resumed" : "repl kernel rebuilt";
+	if (wedged) return `${verb}, snapshot revive skipped (wedged)`;
 	const revived = restore?.restored.length ?? 0;
 	const lost = restore?.failed.length ?? 0;
 	if (restore && revived > 0) {
 		const counts = lost > 0 ? `, ${lost} lost` : "";
 		const noun = revived === 1 ? "name" : "names";
-		return resumed
-			? `repl session resumed, ${revived} ${noun} revived${counts}`
-			: `repl kernel rebuilt, ${revived} ${noun} revived${counts}`;
+		return `${verb}, ${revived} ${noun} revived${counts}`;
 	}
-	return resumed
-		? restore === null
-			? "repl session resumed, nothing saved to revive"
-			: "repl session resumed, nothing could be revived"
-		: restore === null
-			? "repl kernel rebuilt, nothing saved to revive"
-			: "repl kernel rebuilt, nothing could be revived";
+	return restore === null ? `${verb}, nothing saved to revive` : `${verb}, nothing could be revived`;
 }
 
 function formatEngineResetNotice(restore: RestoreResult | null, origin: AcquireOrigin): string {
@@ -103,38 +120,99 @@ function formatEngineResetNotice(restore: RestoreResult | null, origin: AcquireO
 
 export class EngineLifecycle<E extends RevivableEngine> {
 	private engine?: E;
-	private revival?: Promise<RestoreResult | null>;
 	private pendingNotice?: string;
-	private pendingReset?: { origin: AcquireOrigin; restore: RestoreResult | null };
+	private pendingReset?: { origin: AcquireOrigin; restore: RestoreResult | null; wedged: boolean };
 	private teardown?: Promise<void>;
 	/** First-build in progress. */
 	private acquiring?: Promise<{ engine: E; restore: RestoreResult | null; created: boolean }>;
+	/** The conversation this engine was built for; a different key on acquire tears it down. */
+	private boundKey?: string;
 
 	constructor(private readonly deps: EngineLifecycleDeps<E>) {}
 
-	/** 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 }> {
+	/** Race one BOOT attempt (kernel start + helpers preload) against the deadline. Recovery is
+	 * deliberately outside this race: it runs as a background quiet-gap job and is bounded by the
+	 * engine's own restore-cell watchdog. A failed start is soft — the first cell observes it and
+	 * the caller rebuilds. */
+	private bootOnce(engine: E, deadlineMs: number): Promise<boolean> {
+		const work = Promise.resolve()
+			.then(() => engine.start(false))
+			.catch(() => {});
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		const guard = new Promise<boolean>((resolve) => {
+			timer = setTimeout(() => resolve(false), deadlineMs);
+			timer.unref?.();
+		});
+		return Promise.race([work.then(() => true), guard]).finally(() => clearTimeout(timer));
+	}
+
+	/**
+	 * Built and booted on demand; the snapshot restore proceeds in the background, so acquire()
+	 * NEVER waits on it. The engine's revive is announced (reset notice + toast) on the first
+	 * cell after it completes.
+	 *
+	 * `sessionKey` guards against sessions bleeding into each other: pi tears the old session
+	 * down before starting the next, but a missed or out-of-order shutdown must never serve one
+	 * conversation's engine and namespace to another — acquire for a different key tears the
+	 * bound engine down (flushing its snapshot) before building the new one.
+	 */
+	async acquire(
+		origin: AcquireOrigin,
+		sessionKey?: string,
+	): Promise<{ engine: E; restore: RestoreResult | null; created: boolean }> {
+		if (sessionKey !== undefined && this.boundKey !== undefined && sessionKey !== this.boundKey) {
+			await this.teardownWith((engine) => this.deps.dispose(engine));
+		}
 		if (this.engine) {
-			return { engine: this.engine, restore: await this.revival!, created: false };
+			return { engine: this.engine, restore: null, created: false };
 		}
 		if (this.acquiring) return this.acquiring;
 		const build = (async () => {
 			while (this.teardown) await this.teardown;
 			if (this.engine) {
 				const held: E = this.engine;
-				return { engine: held, restore: await this.revival!, created: false };
+				return { engine: held, restore: null, created: false };
 			}
-			const engine = this.deps.create();
+			this.boundKey = sessionKey;
+			const deadline = this.deps.bootTimeoutMs ?? DEFAULT_BOOT_TIMEOUT_MS;
+			let engine = this.deps.create();
 			this.engine = engine;
-			this.revival = engine.restoreState().catch(() => null);
-			const restore = await this.revival;
-			// --- 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);
-				this.pendingReset = { origin, restore };
+			let booted = await this.bootOnce(engine, deadline);
+			if (!booted) {
+				// --- the kernel is alive but stuck; only a kill frees it. Retry once WITHOUT the
+				// --- snapshot, so a poisoned snapshot cannot wedge the session twice in a row. ---
+				await (this.deps.discard ?? this.deps.dispose)(engine);
+				engine = this.deps.create(true);
+				this.engine = engine;
+				booted = await this.bootOnce(engine, deadline);
+				if (!booted) {
+					await (this.deps.discard ?? this.deps.dispose)(engine);
+					this.engine = undefined;
+					this.boundKey = undefined;
+					throw new Error("evaluator boot timed out twice (kernel/helpers wedged); no session was started");
+				}
 			}
-			return { engine, restore, created: true };
+			// --- recovery is async and off the first call's critical path: the engine revives in
+			// --- the first quiet gap and the notice lands on the first cell AFTER it completes
+			// --- (index.ts takes it with takeResetNotice after the next execute). announce when
+			// --- mid-session rebuilds happen, or on startup for a conversation with a saved past;
+			// --- a first-ever session stays quiet. ---
+			const announce = origin === "cell" || (origin === "startup" && engine.hasSnapshotHistory());
+			void engine.restoreResult().then((restore) => {
+				if (this.engine !== engine) return; // a replacement engine took over; no stale notice
+				if (!announce) return;
+				const wedged = engine.restoreWasSkipped();
+				this.pendingNotice = wedged
+					? [
+							"<repl_engine_reset>",
+							revivedNoticeBody(origin),
+							"Re-verify a variable before reusing it, especially inside shell interpolation.",
+							"</repl_engine_reset>",
+						].join("\n")
+					: formatEngineResetNotice(restore, origin);
+				this.pendingReset = { origin, restore, wedged };
+			});
+			return { engine, restore: null, created: true };
 		})();
 		this.acquiring = build;
 		try {
@@ -144,14 +222,17 @@ export class EngineLifecycle<E extends RevivableEngine> {
 		}
 	}
 
-	/** Returns the pending reset notice exactly once (alongside its origin and restore result), then clears it. */
-	takeResetNotice(): { notice: string; origin: AcquireOrigin; restore: RestoreResult | null } | undefined {
+	/** Returns the pending reset notice exactly once (alongside its origin, restore result, and
+	 * whether the restore was skipped), then clears it. */
+	takeResetNotice():
+		| { notice: string; origin: AcquireOrigin; restore: RestoreResult | null; wedged: boolean }
+		| undefined {
 		const reset = this.pendingReset;
 		const notice = this.pendingNotice;
 		this.pendingNotice = undefined;
 		this.pendingReset = undefined;
 		if (!notice || !reset) return undefined;
-		return { notice, origin: reset.origin, restore: reset.restore };
+		return { notice, origin: reset.origin, restore: reset.restore, wedged: reset.wedged };
 	}
 
 	async shutdown(): Promise<void> {
@@ -166,7 +247,7 @@ export class EngineLifecycle<E extends RevivableEngine> {
 	private async teardownWith(run: (engine: E) => Promise<void>): Promise<void> {
 		const engine = this.engine;
 		this.engine = undefined;
-		this.revival = undefined;
+		this.boundKey = undefined;
 		this.pendingNotice = undefined;
 		if (!engine) return;
 		const teardown = run(engine).finally(() => {

package/src/extension/state-layout.ts

@@ -0,0 +1,45 @@
+// --- where a conversation's kernel state lives: ~/.pi/agent/pi-repl/state/<key>.
+// --- Keys must never collide across conversations, so the project-root slug joins the
+// --- conversation name. Pre-slug legacy dirs (bare name) migrate to the slug key on the
+// --- owning conversation's next start; the orphan sweep still recognizes both formats,
+// --- so nothing live is ever swept and a deleted conversation loses all its snapshots. ---
+import { existsSync, renameSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+/** The conversation's own name: the session file's basename without .jsonl (unique per conversation). */
+export function conversationName(sessionFile: string): string {
+	return basename(sessionFile).replace(/\.jsonl$/, "");
+}
+
+/** Slug-keyed state dir name: unique among all conversations under one sessions root, so two
+ * conversations whose files happen to share a basename (copied/renamed session files) can never
+ * share a snapshot. */
+export function sessionStateDirName(sessionFile: string): string {
+	return `${basename(dirname(sessionFile))}__${conversationName(sessionFile)}`;
+}
+
+/** The pre-slug dir name; still honored when migrating or scanning live conversations. */
+function legacyStateDirName(sessionFile: string): string {
+	return conversationName(sessionFile);
+}
+
+/**
+ * Resolve a conversation's state dir and snapshot file, migrating a legacy bare-name dir to the
+ * slug key on first start. Two conversations whose files share a basename therefore never share a
+ * snapshot file: whichever starts first migrates the legacy dir to its own key; the other starts
+ * empty rather than bleeding into the first's namespace.
+ */
+export function resolveStateDir(stateRoot: string, sessionFile: string): { dir: string; snapshotPath: string } {
+	const dir = join(stateRoot, sessionStateDirName(sessionFile));
+	const legacy = join(stateRoot, legacyStateDirName(sessionFile));
+	const dirSnap = join(dir, "namespace.snapshot");
+	const legacySnap = join(legacy, "namespace.snapshot");
+	if (legacy !== dir && !existsSync(dirSnap) && existsSync(legacySnap)) {
+		try {
+			renameSync(legacy, dir); // migrate; a racing rename (another conversation) just falls through
+		} catch {
+			// the slug dir already exists or the rename raced: keep it; legacy stays until the sweep sees it live or orphaned
+		}
+	}
+	return { dir, snapshotPath: join(dir, "namespace.snapshot") };
+}