pi-repl-py 0.6.7 → 0.6.9

package/README.md

@@ -64,22 +64,25 @@ On **Termux (Android)**, the `postinstall` venv build can fail because `ipykerne
 
 A **helper** is a `.py` file that gets exec'd into every kernel, so whatever it defines
 (like functions, classes, constants, imports, or a module that manages a tricky piece of
-complexity) is available in the workspace. Drop a file in the one helpers directory and
-restart the session; e.g. `helpers/double.py` defining `def double(x)` becomes callable as
-`double(...)`. It ships **empty** (shell and file IO are already plain Python), so a fresh
-install preloads nothing until you add one. Each helper's `helper_description` is shown to
-the model verbatim; the full contract lives in [docs/helpers.md](docs/helpers.md).
+complexity) is available in the workspace. Drop a file in a `.pi/helpers/` directory in
+your project (or `~/.pi/agent/pi-repl/helpers/` for every project) and restart the session;
+e.g. `helpers/double.py` defining `def double(x)` becomes callable as `double(...)`. Global
+helpers ship **empty** (shell and file IO are already plain Python), so a fresh install
+preloads nothing until you add one. Project helpers shadow same-named global ones. Each
+helper's `helper_description` is shown to the model verbatim; the full contract lives in
+[docs/helpers.md](docs/helpers.md).
 
-Everything the extension keeps lives under one folder in your home directory:
+The extension keeps its runtime under one folder in your home directory:
 
 ```
 ~/.pi/agent/pi-repl/
   venv/         the Python interpreter + ipykernel
-  helpers/      your helpers (created empty on install; every *.py loads)
+  helpers/      global helpers (created empty on install; every *.py loads)
   state/        per-session namespace snapshots
 ```
 
-The helpers directory is fixed at `~/.pi/agent/pi-repl/helpers`. No config file.
+Project helpers live in `<project>/.pi/helpers/` instead; both tiers are scanned with the
+project one first. No config file.
 
 Changing a helper (adding/removing a file, renaming one with a `_` prefix) needs a
 **session restart / `/reload`**: the prompt list is built when `execute` is registered and

package/docs/ARCHITECTURE.md

@@ -98,20 +98,23 @@ 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's abort grace then
-kills the kernel after 500 ms, and the next call rebuilds it from the last snapshot.
+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.
 
 ## Helpers loading
 
-At boot, the kernel and the host both read the same helpers directory:
-`~/.pi/agent/pi-repl/helpers`. It is created empty on install. No shipped toolbox is merged in.
+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.
 
 - **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.
 
-Both sides read the same directory, so the names described to the model come from files the
+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
@@ -145,7 +148,7 @@ what was lost, so the model re-verifies before reusing state that may be gone.
 | Failure | Behaviour |
 | --- | --- |
 | Cell throws | `error` status with traceback; kernel namespace intact |
-| Cell silent or wedged | the watchdog sends an `interrupt_request`; a caller abort then kills the kernel after a 500 ms grace |
+| 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 |
 | Host exits | `process.on("exit")` SIGKILLs live kernels (a child does not die with its parent) |
 | Output flood | capped per channel, truncation announced |
@@ -175,11 +178,13 @@ watchdog timeout.
   state/        per-session namespace snapshots
 ```
 
-The helpers directory is fixed at `~/.pi/agent/pi-repl/helpers` (matching the kernel's
-`readHelperSources` default), so both sides are guaranteed to read the same directory. 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).
+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).
 
 ## Reference documentation
 

package/docs/helpers.md

@@ -9,13 +9,26 @@ name or any other public name in the file.
 
 ## Where helpers live
 
+Helpers come from two places: a **project** directory and a **global** directory.
+
 ```text
-~/.pi/agent/pi-repl/helpers/
+<project>/.pi/helpers/                 project helpers (looked up from the working dir)
+~/.pi/agent/pi-repl/helpers/           global helpers (every project)
 ```
 
-The directory is created empty when pi-repl is installed. Every `.py` file in it is loaded when the evaluator starts. Files whose names begin with `_` are ignored.
+The global directory is created empty when pi-repl is installed. In a project, any
+`.pi/helpers/` directory is picked up by walking up from the working directory to the
+git repo root, so a helper works no matter how deep in the project you are.
+
+Every `.py` file found is loaded when the evaluator starts; files whose names begin with
+`_` are ignored.
+
+The two tiers merge: a project helper **shadows** a same-named global helper, and global
+helpers fill in whatever the project does not define. One file name appears once in the
+tool prompt and once in the kernel.
 
-After adding, changing, renaming, or disabling a helper, run `/reload` or start a new `pi --repl` session. The running evaluator does not watch the directory for changes.
+After adding, changing, renaming, or disabling a helper, run `/reload` or start a new
+`pi --repl` session. The running evaluator does not watch the directories for changes.
 
 ## A small function helper
 
@@ -109,7 +122,7 @@ Use docstrings for argument details, defaults, return values, errors, environmen
 
 ## How loading works
 
-At startup, two parts of pi-repl read the same helper directory:
+At startup, two parts of pi-repl read the same merged helper list (project dirs first, global last):
 
 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.
@@ -196,7 +209,7 @@ The loader skips it. Rename it back and reload when you want it again.
 
 ## Checklist
 
-- [ ] The file is in `~/.pi/agent/pi-repl/helpers/`.
+- [ ] The file is in `~/.pi/agent/pi-repl/helpers/` (global) or in `<project>/.pi/helpers/` (project-scoped).
 - [ ] Its public names and call shapes are clear.
 - [ ] `helper_description` is short enough for every-turn context.
 - [ ] Detailed behavior is in docstrings.

package/index.ts

@@ -125,16 +125,18 @@ export default function (pi: ExtensionAPI) {
 		label: "execute",
 		description: EXECUTE_DESCRIPTION,
 		promptSnippet: EXECUTE_PROMPT_SNIPPET,
-		promptGuidelines: buildExecutePromptGuidelines(),
+		promptGuidelines: buildExecutePromptGuidelines(process.cwd()),
 		parameters: executeSchema,
 		renderShell: "self",
 		renderCall(args, theme, context) {
 			const state = syncRenderState(context.state, { ...context, args });
+			state.version = (state.version ?? 0) + 1;
 			// --- compact header lives in the call slot ---
 			return new ExecuteCellComponent(state, theme, "header");
 		},
 		renderResult(result, options, _theme, context) {
 			const state = syncRenderState(context.state, context);
+			state.version = (state.version ?? 0) + 1;
 			state.hasResult = true;
 			state.isPartial = options.isPartial;
 			state.expanded = options.expanded;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-repl-py",
-	"version": "0.6.7",
+	"version": "0.6.9",
 	"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/helpers-locate.ts

@@ -0,0 +1,24 @@
+// --- shared helper-dir resolution: prompt and kernel must read the same ordered list ---
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+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) {
+		let cur = resolve(cwd);
+		for (;;) {
+			const d = join(cur, ".pi", "helpers");
+			if (existsSync(d)) dirs.push(d);
+			if (existsSync(join(cur, ".git"))) break;
+			const parent = dirname(cur);
+			if (parent === cur) break;
+			cur = parent;
+		}
+	}
+	dirs.push(globalDir ?? GLOBAL_HELPERS_DIR);
+	return dirs;
+}

package/src/engine/index.ts

