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

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);
@@ -93,11 +111,22 @@ 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),
+		jsEnvironments: new JsEnvironments({
+			artifactsDir: artifacts.dir,
+			cwd: ctx.cwd,
+			runtime: jsRuntimeInfo().name,
+			env: { ...process.env, ...sessionEnv },
+			settings,
+		}),
 		...(availability.py.detected.ok && enabledLanguages.py
 			? {
 					pythonEnvironments: new PythonEnvironments({
@@ -111,6 +140,14 @@ export async function createRuntime(
 	};
 }
 
+/** 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-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";
@@ -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,

package/src/index.ts

@@ -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/js/cell-dispatch.ts

@@ -0,0 +1,44 @@
+import type { HostToKernelMessage } from "../../bridge/protocol.ts";
+import type { HostCellExecutor } from "../../tool/types.ts";
+import { inputAtStart } from "../shared/cell-source-at-start.ts";
+import { refusedEntry } from "./host-entries.ts";
+import {
+	type JavaScriptKernelOptions,
+	type JavaScriptRunInput,
+	resolveKernelToolNameSource,
+} from "./kernel-contract.ts";
+import type { LocalModuleLoader } from "./local-module-loader.ts";
+
+export type CellDispatch =
+	| { readonly kind: "host"; readonly host: HostCellExecutor }
+	| { readonly kind: "worker"; readonly frames: readonly HostToKernelMessage[] };
+
+/**
+ * Decides at the cell's turn how it runs: as a host entry (an install, or a turn-time refusal such as an unreadable
+ * `%load` file) or in the worker, with the frames the worker needs (the current kernel-tool names, then the cell).
+ */
+export function dispatchCell(
+	queued: JavaScriptRunInput,
+	loader: LocalModuleLoader,
+	options: Pick<JavaScriptKernelOptions, "hostToolNames" | "foreignLanguageNames">,
+): CellDispatch {
+	const input = inputAtStart(queued);
+	if ("refused" in input) return { kind: "host", host: refusedEntry(input.refused) };
+	if (input.host !== undefined) return { kind: "host", host: input.host };
+	return {
+		kind: "worker",
+		frames: [
+			{
+				type: "kernel-tools-names",
+				hostToolNames: resolveKernelToolNameSource(options.hostToolNames),
+				foreignLanguageNames: resolveKernelToolNameSource(options.foreignLanguageNames),
+			},
+			{
+				type: "run",
+				cellId: input.cellId,
+				code: loader.prepareCell(input.code, input.kernelPreludes, input.sourceFile, input.packageRoot?.()),
+				timeoutMs: input.timeoutMs,
+			},
+		],
+	};
+}

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

@@ -1,20 +1,21 @@
 import type { HostToKernelMessage, KernelToHostMessage } from "../../bridge/protocol.ts";
-import { CHILD_LIFECYCLE_OP, INTERRUPT_ACK_OP } from "../../bridge/reserved.ts";
 import type { KernelInterruptHandle } from "../../tool/types.ts";
-import { inputAtStart } from "../shared/cell-source-at-start.ts";
 import { KernelToolHostPump } from "../shared/kernel-tools-pump.ts";
 import { ActiveCellControl } from "./active-cell-control.ts";
-import { DEFAULT_INTERRUPT_BOUNDS, type WorkerRetirement } from "./interrupt-bounds.ts";
+import { dispatchCell } from "./cell-dispatch.ts";
+import { consumeControlFrame } from "./control-frames.ts";
+import { HostEntries } from "./host-entries.ts";
+import { DEFAULT_INTERRUPT_BOUNDS, JS_INTERRUPT_GRACE_MS, type WorkerRetirement } from "./interrupt-bounds.ts";
 import {
 	assertJavaScriptKernelOpen,
 	type JavaScriptKernelMode,
 	type JavaScriptRunInput,
 	type LifecycleState,
 	type ResultMessage,
-	resolveKernelToolNameSource,
 	type ToolCallMessage,
 } from "./kernel-contract.ts";
-import { type JavaScriptMemoryReading, KernelMemoryBridge } from "./kernel-memory-bridge.ts";
+import { JavaScriptKernelMemory } from "./kernel-memory.ts";
+import type { JavaScriptMemoryReading } from "./kernel-memory-bridge.ts";
 import { kernelToolError } from "./kernel-tools-errors.ts";
 import type {
 	KernelToolsDescribeResult,
@@ -22,10 +23,9 @@ import type {
 	KernelToolsInvokeRequest,
 } from "./kernel-tools-types.ts";
 import { type JavaScriptKernelOptions, LocalModuleLoader } from "./local-module-loader.ts";
-import { JavaScriptRunQueue } from "./run-queue.ts";
+import { JavaScriptRunQueue, type PendingJavaScriptRun } from "./run-queue.ts";
 import { ToolCallQueue } from "./tool-call-queue.ts";
 import { WorkerChildren } from "./worker-children.ts";
-import { crashedResult } from "./worker-host.ts";
 import { WorkerRecovery } from "./worker-recovery.ts";
 import { WorkerSlot } from "./worker-slot.ts";
 
@@ -35,6 +35,15 @@ export type { JavaScriptKernelOptions } from "./local-module-loader.ts";
 export { type JavaScriptWorkerEntryUrlOptions, resolveJsWorkerEntryUrl } from "./worker-startup.ts";
 
 export class JavaScriptKernel {
+	readonly #hostEntries = new HostEntries<PendingJavaScriptRun>({
+		emit: (run, message) => (run.input.onMessage ?? this.#options.onMessage)?.(message),
+		settle: (run, result) => {
+			if (!this.#runs.releaseActive(run)) return;
+			this.#runs.settle(run, result);
+			this.#startNext();
+		},
+		durationMs: (run) => this.#runs.durationMs(run, performance.now()),
+	});
 	readonly #options: JavaScriptKernelOptions;
 	readonly #moduleLoader: LocalModuleLoader;
 	readonly #slot: WorkerSlot;
@@ -48,7 +57,7 @@ export class JavaScriptKernel {
 	);
 	readonly #toolCalls = new ToolCallQueue();
 	readonly #children: WorkerChildren;
-	readonly #memory: KernelMemoryBridge;
+	readonly #memory: JavaScriptKernelMemory;
 	readonly #activeCell: ActiveCellControl;
 	readonly #recovery = new WorkerRecovery({
 		runs: this.#runs,
@@ -67,7 +76,7 @@ export class JavaScriptKernel {
 			recover: () => void this.#recovery.recover(() => Promise.resolve()),
 			clearToolCalls: () => this.#toolCalls.clear(),
 		});
-		this.#memory = new KernelMemoryBridge(options.memory, options.onMemoryCollected);
+		this.#memory = new JavaScriptKernelMemory(options, () => this.#slot.processPid);
 		this.#children = new WorkerChildren(options.collectOrphanedChildren);
 		this.#moduleLoader = new LocalModuleLoader(options);
 		this.#slot = new WorkerSlot(options, {
@@ -81,15 +90,20 @@ export class JavaScriptKernel {
 		return this.#slot.mode;
 	}
 
-	/** The last heap reading the worker sent (a result, an idle collection, a query); none before the first. */
+	/** The kernel process's pid in process mode; none in worker mode or before it starts. */
+	get processPid(): number | undefined {
+		return this.#slot.processPid;
+	}
+
+	/** The last memory reading (a result, an idle collection, a query); none before the first. */
 	get lastLiveBytes(): number | undefined {
 		return this.#memory.lastLiveBytes;
 	}
 
 	/** A heap reading taken between cells without running one; nothing when no worker is live to ask. */
 	async queryMemory(): Promise<JavaScriptMemoryReading | undefined> {
-		if (this.#lifecycle !== "open" || !this.#slot.present || this.#slot.startingUp) return undefined;
-		return await this.#memory.query((message) => this.#slot.postMessage(message));
+		const ready = this.#lifecycle === "open" && this.#slot.present && !this.#slot.startingUp;
+		return await this.#memory.query(ready ? (message) => this.#slot.postMessage(message) : undefined);
 	}
 
 	get kernelToolEvents(): EventTarget {
@@ -129,6 +143,7 @@ export class JavaScriptKernel {
 			const cancelled = this.cancelQueued(cellId, reason);
 			return { stateRetained: Promise.resolve(true), ...(cancelled ? {} : { note: "cell not found" }) };
 		}
+		if (active && this.#hostEntries.abort(active, reason)) return { stateRetained: Promise.resolve(true) };
 		if (!active) {
 			// A worker still stuck in startup is not a healthy idle worker: retiring it is the only recovery.
 			const wedgedInStartup = this.#slot.startingUp;
@@ -163,11 +178,14 @@ export class JavaScriptKernel {
 		if (this.#closePromise) return await this.#closePromise;
 		this.#slot.postMessage({ type: "close" });
 		this.#lifecycle = "closing";
+		const graceMs = this.#options.interruptBounds?.graceMs ?? JS_INTERRUPT_GRACE_MS;
+		const hostEntriesStopped = this.#hostEntries.stopAll("JS kernel closed", graceMs);
 		this.#runs.settleAll("JS kernel closed");
 		this.#kernelTools.rejectAll(kernelToolError("kernel_tool_stale", "JS kernel closed"));
 		this.#toolCalls.clear();
 		const recovery = this.#recovery.inFlight;
 		const closePromise = (async () => {
+			await hostEntriesStopped;
 			if (recovery) await recovery;
 			await this.#terminate();
 		})().finally(() => {
@@ -189,38 +207,26 @@ export class JavaScriptKernel {
 
 	async #ensureReady(): Promise<void> {
 		assertJavaScriptKernelOpen(this.#lifecycle, "run");
-		await this.#slot.ensureReady();
+		try {
+			await this.#slot.ensureReady();
+		} catch (error) {
+			if (this.#options.isolation !== "process") throw error;
+			// Process mode reports a failed start on the waiting cell, never as a rejection of run().
+			if (this.#lifecycle === "open") this.#runs.settleAll(error instanceof Error ? error.message : String(error));
+		}
 	}
 
 	#startNext(): void {
 		if (this.#lifecycle !== "open" || this.#runs.active || !this.#slot.present) return;
 		const next = this.#runs.startNext(performance.now());
 		if (!next) return;
-		const input = inputAtStart(next.input);
-		if ("refused" in input) {
-			this.#runs.releaseActive(next);
-			this.#runs.settle(next, {
-				type: "result",
-				cellId: next.input.cellId,
-				ok: false,
-				error: { message: input.refused },
-				durationMs: 0,
-			});
-			this.#startNext();
+		const dispatch = dispatchCell(next.input, this.#moduleLoader, this.#options);
+		if (dispatch.kind === "host") {
+			this.#hostEntries.start(next, dispatch.host);
 			return;
 		}
 		this.#activeCell.arm(next);
-		this.#slot.postMessage({
-			type: "kernel-tools-names",
-			hostToolNames: resolveKernelToolNameSource(this.#options.hostToolNames),
-			foreignLanguageNames: resolveKernelToolNameSource(this.#options.foreignLanguageNames),
-		});
-		this.#slot.postMessage({
-			type: "run",
-			cellId: next.input.cellId,
-			code: this.#moduleLoader.prepareCell(input.code, input.kernelPreludes, input.sourceFile),
-			timeoutMs: next.input.timeoutMs,
-		});
+		for (const frame of dispatch.frames) this.#slot.postMessage(frame);
 	}
 
 	async #restartAfterStop(): Promise<void> {
@@ -229,15 +235,7 @@ export class JavaScriptKernel {
 
 	#handleMessage(message: KernelToHostMessage): void {
 		if (this.#kernelTools.consume(message) && message.type !== "tool-call") return;
-		if (this.#memory.consume(message)) return;
-		if (message.type === "status" && message.event.op === INTERRUPT_ACK_OP) {
-			this.#runs.acknowledgeInterrupt(message.event);
-			return;
-		}
-		if (message.type === "status" && message.event.op === CHILD_LIFECYCLE_OP) {
-			this.#children.track(message.event);
-			return;
-		}
+		if (consumeControlFrame(message, { memory: this.#memory, runs: this.#runs, children: this.#children })) return;
 		(this.#runs.active?.input.onMessage ?? this.#options.onMessage)?.(message);
 		if (message.type === "tool-call") {
 			this.#toolCalls.push(message);
@@ -260,13 +258,10 @@ export class JavaScriptKernel {
 		if (!active && this.#slot.startingUp) return;
 		this.#activeCell.disarm();
 		this.#kernelTools.rejectAll(kernelToolError("kernel_tool_stale", error.message));
-		this.#memory.workerLost(error);
-		if (active) {
-			this.#runs.releaseActive(active);
-			this.#runs.settle(
-				active,
-				crashedResult(active.input.cellId, error, this.#runs.durationMs(active, performance.now())),
-			);
+		this.#memory.crashed(error);
+		// A crash mid-install stops the install (process group killed, nothing published); it settles itself once stopped.
+		if (active && !this.#hostEntries.abort(active, `JavaScript worker crashed: ${error.message}`)) {
+			this.#runs.settleCrashed(active, error);
 		}
 		this.#toolCalls.clear();
 		void this.#restartAfterStop();

package/src/kernels/js/control-frames.ts

@@ -0,0 +1,24 @@
+import type { KernelToHostMessage } from "../../bridge/protocol.ts";
+import { CHILD_LIFECYCLE_OP, INTERRUPT_ACK_OP } from "../../bridge/reserved.ts";
+import type { JavaScriptKernelMemory } from "./kernel-memory.ts";
+import type { JavaScriptRunQueue } from "./run-queue.ts";
+import type { WorkerChildren } from "./worker-children.ts";
+
+export interface ControlFrameOwners {
+	readonly memory: Pick<JavaScriptKernelMemory, "consume">;
+	readonly runs: Pick<JavaScriptRunQueue, "acknowledgeInterrupt">;
+	readonly children: Pick<WorkerChildren, "track">;
+}
+
+/** Routes a worker's side-channel frames (memory readings, interrupt acks, child lifecycle) to their owners. */
+export function consumeControlFrame(message: KernelToHostMessage, owners: ControlFrameOwners): boolean {
+	if (owners.memory.consume(message)) return true;
+	if (message.type !== "status") return false;
+	if (message.event.op === INTERRUPT_ACK_OP) {
+		owners.runs.acknowledgeInterrupt(message.event);
+		return true;
+	}
+	if (message.event.op !== CHILD_LIFECYCLE_OP) return false;
+	owners.children.track(message.event);
+	return true;
+}

package/src/kernels/js/host-entries.ts

@@ -0,0 +1,62 @@
+import type { KernelToHostMessage } from "../../bridge/protocol.ts";
+import type { HostCellExecutor } from "../../tool/types.ts";
+import { runHostCell } from "../shared/host-cell.ts";
+import type { ResultMessage } from "./kernel-contract.ts";
+
+export interface HostEntryKernel<Run> {
+	emit(run: Run, message: KernelToHostMessage): void;
+	settle(run: Run, result: ResultMessage): void;
+	durationMs(run: Run): number;
+}
+
+/** The host entries (installs) a JavaScript kernel is running: started per queue slot, stopped by interrupt and close. */
+export class HostEntries<Run extends { readonly input: { readonly cellId: string } }> {
+	readonly #aborts = new Map<Run, AbortController>();
+	readonly #done = new Map<Run, Promise<unknown>>();
+	readonly #kernel: HostEntryKernel<Run>;
+
+	constructor(kernel: HostEntryKernel<Run>) {
+		this.#kernel = kernel;
+	}
+
+	/** Runs `host` for `run`'s queue slot; it holds the slot like a cell but never reaches the worker. */
+	start(run: Run, host: HostCellExecutor): void {
+		const entry = runHostCell(run.input.cellId, host, {
+			emit: (message) => this.#kernel.emit(run, message),
+			settle: (result) => {
+				this.#aborts.delete(run);
+				this.#kernel.settle(run, result);
+			},
+			durationMs: () => this.#kernel.durationMs(run),
+			settleAfterAbort: true,
+		});
+		this.#aborts.set(run, entry.abort);
+		this.#done.set(run, entry.done);
+		void entry.done.finally(() => this.#done.delete(run));
+	}
+
+	/** Aborts `run`'s host entry; false when `run` is not one. */
+	abort(run: Run, reason: string): boolean {
+		const abort = this.#aborts.get(run);
+		if (abort === undefined) return false;
+		abort.abort(new Error(reason));
+		return true;
+	}
+
+	/** Aborts every running entry and waits for them to stop, at most `ms`: a closed kernel leaves no install running. */
+	async stopAll(reason: string, ms: number): Promise<void> {
+		const running = [...this.#done.values()];
+		for (const abort of this.#aborts.values()) abort.abort(new Error(reason));
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		await Promise.race([
+			Promise.allSettled(running),
+			new Promise<void>((resolve) => (timer = setTimeout(resolve, ms))),
+		]);
+		if (timer !== undefined) clearTimeout(timer);
+	}
+}
+
+/** A turn-time refusal (an unreadable `%load` file, a refused magic) settles in queue order as a failed host entry. */
+export function refusedEntry(message: string): HostCellExecutor {
+	return async () => ({ ok: false, error: { message } });
+}

package/src/kernels/js/kernel-contract.ts

@@ -7,7 +7,7 @@ import type { JavaScriptInterruptBounds } from "./interrupt-bounds.ts";
 export type ResultMessage = Extract<KernelToHostMessage, { type: "result" }>;
 export type ToolCallMessage = Extract<KernelToHostMessage, { type: "tool-call" }>;
 
-export type JavaScriptKernelMode = "worker" | "inline";
+export type JavaScriptKernelMode = "worker" | "inline" | "process";
 
 /** Snapshot or live provider consulted when the worker registry checks collisions. */
 export type KernelToolNameSource = readonly string[] | (() => readonly string[]);
@@ -30,8 +30,23 @@ export interface JavaScriptKernelOptions {
 	readonly workerEntryUrl?: URL;
 	/** Per-session PI_* values applied to the worker environment before the first cell runs. */
 	readonly sessionEnv?: SessionEnvironment;
+	/** Opt-in child-process kernel; absent keeps the worker-thread kernel. */
+	readonly isolation?: "process";
+	/** Resolution root for the process-mode runtime (bun, then node); `""` names a machine with none on PATH. */
+	readonly processCommandPath?: string;
+	/** The host's executable, which runs the child when it is bun or node; defaults to `process.execPath`. */
+	readonly processExecPath?: string;
+	/** How long a process-mode child gets to report ready; defaults to `PROCESS_STARTUP_DEADLINE_MS`. */
+	readonly processStartupDeadlineMs?: number;
+	/** Process-mode memory policy: the host reads the child's footprint instead of the in-heap worker reading. */
+	readonly processMemory?: {
+		readonly thresholds: KernelMemoryThresholds;
+		readonly readFootprint?: (pid: number) => { readonly bytes: number } | undefined;
+	};
 	/** Host tool names denied as JS kernel-tool identifiers (init protocol). */
 	readonly hostToolNames?: KernelToolNameSource;
+	/** `kernelTools.enabled`; false makes `tool(fn)` refuse with `tools_unavailable`. Unset keeps them on. */
+	readonly kernelToolsEnabled?: boolean;
 	/** Tool names registered in another kernel language, denied as JS kernel-tool identifiers. */
 	readonly foreignLanguageNames?: KernelToolNameSource;
 	/** Post-cell collection, notice, and ceiling thresholds; absent leaves the worker's memory unmanaged. */

package/src/kernels/js/kernel-memory-bridge.ts

@@ -6,7 +6,7 @@ import type { ResultMessage } from "./kernel-contract.ts";
 
 export interface JavaScriptMemoryReading {
 	readonly liveBytes: number;
-	readonly measure: "heap";
+	readonly measure: "heap" | "footprint";
 }
 
 /** A query waits at most this long: the worker answers between cells, never inside one. */