@code-yeongyu/senpi-codemode 2026.10.9 → 2026.10.10-11

package/src/environments/py-installer.ts

@@ -125,7 +125,11 @@ export function splitShellWords(text: string, posix = process.platform !== "win3
 }
 
 export function parsePipRequirements(text: string): string[] {
-	const args = splitShellWords(text);
+	return normalizePipInstall(splitShellWords(text));
+}
+
+/** `%pip` words already split (`["install", ...]`): `packages.install()` passes its list as-is, so nothing is re-quoted. */
+export function normalizePipInstall(args: readonly string[]): string[] {
 	const command = args[0] === "install" ? args.slice(1) : undefined;
 	if (command === undefined) {
 		throw new EnvironmentError("environment_install_failed", "only `%pip install <requirements>` is supported");

package/src/environments/python-environments.ts

@@ -47,7 +47,7 @@ export class PythonEnvironments {
 	}
 
 	async install(
-		requirements: string,
+		requirements: string | readonly string[],
 		signal: AbortSignal,
 		onOutput?: (stream: "stdout" | "stderr", data: string) => void,
 	): Promise<InstallReceipt> {

package/src/environments/revision-store.ts

@@ -1,8 +1,9 @@
 import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
-import { cp, mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { chmod, cp, mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { type LockWaitNotice, withRootLock } from "./install-lock.ts";
+import { assertLinkStaysInside, assertNoLinksBelow, recordedInstallSources } from "./no-links.ts";
 import { EnvironmentError } from "./py-installer.ts";
 
 const POINTER = "active";
@@ -50,7 +51,7 @@ export async function publishNextRevision(
 	signal?: AbortSignal,
 	onLockWait?: (notice: LockWaitNotice) => void,
 ): Promise<{ readonly revision: Revision; readonly previous: Revision | undefined }> {
-	await mkdir(base, { recursive: true });
+	await mkdirPrivate(base);
 	return withRootLock(
 		base,
 		async () => {
@@ -59,8 +60,18 @@ export async function publishNextRevision(
 			const staging = join(base, `.staging-rev-${number}-${process.pid}-${randomUUID()}`);
 			const dir = join(base, `rev-${number}`);
 			try {
-				if (previous === undefined) await mkdir(staging, { recursive: true });
-				else await cp(previous.dir, staging, { recursive: true, verbatimSymlinks: true });
+				if (previous === undefined) await mkdir(staging, { mode: 0o700 });
+				else {
+					await assertNoLinksBelow(base, previous.dir);
+					const sources = await recordedInstallSources(previous.dir);
+					await cp(previous.dir, staging, {
+						recursive: true,
+						verbatimSymlinks: true,
+						filter: async (source) => await assertLinkStaysInside(source, previous.dir, sources),
+					});
+				}
+				// Explicit, not left to the umask: a revision holds the user's installed packages and carried registry config.
+				await chmod(staging, 0o700);
 				await build(staging, previous);
 				signal?.throwIfAborted();
 				await renameRetrying(staging, dir);
@@ -108,3 +119,8 @@ async function highestRevision(base: string): Promise<number> {
 	}
 	return highest;
 }
+
+/** Creates `dir` and any missing parents private to the user (0700; the umask can only narrow it further). */
+export async function mkdirPrivate(dir: string): Promise<void> {
+	await mkdir(dir, { recursive: true, mode: 0o700 });
+}

package/src/extension/bridge-tool-call.ts

@@ -19,7 +19,10 @@ export interface BridgeToolCallRequest {
 // and ordinary tool results are marshalled to { text, images, details, hasError } — the raw
 // { content } shape left python cells unable to reach tool.read image blocks.
 export async function routeBridgeToolCall(
-	options: Pick<CreateCodemodeSessionManagerOptions, "executeTool" | "listTools" | "settings" | "handles">,
+	options: Pick<
+		CreateCodemodeSessionManagerOptions,
+		"executeTool" | "listTools" | "settings" | "handles" | "environments"
+	>,
 	request: BridgeToolCallRequest,
 	evalHandleHost?: EvalHandleHost,
 ): Promise<unknown> {
@@ -39,5 +42,6 @@ export async function routeBridgeToolCall(
 		marshalToolResult,
 		...(options.handles === undefined ? {} : { handles: options.handles }),
 		...(evalHandleHost === undefined ? {} : { evalHandleHost }),
+		...(options.environments === undefined ? {} : { environments: options.environments }),
 	});
 }

package/src/extension/eval-notifier.ts

@@ -1,4 +1,9 @@
 import type { ExtensionContext } from "@code-yeongyu/senpi";
+import type { EvalImageContent } from "../tool/image-resize.ts";
+
+/** A notification's message content: plain text, or text and the cells' images in one message. */
+export type EvalNotificationContent = string | ({ readonly type: "text"; readonly text: string } | EvalImageContent)[];
+
 import type { EvalDetachedCellNotification, EvalDetachedCellNotifier } from "../tool/detached-cell-manager.ts";
 
 const NON_INTERACTIVE_MODES = new Set(["print", "json"]);
@@ -11,7 +16,7 @@ export type EvalNotifyMode = "wake" | "next-turn" | "off";
 export interface EvalNotifierDeps {
 	/** Deliver a model-visible notification without rendering synthetic user input. */
 	readonly sendMessage: (
-		message: { customType: string; content: string; display: boolean },
+		message: { customType: string; content: EvalNotificationContent; display: boolean },
 		options: { triggerTurn: boolean; deliverAs: "steer" | "followUp" },
 	) => void;
 	readonly getContext: () => ExtensionContext | undefined;
@@ -43,10 +48,16 @@ export class EvalNotifier implements EvalDetachedCellNotifier {
 		this.#deps.sendMessage(
 			{
 				customType: EVAL_NOTIFICATION_CUSTOM_TYPE,
-				content: pending.map((cell) => cell.content).join("\n\n"),
+				content: notificationContent(pending),
 				display: false,
 			},
 			{ triggerTurn: true, deliverAs: mode === "wake" ? "steer" : "followUp" },
 		);
 	}
 }
+
+function notificationContent(cells: readonly EvalDetachedCellNotification[]): EvalNotificationContent {
+	const text = cells.map((cell) => cell.content).join("\n\n");
+	const images = cells.flatMap((cell) => cell.images ?? []);
+	return images.length === 0 ? text : [{ type: "text", text }, ...images];
+}

package/src/extension/kernel-registration.ts

@@ -63,11 +63,16 @@ export class SessionKernelRegistrations {
 }
 
 export function javaScriptKernelMemory(kernel: JavaScriptKernel): RegisteredKernelSource {
+	const measure = kernel.mode === "process" ? "footprint" : "heap";
 	return {
-		measure: "heap",
+		measure,
 		lastLiveBytes: () => kernel.lastLiveBytes,
 		busy: () => kernel.queueSnapshot().activeCellId !== null,
-		queryMemory: () => kernel.queryMemory(),
+		queryMemory: async () => {
+			const reading = await kernel.queryMemory();
+			return reading === undefined ? undefined : { liveBytes: reading.liveBytes, measure: reading.measure };
+		},
+		...(measure === "footprint" ? { pid: () => kernel.processPid } : {}),
 	};
 }
 

package/src/extension/runtime-factory.ts

@@ -2,12 +2,15 @@ import { type ExtensionContext, withBundledBunCommands } from "@code-yeongyu/sen
 import type { AgentExecuteTool } from "../bridges/agent-bridge.ts";
 import type { EvalSchemaToolInfo } from "../bridges/schema-bridge.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
+import { resolveJsIsolation } from "../config/feature-settings.ts";
+import { withoutUntrustedInterpreter } from "../config/project-trust.ts";
 import {
 	type CodemodeSettings,
 	loadCodemodeSettings,
 	type ResolvedCodemodeSettings,
 	resolveEnabledLanguages,
 } from "../config/settings.ts";
+import { JsEnvironments } from "../environments/js-environments.ts";
 import { PythonEnvironments } from "../environments/python-environments.ts";
 import type { HandleRegistry } from "../handles/handle-registry.ts";
 import {
@@ -15,6 +18,7 @@ import {
 	getInterpreterAvailability,
 	type InterpreterAvailability,
 } from "../interpreters/detect.ts";
+import { processRuntimeInfo } from "../kernels/js/process-worker.ts";
 import { sessionEnvironmentFrom } from "../kernels/session-env.ts";
 import { resolveSessionArtifactsDir } from "../output/streaming-output.ts";
 import type { EnabledEvalLanguages, EvalLanguage, EvalRuntimes } from "../tool/types.ts";
@@ -49,6 +53,7 @@ export type SessionRuntime = {
 	readonly executeTool: AgentExecuteTool;
 	readonly spawns: boolean;
 	readonly pythonEnvironments?: PythonEnvironments;
+	readonly jsEnvironments: JsEnvironments;
 };
 
 export async function createRuntime(
@@ -60,12 +65,25 @@ export async function createRuntime(
 	handles?: HandleRegistry,
 ): Promise<SessionRuntime> {
 	const loaded = await loadCodemodeSettings({ cwd: ctx.cwd });
+	const trusted = withoutUntrustedInterpreter(
+		loaded.settings,
+		loaded.source,
+		ctx.cwd,
+		typeof ctx.isProjectTrusted === "function" ? () => ctx.isProjectTrusted() : undefined,
+	);
 	const settings: ResolvedCodemodeSettings = {
-		...loaded.settings,
-		languages: resolveEnabledLanguages(loaded.settings),
+		...trusted.settings,
+		languages: resolveEnabledLanguages(trusted.settings),
 	};
 	const availability = await getInterpreterAvailability(settings, createInterpreterDetector());
+	const pyReason = availability.py.detected.ok ? undefined : availability.py.detected.reason;
+	reportSettingsProblems(ctx, [
+		...loaded.warnings,
+		...(trusted.warning === undefined ? [] : [trusted.warning]),
+		...(pyReason === undefined ? [] : [pyReason]),
+	]);
 	const enabledLanguages = enabledLanguagesFrom(settings, availability);
+	const jsProcessIsolation = resolveJsIsolation(settings) === "process";
 	const artifacts = resolveSessionArtifactsDir(ctx.sessionManager.getSessionFile());
 	const activeTools = new Set(pi.getActiveTools());
 	const executeTool = createExecuteTool(pi, activeTools);
@@ -74,6 +92,15 @@ export async function createRuntime(
 	const sessionEnv = { ...sessionEnvironmentFrom(ctx), ...bundledBunPathEntry() };
 	const configuredPoolWidth = settings.parallelPoolWidth;
 	const parallelPoolWidth = Number.isFinite(configuredPoolWidth) ? Math.max(1, Math.trunc(configuredPoolWidth)) : 1;
+	const pythonEnvironments =
+		availability.py.detected.ok && enabledLanguages.py
+			? new PythonEnvironments({
+					artifactsDir: artifacts.dir,
+					cwd: ctx.cwd,
+					interpreter: availability.py.detected.path,
+					settings,
+				})
+			: undefined;
 	const manager = await create({
 		sessionId,
 		ownerSessionId: ctx.sessionManager.getSessionId(),
@@ -86,6 +113,7 @@ export async function createRuntime(
 		listTools: () => pi.getAllTools(),
 		complete,
 		...(handles === undefined ? {} : { handles }),
+		...(pythonEnvironments === undefined ? {} : { environments: { python: pythonEnvironments } }),
 	});
 	return {
 		sessionId,
@@ -93,24 +121,34 @@ export async function createRuntime(
 		parallelPoolWidth,
 		manager,
 		enabledLanguages,
-		runtimes: runtimesFromAvailability(availability, jsRuntimeInfo()),
+		runtimes: runtimesFromAvailability(
+			availability,
+			(jsProcessIsolation ? processRuntimeInfo(undefined) : undefined) ??
+				jsRuntimeInfo(process.versions, process.execPath, jsProcessIsolation),
+		),
 		settings,
 		artifactsDir: artifacts.dir,
 		executeTool,
 		spawns: activeTools.has(settings.taskTools.task),
-		...(availability.py.detected.ok && enabledLanguages.py
-			? {
-					pythonEnvironments: new PythonEnvironments({
-						artifactsDir: artifacts.dir,
-						cwd: ctx.cwd,
-						interpreter: availability.py.detected.path,
-						settings,
-					}),
-				}
-			: {}),
+		jsEnvironments: new JsEnvironments({
+			artifactsDir: artifacts.dir,
+			cwd: ctx.cwd,
+			runtime: jsRuntimeInfo().name,
+			env: { ...process.env, ...sessionEnv },
+			settings,
+		}),
+		...(pythonEnvironments === undefined ? {} : { pythonEnvironments }),
 	};
 }
 
+/** Settings problems reach the user: a notice with a UI, otherwise stderr (print and RPC runs). */
+function reportSettingsProblems(ctx: ExtensionContext, problems: readonly string[]): void {
+	for (const problem of problems) {
+		if (ctx.hasUI) ctx.ui.notify(`[senpi-codemode] ${problem}`, "warning");
+		else console.error(`[senpi-codemode] ${problem}`);
+	}
+}
+
 export function createExecuteTool(pi: CodemodeRuntimeAPI, activeTools?: ReadonlySet<string>): AgentExecuteTool {
 	// A cell names tools directly and cannot run tool_search first, so eval opts in to
 	// lazy activation. Eligibility still belongs to the extension that registered the tool.

package/src/extension/runtime-info.ts

@@ -10,10 +10,14 @@ export interface JsRuntimeVersions {
 export function jsRuntimeInfo(
 	versions: JsRuntimeVersions = process.versions,
 	execPath: string = process.execPath,
+	processIsolation = false,
 ): EvalRuntimeInfo {
 	const bun = versions.bun;
-	if (bun !== undefined && bun.length > 0) return { name: "bun", version: bun, path: execPath };
-	return { name: "node", version: versions.node, path: execPath };
+	const base =
+		bun !== undefined && bun.length > 0
+			? { name: "bun", version: bun, path: execPath }
+			: { name: "node", version: versions.node, path: execPath };
+	return processIsolation ? { ...base, isolation: "process" } : base;
 }
 
 /** Short host-line segment, e.g. "node 26.7.0" or "bun 1.4.0". */

package/src/extension/session-cwd.ts

@@ -1,3 +1,4 @@
+import { statSync } from "node:fs";
 import { stat } from "node:fs/promises";
 
 // Only these codes mean the directory is gone or was never one; anything else (EACCES, ELOOP,
@@ -21,15 +22,30 @@ export async function assertSessionCwdAvailable(cwd: string): Promise<void> {
 	try {
 		isDirectory = (await stat(cwd)).isDirectory();
 	} catch (error) {
-		if (
-			error instanceof Error &&
-			"code" in error &&
-			typeof error.code === "string" &&
-			MISSING_DIRECTORY_CODES.has(error.code)
-		) {
-			throw new CodemodeSessionCwdUnavailableError(cwd, error.code);
-		}
-		throw error;
+		throw sessionCwdStatError(cwd, error);
 	}
 	if (!isDirectory) throw new CodemodeSessionCwdUnavailableError(cwd, "not a directory");
 }
+
+/** Warm reuse checks every cell without a filesystem thread-pool round trip. */
+export function assertSessionCwdAvailableSync(cwd: string): void {
+	let isDirectory: boolean;
+	try {
+		isDirectory = statSync(cwd).isDirectory();
+	} catch (error) {
+		throw sessionCwdStatError(cwd, error);
+	}
+	if (!isDirectory) throw new CodemodeSessionCwdUnavailableError(cwd, "not a directory");
+}
+
+function sessionCwdStatError(cwd: string, error: unknown): unknown {
+	if (
+		error instanceof Error &&
+		"code" in error &&
+		typeof error.code === "string" &&
+		MISSING_DIRECTORY_CODES.has(error.code)
+	) {
+		return new CodemodeSessionCwdUnavailableError(cwd, error.code);
+	}
+	return error;
+}

package/src/extension/session-manager-contract.ts

@@ -2,6 +2,7 @@ import type { ExtensionContext } from "@code-yeongyu/senpi";
 import type { EvalSchemaToolInfo } from "../bridges/schema-bridge.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
 import type { CodemodeSettings } from "../config/settings.ts";
+import type { PackagesInstallEnvironments } from "../environments/packages-install.ts";
 import type { HandleRegistry } from "../handles/handle-registry.ts";
 import type { InterpreterAvailability } from "../interpreters/detect.ts";
 import type { SessionEnvironment } from "../kernels/session-env.ts";
@@ -42,4 +43,6 @@ export interface CreateCodemodeSessionManagerOptions {
 	readonly complete: (request: CompletionRequest, ctx: ExtensionContext) => Promise<CompletionResult>;
 	/** The session generation's handle registry; subprocess kernels reach `wait()`/`handle()` through the bridge. */
 	readonly handles?: HandleRegistry;
+	/** The Python environment `packages.install("pip", ...)` reaches from a Python cell over the bridge. */
+	readonly environments?: PackagesInstallEnvironments;
 }

package/src/extension/session-manager.ts

@@ -1,12 +1,15 @@
 import { join } from "node:path";
 import type { ExtensionContext } from "@code-yeongyu/senpi";
+import { readProcessFootprint } from "@code-yeongyu/senpi";
 import { type BridgeServerHandle, startBridgeServer } from "../bridge/http-server.ts";
 import type { KernelToHostMessage } from "../bridge/protocol.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
+import { resolveJsIsolation, resolveKernelToolsEnabled } from "../config/feature-settings.ts";
 import { resolveKernelMemoryThresholds } from "../config/memory-settings.ts";
 import { collectOrphanedChildren } from "../host-sdk.ts";
 import { JavaScriptKernel } from "../kernels/js/context-manager.ts";
 import type { KernelToolsCapability, KernelToolsDescribeResult } from "../kernels/js/kernel-tools-types.ts";
+import type { SessionEnvironment } from "../kernels/session-env.ts";
 import type { KernelLifecycle } from "../kernels/shared/kernel-death.ts";
 import type { EvalKernel, EvalLanguage } from "../tool/types.ts";
 import { type BridgeDispatchContext, dispatchBridgeCompletion } from "./bridge-dispatch.ts";
@@ -21,7 +24,7 @@ import {
 } from "./kernel-registration.ts";
 import type { RegisteredKernelSource } from "./kernel-registry.ts";
 import { ReplaceableKernel } from "./kernel-replacement.ts";
-import { assertSessionCwdAvailable } from "./session-cwd.ts";
+import { assertSessionCwdAvailable, assertSessionCwdAvailableSync } from "./session-cwd.ts";
 import type {
 	BridgeEndpoint,
 	CodemodeSessionManager,
@@ -111,7 +114,7 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 		this.#onMessageRefs.set(language, onMessage);
 		const existing = this.#kernels.get(language);
 		if (existing) {
-			await assertSessionCwdAvailable(this.#options.cwd);
+			assertSessionCwdAvailableSync(this.#options.cwd);
 			return existing;
 		}
 		const pending = this.#kernelCreations.get(language);
@@ -252,6 +255,8 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 			this.#options.localRoots ??
 			(this.#options.artifactsDir ? { local: join(this.#options.artifactsDir, "local") } : undefined);
 		if (language === "js") {
+			const memoryThresholds = resolveKernelMemoryThresholds(this.#options.settings.memory);
+			const processIsolation = resolveJsIsolation(this.#options.settings) === "process";
 			const kernel = new JavaScriptKernel({
 				sessionId: this.#options.sessionId,
 				cwd: this.#options.cwd,
@@ -259,8 +264,13 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 				onMessage,
 				hostToolNames: () => this.#options.listTools?.().map((tool) => tool.name) ?? [],
 				foreignLanguageNames: () => this.#foreignKernelToolNames(),
-				memory: resolveKernelMemoryThresholds(this.#options.settings.memory),
+				memory: memoryThresholds,
 				collectOrphanedChildren,
+				...(processIsolation ? { isolation: "process" as const } : {}),
+				...(processIsolation && memoryThresholds !== undefined
+					? { processMemory: { thresholds: memoryThresholds, readFootprint: readProcessFootprint } }
+					: {}),
+				...(resolveKernelToolsEnabled(this.#options.settings) ? {} : { kernelToolsEnabled: false }),
 				...(this.#options.sessionEnv ? { sessionEnv: this.#options.sessionEnv } : {}),
 				...(localRoots ? { localRoots: { ...localRoots } } : {}),
 				...(this.#options.artifactsDir ? { artifactsDir: this.#options.artifactsDir } : {}),
@@ -276,10 +286,14 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 			...(localRoots ? { localRoots: { ...localRoots } } : {}),
 			...(this.#options.artifactsDir ? { artifactsDir: this.#options.artifactsDir } : {}),
 		};
+		// The Python prelude reads this when a cell defines an @tool; only a disabled setting adds it.
+		const sessionEnv: SessionEnvironment | undefined = resolveKernelToolsEnabled(this.#options.settings)
+			? this.#options.sessionEnv
+			: { ...this.#options.sessionEnv, SENPI_CODEMODE_KERNEL_TOOLS: "0" };
 		const shared = {
 			sessionId: this.#options.sessionId,
 			cwd: this.#options.cwd,
-			...(this.#options.sessionEnv ? { sessionEnv: this.#options.sessionEnv } : {}),
+			...(sessionEnv ? { sessionEnv } : {}),
 			connection,
 			onMessage,
 			...lifecycle,
@@ -297,8 +311,8 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 	/** Only an already running JavaScript kernel can define a colliding name; none is started for this. */
 	#javaScriptKernelToolsDescribe(names: readonly string[]): Promise<KernelToolsDescribeResult> | undefined {
 		const js = this.#kernels.get("js");
-		if (!js || !("describeKernelTools" in js) || typeof js.describeKernelTools !== "function") return undefined;
-		return (js.describeKernelTools as (names: readonly string[]) => Promise<KernelToolsDescribeResult>)(names);
+		if (!js || typeof js.describeKernelTools !== "function") return undefined;
+		return js.describeKernelTools(names);
 	}
 
 	#foreignKernelToolNames(): string[] {

package/src/index.ts

@@ -10,7 +10,7 @@ import {
 	resolveMaxDetachedCells,
 	resolveRunBudgetSeconds,
 } from "./config/settings.ts";
-import { EvalNotifier } from "./extension/eval-notifier.ts";
+import { type EvalNotificationContent, EvalNotifier } from "./extension/eval-notifier.ts";
 import { EVAL_CELLS_STATUS_KEY } from "./extension/eval-status.ts";
 import { EvalStatusTicker } from "./extension/eval-status-ticker.ts";
 import { hostLine, modelIdFrom } from "./extension/host-facts.ts";
@@ -57,7 +57,7 @@ export interface CodemodeExtensionAPI {
 	getActiveTools(): string[];
 	getAllTools(): readonly EvalSchemaToolInfo[];
 	sendMessage(
-		message: { customType: string; content: string; display: boolean },
+		message: { customType: string; content: EvalNotificationContent; display: boolean },
 		options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
 	): void;
 	/** Optional host event bus; a host without one turns extension event emission into a harmless no-op. */
@@ -158,6 +158,7 @@ export default function senpiCodemode(pi: CodemodeExtensionAPI, options: SenpiCo
 					settings: runtime.settings,
 					artifactsDir: runtime.artifactsDir,
 					...(runtime.pythonEnvironments === undefined ? {} : { pythonEnvironments: runtime.pythonEnvironments }),
+					jsEnvironments: runtime.jsEnvironments,
 					cellManager,
 					handles,
 					executionTracker: manager,

package/src/interpreters/detect.ts

@@ -20,6 +20,8 @@ export interface InterpreterDetected {
 
 export interface InterpreterUnavailable {
 	readonly ok: false;
+	/** Why a configured interpreter could not be used; unset when detection simply found none. */
+	readonly reason?: string;
 }
 
 export type InterpreterDetection = InterpreterDetected | InterpreterUnavailable;
@@ -43,6 +45,8 @@ export interface CreateInterpreterDetectorOptions {
 
 export interface InterpreterDetector {
 	detect(language: CodemodeLanguage): Promise<InterpreterDetection>;
+	/** Probes exactly this executable (no PATH candidates, no splitting on spaces). */
+	detectExplicit(path: string): Promise<InterpreterDetection>;
 }
 
 export interface LanguageAvailability {
@@ -74,6 +78,9 @@ export function createInterpreterDetector(options: CreateInterpreterDetectorOpti
 			cache.set(language, pending);
 			return pending;
 		},
+		detectExplicit(path) {
+			return probeExplicit(path, probe);
+		},
 	};
 }
 
@@ -82,7 +89,7 @@ export async function getInterpreterAvailability(
 	detector: InterpreterDetector,
 ): Promise<InterpreterAvailability> {
 	return {
-		py: await availabilityFor("py", settings.languages.py, detector),
+		py: await pythonAvailability(settings, detector),
 		js: await availabilityFor("js", settings.languages.js, detector),
 		rb: await availabilityFor("rb", settings.languages.rb, detector),
 		jl: await availabilityFor("jl", settings.languages.jl, detector),
@@ -100,6 +107,32 @@ async function availabilityFor(
 	};
 }
 
+/** `languages.pyInterpreter`, when set, is the only interpreter Python uses; a path that does not answer makes Python unavailable. */
+async function pythonAvailability(
+	settings: CodemodeSettings,
+	detector: InterpreterDetector,
+): Promise<LanguageAvailability> {
+	const configured = settings.languages.pyInterpreter;
+	if (configured === undefined || !settings.languages.py)
+		return await availabilityFor("py", settings.languages.py, detector);
+	return { enabled: true, detected: await detector.detectExplicit(configured) };
+}
+
+async function probeExplicit(path: string, probe: ExecFileProbe): Promise<InterpreterDetection> {
+	const reason = (detail: string): InterpreterUnavailable => ({
+		ok: false,
+		reason: `languages.pyInterpreter "${path}" ${detail}; Python is unavailable in this session`,
+	});
+	try {
+		const result = await probe(path, ["--version"], { timeoutMs: probeTimeoutMs });
+		const version = parseVersion(`${result.stdout}\n${result.stderr}`);
+		if (version === null) return reason("did not report a Python version");
+		return { ok: true, path, version, resolvedPath: path };
+	} catch (error) {
+		return reason(`could not run (${error instanceof Error ? error.message.split("\n")[0] : String(error)})`);
+	}
+}
+
 async function detectUncached(
 	language: CodemodeLanguage,
 	hostPlatform: NodeJS.Platform,

package/src/kernels/AGENTS.md

@@ -16,6 +16,8 @@ runner/prelude assets).
 | Julia kernel | `jl/kernel.ts` + `jl/prelude.jl`, `jl/runner.jl` |
 | Shared subprocess layer | `shared/subprocess-kernel.ts`, `subprocess-{contract,process,queue,run}.ts`, `runtime-asset.ts` |
 | Session environment | `session-env.ts` (PI_* contract shared by all kernels; mirrors the core bash tool) |
+| JS process isolation | `js/process-worker.ts` (host side), `js/process-entry.js` (child entry), `js/kernel-memory.ts`, `js/control-frames.ts` |
+| Sandbox cells | `sandbox/sandbox-cell.ts` (host executor); `sandbox/vendor/pi-codemode/**` (vendored runtime, see its `VENDORED.md`) |
 
 ## CONVENTIONS
 

package/src/kernels/jl/runner.jl

@@ -16,6 +16,7 @@ include("prelude.jl")
 const senpi_connection = Dict{String, Any}()
 const senpi_write_lock = ReentrantLock()
 global senpi_current_cell = nothing
+global senpi_memory_cell = nothing
 
 function senpi_escape(text::AbstractString)
     out = IOBuffer()
@@ -290,9 +291,7 @@ function senpi_set_connection(value)
     end
 end
 
-const senpi_memory = Ref{Any}(nothing)
-
-const SENPI_MEMORY_INTERNALS = Set([:senpi_current_cell, :senpi_memory, :senpi_connection, :senpi_frame_io, :senpi_stdout_capture, :senpi_stderr_capture, :senpi_protocol_stdin])
+const SENPI_MEMORY_INTERNALS = Set([:senpi_current_cell, :senpi_connection, :senpi_frame_io, :senpi_stdout_capture, :senpi_stderr_capture, :senpi_protocol_stdin])
 
 const SENPI_SIZER_SAMPLE = 1_000
 const SENPI_SIZER_NODE_BUDGET = 5_000
@@ -421,21 +420,6 @@ function senpi_largest_globals(limit::Int)
     end
 end
 
-function senpi_memory_report()
-    try
-        senpi_memory[] === nothing && return nothing
-        # The host reads the interpreter's current footprint and decides on the notice; the runner only
-        # names its largest globals, with a bounded walk, so a cell never pays for an unbounded scan.
-        named = senpi_largest_globals(5)
-        # The host replaces liveBytes with the interpreter footprint it reads itself; only globals is used.
-        report = Dict{String, Any}("liveBytes" => 0, "measure" => "footprint")
-        isempty(named) || (report["globals"] = named)
-        report
-    catch
-        nothing
-    end
-end
-
 function senpi_run_cell(message)
     cell_id = string(get(message, "cellId", ""))
     code = string(get(message, "code", ""))
@@ -452,13 +436,12 @@ function senpi_run_cell(message)
         yield()
         frame = Dict{String, Any}("type" => "result", "cellId" => cell_id, "ok" => true, "durationMs" => round(Int, (time() - started) * 1000))
         value !== nothing && senpi_should_display_result(parsed) && (frame["valueRepr"] = senpi_json(value))
-        memory = senpi_memory_report()
-        memory !== nothing && (frame["memory"] = memory)
         senpi_emit(frame)
     catch error
         senpi_emit(Dict("type" => "result", "cellId" => cell_id, "ok" => false, "error" => senpi_error(error), "durationMs" => round(Int, (time() - started) * 1000)))
     finally
         global senpi_current_cell = nothing
+        global senpi_memory_cell = cell_id
     end
 end
 
@@ -472,10 +455,16 @@ while !eof(SENPI_ORIGINAL_STDIN)
         if kind == "init"
             senpi_emit(Dict("type" => "status", "event" => Dict("op" => "kernel-startup", "stage" => "host-init")))
             senpi_set_connection(get(message, "connection", nothing))
-            senpi_memory[] = get(message, "memory", nothing)
-            senpi_emit(Dict("type" => "ready"))
+            senpi_emit(Dict("type" => "ready", "memoryGlobals" => true))
         elseif kind == "run"
+            global senpi_memory_cell = nothing
             senpi_run_cell(message)
+        elseif kind == "memory-globals"
+            cell_id = get(message, "cellId", nothing)
+            if cell_id == senpi_memory_cell && senpi_current_cell === nothing
+                senpi_emit(Dict("type" => "memory-globals-result", "cellId" => cell_id, "globals" => senpi_largest_globals(5)))
+                global senpi_memory_cell = nothing
+            end
         elseif kind == "close"
             senpi_emit(Dict("type" => "closed"))
             break