pi-repl-py 0.6.13 → 0.7.0

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,111 @@ 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; a binding skipped
+at save time is named in the resume notice, never dropped silently, and a failed snapshot leaves
+the retry gate in place (only a persisted write advances it); a periodic refresh (default 2 min, `snapshot.periodMs`, 0 disables) bounds the loss window for same-name mutations and stands down when the last snapshot exceeded 8 MiB; value entries are zlib-compressed (file format version 3 — v1/v2 files remain restorable); 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 /fork'd conversation inherits the parent's last snapshot — copied once into the fork's own key at first start, so it resumes with state, carries the standard reset marker on its first cell, and the human gets a dedicated fork toast; the parent is untouched.
+
+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 +130,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 +143,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,21 +159,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).
-
-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.
+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/docs/helpers.md

@@ -79,6 +79,10 @@ A helper may define `helper_description`:
 helper_description = """double(x) — multiply a value by two."""
 ```
 
+The value must be a **triple-quoted string** (`"""..."""` or `'''...'''`): a plain-quoted
+assignment is not recognized, and the helper is advertised with a pointer text telling the
+model to inspect it (`print(double.__doc__)`) instead.
+
 The host reads this value and puts it in the `execute` tool description verbatim. It is guidance for the model, not a registration mechanism or generated API. Keep it short: it
 is included in the model's context on every turn.
 
@@ -127,6 +131,15 @@ At startup, two parts of pi-repl read the same merged helper list (project dirs
 1. The kernel executes each eligible `.py` file. Its definitions become names in the Python workspace.
 2. The host reads `helper_description` to build the helper guidance shown to the model.
 
+Both resolve the list from the **session's working directory** (not the folder pi was launched
+from), so a resumed session advertises exactly the helpers its kernel loads. The per-session
+list is rebuilt at every agent start and stated in the system prompt.
+
+Each helper file executes in its **own cell**, so a broken helper (a syntax error or a top-level
+raise) fails alone and does not stop the others. When a helper fails to load, the next cell's
+output carries a `<repl_helpers_failed: name (error)>` line, and you get a toast; an
+all-good boot stays silent.
+
 The host does not inspect `def` lines or infer signatures from filenames. A helper does not need to define one particular symbol. The file is the unit of loading; its public names are the names it defines or imports for use in
 the workspace.
 

package/index.ts

@@ -5,9 +5,11 @@ 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 { buildHelpersPromptSection } from "./src/extension/helpers.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 { EngineLifecycle, formatForkToast, formatHelperFailuresLine, formatHelperToast, formatResetToast } from "./src/extension/session-engine.js";
+import { conversationName, inheritForkSnapshot, 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,33 +60,38 @@ 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. ---
+		// --- bound the boot: a wedged first boot would hang every cell (acquire() dedupes onto it) ---
 		bootTimeoutMs: Number(process.env.PI_REPL_BOOT_TIMEOUT_MS ?? 90_000) || 90_000,
-		create() {
+		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) {
+			// --- state lives under ~/.pi/agent/pi-repl/state/<slug>__<conv>; conversations never share a snapshot; ephemeral sessions get none ---
+			const stateRoot = join(homedir(), ".pi", "agent", "pi-repl", "state");
+			let snapshot: { path: string } | undefined;
+			let forkInherited = false;
+			let currentDir: string | undefined;
+			if (sessionFile) {
+				const { dir, snapshotPath } = resolveStateDir(stateRoot, sessionFile);
+				currentDir = basename(dir);
+				snapshot = { path: snapshotPath };
+				// --- a /fork'd conversation inherits the parent's last namespace (copied once into the fork's own key) ---
 				try {
-					pruneSnapshotDirs(join(stateDir, ".."), 25, sessionKey);
+					forkInherited = inheritForkSnapshot(stateRoot, sessionFile, snapshotPath);
 				} 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. ---
+				// --- keep the state root from growing one dir per session forever; the live dir is exempt ---
 				try {
-					pruneOrphanedSnapshotDirs(join(stateDir, ".."), sessionFile ? dirname(dirname(sessionFile)) : undefined, sessionKey);
+					pruneSnapshotDirs(stateRoot, 25, currentDir);
+				} catch {}
+				// --- sweep state dirs whose conversation file exists in no project root: deleting a conversation deletes its snapshots (both dir formats) ---
+				try {
+					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 per-conversation; skipRestore marks the wedged-boot retry ---
+				snapshot,
+				skipRestore,
+				forkInherited,
 			});
 		},
 		async dispose(engine) {
@@ -104,14 +111,12 @@ export default function (pi: ExtensionAPI) {
 			pi.setActiveTools(pi.getActiveTools().filter((name) => name !== "execute"));
 			return;
 		}
-		// --- active: the whole surface collapses to the one tool ---
 		pi.setActiveTools(["execute"]);
-		// --- warm the engine (and its revive) in the background; no popup. ---
-		// --- acquire() dedupes, so the first execute awaits this same in-flight boot ---
+		// --- warm the engine in the background; acquire() dedupes, so the first execute awaits this same boot ---
 		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. A resume's notice lands on the first cell. ---
+		const sessionKey = location.sessionFile ? conversationName(location.sessionFile) : undefined;
+		void lifecycle.acquire("startup", sessionKey).catch(() => {
+			// --- swallow the warm boot's rejection: boot/revive are handled on the execute path ---
 		});
 	});
 
@@ -128,14 +133,14 @@ export default function (pi: ExtensionAPI) {
 		return { content: event.content, details: stashed.details, isError: true };
 	});
 
-	// --- pi gates skills on the read tool (absent in repl); re-emit them via withSkillsBlock. ---
-	pi.on("before_agent_start", (event) => {
+	// --- pi gates skills on the read tool (absent in repl); the helper roster is rebuilt per session from the session cwd, not the launch cwd, so resumes advertise what the kernel loaded ---
+	pi.on("before_agent_start", (event, ctx) => {
 		if (!active()) return;
-		const systemPrompt = withSkillsBlock(
-			event.systemPrompt,
-			event.systemPromptOptions?.skills ?? [],
-		);
-		return systemPrompt === undefined ? undefined : { systemPrompt };
+		const skillsPrompt = withSkillsBlock(event.systemPrompt, event.systemPromptOptions?.skills ?? []);
+		let systemPrompt = skillsPrompt ?? event.systemPrompt;
+		const helpersBlock = buildHelpersPromptSection(ctx?.cwd ?? process.cwd());
+		if (helpersBlock) systemPrompt = `${systemPrompt}\n\n${helpersBlock}`;
+		return systemPrompt === event.systemPrompt ? undefined : { systemPrompt };
 	});
 
 	pi.registerTool<typeof executeSchema, ExecuteDetails, Partial<ExecuteRenderState>>({
@@ -143,7 +148,7 @@ export default function (pi: ExtensionAPI) {
 		label: "execute",
 		description: EXECUTE_DESCRIPTION,
 		promptSnippet: EXECUTE_PROMPT_SNIPPET,
-		promptGuidelines: buildExecutePromptGuidelines(process.cwd()),
+		promptGuidelines: buildExecutePromptGuidelines(),
 		parameters: executeSchema,
 		renderShell: "self",
 		renderCall(args, theme, context) {
@@ -171,11 +176,10 @@ export default function (pi: ExtensionAPI) {
 				throw new Error("pi-repl is dormant in this session. Start pi with --repl (or PI_REPL_FORCE=1) to use execute.");
 			}
 			if (ctx?.cwd) location = { cwd: ctx.cwd, sessionFile: ctx.sessionManager?.getSessionFile?.() ?? undefined };
-			// --- establish the body slot at call time so Ctrl+O can expand a live (still-awaiting) stream;
-			// --- without this the host only renders the result once the first partial or the final result lands ---
+			// --- establish the body slot at call time so Ctrl+O can expand a live, still-streaming cell ---
 			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 = "";
@@ -186,11 +190,23 @@ export default function (pi: ExtensionAPI) {
 						onUpdate?.({ content: [{ type: "text", text: streamed }], details: {} });
 					},
 				});
-				// --- 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 ---
+				// --- reset notice leads so the model reads the rebuild; the human gets a terse toast instead ---
 				const reset = lifecycle.takeResetNotice();
-				if (reset?.notice) ctx?.ui?.notify?.(formatResetToast(reset.origin, reset.restore), "info");
-				const sections = [reset?.notice, r.stdout, r.stderr, r.result];
+				if (reset?.notice)
+					ctx?.ui?.notify?.(
+						m.inheritedFromFork ? formatForkToast(reset.restore) : formatResetToast(reset.origin, reset.restore, reset.wedged),
+						"info",
+					);
+				// --- helper verdicts once per boot: toast for the human, marker for the model only when a helper failed (all-good boots stay silent) ---
+				const helperReport = m.takeHelperReport();
+				if (helperReport && helperReport.length > 0) ctx?.ui?.notify?.(formatHelperToast(helperReport), "info");
+				const sections = [
+					reset?.notice,
+					formatHelperFailuresLine(helperReport),
+					r.stdout,
+					r.stderr,
+					r.result,
+				];
 				const errorLines = r.error ? composeErrorLines(r.error) : undefined;
 				if (r.status === "error" && errorLines) sections.push(errorLines.join("\n"));
 				if (r.status === "aborted") sections.push("[cell aborted]");

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-repl-py",
-	"version": "0.6.13",
+	"version": "0.7.0",
 	"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/scripts/setup-venv.mjs

@@ -1,16 +1,5 @@
 #!/usr/bin/env node
-/**
- * postinstall: build the stable per-user Python venv the evaluator needs.
- *
- * On a package install the venv is built at a stable path the engine knows:
- *
- *   ~/.pi/agent/pi-repl/venv/bin/python3
- *
- * The venv is repaired in place: if it exists but ipykernel is not importable,
- * this reflushes the venv and reinstalls rather than trusting a half-built one.
- * Failures are NOT silent: a bad build exits non-zero so `npm install` / `pi
- * install` visibly fails instead of leaving a broken evaluator.
- */
+/** postinstall: build the stable per-user venv at ~/.pi/agent/pi-repl/venv; repair in place if ipykernel is missing; a bad build fails the install loudly. */
 
 import { execSync } from "node:child_process";
 import { mkdirSync } from "node:fs";
@@ -22,8 +11,7 @@ const PY = join(VENV_DIR, "bin", "python3");
 const DEPS = ["ipykernel"];
 const HELPERS_DIR = join(homedir(), ".pi", "agent", "pi-repl", "helpers");
 
-// A venv that exists but can't import ipykernel is broken. Never trust the
-// binary alone — a half-built venv otherwise looks "already up" forever.
+// A venv that can't import ipykernel is broken — never trust the binary alone.
 function ipykernelOk() {
   try {
     execSync(`${PY} -c "import ipykernel"`, { stdio: "ignore" });
@@ -50,10 +38,7 @@ function findSystemPython() {
   return null;
 }
 
-// ---------------------------------------------------------------- helpers dir
-// The helpers dir is user-owned. We create it empty on install. The REPL
-// provides shell and file IO natively; helpers are for things the user adds
-// themselves (e.g. web_search, custom skills). Existing files are never clobbered.
+// --- helpers dir: user-owned, created empty; existing files are never clobbered ---
 function seedHelpersDir() {
   try {
     mkdirSync(HELPERS_DIR, { recursive: true });
@@ -89,9 +74,7 @@ function main() {
     }
     log("done. The pi-repl evaluator will use this venv.");
   } catch (error) {
-    // A real failure must not exit 0 with a broken venv. npm/pi will see the
-    // nonzero exit and report the install as failed instead of silently
-    // handing the user a dead evaluator.
+    // a real failure must exit non-zero — never hand the user a dead evaluator
     fail(`could not build the evaluator venv (${error && error.message ? error.message : error}). `);
   }
 }
@@ -101,4 +84,4 @@ function fail(m) {
   process.exit(1);
 }
 
-main();
+main();

package/src/engine/helpers-locate.ts

@@ -5,7 +5,6 @@ import { dirname, join, resolve } from "node:path";
 
 const GLOBAL_HELPERS_DIR = join(homedir(), ".pi", "agent", "pi-repl", "helpers");
 
-/** Ordered candidate dirs: nearest .pi/helpers up to the git root, then the global dir last. */
 export function resolveHelperDirs(cwd?: string, globalDir?: string): string[] {
 	const dirs: string[] = [];
 	if (cwd) {