@@ -116,6 +116,8 @@ export class EngineManager {
 	private startPromise?: Promise<void>;
 	private executionQueue: Promise<unknown> = Promise.resolve();
 	private snapshotTimer?: ReturnType<typeof setTimeout>;
+	/** User cells currently running on the kernel; the debounced snapshot never cuts in front of one. */
+	private inFlightCells = 0;
 	/** Last-seen top-level namespace names; snapshots are gated on this set changing. */
 	private lastNamespaceNames?: string[];
 	private pythonPath?: string;
@@ -254,13 +256,16 @@ export class EngineManager {
 			};
 			opts.signal?.addEventListener("abort", onAbort, { once: true });
 
+			this.inFlightCells++;
 			try {
 				const r = await this.kernel!.executeCell(code, {
 					signal: opts.signal,
 					onStream: opts.onStream,
 					maxOutputChars: maxChars,
 				});
-				if (r.status === "ok") void this.scheduleSnapshotIfChanged();
+				// --- names gate runs off the critical path so the next execute's kernel
+				// --- request enqueues before the list-names hop, not behind it ---
+				if (r.status === "ok") setImmediate(() => void this.scheduleSnapshotIfChanged());
 				const status: ExecuteResult["status"] = opts.signal?.aborted ? "aborted" : r.status;
 				// Channel cap (truncateWithMarker), then per-line cap; both append a marker so truncation is explicit.
 				const finalize = (text: string, channelTruncated: boolean): string => {
@@ -286,6 +291,7 @@ export class EngineManager {
 			} finally {
 				opts.signal?.removeEventListener("abort", onAbort);
 				if (graceTimer) clearTimeout(graceTimer);
+				this.inFlightCells--;
 			}
 		} finally {
 			release();
@@ -349,10 +355,20 @@ export class EngineManager {
 		const config = this.options.snapshot;
 		if (!config) return;
 		this.clearSnapshotTimer();
-		this.snapshotTimer = setTimeout(() => {
+		const quiet = config.debounceMs ?? DEFAULT_SNAPSHOT_DEBOUNCE_MS;
+		const fire = () => {
 			this.snapshotTimer = undefined;
+			if (this.inFlightCells > 0) {
+				// --- a pickling cell would wait ahead of the user's next request on the
+				// --- kernel's single queue; the snapshot only lands in a real quiet gap,
+				// --- so re-arm the full quiet window and let activity settle instead ---
+				this.snapshotTimer = setTimeout(fire, quiet);
+				this.snapshotTimer.unref?.();
+				return;
+			}
 			void this.snapshotState();
-		}, config.debounceMs ?? DEFAULT_SNAPSHOT_DEBOUNCE_MS);
+		};
+		this.snapshotTimer = setTimeout(fire, quiet);
 		this.snapshotTimer.unref?.();
 	}
 

package/src/engine/kernel.ts

@@ -3,8 +3,9 @@
 import { type ChildProcess, spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
-import { homedir, tmpdir } from "node:os";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { resolveHelperDirs } from "./helpers-locate.js";
 import {
 	type ConnectionFile,
 	executeRequest,
@@ -62,18 +63,22 @@ function resolveCwd(requested?: string): string {
 	if (requested && existsSync(requested)) return requested;
 	return process.cwd();
 }
-function readHelperSources(dir?: string): { name: string; source: string }[] {
-	// --- one fixed dir, resolved like the prompt side (helpers.ts) so both always agree ---
-	const d = dir ?? join(homedir(), ".pi", "agent", "pi-repl", "helpers");
-	if (!existsSync(d)) return [];
+function readHelperSources(dirs: string[]): { name: string; source: string }[] {
+	// --- merged dirs come pre-ordered (project first, global last); first-seen name wins ---
+	const seen = new Set<string>();
 	const out: { name: string; source: string }[] = [];
-	for (const file of readdirSync(d).sort()) {
-		if (!file.endsWith(".py")) continue;
-		const name = file.slice(0, -3);
-		if (!/^[A-Za-z_]\w*$/.test(name) || name.startsWith("_")) continue;
-		try {
-			out.push({ name, source: readFileSync(join(d, file), "utf8") });
-		} catch {}
+	for (const d of dirs) {
+		if (!existsSync(d)) continue;
+		for (const file of readdirSync(d).sort()) {
+			if (!file.endsWith(".py")) continue;
+			const name = file.slice(0, -3);
+			if (!/^[A-Za-z_]\w*$/.test(name) || name.startsWith("_")) continue;
+			if (seen.has(name)) continue;
+			seen.add(name);
+			try {
+				out.push({ name, source: readFileSync(join(d, file), "utf8") });
+			} catch {}
+		}
 	}
 	return out;
 }
@@ -184,7 +189,9 @@ export class KernelClient {
 
 	private constructor(conn: ConnectionFile, opts: KernelOptions) {
 		this.session = new JupyterSession({ key: conn.key });
-		this.helperSources = readHelperSources(opts.env?.PI_HELPERS_DIR);
+		this.helperSources = opts.env?.PI_HELPERS_DIR
+			? readHelperSources([opts.env.PI_HELPERS_DIR])
+			: readHelperSources(resolveHelperDirs(opts.cwd, opts.env?.PI_HELPERS_GLOBAL_DIR));
 		this.timeoutMs = opts.timeoutMs ?? 0;
 	}
 

package/src/extension/helpers.ts

@@ -1,8 +1,9 @@
-/** Loads helpers from the ONE fixed dir; `helper_description` surfaces verbatim (no signature parsing). */
+/** Loads helpers from project then global dirs; `helper_description` surfaces verbatim (no signature parsing). */
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { resolveHelperDirs } from "../engine/helpers-locate.js";
 
 const DEFAULT_HELPERS_DIR = join(homedir(), ".pi", "agent", "pi-repl", "helpers");
 
@@ -11,35 +12,47 @@ interface HelperEntry {
 	description: string; // full helper_description body, "" if absent
 }
 
-/** Extract `helper_description = """..."""` (or `'''`) verbatim; no signature parsing. */
+/** Extract `helper_description` verbatim; no signature parsing. */
 function parseDescription(source: string): string {
 	const m = source.match(/helper_description\s*=\s*("""|''')([\s\S]*?)\1/);
 	return m ? m[2].trim() : "";
 }
 
-/** Load {name → entry} for each non-underscore *.py in the helpers dir. */
-function loadHelperEntries(dir?: string): HelperEntry[] {
-	const d = dir ?? DEFAULT_HELPERS_DIR;
-	if (!existsSync(d)) return [];
+/** Merge entries from ordered dirs; first-seen name wins, so a project helper shadows the global one. */
+function loadHelperEntries(dirs: string[]): HelperEntry[] {
+	const seen = new Set<string>();
 	const entries: HelperEntry[] = [];
-	for (const file of readdirSync(d).sort()) {
-		if (!file.endsWith(".py")) continue;
-		const name = file.slice(0, -3);
-		if (!/^[A-Za-z_]\w*$/.test(name)) continue;
-		// --- underscore-prefixed files are neither loaded nor advertised ---
-		if (name.startsWith("_")) continue;
-		try {
-			const source = readFileSync(join(d, file), "utf8");
-			entries.push({ name, description: parseDescription(source) });
-		} catch {}
+	for (const d of dirs) {
+		if (!existsSync(d)) continue;
+		for (const file of readdirSync(d).sort()) {
+			if (!file.endsWith(".py")) continue;
+			const name = file.slice(0, -3);
+			if (!/^[A-Za-z_]\w*$/.test(name)) continue;
+			// --- underscore-prefixed files are neither loaded nor advertised ---
+			if (name.startsWith("_")) continue;
+			if (seen.has(name)) continue;
+			seen.add(name);
+			try {
+				const source = readFileSync(join(d, file), "utf8");
+				entries.push({ name, description: parseDescription(source) });
+			} catch {}
+		}
 	}
 	return entries;
 }
 
-/** The prompt-facing list, one bullet per loaded file (verbatim description, or an introspection pointer). */
+/** The prompt-facing list for ONE dir: verbatim description, or an introspection pointer. */
 export function buildHelpersMap(dir?: string): string[] {
-	// pi renders each prompt guideline as "- <line>"; these lines are bare, no bullet prefix.
-	return loadHelperEntries(dir).map((t) =>
+	return loadHelperEntries([dir ?? DEFAULT_HELPERS_DIR]).map((t) =>
+		t.description
+			? t.description.replace(/\n/g, "\n  ")
+			: `${t.name} (no description, inspect it with print(${t.name}.__doc__))`,
+	);
+}
+
+/** The prompt-facing list at a cwd: project .pi/helpers first (up to the git root), global fallback, project shadows. */
+export function buildHelpersMapForCwd(cwd: string, globalDir?: string): string[] {
+	return loadHelperEntries(resolveHelperDirs(cwd, globalDir)).map((t) =>
 		t.description
 			? t.description.replace(/\n/g, "\n  ")
 			: `${t.name} (no description, inspect it with print(${t.name}.__doc__))`,

package/src/extension/preview/candidates.ts

@@ -1,126 +1,87 @@
-// --- candidates: the five detectors that name a cell's intent, plus generic scoring ---
+// --- candidates: a Python-flavored file detector plus generic line scoring ---
 
 import { descriptor } from "./descriptor.js";
-import { maskSpan, scanTemplate, substituteVars } from "./scan.js";
-import { previewShellCommand, previewShellCommandScored, SHELL_SETUP_WORDS, shellWords } from "./shell.js";
-import { BACKTICK, type Candidate } from "./types.js";
+import type { Candidate } from "./types.js";
 
-const SHELL_OPEN_PATTERN = new RegExp(`Bun\\s*\\.\\s*\\$\\s*(?:\\([^)]*\\)\\s*)?${BACKTICK}`, "g");
+// --- Python file effects: verb + literal path, in the idioms this evaluator runs ---
 
-export function shellCandidates(
-	source: string,
-	vars: ReadonlyMap<string, string>,
-): { candidates: Candidate[]; masked: string } {
-	const candidates: Candidate[] = [];
-	let masked = source;
-	SHELL_OPEN_PATTERN.lastIndex = 0;
-	let match = SHELL_OPEN_PATTERN.exec(masked);
-	while (match) {
-		const span = scanTemplate(masked, match.index + match[0].length - 1);
-		const command = previewShellCommandScored(substituteVars(span.body, vars));
-		// --- the command's own strength breaks ties; setup-only drops lower ---
-		if (command.text) {
-			const setupOnly = SHELL_SETUP_WORDS.has(shellWords(command.text)[0] ?? "");
-			const score = setupOnly ? 72 : 90 + Math.min(command.strength, 200) / 25;
-			candidates.push({ kind: "shell", text: command.text, score });
-		}
-		masked = maskSpan(masked, span);
-		SHELL_OPEN_PATTERN.lastIndex = span.end;
-		match = SHELL_OPEN_PATTERN.exec(masked);
-	}
-	return { candidates, masked };
-}
-
-const FILE_EFFECT_PATTERN =
-	/(?:Bun\.write|\b(?:fs|fsp|promises)\.(?:writeFileSync|writeFile|appendFileSync|appendFile|mkdirSync|mkdir|rmSync|rmdirSync|unlinkSync|unlink|renameSync|rename|copyFileSync|copyFile|cpSync|cp)|\b(?:writeFileSync|writeFile|appendFileSync|mkdirSync|rmSync|unlinkSync|renameSync|copyFileSync))\s*\(\s*([^,)\n]+)/g;
-
-const FILE_EFFECT_VERBS: ReadonlyArray<[string, string]> = [
-	["Bun.write", "write"],
-	["writeFileSync", "write"],
-	["writeFile", "write"],
-	["appendFileSync", "append"],
-	["appendFile", "append"],
-	["mkdirSync", "mkdir"],
-	["mkdir", "mkdir"],
-	["rmdirSync", "delete"],
-	["rmSync", "delete"],
-	["rm", "delete"],
-	["unlinkSync", "delete"],
-	["unlink", "delete"],
-	["renameSync", "rename"],
-	["rename", "rename"],
-	["copyFileSync", "copy"],
-	["copyFile", "copy"],
-	["cpSync", "copy"],
-	["cp", "copy"],
+const PY_CHAINED_METHOD: ReadonlyArray<[string, string, number]> = [
+	["write_text", "write", 95],
+	["write_bytes", "write", 95],
+	["append_text", "append", 90],
+	["read_text", "read", 70],
+	["read_bytes", "read", 70],
+	["mkdir", "mkdir", 80],
+	["rmdir", "delete", 85],
+	["unlink", "delete", 85],
+	["touch", "touch", 80],
+	["write", "write", 95],
+	["read", "read", 70],
 ];
 
-// --- resolve a quoted literal, a known const, or an interpolated template into a plain string ---
-function resolveArgText(arg: string, vars: ReadonlyMap<string, string>): string | undefined {
-	const trimmed = arg.trim();
-	const literalPattern = new RegExp(`^["'${BACKTICK}]([^"'${BACKTICK}]*)["'${BACKTICK}]$`);
-	const literal = trimmed.match(literalPattern);
-	if (literal?.[1]) return literal[1];
-	if (/^[A-Za-z_$][\w$]*$/.test(trimmed)) return vars.get(trimmed);
-	if (trimmed.startsWith(BACKTICK)) return substituteVars(trimmed.slice(1, -1), vars);
-	return undefined;
-}
+const PY_METHOD_VERB: Record<string, [string, number]> = Object.fromEntries(
+	PY_CHAINED_METHOD.map(([method, verb, score]) => [method, [verb, score]]),
+);
 
-const FILE_READ_PATTERN = /Bun\.file\s*\(\s*([^,)\n]+?)\s*\)\s*\.\s*(?:text|json|arrayBuffer|bytes|stream)\s*\(/g;
+/** `Path("p").method(...)` / `open("p"[, "mode"]).method(...)` — mode overrides the method verb. */
+const PY_CHAINED_PATTERN = new RegExp(
+	"(?:Path|open)\\s*\\(\\s*([rf]?[\"'])([^\"']+)\\1\\s*(?:,\\s*[\"']([rawx])[\"'])?\\s*\\)\\s*\\.\\s*(" +
+		PY_CHAINED_METHOD.map(([method]) => method).join("|") +
+		")\\s*\\(",
+	"g",
+);
 
-export function fileCandidates(source: string, vars: ReadonlyMap<string, string>): Candidate[] {
-	const candidates: Candidate[] = [];
-	for (const match of source.matchAll(FILE_EFFECT_PATTERN)) {
-		const call = match[0];
-		const verb = FILE_EFFECT_VERBS.find(([name]) => call.includes(name))?.[1];
-		if (!verb) continue;
-		const path = resolveArgText(match[1] ?? "", vars);
-		if (path) candidates.push({ kind: "ts", text: descriptor(`${verb} ${path}`), score: 95 });
-	}
-	for (const match of source.matchAll(FILE_READ_PATTERN)) {
-		const path = resolveArgText(match[1] ?? "", vars);
-		if (path) candidates.push({ kind: "ts", text: descriptor(`read ${path}`), score: 70 });
-	}
-	for (const match of source.matchAll(/\bfetch\s*\(\s*([^,)\n]+)/g)) {
-		const url = resolveArgText(match[1] ?? "", vars);
-		if (url) candidates.push({ kind: "ts", text: descriptor(`fetch ${url}`), score: 75 });
-	}
-	return candidates;
-}
+/** A bare `open("p", "mode")`, including `with open(...)` blocks. */
+const PY_OPEN_PATTERN = /open\s*\(\s*([rf]?["'])([^"']+)\1\s*,\s*["']([rawx])["']\s*\)/g;
 
-// --- per-tool: which arg names the target, the verb shown, and its scoring band ---
-const BRIDGED_TOOLS: Record<string, { arg: string; verb: string; score: number }> = {
-	read: { arg: "path", verb: "read", score: 70 },
-	bash: { arg: "command", verb: "", score: 88 },
-	edit: { arg: "path", verb: "edit", score: 95 },
-	write: { arg: "path", verb: "write", score: 95 },
-	grep: { arg: "pattern", verb: "grep", score: 68 },
-	find: { arg: "pattern", verb: "find", score: 68 },
-	ls: { arg: "path", verb: "ls", score: 68 },
+/** Function-form effects from the stdlib modules this repl's cells actually use. */
+const PY_FN_PATTERN =
+	/((?:shutil|os)\.(?:copy|copytree|move|rmtree|remove|unlink|rmdir|mkdir|makedirs|rename|replace))\s*\(\s*([rf]?["'])([^"']+)\2(?:\s*,\s*([rf]?["'])([^"']+)\4)?/g;
+
+const PY_FN_VERB: Record<string, [string, number]> = {
+	"shutil.copy": ["copy", 85],
+	"shutil.copytree": ["copy", 85],
+	"shutil.move": ["move", 85],
+	"shutil.rmtree": ["delete", 90],
+	"os.remove": ["delete", 85],
+	"os.unlink": ["delete", 85],
+	"os.rmdir": ["delete", 85],
+	"os.mkdir": ["mkdir", 80],
+	"os.makedirs": ["mkdir", 80],
+	"os.rename": ["rename", 85],
+	"os.replace": ["rename", 85],
 };
 
-export function bridgedToolCandidates(source: string, vars: ReadonlyMap<string, string>): Candidate[] {
+export function pythonFileCandidates(source: string): Candidate[] {
 	const candidates: Candidate[] = [];
-	for (const match of source.matchAll(/\btools\.(\w+)\s*\(\s*\{([^}]*)\}/g)) {
-		const spec = BRIDGED_TOOLS[match[1] ?? ""];
+	for (const match of source.matchAll(PY_CHAINED_PATTERN)) {
+		const spec = PY_METHOD_VERB[match[4] ?? ""];
+		if (!spec) continue;
+		const mode = match[3];
+		const verb = mode === "a" ? "append" : mode === "w" || mode === "x" ? "write" : mode === "r" ? "read" : spec[0];
+		candidates.push({ text: descriptor(`${verb} ${match[2]}`), score: mode === undefined ? spec[1] : 95 });
+	}
+	for (const match of source.matchAll(PY_OPEN_PATTERN)) {
+		const verb = match[3] === "a" ? "append" : match[3] === "r" ? "read" : "write";
+		candidates.push({ text: descriptor(`${verb} ${match[2]}`), score: 95 });
+	}
+	for (const match of source.matchAll(PY_FN_PATTERN)) {
+		const spec = PY_FN_VERB[match[1] ?? ""];
 		if (!spec) continue;
-		const props = match[2] ?? "";
-		const argMatch = props.match(new RegExp(`${spec.arg}\\s*:\\s*([^,}]+)`));
-		const target = argMatch ? resolveArgText(argMatch[1] ?? "", vars) : undefined;
-		if (!target) continue;
-		// --- a bridged bash call is a command like any other ---
-		const text = spec.verb ? `${spec.verb} ${target}` : previewShellCommand(target) || target;
-		candidates.push({ kind: "ts", text: descriptor(text), score: spec.score });
+		const target = match[5];
+		const text = target ? `${spec[0]} ${match[3]} → ${target}` : `${spec[0]} ${match[3]}`;
+		candidates.push({ text: descriptor(text), score: spec[1] });
 	}
 	return candidates;
 }
 
-const SKIP_LINE_PATTERN = /^(?:$|\/\/|\/\*|\*|import\s|export\s+(?:type\s|\{)|[})\];,]+$)/;
-const DEFINITION_PATTERN = /^(?:export\s+)?(?:async\s+)?(?:function\s|class\s|interface\s|type\s+\w+\s*=)/;
+const SKIP_LINE_PATTERN = /^(?:$|#|\/\/|\/\*|\*|import\s|from\s+\S+\s+import|export\s+(?:type\s|\{)|[})\];,]+$)/;
+const DEFINITION_PATTERN = /^(?:export\s+)?(?:async\s+)?(?:function\s|def\s|class\s|interface\s|type\s+\w+\s*=)/;
 const ARROW_DEFINITION_PATTERN = /^(?:const|let)\s+[A-Za-z_$][\w$]*\s*=\s*(?:async\s*)?\(?[^)=]*\)?\s*=>/;
 const CONTROL_PATTERN = /^(?:if|for|while|switch|try|do)\b/;
 const CALL_STATEMENT_PATTERN = /^(?:await\s+)?[A-Za-z_$][\w$.]*\s*\(/;
-const ASSIGNMENT_CALL_PATTERN = /^(?:const|let|var)\s+[^=]{1,60}=\s*(?:await\s+)?(?:new\s+)?[A-Za-z_$][\w$.]*\s*\(/;
+const ASSIGNMENT_CALL_PATTERN = /^(?:const|let|var|def)\s+[^=]{1,60}=\s*(?:await\s+)?(?:new\s+)?[A-Za-z_$][\w$.]*\s*\(/;
+const PY_ASSIGNMENT_CALL_PATTERN = /^[A-Za-z_][\w]*\s*=\s*(?:await\s+)?[A-Za-z_$][\w$.]*\s*\(/;
 const LOW_SIGNAL_CALL_PATTERN =
 	/^(?:await\s+)?(?:console\.\w+|String|Number|Boolean|JSON\.stringify|JSON\.parse|structuredClone)\s*\(/;
 const LOW_SIGNAL_ASSIGNMENT_PATTERN =
@@ -139,21 +100,21 @@ function genericLineScore(line: string): number {
 	if (DEFINITION_PATTERN.test(line) || ARROW_DEFINITION_PATTERN.test(line)) return 50;
 	if (CONTROL_PATTERN.test(line)) return 20;
 	if (/^(?:return|throw)\b/.test(line)) return 45;
-	if (ASSIGNMENT_CALL_PATTERN.test(line)) return 60;
+	if (ASSIGNMENT_CALL_PATTERN.test(line) || PY_ASSIGNMENT_CALL_PATTERN.test(line)) return 60;
 	if (CALL_STATEMENT_PATTERN.test(line)) return 65;
 	if (/^(?:const|let|var)\s/.test(line)) return 22;
 	return 30;
 }
 
-export function genericCandidates(masked: string): Candidate[] {
+export function genericCandidates(source: string): Candidate[] {
 	const candidates: Candidate[] = [];
-	for (const [index, rawLine] of masked.split("\n").entries()) {
+	for (const [index, rawLine] of source.split("\n").entries()) {
 		const line = rawLine.trim();
 		const score = genericLineScore(line);
 		if (score < 0) continue;
 		const text = consoleInnerCall(line) ?? line;
 		// --- later lines win ties: cells read as setup-then-act, and the act is the story ---
-		candidates.push({ kind: "ts", text: descriptor(text), score: score + Math.min(index, 90) / 100 });
+		candidates.push({ text: descriptor(text), score: score + Math.min(index, 90) / 100 });
 	}
 	return candidates;
 }

package/src/extension/preview/index.ts

@@ -1,31 +1,21 @@
 // --- preview entry: score the whole cell for its one truthful line ---
 
-import { bridgedToolCandidates, fileCandidates, genericCandidates, shellCandidates } from "./candidates.js";
+import { genericCandidates, pythonFileCandidates } from "./candidates.js";
 import { descriptor } from "./descriptor.js";
-import { stringConsts } from "./scan.js";
-import { previewShellCommand } from "./shell.js";
 import type { CellPreview } from "./types.js";
 
 export type { CellPreview };
-export { descriptor, previewShellCommand };
+export { descriptor };
 
 export function previewCell(code: string): CellPreview {
 	const source = code.trimEnd();
-	if (!source) return { kind: "ts", text: "" };
-	const vars = stringConsts(source);
+	if (!source) return { text: "" };
+	// --- file effects carry the most signal; generic line shape fills the rest ---
+	const candidates = [...pythonFileCandidates(source), ...genericCandidates(source)];
 
-	// --- scan order: shell masks shell-looking syntax, then file/tool/generic ---
-	const shell = shellCandidates(source, vars);
-	const candidates = [
-		...shell.candidates,
-		...fileCandidates(shell.masked, vars),
-		...bridgedToolCandidates(shell.masked, vars),
-		...genericCandidates(shell.masked),
-	];
-
-	let best: { kind: CellPreview["kind"]; text: string; score: number } | undefined;
+	let best: { text: string; score: number } | undefined;
 	for (const candidate of candidates) {
 		if (candidate.text && (!best || candidate.score > best.score)) best = candidate;
 	}
-	return best ?? { kind: "ts", text: "" };
+	return best ?? { text: "" };
 }

package/src/extension/preview/types.ts

@@ -1,23 +1,10 @@
-// --- shared preview types; tiny module so every consumer imports only the shape it needs ---
-type CellPreviewKind = "shell" | "ts";
-
-export interface CellPreview {
-	kind: CellPreviewKind;
-	text: string;
-}
-
-// --- a [start, end) slice of the source with its captured body ---
-export interface Span {
-	start: number;
-	end: number;
-	body: string;
-}
-
-// --- the winner of each detector, ranked by score in the orchestration ---
+/** A scored preview candidate for one cell in the transcript header. */
 export interface Candidate {
-	kind: CellPreviewKind;
 	text: string;
 	score: number;
 }
 
-export const BACKTICK = "\u0060";
+/** The one-line semantic summary a collapsed cell shows. */
+export interface CellPreview {
+	text: string;
+}

package/src/extension/prompt.ts

@@ -12,12 +12,19 @@ export const executePromptSnippet = "Execute Python in a persistent shell (read,
 // --- the model-facing guidelines, flat bullets like pi's own tool contributions ---
 export function buildPromptGuidelines(preloaded: string[]): string[] {
 	return [
-		"State persists across cells, so define a function once and keep building on it.",
-		"Find, filter, fetch, read: narrow the output in Python, then print the exact slice you need.",
-		"Keep the result in a variable and reuse it, instead of re-fetching the same thing.",
+		"Find, filter, fetch, sample: narrow the output in Python, then print only the exact slice you need.",
 		"Make surgical, precise changes over rewrites or whole-file dumps: a small unique anchor, replace, verify, read the file back before trusting it.",
-		"The evaluator runs in a project-local venv. Do not install a project's dependencies into it; run external projects through their own interface. If output begins with <repl_engine_reset>, the kernel rebuilt; re-verify a revived variable.",
-		...(preloaded.length ? ["Preloaded helpers, use them as any loaded function or variable:", ...preloaded] : []),
+		"Reference what the persistent shell already holds, don't redefine it.",
+		"Write modern idiomatic Python.",
+		"If output begins with <repl_engine_reset>, the kernel rebuilt; re-verify a revived variable.",
+		...(preloaded.length
+			? [
+					[
+						"Preloaded helpers, use them as any loaded function or variable:",
+						...preloaded.map((line) => `  - ${line.replace(/\n/g, "\n    ")}`),
+					].join("\n"),
+				]
+			: []),
 		"Be concise.",
 	];
 }

package/src/extension/render-core.ts

@@ -19,6 +19,8 @@ export interface ExecuteRenderState {
 	expanded: boolean;
 	executionStarted: boolean;
 	hasResult: boolean;
+	/** Monotonic dirty counter, bumped by the host on every content/status change. */
+	version?: number;
 }
 
 import { previewCell } from "./preview/index.js";
@@ -185,8 +187,7 @@ function outputText(state: ExecuteRenderState): string {
 function topLine(state: ExecuteRenderState, width: number, deps: RenderDeps): string {
 	const code = state.code.trimEnd();
 	const preview = previewCell(code);
-	const language = preview.kind === "shell" ? "repl · shell" : "repl";
-	const prefix = `${marker(state, deps)} ${deps.fg("muted", language)}`;
+	const prefix = `${marker(state, deps)} ${deps.fg("muted", "repl")}`;
 
 	// --- suffix priority: expand hint > error > duration > counts, so truncation never hides the expand key ---
 	const suffixParts: string[] = [];
@@ -222,10 +223,7 @@ function topLine(state: ExecuteRenderState, width: number, deps: RenderDeps): st
 	// --- a semantic preview is a one-line summary; highlight Python code, accent shell intent ---
 	let middle = "";
 	if (preview.text) {
-		const previewText =
-			preview.kind === "ts"
-				? (deps.highlight(preview.text)[0] ?? deps.fg("accent", preview.text))
-				: deps.fg("accent", preview.text);
+		const previewText = deps.highlight(preview.text)[0] ?? deps.fg("accent", preview.text);
 		middle = deps.truncateToWidth(previewText, previewBudget, "…");
 	} else if (!state.executionStarted) {
 		middle = deps.fg("muted", "waiting for code");
@@ -244,20 +242,24 @@ function sanitizeTuiOutput(text: string): string {
 		.replace(/[\x00-\x08\x0b-\x0c\x0e-\x1f\x7f-\x9f]/g, "�");
 }
 
-type PreviewEntry = { kind: "line"; line: string } | { kind: "hidden"; hidden: number };
-
-/** Head/tail truncation with a hidden-line marker, adapted from pi-fabric. */
-function selectPreviewLines(lines: string[], limit: number): PreviewEntry[] {
-	const lineEntry = (line: string): PreviewEntry => ({ kind: "line", line });
-	if (lines.length <= limit || limit <= 0) return lines.map(lineEntry);
-	if (limit < 8) return [...lines.slice(0, limit).map(lineEntry), { kind: "hidden", hidden: lines.length - limit }];
-	const head = Math.ceil(limit * 0.65);
-	const tail = Math.max(1, limit - head - 1);
-	return [
-		...lines.slice(0, head).map(lineEntry),
-		{ kind: "hidden", hidden: lines.length - head - tail },
-		...lines.slice(-tail).map(lineEntry),
-	];
+/** Wrap a ready-colored span into `lines`: first row takes the prefix, wrapped
+ * continuations take indent (and an optional extra indent), each row is
+ * truncated to pane width and closed if it ends on an open SGR color. */
+function pushWrappedLines(
+	lines: string[],
+	prefix: string,
+	coloredText: string,
+	width: number,
+	deps: RenderDeps,
+	indentAfter?: number,
+): void {
+	const available = Math.max(1, width - 1 - deps.visibleWidth(prefix));
+	const wrapped = deps.wrapTextWithAnsi(coloredText, available);
+	for (const [index, line] of (wrapped.length > 0 ? wrapped : [""]).entries()) {
+		const linePrefix = index === 0 ? prefix : " ".repeat(deps.visibleWidth(prefix));
+		const continuationIndent = index > 0 && indentAfter ? " ".repeat(indentAfter) : "";
+		lines.push(deps.truncateToWidth(` ${linePrefix}${continuationIndent}${closeOpenSgr(line)}`, width, ""));
+	}
 }
 
 function addWrapped(
@@ -269,13 +271,7 @@ function addWrapped(
 	options: { sanitize?: boolean; indentAfter?: number } = {},
 ): void {
 	const safe = options.sanitize === false ? text : sanitizeTuiOutput(text);
-	const available = Math.max(1, width - 1 - deps.visibleWidth(prefix));
-	const wrapped = deps.wrapTextWithAnsi(safe, available);
-	for (const [index, line] of (wrapped.length > 0 ? wrapped : [""]).entries()) {
-		const linePrefix = index === 0 ? prefix : " ".repeat(deps.visibleWidth(prefix));
-		const continuationIndent = index > 0 && options.indentAfter ? " ".repeat(options.indentAfter) : "";
-		lines.push(deps.truncateToWidth(` ${linePrefix}${continuationIndent}${closeOpenSgr(line)}`, width, ""));
-	}
+	pushWrappedLines(lines, prefix, safe, width, deps, options.indentAfter);
 }
 
 function renderCode(state: ExecuteRenderState, lines: string[], width: number, deps: RenderDeps): boolean {
@@ -296,7 +292,162 @@ function renderCode(state: ExecuteRenderState, lines: string[], width: number, d
 	return true;
 }
 
-const MAX_OUTPUT_LINES = 50;
+/**
+ * Streaming output is append-only, so a wrapped blob only changes at its tail.
+ * The cache lives on the (persistent) state object via a WeakMap, letting an
+ * updated body re-wrap just the appended delta: O(chunk) instead of O(output).
+ * Fresh states (unit tests, first render) fall back to a full wrap.
+ */
+interface BlobWrapEntry {
+	text: string;
+	color: string;
+	lines: string[];
+	/** Last raw line when `text` has no trailing newline; it may still grow. */
+	partial?: { raw: string; wrapped: string[] };
+}
+
+const blobWrapCache = new WeakMap<ExecuteRenderState, Map<number, BlobWrapEntry>>();
+
+const CJK_WIDE_RE =
+	/[\p{Script_Extensions=Han}\p{Script_Extensions=Hiragana}\p{Script_Extensions=Katakana}\p{Script_Extensions=Hangul}\p{Script_Extensions=Bopomofo}]/u;
+
+function widthOf(ch: string): number {
+	const code = ch.charCodeAt(0);
+	return code < 0x80 ? 1 : CJK_WIDE_RE.test(ch) ? 2 : 1;
+}
+
+/** Fast single-pass word wrap for ANSI-free text: pi-tui's ANSI-aware wrap is
+ * ~45ms on a 45K blob; sanitized output needs no ANSI handling, so this splits
+ * at spaces with an O(width) scan per row and hard-breaks overlong words. */
+function wrapPlainText(text: string, width: number): string[] {
+	if (width <= 0 || text.length <= width) return [text];
+	// --- fast path: pure ASCII, break by char index ---
+	let ascii = true;
+	for (let i = 0; i < text.length; i++) {
+		if (text.charCodeAt(i) >= 0x80) {
+			ascii = false;
+			break;
+		}
+	}
+	const rows: string[] = [];
+	if (ascii) {
+		let i = 0;
+		for (;;) {
+			const end = i + width;
+			if (end >= text.length) {
+				rows.push(text.slice(i));
+				break;
+			}
+			const brk = text.lastIndexOf(" ", end);
+			if (brk > i) {
+				rows.push(text.slice(i, brk));
+				i = brk + 1;
+			} else {
+				rows.push(text.slice(i, end));
+				i = end;
+			}
+		}
+		return rows;
+	}
+	// --- wide characters: accumulate visible width, track a last-space break ---
+	let row = "";
+	let rowVis = 0;
+	let lastSpace = -1;
+	let lastSpaceVis = 0;
+	const visRaw: number[] = [];
+	const repoint = (start: number) => {
+		visRaw.length = 0;
+		let v = 0;
+		for (let k = start; k < row.length; k++) {
+			visRaw[v] = k;
+			v += widthOf(row[k]);
+		}
+	};
+	for (let i = 0; i < text.length; i++) {
+		const ch = text[i];
+		const w = widthOf(ch);
+		visRaw[rowVis] = row.length;
+		row += ch;
+		rowVis += w;
+		if (ch === " ") {
+			lastSpace = row.length;
+			lastSpaceVis = rowVis;
+		}
+		if (rowVis > width) {
+			if (lastSpace !== -1) {
+				rows.push(row.slice(0, lastSpace - 1));
+				row = row.slice(lastSpace);
+				rowVis -= lastSpaceVis;
+				lastSpace = -1;
+				lastSpaceVis = 0;
+				repoint(0);
+			} else {
+				const cut = visRaw[width] ?? row.length;
+				rows.push(row.slice(0, cut));
+				row = row.slice(cut);
+				rowVis -= width;
+				repoint(0);
+			}
+		}
+	}
+	if (row) rows.push(row);
+	return rows;
+}
+
+/** Wrap a raw output line exactly the way the section loops did: sanitize, wrap (fast),
+ * then colorize row-by-row so the color span never bleeds across rows. */
+function wrapRawOutputLine(lines: string[], raw: string, color: string, width: number, deps: RenderDeps): string[] {
+	const before = lines.length;
+	const safe = sanitizeTuiOutput(raw || " ");
+	const available = Math.max(1, width - 1 - deps.visibleWidth(OUTPUT_INDENT));
+	const rows = wrapPlainText(safe, available);
+	for (const [index, row] of (rows.length > 0 ? rows : [""]).entries()) {
+		const linePrefix = index === 0 ? OUTPUT_INDENT : " ".repeat(deps.visibleWidth(OUTPUT_INDENT));
+		lines.push(deps.truncateToWidth(` ${linePrefix}${closeOpenSgr(deps.fg(color, row))}`, width, ""));
+	}
+	return lines.slice(before);
+}
+
+function wrapBlob(state: ExecuteRenderState, width: number, text: string, color: string, deps: RenderDeps): string[] {
+	let perWidth = blobWrapCache.get(state);
+	if (!perWidth) {
+		perWidth = new Map();
+		blobWrapCache.set(state, perWidth);
+	}
+	const fresh = (): BlobWrapEntry => {
+		const lines: string[] = [];
+		let partial: { raw: string; wrapped: string[] } | undefined;
+		const parts = text.split("\n");
+		for (let i = 0; i < parts.length; i++) {
+			const wrapped = wrapRawOutputLine(lines, parts[i], color, width, deps);
+			if (i === parts.length - 1 && !text.endsWith("\n")) {
+				partial = { raw: parts[i], wrapped };
+			}
+		}
+		const entry: BlobWrapEntry = { text, color, lines, partial };
+		perWidth.set(width, entry);
+		return entry;
+	};
+	const entry = perWidth.get(width);
+	if (!entry || entry.color !== color) return fresh().lines;
+	if (entry.text === text) return entry.lines;
+	if (text.startsWith(entry.text)) {
+		// --- append: cached prefix rows stay; re-wrap only the growing tail ---
+		const delta = text.slice(entry.text.length);
+		const combined = entry.partial ? entry.partial.raw + delta : delta;
+		if (entry.partial) entry.lines.length -= entry.partial.wrapped.length;
+		const parts = combined.split("\n");
+		for (let i = 0; i < parts.length; i++) {
+			const wrapped = wrapRawOutputLine(entry.lines, parts[i], color, width, deps);
+			if (i === parts.length - 1) {
+				entry.partial = combined.endsWith("\n") ? undefined : { raw: parts[i], wrapped };
+			}
+		}
+		entry.text = text;
+		return entry.lines;
+	}
+	return fresh().lines;
+}
 
 function renderOutput(
 	state: ExecuteRenderState,
@@ -319,19 +470,13 @@ function renderOutput(
 		if (!text?.trim()) continue;
 		renderedText = true;
 		output.push(` ${OUTPUT_INDENT}${deps.fg("dim", `${label}:`)}`);
-		for (const line of text.split("\n")) {
-			const safe = sanitizeTuiOutput(line || " ");
-			addWrapped(output, OUTPUT_INDENT, deps.fg(color, safe), width, deps, { sanitize: false });
-		}
+		output.push(...wrapBlob(state, width, text, color, deps));
 	}
 
 	if (!renderedText && !details && state.contentText?.trim()) {
 		renderedText = true;
 		const color = state.isError ? "error" : "toolOutput";
-		for (const line of state.contentText.trim().split("\n")) {
-			const safe = sanitizeTuiOutput(line || " ");
-			addWrapped(output, OUTPUT_INDENT, deps.fg(color, safe), width, deps, { sanitize: false });
-		}
+		output.push(...wrapBlob(state, width, state.contentText.trim(), color, deps));
 	}
 
 	if (details?.errorStack && details.errorStack.length > 0) {
@@ -347,16 +492,9 @@ function renderOutput(
 		addWrapped(output, OUTPUT_INDENT, deps.fg("muted", message), width, deps, { sanitize: false });
 	}
 
-	const entries = selectPreviewLines(output, MAX_OUTPUT_LINES);
-	if (entries.length > 0 && hasCode) lines.push("");
-	for (const entry of entries) {
-		if (entry.kind === "hidden") {
-			const marker = ` … ${entry.hidden} line${entry.hidden === 1 ? "" : "s"} hidden … `;
-			lines.push(` ${OUTPUT_INDENT}${deps.fg("muted", marker)}`);
-		} else {
-			lines.push(entry.line);
-		}
-	}
+	// --- expanded cells render the whole output: the data cap bounds it ---
+	if (output.length > 0 && hasCode) lines.push("");
+	lines.push(...output);
 }
 
 /** Paint the status-matched panel background across the row, surviving inner SGR resets. */

package/src/extension/render.ts

@@ -30,21 +30,13 @@ function makeDeps(theme: Theme): RenderDeps {
 	};
 }
 
-/** The layout only changes on state/spinner change, but the TUI repaints every frame; key by both to avoid recompute flicker. */
-function renderVersion(state: ExecuteRenderState): string {
-	const details = state.details ? JSON.stringify(state.details) : "";
-	return [
-		state.code.length,
-		state.contentText?.length ?? 0,
-		details.length,
-		state.isPartial,
-		state.isError,
-		state.expanded,
-		state.executionStarted,
-		state.hasResult,
-		// --- fold the animation frame in while running so the spinner still turns ---
-		statusKind(state) === "running" ? Math.floor(Date.now() / 120) % 4 : -1,
-	].join("|");
+/** O(1) key: a host-bumped dirty counter plus mode state. `withSpinner` folds
+ * the animation frame so the header alone animates while running; the body key
+ * excludes it, so a running cell only redraws when output actually changes
+ * instead of re-wrapping the whole body every 120ms. */
+function renderVersion(state: ExecuteRenderState, withSpinner: boolean): string {
+	const spinner = withSpinner && statusKind(state) === "running" ? Math.floor(Date.now() / 120) % 4 : -1;
+	return `${state.version ?? 0}|${state.expanded}|${spinner}`;
 }
 
 export class ExecuteCellComponent {
@@ -66,7 +58,12 @@ export class ExecuteCellComponent {
 	}
 
 	render(width: number): string[] {
-		const key = `${renderVersion(this.state)}|${this.mode}`;
+		const key =
+			this.mode === "header"
+				? `${renderVersion(this.state, true)}|header`
+				: this.mode === "body"
+					? `${renderVersion(this.state, false)}|body`
+					: `${renderVersion(this.state, true)}|cell`;
 		if (this.cachedLines && this.cachedWidth === width && this.cachedKey === key) {
 			return this.cachedLines;
 		}

package/src/extension/tool-meta.ts

@@ -1,15 +1,15 @@
 // --- tool-meta: thin surface assembling the execute tool's prompt from pure modules ---
 // --- the model contract lives in prompt.ts; only the helpers wiring stays here ---
 
-import { buildHelpersMap } from "./helpers.js";
+import { buildHelpersMap, buildHelpersMapForCwd } from "./helpers.js";
 import { buildPromptGuidelines, executePromptSnippet, executeToolDescription } from "./prompt.js";
 
 export const EXECUTE_DESCRIPTION = executeToolDescription;
 export const EXECUTE_PROMPT_SNIPPET = executePromptSnippet;
 
-// --- build the guidelines from the one helpers dir (default ~/.pi/agent/pi-repl/helpers) ---
-export function buildExecutePromptGuidelines(): string[] {
-	const map = buildHelpersMap();
+// --- build the guidelines from project + global helper dirs ---
+export function buildExecutePromptGuidelines(cwd?: string): string[] {
+	const map = cwd ? buildHelpersMapForCwd(cwd) : buildHelpersMap();
 	const preloaded = map.length > 0 ? map : [];
 	return buildPromptGuidelines(preloaded);
 }

package/src/extension/preview/scan.ts

@@ -1,59 +0,0 @@
-// --- scan: tokenizer source → template spans, string constants, and masks ---
-import { BACKTICK, type Span } from "./types.js";
-
-// --- capture the template opened at start; tracks escapes + interpolation nesting so a shell command reads whole, and an unclosed template returns the rest (partial is better than none) ---
-export function scanTemplate(source: string, start: number): Span {
-	let depth = 0;
-	let inNested = false;
-	for (let i = start + 1; i < source.length; i++) {
-		const ch = source[i];
-		if (ch === "\\") {
-			i += 1;
-			continue;
-		}
-		if (ch === BACKTICK) {
-			if (depth === 0 && !inNested) return { start, end: i + 1, body: source.slice(start + 1, i) };
-			inNested = !inNested;
-			continue;
-		}
-		if (!inNested && ch === "$" && source[i + 1] === "{") {
-			depth += 1;
-			i += 1;
-			continue;
-		}
-		if (!inNested && depth > 0 && ch === "}") depth -= 1;
-	}
-	return { start, end: source.length, body: source.slice(start + 1) };
-}
-
-const CONST_STRING_PATTERN = new RegExp(
-	'(?:const|let|var)\\s+([A-Za-z_$][\\w$]*)\\s*=\\s*(?:"([^"\\n]*)"|' +
-		"'([^'\\n]*)'|" +
-		BACKTICK +
-		"([^" +
-		BACKTICK +
-		"$\\n]*)" +
-		BACKTICK +
-		")",
-	"g",
-);
-
-// --- collected simple string constants, for resolving interpolations and path args ---
-export function stringConsts(source: string): Map<string, string> {
-	const vars = new Map<string, string>();
-	for (const match of source.matchAll(CONST_STRING_PATTERN)) {
-		const name = match[1];
-		const value = match[2] ?? match[3] ?? match[4];
-		if (name && value !== undefined) vars.set(name, value);
-	}
-	return vars;
-}
-
-export function substituteVars(text: string, vars: ReadonlyMap<string, string>): string {
-	return text.replace(/\$\{\s*([A-Za-z_$][\w$]*)\s*\}/g, (whole, name: string) => vars.get(name) ?? whole);
-}
-
-// --- blank a claimed span so later detectors don't re-read what an earlier one took ---
-export function maskSpan(source: string, span: Span): string {
-	return source.slice(0, span.start) + " ".repeat(span.end - span.start) + source.slice(span.end);
-}

package/src/extension/preview/shell.ts

@@ -1,156 +0,0 @@
-// --- shell: resolve the strongest single line of a (possibly chained) shell command ---
-import { descriptor } from "./descriptor.js";
-
-const CD_PREFIX_PATTERN = /^\s*cd\s+([^&;|]+?)\s*(?:&&|;)\s*/;
-const SHELL_SETUP_PATTERN = /^(?:export\s+\w+=|set\s+[-+]|source\s+\S+|\.\s+\S+)/;
-const HEREDOC_PATTERN = /<<-?\s*['"]?([A-Za-z_][A-Za-z0-9_]*)['"]?/;
-
-export function shellWords(line: string): string[] {
-	const words: string[] = [];
-	for (const match of line.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g)) {
-		words.push(match[1] ?? match[2] ?? match[3] ?? "");
-	}
-	return words;
-}
-
-function pathTail(path: string): string {
-	const cleaned = path.replace(/\/+$/, "");
-	const tail = cleaned.slice(cleaned.lastIndexOf("/") + 1);
-	return tail || cleaned;
-}
-
-function simplifyRunnerCommand(line: string): string | undefined {
-	const words = shellWords(line);
-	if (words[0] === "npm" || words[0] === "pnpm") {
-		const runIndex = words.indexOf("run");
-		if (runIndex >= 0 && words[runIndex + 1]) {
-			return `${words[0]} ${words.slice(runIndex + 1).join(" ")}`.trim();
-		}
-	}
-	if (line.includes("node_modules/.bin/")) {
-		return line.replace(/\S*node_modules\/\.bin\//g, "");
-	}
-	return undefined;
-}
-
-function simplifyMutationCommand(line: string): string | undefined {
-	const words = shellWords(line);
-	if (words.length === 0) return undefined;
-	if (words[0] === "cat" && words[1] === ">" && words[2]) return `write ${pathTail(words[2])}`;
-	if (words[0] === "tee" && words.at(-1)) {
-		return (words.includes("-a") ? "append " : "write ") + pathTail(words.at(-1) ?? "");
-	}
-	return undefined;
-}
-
-// --- collapse noisier command forms (runners, writes) down to the intent ---
-function simplifyShellLine(line: string): string {
-	return simplifyRunnerCommand(line) ?? simplifyMutationCommand(line) ?? line;
-}
-
-// --- commands that prepare the ground; the shell only wins when it is the story ---
-export const SHELL_SETUP_WORDS = new Set([
-	"mkdir",
-	"cd",
-	"export",
-	"touch",
-	"chmod",
-	"chown",
-	"ln",
-	"echo",
-	"true",
-	"sleep",
-	"which",
-	"sync",
-]);
-
-const SHELL_ACTION_WORDS = new Set([
-	"rm",
-	"mv",
-	"cp",
-	"git",
-	"npm",
-	"pnpm",
-	"bun",
-	"bunx",
-	"npx",
-	"make",
-	"cargo",
-	"docker",
-	"curl",
-	"gh",
-	"pi",
-]);
-
-function shellLineScore(line: string, index: number): number {
-	const simplified = simplifyShellLine(line);
-	const words = shellWords(line);
-	let score = 30;
-	if (simplified !== line) score += 40;
-	if (SHELL_ACTION_WORDS.has(words[0] ?? "")) score += 20;
-	if (/\b(?:rm|mv|cp|git\s+(?:add|commit|push)|sed\s+-i|perl\s+-pi|tee|cat\s*>)\b/.test(line)) score += 40;
-	return score + index;
-}
-
-function heredocBody(lines: readonly string[], startIndex: number, delimiter: string): string | undefined {
-	const body: string[] = [];
-	for (let i = startIndex + 1; i < lines.length; i++) {
-		if ((lines[i] ?? "").trim() === delimiter) return body.join("\n");
-		body.push(lines[i] ?? "");
-	}
-	return body.length > 0 ? body.join("\n") : undefined;
-}
-
-function previewHeredoc(lines: readonly string[]): string | undefined {
-	for (let i = 0; i < lines.length; i++) {
-		const line = (lines[i] ?? "").trim();
-		const delimiter = line.match(HEREDOC_PATTERN)?.[1];
-		if (!delimiter) continue;
-		const body = heredocBody(lines, i, delimiter);
-		if (!body) continue;
-		// --- the write target is the story; the body is detail for the expanded view ---
-		const catWrite = line.match(/\b(?:cat|tee)\b.*(?:>|\s)(\S+)\s*<<-?/);
-		if (catWrite?.[1]) return (line.includes("tee -a") ? "append " : "write ") + pathTail(catWrite[1]);
-		return descriptor(body);
-	}
-	return undefined;
-}
-
-export function previewShellCommand(command: string): string {
-	return previewShellCommandScored(command).text;
-}
-
-// --- like previewShellCommand but keeps the winning line's strength so several shell calls can rank ---
-export function previewShellCommandScored(command: string): { text: string; strength: number } {
-	const lines = command.split("\n");
-	const heredoc = previewHeredoc(lines);
-	if (heredoc) return { text: descriptor(heredoc), strength: 90 };
-
-	let best: { text: string; score: number } | undefined;
-	let cwdSuffix: string | undefined;
-	let index = 0;
-	for (const rawLine of lines) {
-		for (const rawPart of rawLine.split(/\s*(?:&&|;)\s*/)) {
-			let part = rawPart.trim();
-			if (!part || part.startsWith("#") || SHELL_SETUP_PATTERN.test(part)) continue;
-			const cd = part.match(CD_PREFIX_PATTERN);
-			if (cd?.[1]) {
-				cwdSuffix = pathTail(cd[1].trim());
-				part = part.replace(CD_PREFIX_PATTERN, "").trim();
-			} else if (/^cd\s+\S+$/.test(part)) {
-				cwdSuffix = pathTail(part.slice(2).trim());
-				continue;
-			}
-			if (!part) continue;
-			const candidate = { text: simplifyShellLine(part), score: shellLineScore(part, index) };
-			if (!best || candidate.score > best.score) best = candidate;
-			index += 1;
-		}
-	}
-	if (!best) return { text: "", strength: 0 };
-	// --- trailing redirections are plumbing, not intent ---
-	const cleaned = best.text.replace(/(?:\s*(?:2>&1|[12]?>\s*\/dev\/null|&>\s*\/dev\/null))+\s*$/, "");
-	// --- a stripped cd prefix still matters when it names a non-default dir ---
-	const text = cwdSuffix && !cleaned.includes(cwdSuffix) ? `${cleaned} (${cwdSuffix})` : cleaned;
-	return { text: descriptor(text), strength: best.score };
-}