pi-repl-py 0.6.13 → 0.7.0

package/src/extension/render-core.ts

@@ -114,12 +114,7 @@ function marker(state: ExecuteRenderState, deps: RenderDeps): string {
 	}
 }
 
-/**
- * highlight.js python emits no scope for plain identifiers, so they arrive as raw (uncolored)
- * text mixed with SGR-colored tokens and bare punctuation. Re-color only whole identifier runs
- * that sit outside any colored span, leaving keywords, strings, numbers, and other already
- * colored tokens untouched.
- */
+/** highlight.js emits no scope for bare Python identifiers — re-color only raw runs outside colored spans. */
 function colorBareIdentifiers(line: string, paint: (id: string) => string): string {
 	if (!line.includes("\x1b") && !/[a-zA-Z_]/.test(line)) return line;
 	const out: string[] = [];
@@ -160,7 +155,6 @@ function colorBareIdentifiers(line: string, paint: (id: string) => string): stri
 			i = end;
 			continue;
 		}
-		// only raw (uncolored) text may be repainted; colored tokens pass through untouched
 		if (colored) out.push(line[i]);
 		else pending += line[i];
 		i++;
@@ -242,9 +236,7 @@ function sanitizeTuiOutput(text: string): string {
 		.replace(/[\x00-\x08\x0b-\x0c\x0e-\x1f\x7f-\x9f]/g, "�");
 }
 
