@oh-my-pi/pi-coding-agent 15.10.10 → 15.10.12

package/src/eval/backend.ts

@@ -20,8 +20,6 @@ export interface ExecutorBackendExecOptions {
 	 */
 	idleTimeoutMs: number;
 	reset: boolean;
-	artifactPath: string | undefined;
-	artifactId: string | undefined;
 	onChunk: (chunk: string) => void;
 	/**
 	 * Live status events (read/write/agent/…) delivered as they are emitted,

package/src/eval/completion-bridge.ts

@@ -12,7 +12,8 @@
  * in, text (or, with `schema`, a structured object) out.
  */
 import { instrumentedCompleteSimple, resolveTelemetry } from "@oh-my-pi/pi-agent-core";
-import { type Api, Effort, getSupportedEfforts, type Model, type Tool } from "@oh-my-pi/pi-ai";
+import { type Api, Effort, type Model, type Tool } from "@oh-my-pi/pi-ai";
+import { getSupportedEfforts } from "@oh-my-pi/pi-catalog/model-thinking";
 import * as z from "zod/v4";
 import { extractTextContent, extractToolCall, parseJsonPayload } from "../commit/utils";
 
@@ -162,6 +163,7 @@ export async function runEvalCompletion(
 				apiKey: registry.resolver(model.provider, {
 					sessionId: options.session.getSessionId?.() ?? undefined,
 					baseUrl: model.baseUrl,
+					modelId: model.id,
 				}),
 				signal: options.signal,
 				reasoning: reasoningForTier(tier, model),

package/src/eval/idle-timeout.ts

@@ -6,8 +6,6 @@
  * `agent()`/`parallel()`/`completion()` work is ignored completely, then {@link resume}
  * starts a fresh timeout window once the runtime gets control back.
  *
- * The active timer self-reschedules instead of being torn down on every
- * activity event, so frequent activity costs one timestamp write per event.
  * Pause is reference-counted because `parallel()` can have multiple bridge calls
  * in flight at once.
  */
@@ -36,11 +34,6 @@ export class IdleTimeout {
 		return this.#idleMs;
 	}
 
-	/** Record runtime activity, pushing the active deadline forward by `idleMs`. */
-	bump(): void {
-		if (this.#settled || this.#pauseDepth > 0) return;
-		this.#deadlineMs = Date.now() + this.#idleMs;
-	}
 	/** Suspend timeout accounting while control is delegated to host-side work. */
 	pause(): void {
 		if (this.#settled) return;
@@ -86,8 +79,8 @@ export class IdleTimeout {
 		if (this.#settled || this.#pauseDepth > 0) return;
 		const remainingMs = this.#deadlineMs - Date.now();
 		if (remainingMs > 0) {
-			// A bump moved the deadline forward after this timer was armed; wait
-			// out the remaining window instead of firing early.
+			// The deadline moved forward (resume re-arming) after this timer was
+			// armed; wait out the remaining window instead of firing early.
 			this.#arm(remainingMs);
 			return;
 		}

package/src/eval/js/context-manager.ts

@@ -1,13 +1,10 @@
-import { isCompiledBinary, logger, Snowflake } from "@oh-my-pi/pi-utils";
+import { logger, Snowflake, workerHostEntry } from "@oh-my-pi/pi-utils";
 import type { ToolSession } from "../../tools";
 import { ToolAbortError, ToolError } from "../../tools/tool-errors";
 import { callSessionTool, type JsStatusEvent } from "./tool-bridge";
 import { WorkerCore } from "./worker-core";
-// Worker entry. See `tab-supervisor.ts` for the rationale behind the
-// literal-string + `new URL(import.meta.url)` hybrid: the literal is what
-// Bun's `--compile` bundler discovers, the `new URL` form is what makes dev
-// runs portable across cwds. The worker is registered as an additional
-// `--compile` entrypoint in `scripts/build-binary.ts`.
+// Coding-agent binary/bundle workers route through the CLI entrypoint with a
+// hidden argv mode, so compiled/npm builds only need one JavaScript entry.
 import type {
 	JsDisplayOutput,
 	RunErrorPayload,
@@ -384,8 +381,9 @@ async function raceWithTimeout<T>(promise: Promise<T>, timeoutMs: number, reason
 
 async function spawnJsWorker(): Promise<WorkerHandle> {
 	try {
-		const worker = isCompiledBinary()
-			? new Worker("./packages/coding-agent/src/eval/js/worker-entry.ts", { type: "module" })
+		const hostEntry = workerHostEntry();
+		const worker = hostEntry
+			? new Worker(hostEntry, { type: "module", argv: ["__omp_js_eval_worker"] })
 			: new Worker(new URL("./worker-entry.ts", import.meta.url).href, { type: "module" });
 		return wrapBunWorker(worker);
 	} catch (err) {

package/src/eval/js/executor.ts

@@ -63,9 +63,13 @@ function isTimeoutReason(reason: unknown): boolean {
 }
 
 function formatJsTimeoutAnnotation(timeoutMs: number | undefined): string {
-	if (timeoutMs === undefined) return "Command timed out";
+	// Timeout cancellation force-kills the worker (the only way to interrupt
+	// synchronous user code), which discards the persistent VM state. Say so,
+	// or the model will keep referencing variables that no longer exist.
+	const reset = "The JS worker was force-killed and its VM state was reset; variables from earlier cells are gone.";
+	if (timeoutMs === undefined) return `Command timed out. ${reset}`;
 	const secs = Math.max(1, Math.round(timeoutMs / 1000));
-	return `Command timed out after ${secs} seconds`;
+	return `Command timed out after ${secs} seconds. ${reset}`;
 }
 
 export async function executeJs(code: string, options: JsExecutorOptions): Promise<JsResult> {

package/src/eval/js/index.ts

@@ -30,8 +30,6 @@ export default {
 			sessionId: namespaceSessionId(opts.sessionId),
 			sessionFile: opts.sessionFile,
 			reset: opts.reset,
-			artifactPath: opts.artifactPath,
-			artifactId: opts.artifactId,
 			onChunk: opts.onChunk,
 			onStatus: opts.onStatus,
 			session: opts.session,

package/src/eval/js/shared/helpers.ts

@@ -83,12 +83,11 @@ export function createHelpers(ctx: HelperContext): HelperBundle {
 		},
 		append: async (rawPath, content) => {
 			const target = resolveHelperPath(ctx, rawPath, "write");
-			await Bun.write(
-				target,
-				`${await Bun.file(target)
-					.text()
-					.catch(() => "")}${content}`,
-			);
+			// O(1) append; read-all+rewrite both raced concurrent writers and went
+			// quadratic when called in a loop. Bun.write creates parent dirs, so
+			// keep that behavior for the append path too.
+			await fs.promises.mkdir(path.dirname(target), { recursive: true });
+			await fs.promises.appendFile(target, content, "utf-8");
 			ctx.emitStatus({
 				op: "append",
 				path: target,

package/src/eval/js/shared/local-module-loader.ts

@@ -102,7 +102,7 @@ export class LocalModuleLoader {
 		});
 		const moduleDir = path.dirname(modulePath);
 		const localDeps = new Set<string>();
-		for (const specifier of collectModuleSourceSpecifiers(stripped)) {
+		for (const specifier of await collectModuleSourceSpecifiers(stripped)) {
 			const resolved = resolveImportSpecifier(moduleDir, specifier);
 			if (isLocalPathSpecifier(specifier) && isManagedLocalModulePath(resolved)) {
 				localDeps.add(resolved);

package/src/eval/js/shared/prelude.txt

@@ -90,15 +90,25 @@ if (!globalThis.__omp_js_prelude_loaded__) {
 		const limit = await __concurrencyLimit();
 		const concurrency = limit > 0 ? Math.min(limit, list.length) : list.length;
 		const results = new Array(list.length);
+		// Barrier semantics (mirrors the Python _pool_map): every item settles
+		// before we return or throw, then the lowest-index error propagates.
+		// Early-rejecting would orphan in-flight thunks (e.g. live agent()
+		// subagents) whose worker-side promises would never be observed.
+		const errors = new Map();
 		let next = 0;
 		const worker = async () => {
 			while (true) {
 				const index = next++;
 				if (index >= list.length) return;
-				results[index] = await fn(list[index], index);
+				try {
+					results[index] = await fn(list[index], index);
+				} catch (error) {
+					errors.set(index, error);
+				}
 			}
 		};
 		await Promise.all(Array.from({ length: concurrency }, () => worker()));
+		if (errors.size > 0) throw errors.get(Math.min(...errors.keys()));
 		return results;
 	};
 
@@ -148,6 +158,8 @@ if (!globalThis.__omp_js_prelude_loaded__) {
 
 	const formatArgs = args => args.map(arg => (typeof arg === "string" ? arg : arg));
 
+	const consoleTimers = new Map();
+	const consoleCounts = new Map();
 	const consoleBridge = {
 		log: (...args) => globalThis.__omp_log__("log", ...formatArgs(args)),
 		info: (...args) => globalThis.__omp_log__("info", ...formatArgs(args)),
@@ -158,6 +170,55 @@ if (!globalThis.__omp_js_prelude_loaded__) {
 			columns === undefined
 				? globalThis.__omp_table__(data)
 				: globalThis.__omp_table__(data, columns),
+		dir: (value, _options) => globalThis.__omp_log__("log", value),
+		dirxml: (...args) => globalThis.__omp_log__("log", ...formatArgs(args)),
+		trace: (...args) => {
+			const stack = (new Error().stack ?? "").split("\n").slice(2).join("\n");
+			globalThis.__omp_log__("log", args.length > 0 ? `Trace: ${formatArgs(args).join(" ")}` : "Trace", `\n${stack}`);
+		},
+		assert: (condition, ...args) => {
+			if (condition) return;
+			if (args.length > 0) globalThis.__omp_log__("error", "Assertion failed:", ...formatArgs(args));
+			else globalThis.__omp_log__("error", "Assertion failed");
+		},
+		group: (...args) => {
+			if (args.length > 0) globalThis.__omp_log__("log", ...formatArgs(args));
+		},
+		groupCollapsed: (...args) => {
+			if (args.length > 0) globalThis.__omp_log__("log", ...formatArgs(args));
+		},
+		groupEnd: () => {},
+		time: label => {
+			consoleTimers.set(String(label ?? "default"), Date.now());
+		},
+		timeLog: (label, ...args) => {
+			const key = String(label ?? "default");
+			const start = consoleTimers.get(key);
+			if (start === undefined) {
+				globalThis.__omp_log__("warn", `Timer '${key}' does not exist`);
+				return;
+			}
+			globalThis.__omp_log__("log", `${key}: ${Date.now() - start}ms`, ...formatArgs(args));
+		},
+		timeEnd: label => {
+			const key = String(label ?? "default");
+			const start = consoleTimers.get(key);
+			if (start === undefined) {
+				globalThis.__omp_log__("warn", `Timer '${key}' does not exist`);
+				return;
+			}
+			consoleTimers.delete(key);
+			globalThis.__omp_log__("log", `${key}: ${Date.now() - start}ms`);
+		},
+		count: label => {
+			const key = String(label ?? "default");
+			const next = (consoleCounts.get(key) ?? 0) + 1;
+			consoleCounts.set(key, next);
+			globalThis.__omp_log__("log", `${key}: ${next}`);
+		},
+		countReset: label => {
+			consoleCounts.delete(String(label ?? "default"));
+		},
 	};
 
 	globalThis.console = consoleBridge;

package/src/eval/js/shared/rewrite-imports.ts

@@ -1,4 +1,4 @@
-import { parse as babelParse } from "@babel/parser";
+import type * as BabelParser from "@babel/parser";
 
 // Static ESM `import` declarations are not valid inside vm.runInContext (script-mode parsing),
 // and dynamic `import(...)` would otherwise resolve specifiers against the worker module's URL
@@ -64,9 +64,22 @@ type BabelModuleSourceDeclaration = {
 
 type BabelNode = { type: string; start: number; end: number; [key: string]: unknown };
 
-function parseProgram(code: string): { program: { body: ReadonlyArray<BabelProgramNode> } } | null {
+// @babel/parser sits on the CLI launch graph (tools → eval backend → worker-core →
+// runtime → this module) but only runs when an eval cell executes, so it is loaded
+// lazily and memoized.
+let babelParser: typeof BabelParser | undefined;
+
+async function loadBabelParser(): Promise<typeof BabelParser> {
+	if (!babelParser) {
+		babelParser = await import("@babel/parser");
+	}
+	return babelParser;
+}
+
+async function parseProgram(code: string): Promise<{ program: { body: ReadonlyArray<BabelProgramNode> } } | null> {
+	const { parse } = await loadBabelParser();
 	try {
-		return babelParse(code, {
+		return parse(code, {
 			sourceType: "module",
 			allowAwaitOutsideFunction: true,
 			allowReturnOutsideFunction: true,
@@ -162,10 +175,10 @@ function rewriteImportNode(node: BabelImportDeclaration): string {
 	return `await ${importCall};`;
 }
 
-export function rewriteImports(code: string): string {
+export async function rewriteImports(code: string): Promise<string> {
 	if (!code.includes("import")) return code;
 
-	const ast = parseProgram(code);
+	const ast = await parseProgram(code);
 	if (!ast) {
 		// Parser bailed entirely — let the VM surface the real syntax error.
 		return code;
@@ -201,8 +214,8 @@ export function rewriteImports(code: string): string {
 	}
 	return result;
 }
-export function collectModuleSourceSpecifiers(code: string): string[] {
-	const ast = parseProgram(code);
+export async function collectModuleSourceSpecifiers(code: string): Promise<string[]> {
+	const ast = await parseProgram(code);
 	if (!ast) return [];
 	const sources: string[] = [];
 	for (const node of ast.program.body) {
@@ -218,8 +231,11 @@ export function collectModuleSourceSpecifiers(code: string): string[] {
 	return sources;
 }
 
-export function rewriteModuleSourceSpecifiers(code: string, replacer: (source: string) => string): string {
-	const ast = parseProgram(code);
+export async function rewriteModuleSourceSpecifiers(
+	code: string,
+	replacer: (source: string) => string,
+): Promise<string> {
+	const ast = await parseProgram(code);
 	if (!ast) return code;
 
 	type Edit = { start: number; end: number; text: string };
@@ -249,9 +265,9 @@ export function rewriteModuleSourceSpecifiers(code: string, replacer: (source: s
 	return result;
 }
 
-export function rewriteDynamicImports(code: string, callee = "__omp_import__"): string {
+export async function rewriteDynamicImports(code: string, callee = "__omp_import__"): Promise<string> {
 	if (!code.includes("import")) return code;
-	const ast = parseProgram(code);
+	const ast = await parseProgram(code);
 	if (!ast) return code;
 
 	type Edit = { start: number; end: number; text: string };
@@ -339,10 +355,10 @@ function appendGlobalBindingPublish(source: string, names: readonly string[]): s
  * Nested declarations (inside functions, blocks, classes) are left alone \u2014 they're
  * scoped to their enclosing function/block regardless of `var` vs `let`/`const`.
  */
-function demoteTopLevelLexicals(code: string, options: { publishGlobals?: boolean } = {}): string {
+async function demoteTopLevelLexicals(code: string, options: { publishGlobals?: boolean } = {}): Promise<string> {
 	if (!/\b(?:const|let|class)\b/.test(code)) return code;
 
-	const ast = parseProgram(code);
+	const ast = await parseProgram(code);
 	if (!ast) {
 		return code;
 	}
@@ -381,8 +397,8 @@ function demoteTopLevelLexicals(code: string, options: { publishGlobals?: boolea
 	return result;
 }
 
-function returnFinalExpression(code: string): { source: string; returned: boolean } {
-	const ast = parseProgram(code);
+async function returnFinalExpression(code: string): Promise<{ source: string; returned: boolean }> {
+	const ast = await parseProgram(code);
 	const body = ast?.program.body;
 	if (!body) return { source: code, returned: false };
 	let lastIndex = body.length - 1;
@@ -446,8 +462,8 @@ function containsAsyncWrapperSyntax(value: unknown): boolean {
 	return false;
 }
 
-function requiresAsyncWrapper(code: string): boolean {
-	const ast = parseProgram(code);
+async function requiresAsyncWrapper(code: string): Promise<boolean> {
+	const ast = await parseProgram(code);
 	if (!ast) return false;
 	for (const node of ast.program.body) {
 		if (containsAsyncWrapperSyntax(node)) return true;
@@ -494,13 +510,15 @@ export function stripTypeScriptSyntax(
 const LOOKS_LIKE_TS =
 	/(?:\bimport\s+type\b|\bexport\s+type\b|\b(?:import|export)\s*\{[^}\n]*\btype\s+\w|\binterface\s+\w|\btype\s+\w+\s*=|\b(?:as|satisfies)\s+(?:[A-Z]|\bconst\b)|:\s*(?:string|number|boolean|any|unknown|void|never|object|[A-Z]\w*)\b|<\s*[A-Z]\w*\s*[,>])/;
 
-export function wrapCode(code: string): { source: string; asyncWrapped: boolean; finalExpressionReturned: boolean } {
-	const finalExpression = returnFinalExpression(code);
+export async function wrapCode(
+	code: string,
+): Promise<{ source: string; asyncWrapped: boolean; finalExpressionReturned: boolean }> {
+	const finalExpression = await returnFinalExpression(code);
 	const stripped = stripTypeScript(finalExpression.source);
-	const importsRewritten = rewriteImports(stripped);
-	const needsAsyncWrapper = requiresAsyncWrapper(importsRewritten);
+	const importsRewritten = await rewriteImports(stripped);
+	const needsAsyncWrapper = await requiresAsyncWrapper(importsRewritten);
 	const rewritten = {
-		source: demoteTopLevelLexicals(importsRewritten, { publishGlobals: needsAsyncWrapper }),
+		source: await demoteTopLevelLexicals(importsRewritten, { publishGlobals: needsAsyncWrapper }),
 		returned: finalExpression.returned,
 	};
 	if (!needsAsyncWrapper) {

package/src/eval/js/shared/runtime.ts

@@ -181,7 +181,7 @@ export class JsRuntime {
 			finalExpressionValue: undefined,
 		};
 		return await this.#als.run(context, async () => {
-			const wrapped = wrapCode(code);
+			const wrapped = await wrapCode(code);
 			const value = indirectEval(wrapped.source, filename);
 			if (wrapped.finalExpressionReturned) {
 				const awaited = await awaitMaybePromise(value);

package/src/eval/py/executor.ts

@@ -1,3 +1,4 @@
+import * as fs from "node:fs";
 import * as path from "node:path";
 
 import { getProjectDir, logger } from "@oh-my-pi/pi-utils";
@@ -15,6 +16,7 @@ import {
 	type KernelRuntimeEnv,
 	PythonKernel,
 } from "./kernel";
+import { resolveExplicitPythonRuntime } from "./runtime";
 import { ensurePyToolBridge, registerPyToolBridge } from "./tool-bridge";
 
 export type PythonKernelMode = "session" | "per-call";
@@ -42,6 +44,11 @@ export interface PythonExecutorOptions {
 	kernelOwnerId?: string;
 	/** Kernel mode (session reuse vs per-call) */
 	kernelMode?: PythonKernelMode;
+	/**
+	 * Explicit interpreter path (`python.interpreter` resolved from the
+	 * session's settings). Skips automatic runtime discovery when set.
+	 */
+	interpreter?: string;
 	/** Restart the kernel before executing */
 	reset?: boolean;
 	/** Session file path for accessing task outputs */
@@ -116,9 +123,9 @@ export interface PythonResult {
 // ---------------------------------------------------------------------------
 // Session bookkeeping
 //
-// One PythonKernel subprocess per (session id, cwd) tuple. The runner mutates
-// process-global cwd/sys.path during execution, so cross-directory work MUST
-// never share a live kernel. Multiple agent owners can still register against
+// One PythonKernel subprocess per (session id, cwd, interpreter) tuple. The
+// runner mutates process-global cwd/sys.path during execution, so cross-directory
+// work must never share a live kernel. Multiple agent owners can still register against
 // the same tuple; the kernel stays alive until the last owner detaches.
 // ---------------------------------------------------------------------------
 
@@ -139,8 +146,19 @@ function normalizeSessionCwd(cwd: string): string {
 	return path.resolve(cwd);
 }
 
-function buildSessionKey(sessionId: string, cwd: string): string {
-	return `${sessionId}\0${normalizeSessionCwd(cwd)}`;
+function normalizeExplicitInterpreter(cwd: string, interpreter: string | undefined): string {
+	if (interpreter === undefined) return "";
+	const resolved = resolveExplicitPythonRuntime(interpreter, cwd, {}).pythonPath;
+	try {
+		return fs.realpathSync.native(resolved);
+	} catch {
+		return resolved;
+	}
+}
+
+function buildSessionKey(sessionId: string, cwd: string, interpreter: string | undefined): string {
+	const normalizedCwd = normalizeSessionCwd(cwd);
+	return `${sessionId}\0${normalizedCwd}\0${normalizeExplicitInterpreter(normalizedCwd, interpreter)}`;
 }
 
 // ---------------------------------------------------------------------------
@@ -326,6 +344,7 @@ async function startKernel(cwd: string, options: PythonExecutorOptions): Promise
 		env: buildKernelEnv(options),
 		signal: options.signal,
 		deadlineMs: options.deadlineMs,
+		interpreter: options.interpreter,
 	});
 }
 
@@ -587,7 +606,10 @@ async function executeWithKernel(
 }
 
 async function ensureKernelAvailable(cwd: string, options: PythonExecutorOptions): Promise<void> {
-	const availability = await waitForPromiseWithCancellation(checkPythonKernelAvailability(cwd), options);
+	const availability = await waitForPromiseWithCancellation(
+		checkPythonKernelAvailability(cwd, options.interpreter),
+		options,
+	);
 	if (!availability.ok) {
 		throw new Error(availability.reason ?? "Python kernel unavailable");
 	}
@@ -618,7 +640,7 @@ async function executePerCall(code: string, cwd: string, options: PythonExecutor
 
 async function executeOnSession(code: string, cwd: string, options: PythonExecutorOptions): Promise<PythonResult> {
 	const sessionId = options.sessionId ?? `session:${cwd}`;
-	const sessionKey = buildSessionKey(sessionId, cwd);
+	const sessionKey = buildSessionKey(sessionId, cwd, options.interpreter);
 	if (options.bridge && !options.bridgeSessionId) {
 		options.bridgeSessionId = sessionId;
 	}

package/src/eval/py/index.ts

@@ -19,13 +19,17 @@ function readSetting<T>(session: ToolSession, key: string): T | undefined {
 	return settings?.get?.(key);
 }
 
+function readInterpreterSetting(session: ToolSession): string | undefined {
+	return readSetting<string>(session, "python.interpreter")?.trim() || undefined;
+}
+
 export default {
 	id: "python",
 	label: "Python",
 	highlightLang: "python",
 
 	async isAvailable(session: ToolSession): Promise<boolean> {
-		const availability = await checkPythonKernelAvailability(session.cwd);
+		const availability = await checkPythonKernelAvailability(session.cwd, readInterpreterSetting(session));
 		return availability.ok;
 	},
 
@@ -37,13 +41,12 @@ export default {
 			signal: opts.signal,
 			sessionId: namespaceSessionId(opts.sessionId),
 			kernelMode,
+			interpreter: readInterpreterSetting(opts.session),
 			sessionFile: opts.sessionFile,
 			artifactsDir: opts.session.getArtifactsDir?.() ?? undefined,
 			localRoots: resolveEvalUrlRoots(opts.session),
 			kernelOwnerId: opts.kernelOwnerId,
 			reset: opts.reset,
-			artifactPath: opts.artifactPath,
-			artifactId: opts.artifactId,
 			onChunk: opts.onChunk,
 			onStatus: opts.onStatus,
 			toolSession: opts.session,

package/src/eval/py/kernel.ts

@@ -17,7 +17,13 @@ import { Settings } from "../../config/settings";
 import { type KernelDisplayOutput, renderKernelDisplay } from "./display";
 import { PYTHON_PRELUDE } from "./prelude";
 import RUNNER_SCRIPT from "./runner.py" with { type: "text" };
-import { enumeratePythonRuntimes, filterEnv, type PythonRuntime, resolvePythonRuntime } from "./runtime";
+import {
+	enumeratePythonRuntimes,
+	filterEnv,
+	type PythonRuntime,
+	resolveExplicitPythonRuntime,
+	resolvePythonRuntime,
+} from "./runtime";
 import { hostHasInheritableConsole, shouldHideKernelWindow } from "./spawn-options";
 
 export type { KernelDisplayOutput, PythonStatusEvent } from "./display";
@@ -96,6 +102,11 @@ interface KernelLifecycleOptions {
 interface KernelStartOptions extends KernelLifecycleOptions {
 	cwd: string;
 	env?: Record<string, string | undefined>;
+	/**
+	 * Explicit interpreter path (`python.interpreter` from the session's
+	 * settings). When set, runtime discovery is skipped entirely.
+	 */
+	interpreter?: string;
 }
 
 interface KernelShutdownOptions {
@@ -129,15 +140,40 @@ function throwIfAborted(signal: AbortSignal | undefined, fallbackReason: string)
 	throw createAbortError("AbortError", typeof reason === "string" ? reason : fallbackReason);
 }
 
-export async function checkPythonKernelAvailability(cwd: string): Promise<PythonKernelAvailability> {
+// Cache successful probes per resolved cwd + explicit interpreter: every cell
+// otherwise pays one (or two — backend.isAvailable + ensureKernelAvailable)
+// interpreter spawns even when the kernel is already hot. Failures are not
+// cached so installing a Python mid-session is picked up on the next attempt.
+const availabilityCache = new Map<string, Promise<PythonKernelAvailability>>();
+
+export async function checkPythonKernelAvailability(
+	cwd: string,
+	interpreter?: string,
+): Promise<PythonKernelAvailability> {
 	if (isBunTestRuntime() || $flag("PI_PYTHON_SKIP_CHECK")) {
 		return { ok: true };
 	}
+	const resolvedCwd = path.resolve(cwd);
+	const key = `${resolvedCwd}\0${interpreter ?? ""}`;
+	const cached = availabilityCache.get(key);
+	if (cached) return await cached;
+	const probe = probePythonKernelAvailability(resolvedCwd, interpreter);
+	availabilityCache.set(key, probe);
+	const result = await probe;
+	if (!result.ok && availabilityCache.get(key) === probe) {
+		availabilityCache.delete(key);
+	}
+	return result;
+}
+
+async function probePythonKernelAvailability(cwd: string, interpreter?: string): Promise<PythonKernelAvailability> {
 	try {
 		const settings = await Settings.init();
 		const { env } = settings.getShellConfig();
 		const baseEnv = filterEnv(env);
-		const runtimes = enumeratePythonRuntimes(cwd, baseEnv);
+		const runtimes = interpreter
+			? [resolveExplicitPythonRuntime(interpreter, cwd, baseEnv)]
+			: enumeratePythonRuntimes(cwd, baseEnv);
 		if (runtimes.length === 0) {
 			return { ok: false, reason: "Python executable not found on PATH" };
 		}
@@ -220,6 +256,7 @@ export class PythonKernel {
 			"PythonKernel.start:availabilityCheck",
 			checkPythonKernelAvailability,
 			options.cwd,
+			options.interpreter,
 		);
 		if (!availability.ok) {
 			throw new Error(availability.reason ?? "Python kernel unavailable");
@@ -232,7 +269,9 @@ export class PythonKernel {
 		let runtime = availability.runtime;
 		if (!runtime) {
 			const { env: shellEnv } = (await Settings.init()).getShellConfig();
-			runtime = resolvePythonRuntime(options.cwd, filterEnv(shellEnv));
+			runtime = options.interpreter
+				? resolveExplicitPythonRuntime(options.interpreter, options.cwd, filterEnv(shellEnv))
+				: resolvePythonRuntime(options.cwd, filterEnv(shellEnv));
 		}
 		const spawnEnv: Record<string, string> = {};
 		for (const [key, value] of Object.entries(runtime.env)) {