-/** 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. */
+/** Wrap a colored span: first row takes the prefix, continuations the indent; truncate to width and close open SGR colors. */
 function pushWrappedLines(
 	lines: string[],
 	prefix: string,
@@ -306,12 +298,7 @@ function renderCode(state: ExecuteRenderState, lines: string[], width: number, d
 	return true;
 }
 
-/**
- * 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.
- */
+/** Output is append-only: the cached wrap re-wraps just the tail — O(chunk) instead of O(output). */
 interface BlobWrapEntry {
 	text: string;
 	color: string;
@@ -321,20 +308,14 @@ interface BlobWrapEntry {
 }
 
 const blobWrapCache = new WeakMap<ExecuteRenderState, Map<number, BlobWrapEntry>>();
-/** Wrapped+highlighted rows rebuild only when their inputs (text/width) change; the
- * TUI re-renders bodies on every frame, so these caches turn per-frame work into
- * one build per change. They live on the persistent per-call state, which the host
- * keeps for the session, so a small bound per state keeps resize churn bounded. */
+/** Row caches keyed by text/width turn per-frame renders into one build per change; bounded per state against resize churn. */
 interface CodeEntry {
 	code: string;
 	lines: string[];
 }
 const codeWrapCache = new WeakMap<ExecuteRenderState, Map<number, CodeEntry>>();
 
-/** Window resizes add a per-width entry per cell; keep a small bound so a long
- * session with resize churn cannot grow the wrap caches without limit. Map
- * iteration order is insertion order, so evicting the first key drops the oldest
- * width rather than the one in use. */
+/** Bound per-width cache entries; insertion order evicts the oldest width first. */
 const MAX_CACHED_WIDTHS_PER_STATE = 3;
 function boundWidthCache(perWidth: Map<number, unknown>): void {
 	while (perWidth.size >= MAX_CACHED_WIDTHS_PER_STATE) {
@@ -352,9 +333,7 @@ function widthOf(ch: string): number {
 	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. */
+/** Fast word wrap for sanitized text: pi-tui's ANSI-aware wrap costs ~45ms on a 45K blob. */
 function wrapPlainText(text: string, width: number): string[] {
 	if (width <= 0 || text.length <= width) return [text];
 	// --- fast path: pure ASCII, break by char index ---
@@ -430,8 +409,7 @@ function wrapPlainText(text: string, width: number): string[] {
 	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. */
+/** Sanitize → fast wrap → colorize rows, so an SGR 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 || " ");
@@ -517,8 +495,7 @@ 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 ---
+		// --- a traceback IS output: without this, a pure-traceback error cell also rendered "no output" below it ---
 		renderedText = true;
 		output.push(` ${OUTPUT_INDENT}${deps.fg("dim", "traceback:")}`);
 		for (const line of details.errorStack) {
@@ -532,10 +509,7 @@ 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.) ---
+	// --- the panel always ends with one blank row: streams end with a newline, tracebacks and placeholders don't ---
 	const lastRow = output[output.length - 1];
 	if (lastRow !== undefined && lastRow.replace(SGR_PATTERN, "").trim() !== "") output.push("");
 
@@ -544,7 +518,6 @@ function renderOutput(
 	lines.push(...output);
 }
 
-/** Paint the status-matched panel background across the row, surviving inner SGR resets. */
 export function paintBackground(line: string, width: number, kind: StatusKind, deps: RenderDeps): string {
 	const bgAnsi = deps.getBgAnsi(backgroundFor(kind));
 	const padded = line + " ".repeat(Math.max(0, width - deps.visibleWidth(line)));

package/src/extension/render.ts

@@ -30,10 +30,7 @@ function makeDeps(theme: Theme): RenderDeps {
 	};
 }
 
-/** 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. */
+/** O(1) body key excludes the spinner frame, so a running cell redraws only when output changes, not 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}`;

package/src/extension/session-engine.ts

@@ -1,6 +1,6 @@
-// revival is part of create() so a session that gets teardown without a session_start reload still revives
+// Lifecycle: boot, session binding, reset announcements. Recovery is a background quiet-gap job; the notice lands on the first cell after the restore.
 
-import type { RestoreResult } from "../engine/index.js";
+import type { HelperLoadResult, RestoreResult } from "../engine/index.js";
 
 /** Show enough names to orient, then count the rest (a revive can carry hundreds). */
 function summarizeNames(names: readonly string[], limit: number): string {
@@ -10,33 +10,32 @@ function summarizeNames(names: readonly string[], limit: number): string {
 
 /** The part of EngineManager this lifecycle needs; narrowed so tests can fake it. */
 export interface RevivableEngine {
-	/** Boot the engine and revive the snapshot; `skip` boots fresh, deliberately not reviving. */
-	restoreState(skip?: boolean): Promise<RestoreResult | null>;
+	/** Boot the kernel (and preload helpers), independent of snapshot recovery. */
+	start(skipRestore?: boolean): Promise<void>;
+	/** Recovery outcome: revived names, or null when nothing to revive / skipped / 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;
+	/** Fresh engine; skipRestore is the retry after a wedged boot, so a poisoned snapshot can't 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, snapshot restore) that
-	 * outlives it is killed and retried fresh. Default 90s. */
+	/** Boot deadline (default 90s): an overlong boot is killed and retried. Recovery is outside it — background, bounded by the restore-cell watchdog. */
 	bootTimeoutMs?: number;
 }
 
-/** Sentinel: the boot outlived its deadline. Distinct from null, which means "booted, nothing revived". */
-const BOOT_WEDGED = Symbol("boot wedged");
-
-/** `startup` restores then announces on the first cell when the conversation has a saved past; `cell` means an engine was rebuilt mid-session and announces immediately. */
+/** startup: announce when the conversation has a saved past; cell: a mid-session rebuild 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
@@ -44,27 +43,19 @@ function revivedNoticeBody(origin: AcquireOrigin): string {
 		: "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 {
+// --- human toast, separate from the model marker; counts come from the same restore, so the two never disagree ---
+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 {
@@ -118,88 +109,113 @@ function formatEngineResetNotice(restore: RestoreResult | null, origin: AcquireO
 	return lines.join("\n");
 }
 
+/** Human toast when a /fork'd conversation inherited its parent's namespace — same counts as the reset marker, named as a fork so it can't pass for a plain resume. */
+export function formatForkToast(restore: RestoreResult | null): string {
+	const revived = restore?.restored.length ?? 0;
+	if (revived > 0) {
+		const noun = revived === 1 ? "name" : "names";
+		return `repl fork started — ${revived} ${noun} inherited from the parent session`;
+	}
+	return restore === null
+		? "repl fork started — nothing to inherit"
+		: "repl fork started — parent snapshot revived nothing";
+}
+
+// --- split audience: toast for the human whenever a boot preloaded anything; a marker for the model ONLY when a helper failed (all-good boots are silent) ---
+
+export function formatHelperToast(report: readonly HelperLoadResult[]): string {
+	const loaded = report.filter((h) => h.ok).map((h) => h.name);
+	const failed = report.filter((h) => !h.ok);
+	const loadedPart = loaded.length > 0 ? `helpers loaded: ${loaded.join(", ")}` : "no helpers loaded";
+	const failedPart =
+		failed.length > 0 ? ` · failed: ${failed.map((f) => `${f.name} (${f.error ?? "failed to load"})`).join(", ")}` : "";
+	return `repl ${loadedPart}${failedPart}`;
+}
+
+export function formatHelperFailuresLine(report: readonly HelperLoadResult[] | null): string | undefined {
+	if (!report) return undefined;
+	const failed = report.filter((h) => !h.ok);
+	if (failed.length === 0) return undefined;
+	return `<repl_helpers_failed: ${failed.map((f) => `${f.name} (${f.error ?? "failed to load"})`).join(", ")}>`;
+}
+
 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>) {}
 
-	/** Race one boot attempt against the deadline. The losing attempt is abandoned (and the
-	 * engine killed by the caller): its promise gets a no-op catch so killing the kernel
-	 * cannot surface an unhandled rejection later. */
-	private bootOnce(
-		engine: E,
-		deadlineMs: number,
-		skipRestore: boolean,
-	): Promise<RestoreResult | null | typeof BOOT_WEDGED> {
-		const work = engine.restoreState(skipRestore).catch(() => null);
+	/** Race one boot (kernel start + helpers preload) against the deadline; a failed start is soft — the first cell observes it and 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<typeof BOOT_WEDGED>((resolve) => {
-			timer = setTimeout(() => resolve(BOOT_WEDGED), deadlineMs);
+		const guard = new Promise<boolean>((resolve) => {
+			timer = setTimeout(() => resolve(false), deadlineMs);
 			timer.unref?.();
 		});
-		return Promise.race([work, guard]).finally(() => clearTimeout(timer));
+		return Promise.race([work.then(() => true), guard]).finally(() => clearTimeout(timer));
 	}
 
-	/** Built and revived on demand; awaited so callers never see an un-revived namespace. */
-	async acquire(origin: AcquireOrigin): Promise<{ engine: E; restore: RestoreResult | null; created: boolean }> {
+	/** Built on demand; acquire() never waits on the background restore (announced on the first cell after it completes). sessionKey: a different conversation's acquire tears the bound engine down, so sessions can't bleed into each other. */
+	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 };
 			}
+			this.boundKey = sessionKey;
+			const deadline = this.deps.bootTimeoutMs ?? DEFAULT_BOOT_TIMEOUT_MS;
 			let engine = this.deps.create();
 			this.engine = engine;
-			// --- the boot is bounded: kernel start, helpers preload, and snapshot restore all
-			// --- run as kernel cells with no deadline of their own, and acquire() dedupes, so
-			// --- one wedged boot (venv swapped mid-update, a poisoned pickle) would otherwise
-			// --- hang the first cell and every cell after it. ---
-			const deadline = this.deps.bootTimeoutMs ?? DEFAULT_BOOT_TIMEOUT_MS;
-			let restore = await this.bootOnce(engine, deadline, false);
-			if (restore === BOOT_WEDGED) {
-				// --- the kernel is alive but stuck; only a kill frees it. Retry once WITHOUT the
-				// --- snapshot, so a poisoned pickle cannot wedge the session twice in a row. ---
+			let booted = await this.bootOnce(engine, deadline);
+			if (!booted) {
+				// --- the kernel is stuck, not dead; kill and retry once WITHOUT the snapshot so a poisoned one can't wedge twice ---
 				await (this.deps.discard ?? this.deps.dispose)(engine);
-				engine = this.deps.create();
+				engine = this.deps.create(true);
 				this.engine = engine;
-				restore = await this.bootOnce(engine, deadline, true);
-				if (restore === BOOT_WEDGED) {
+				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");
 				}
-				// --- the snapshot existed but reviving it is what wedged: say exactly that, not
-				// --- "no snapshot available", so the model doesn't go hunting for a missing file ---
-				if (origin === "cell" || (origin === "startup" && engine.hasSnapshotHistory())) {
-					this.pendingNotice = [
-						"<repl_engine_reset>",
-						revivedNoticeBody(origin),
-						"Re-verify a variable before reusing it, especially inside shell interpolation.",
-						"</repl_engine_reset>",
-					].join("\n");
-					this.pendingReset = { origin, restore: null };
-				}
-				this.revival = Promise.resolve(null);
-				return { engine, restore: null, created: true };
-			}
-			this.revival = Promise.resolve(restore);
-			// --- mid-session rebuilds always announce; startup announces only when the
-			// --- conversation has a saved past, so a first-ever session stays quiet ---
-			if (origin === "cell" || (origin === "startup" && engine.hasSnapshotHistory())) {
-				this.pendingNotice = formatEngineResetNotice(restore, origin);
-				this.pendingReset = { origin, restore };
 			}
-			return { engine, restore, created: true };
+			// --- the notice lands on the first cell AFTER the restore completes; announce mid-session rebuilds and resumes with a saved past, never first sessions ---
+			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 {
@@ -209,14 +225,16 @@ 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 {
+	/** The pending reset notice, taken exactly once. */
+	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> {
@@ -231,7 +249,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/skill-hook.ts

@@ -1,5 +1,4 @@
-// --- skills cannot reach the prompt in --repl: pi gates <available_skills> on the read tool
-// (hasRead), which repl doesn't have. Re-emit them with pi's own formatter in pi's slot. ---
+// --- pi gates skills on the read tool (absent in repl); re-emit them with pi's own formatter in pi's slot ---
 import { formatSkillsForPrompt, type Skill } from "@mariozechner/pi-coding-agent";
 
 const CWD_MARKER = "\nCurrent working directory:"; // skills sit just before this, pi's last line

package/src/extension/state-layout.ts

@@ -0,0 +1,58 @@
+// --- state lives at ~/.pi/agent/pi-repl/state/<slug>__<conv>: legacy bare-name dirs migrate on the owning conversation's next start, and the sweep knows both formats, so nothing live is swept and a deleted conversation loses its snapshots ---
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+export function conversationName(sessionFile: string): string {
+	return basename(sessionFile).replace(/\.jsonl$/, "");
+}
+
+/** Slug-keyed dir name: conversations whose files share a basename can never share a snapshot. */
+export function sessionStateDirName(sessionFile: string): string {
+	return `${basename(dirname(sessionFile))}__${conversationName(sessionFile)}`;
+}
+
+function legacyStateDirName(sessionFile: string): string {
+	return conversationName(sessionFile);
+}
+
+/** Resolve the state dir, migrating a legacy bare-name dir on first start — whichever conversation starts first owns the legacy dir; the other starts empty. */
+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") };
+}
+
+/** The /fork header's parentSession -> the parent's own snapshot file, when the fork has no history yet. */
+export function forkParentSnapshot(stateRoot: string, sessionFile: string, snapshotPath: string): string | undefined {
+	if (existsSync(snapshotPath)) return undefined; // the fork already built its own history
+	let header: { parentSession?: unknown };
+	try {
+		const first = readFileSync(sessionFile, "utf8").split("\n", 1)[0] ?? "";
+		header = JSON.parse(first) as { parentSession?: unknown };
+	} catch {
+		return undefined; // unreadable / not a session file — not a fork
+	}
+	if (typeof header.parentSession !== "string" || header.parentSession === "") return undefined;
+	const parent = resolveStateDir(stateRoot, header.parentSession);
+	return existsSync(parent.snapshotPath) ? parent.snapshotPath : undefined;
+}
+
+/** Copy the parent's last snapshot into the fork's own key once (true when something was inherited); the fork then restores like any resume, and the parent is never touched. */
+export function inheritForkSnapshot(stateRoot: string, sessionFile: string, snapshotPath: string): boolean {
+	const parentSnap = forkParentSnapshot(stateRoot, sessionFile, snapshotPath);
+	if (parentSnap === undefined) return false;
+	mkdirSync(dirname(snapshotPath), { recursive: true });
+	const tmp = `${snapshotPath}.tmp`;
+	copyFileSync(parentSnap, tmp);
+	renameSync(tmp, snapshotPath);
+	return true;
+}

package/src/extension/tool-meta.ts

@@ -1,15 +1,8 @@
-// --- 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, 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 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);
+export function buildExecutePromptGuidelines(): string[] {
+	return buildPromptGuidelines([]);
 }