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

package/src/kernels/js/process-worker.ts

@@ -0,0 +1,298 @@
+import { execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { accessSync, constants } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import type { KernelToHostMessage } from "../../bridge/protocol.ts";
+import { isKernelToHostMessage, parseBridgeJsonLine, validateBridgeMessage } from "../../bridge/protocol.ts";
+import type { EvalRuntimeInfo } from "../../tool/types.ts";
+import { type CodemodeRuntimeAssetEnvironment, requireCodemodeRuntimeAsset } from "../shared/runtime-asset.ts";
+import { type SubprocessLike, SubprocessProcess, spawnSubprocess } from "../shared/subprocess-process.ts";
+import type { WorkerLike } from "./inline-worker.ts";
+import { JavaScriptWorkerExitedError } from "./worker-host.ts";
+
+const PROCESS_CLOSE_GRACE_MS = 2_000;
+
+export interface JavaScriptProcessEntryUrlOptions extends CodemodeRuntimeAssetEnvironment {
+	readonly localPath?: string;
+}
+
+export function resolveJsProcessEntryUrl(options: JavaScriptProcessEntryUrlOptions = {}): URL {
+	const localPath = options.localPath ?? join(dirname(fileURLToPath(import.meta.url)), "process-entry.js");
+	return pathToFileURL(requireCodemodeRuntimeAsset(localPath, join("kernels", "js", "process-entry.js"), options));
+}
+
+export class JavaScriptProcessRuntimeUnavailableError extends Error {
+	readonly name = "JavaScriptProcessRuntimeUnavailableError";
+	readonly runtime: string;
+	readonly searchPath: string;
+
+	constructor(runtime: string, searchPath: string) {
+		super(
+			`JavaScript runtime is unavailable: no ${runtime} executable found on PATH${searchPath.length === 0 ? " (empty)" : ""}. Install bun or node, or use isolation.js: "worker".`,
+		);
+		this.runtime = runtime;
+		this.searchPath = searchPath;
+	}
+}
+
+export interface JavaScriptProcessWorkerOptions {
+	readonly cwd: string;
+	readonly parallelPoolWidth: number;
+	readonly searchPath?: string;
+	readonly execPath?: string;
+	readonly env?: NodeJS.ProcessEnv;
+	readonly spawn?: (
+		command: string,
+		args: readonly string[],
+		options: { cwd?: string; env?: NodeJS.ProcessEnv },
+	) => SubprocessLike;
+}
+
+export interface JavaScriptProcessWorker extends WorkerLike {
+	readonly pid?: number;
+}
+
+/**
+ * The runtime that runs the kernel child: the host's own runtime (bun when senpi runs on Bun, node otherwise), taken
+ * from the host's executable when that is the runtime itself, else found on PATH, the host's runtime first.
+ */
+export function resolveJavaScriptProcessCommand(
+	searchPath: string | undefined,
+	platform: NodeJS.Platform = process.platform,
+	hostRuntime: string = process.versions.bun === undefined ? "node" : "bun",
+	execPath: string = process.execPath,
+): string {
+	const candidates = hostRuntime === "bun" ? ["bun", "node"] : ["node", "bun"];
+	const extensions = platform === "win32" ? [".exe", ".cmd", ".bat", ""] : [""];
+	if (runtimeNameOf(execPath) !== undefined && isExecutable(execPath)) return execPath;
+	const pathValue = searchPath ?? process.env.PATH ?? "";
+	if (pathValue.trim().length === 0) throw new JavaScriptProcessRuntimeUnavailableError(hostRuntime, "");
+	const directories = pathValue.split(platform === "win32" ? ";" : ":").filter((directory) => directory.length > 0);
+	for (const name of candidates) {
+		for (const directory of directories) {
+			for (const extension of extensions) {
+				const candidate = join(directory, `${name}${extension}`);
+				if (isExecutable(candidate)) return candidate;
+			}
+		}
+	}
+	throw new JavaScriptProcessRuntimeUnavailableError(hostRuntime, pathValue);
+}
+
+/**
+ * The badge identity of the child a process-mode kernel runs: the host's own identity when the child is the host's
+ * executable, else the resolved runtime with the version it reports. Undefined when no runtime resolves (the kernel
+ * then reports the capability gap on its first cell).
+ */
+export function processRuntimeInfo(searchPath: string | undefined): EvalRuntimeInfo | undefined {
+	let command: string;
+	try {
+		command = resolveJavaScriptProcessCommand(searchPath);
+	} catch (error) {
+		if (error instanceof JavaScriptProcessRuntimeUnavailableError) return undefined;
+		throw error;
+	}
+	const name = runtimeNameOf(command);
+	if (command === process.execPath || name === undefined) return undefined;
+	const version = execFileSync(command, ["--version"], { encoding: "utf8", timeout: 5_000 }).trim().replace(/^v/, "");
+	return { name, version, path: command, isolation: "process" };
+}
+
+/** "bun" or "node" from an executable path; undefined for anything else (a compiled senpi binary, for one). */
+export function runtimeNameOf(command: string): "bun" | "node" | undefined {
+	const name = basename(command).replace(/\.(exe|cmd|bat)$/i, "");
+	return name === "bun" || name === "node" ? name : undefined;
+}
+
+function isExecutable(path: string): boolean {
+	try {
+		accessSync(path, constants.X_OK);
+		return true;
+	} catch (error) {
+		if (
+			error instanceof Error &&
+			"code" in error &&
+			(error.code === "ENOENT" || error.code === "EACCES" || error.code === "ENOTDIR")
+		) {
+			return false;
+		}
+		throw error;
+	}
+}
+
+export function spawnProcessWorker(url: URL, options: JavaScriptProcessWorkerOptions): JavaScriptProcessWorker {
+	const command = resolveJavaScriptProcessCommand(options.searchPath, process.platform, undefined, options.execPath);
+	const isBun = runtimeNameOf(command) === "bun";
+	const args = isBun ? [fileURLToPath(url)] : ["--experimental-strip-types", fileURLToPath(url)];
+	const env: NodeJS.ProcessEnv = {
+		...process.env,
+		...options.env,
+		SENPI_CODEMODE_PROCESS_CWD: options.cwd,
+		SENPI_CODEMODE_PROCESS_POOL_WIDTH: String(options.parallelPoolWidth),
+	};
+	const child =
+		options.spawn === undefined
+			? spawnSubprocess(undefined, { command, args, cwd: options.cwd, env })
+			: options.spawn(command, args, { cwd: options.cwd, env });
+	const messageHandlers = new Set<(message: KernelToHostMessage) => void>();
+	const errorHandlers = new Set<(error: Error) => void>();
+	const frameToken = randomBytes(16).toString("hex");
+	const framePrefix = `${frameToken} `;
+	let crashCause: Error | undefined;
+	let stderrTail = "";
+	// A line that fails to parse may be the end of a frame a dying child was writing; it is reported only once the
+	// channel carries on, so the crash cause or the exit itself, not "invalid frame", settles the cell.
+	let pendingInvalidFrame: Error | undefined;
+	const reportPendingInvalidFrame = () => {
+		const error = pendingInvalidFrame;
+		pendingInvalidFrame = undefined;
+		if (error !== undefined) for (const handler of [...errorHandlers]) handler(error);
+	};
+	// Attached directly, not through SubprocessProcess, which stops reading stderr as soon as the exit is observed.
+	child.stderr.on("data", (chunk: string | Buffer) => {
+		stderrTail = `${stderrTail}${String(chunk)}`.slice(-STDERR_TAIL_CHARS);
+		const crash = crashCauseFrom(stderrTail, frameToken);
+		if (crash !== undefined) crashCause = crash;
+	});
+	const subprocess = new SubprocessProcess(child, {
+		onLine: (_process, line) => {
+			// Only a line carrying this process's token is a frame; any other line is output that
+			// reached the channel (a raw fd write, a child process) and is delivered as text.
+			if (!line.startsWith(framePrefix)) {
+				if (line.trim().length === 0) return;
+				reportPendingInvalidFrame();
+				for (const handler of [...messageHandlers]) handler({ type: "text", stream: "stdout", data: line });
+				return;
+			}
+			const parsed = decodeProcessFrame(line.slice(framePrefix.length), frameToken);
+			if (!parsed.ok) {
+				reportPendingInvalidFrame();
+				pendingInvalidFrame = new Error(
+					`JavaScript kernel process emitted an invalid frame: ${parsed.error.message}`,
+				);
+				return;
+			}
+			reportPendingInvalidFrame();
+			const message = parsed.message;
+			if (!isKernelToHostMessage(message)) return;
+			for (const handler of [...messageHandlers]) handler(message);
+		},
+		// Crash causes are read by the listener below, which stays attached until stderr ends.
+		onStderr: () => {},
+		onExit: (_process, code, signal) => {
+			pendingInvalidFrame = undefined;
+			// A dead child's last stderr bytes can still be in flight when its exit is observed: settle once stderr has
+			// ended (bounded), so the cause it reported is not replaced by the bare exit.
+			void stderrEnded(child.stderr, STDERR_DRAIN_GRACE_MS).then(() => {
+				// The child's own report of what killed it, as worker mode reports a thread's error; else the exit itself.
+				const error = crashCause ?? new JavaScriptWorkerExitedError(code ?? -1, signal);
+				for (const handler of [...errorHandlers]) handler(error);
+			});
+		},
+		onError: (_process, error) => {
+			for (const handler of [...errorHandlers]) handler(error);
+		},
+	});
+	// The token is the first line the entry reads, before any cell can run.
+	subprocess.send(`${frameToken}\n`);
+	return {
+		mode: "process",
+		get pid() {
+			return child.pid;
+		},
+		postMessage(message) {
+			subprocess.send(`${JSON.stringify(message)}\n`);
+		},
+		onMessage(handler) {
+			messageHandlers.add(handler);
+			return () => {
+				messageHandlers.delete(handler);
+			};
+		},
+		onError(handler) {
+			errorHandlers.add(handler);
+			return () => {
+				errorHandlers.delete(handler);
+			};
+		},
+		async terminate() {
+			const exited = await subprocess.shutdown(`${JSON.stringify({ type: "close" })}\n`);
+			if (!exited) await subprocess.terminate("SIGKILL", PROCESS_CLOSE_GRACE_MS);
+		},
+	};
+}
+
+const STDERR_TAIL_CHARS = 16 * 1024;
+const STDERR_DRAIN_GRACE_MS = 1_000;
+
+/** Resolves when the stream has ended or closed, or after the grace period, whichever comes first. */
+function stderrEnded(stream: NodeJS.ReadableStream, graceMs: number): Promise<void> {
+	if (("readableEnded" in stream && stream.readableEnded === true) || ("closed" in stream && stream.closed === true)) {
+		return Promise.resolve();
+	}
+	return new Promise((resolve) => {
+		const done = () => {
+			clearTimeout(timer);
+			stream.removeListener("end", done);
+			stream.removeListener("close", done);
+			resolve();
+		};
+		const timer = setTimeout(done, graceMs);
+		stream.once("end", done);
+		stream.once("close", done);
+	});
+}
+const BIGINT_MARKER = "\u0000senpi:bigint:";
+const UNDEFINED_MARKER = "\u0000senpi:undefined:";
+const BIGINT_DIGITS = /^-?\d+$/;
+
+/**
+ * A frame's `BigInt` and `undefined` values travel as markers (see process-entry.js `replacer`). They are revived
+ * before the frame is checked against the bridge schema: an optional field the child left `undefined` (a cell whose
+ * value is `undefined` has no `valueRepr`) arrives as a marker, and checked as-is it would fail the schema.
+ */
+function decodeProcessFrame(line: string, token: string): ReturnType<typeof validateBridgeMessage> {
+	const parsed = parseBridgeJsonLine(line);
+	if (!parsed.ok) return parsed;
+	const value = parsed.value;
+	if (typeof value === "object" && value !== null) reviveFrameValues(value, token);
+	return validateBridgeMessage(value);
+}
+
+/** The cause the child reported on stderr just before exiting (see process-entry.js `reportCrash`). */
+function crashCauseFrom(stderr: string, token: string): Error | undefined {
+	const prefix = `senpi-kernel-crash ${token} `;
+	const line = stderr.split("\n").find((candidate) => candidate.startsWith(prefix));
+	if (line === undefined) return undefined;
+	try {
+		const cause: unknown = JSON.parse(line.slice(prefix.length));
+		if (typeof cause !== "object" || cause === null || !("message" in cause) || typeof cause.message !== "string") {
+			return undefined;
+		}
+		const error = new Error(cause.message);
+		if ("name" in cause && typeof cause.name === "string") error.name = cause.name;
+		return error;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Turns the child's markers back, in place, into the values JSON cannot carry (a BigInt, an `undefined` property or
+ * element), so a frame matches what worker mode's structured clone delivers. A marker carries this child's frame
+ * token, so a cell's own data that merely looks like one is delivered as it is.
+ */
+function reviveFrameValues(container: object, token: string): void {
+	const bigintKey = `${BIGINT_MARKER}${token}`;
+	const undefinedKey = `${UNDEFINED_MARKER}${token}`;
+	for (const key of Object.keys(container)) {
+		const value: unknown = Reflect.get(container, key);
+		if (typeof value !== "object" || value === null) continue;
+		const keys = Object.keys(value);
+		const digits: unknown = keys.length === 1 && keys[0] === bigintKey ? Reflect.get(value, bigintKey) : undefined;
+		if (typeof digits === "string" && BIGINT_DIGITS.test(digits)) Reflect.set(container, key, BigInt(digits));
+		else if (keys.length === 1 && keys[0] === undefinedKey) Reflect.set(container, key, undefined);
+		else reviveFrameValues(value, token);
+	}
+}

package/src/kernels/js/run-queue.ts

@@ -1,5 +1,6 @@
 import type { EvalStatusEvent, KernelToHostMessage } from "../../bridge/protocol.ts";
 import type { JavaScriptRunInput } from "./kernel-contract.ts";
+import { crashedResult } from "./worker-host.ts";
 
 type ResultMessage = Extract<KernelToHostMessage, { type: "result" }>;
 
@@ -83,6 +84,12 @@ export class JavaScriptRunQueue {
 		return Math.max(0, Math.round(finishedAtMs - run.startedAtMs));
 	}
 
+	/** Settles `run` as crashed with `error`: the worker died under it. */
+	settleCrashed(run: PendingJavaScriptRun, error: Error): void {
+		this.releaseActive(run);
+		this.settle(run, crashedResult(run.input.cellId, error, this.durationMs(run, performance.now())));
+	}
+
 	releaseActive(run: PendingJavaScriptRun): boolean {
 		if (this.#active !== run) return false;
 		this.#active = null;

package/src/kernels/js/worker-core.js

@@ -128,7 +128,7 @@ export function createWorkerCore(transport, options) {
 		}
 		if (message.type === "init") {
 			applySessionEnvironment(message.sessionEnv);
-			installSessionCwd(options.cwd);
+			installSessionCwd(options.cwd, options.cwdInstallOptions);
 			installKernelWebView(requestWebViewPort);
 			installPackageResolver();
 			runtime = new JsWorkerRuntime({
@@ -145,7 +145,9 @@ export function createWorkerCore(transport, options) {
 					if (activeCell?.interruption) acknowledgeInterrupt();
 				},
 			});
-			if (message.memory) {
+			// A process-mode kernel measures its memory host-side as a footprint; the in-heap
+			// worker reading would contradict it, so the child keeps memory collection off.
+			if (message.memory && !options.processModeMemory) {
 				memory = createWorkerMemory(message.memory, (report) => emit({ type: "status", event: { op: MEMORY_COLLECTED_OP, ...report } }));
 				memory.captureBaseline();
 			}

package/src/kernels/js/worker-cwd.js

@@ -52,8 +52,11 @@ const FS_PATH_ARGS = {
 const CHILD_PROCESS_FILE_ARGS = ["spawn", "spawnSync", "execFile", "execFileSync", "fork"];
 const CHILD_PROCESS_COMMAND_ARGS = ["exec", "execSync"];
 
-export function installSessionCwd(cwd) {
-	if (isMainThread) throw new Error("installSessionCwd must only run inside a kernel worker thread");
+export function installSessionCwd(cwd, options) {
+	// A process-mode kernel child IS the main thread; the worker guard relaxes only for that entry.
+	if (isMainThread && options?.allowMainThread !== true) {
+		throw new Error("installSessionCwd must only run inside a kernel worker thread");
+	}
 	const root = resolve(cwd);
 	const rootBytes = Buffer.from(root.endsWith(sep) ? root : `${root}${sep}`);
 	// fs also takes Buffer/Uint8Array paths; a relative one gets the session root prepended as bytes,

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

@@ -1,6 +1,7 @@
 import type { EventEmitter } from "node:events";
 import { Worker } from "node:worker_threads";
 import type { KernelToHostMessage } from "../../bridge/protocol.ts";
+import { describeExit } from "../shared/kernel-death.ts";
 import type { WorkerLike } from "./inline-worker.ts";
 import type { JavaScriptKernelMode } from "./kernel-contract.ts";
 
@@ -22,10 +23,16 @@ export class WorkerStartupCancelledError extends Error {
 export class JavaScriptWorkerExitedError extends Error {
 	readonly name = "JavaScriptWorkerExitedError";
 	readonly exitCode: number;
+	readonly exitSignal: string | null;
 
-	constructor(exitCode: number) {
-		super(`JavaScript worker exited with code ${exitCode}`);
+	constructor(exitCode: number, exitSignal: string | null = null) {
+		super(
+			exitSignal === null
+				? `JavaScript worker exited with code ${exitCode}`
+				: `JavaScript worker exited with ${describeExit(null, exitSignal)} (code ${exitCode})`,
+		);
 		this.exitCode = exitCode;
+		this.exitSignal = exitSignal;
 	}
 }
 

package/src/kernels/js/worker-slot.ts

@@ -4,6 +4,7 @@ import type { WorkerLike } from "./inline-worker.ts";
 import { retireWorker, type WorkerRetirement } from "./interrupt-bounds.ts";
 import type { JavaScriptKernelMode } from "./kernel-contract.ts";
 import type { JavaScriptKernelOptions } from "./local-module-loader.ts";
+import type { JavaScriptProcessWorker } from "./process-worker.ts";
 import { KernelWebViewClients } from "./webview-host.ts";
 import { WorkerStartupCancelledError } from "./worker-host.ts";
 import { startWorkerWithInlineFallback } from "./worker-startup.ts";
@@ -19,6 +20,7 @@ export class WorkerSlot {
 	readonly #options: JavaScriptKernelOptions;
 	readonly #listeners: WorkerSlotListeners;
 	#worker: WorkerLike | null = null;
+	#lastProcessPid: number | undefined;
 	#webViews: KernelWebViewClients | null = null;
 	#mode: JavaScriptKernelMode = "worker";
 	#generation = 0;
@@ -34,6 +36,12 @@ export class WorkerSlot {
 		return this.#mode;
 	}
 
+	get processPid(): number | undefined {
+		const worker = this.#worker;
+		if (worker?.mode === "process") return (worker as JavaScriptProcessWorker).pid;
+		return this.#lastProcessPid;
+	}
+
 	get present(): boolean {
 		return this.#worker !== null;
 	}
@@ -105,6 +113,7 @@ export class WorkerSlot {
 	#publish(worker: WorkerLike, generation: number): void {
 		if (!this.#listeners.isOpen() || generation !== this.#generation) throw new WorkerStartupCancelledError();
 		this.#worker = worker;
+		if (worker.mode === "process") this.#lastProcessPid = (worker as JavaScriptProcessWorker).pid;
 		const webViews = new KernelWebViewClients((message, transfer) => worker.postMessage(message, transfer));
 		this.#webViews = webViews;
 		worker.onMessage((message) => {

package/src/kernels/js/worker-startup.ts

@@ -2,8 +2,10 @@ import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { type CodemodeRuntimeAssetEnvironment, requireCodemodeRuntimeAsset } from "../shared/runtime-asset.ts";
 import { createInlineWorker, type WorkerLike } from "./inline-worker.ts";
+import { retireWorker } from "./interrupt-bounds.ts";
 import { resolveKernelToolNameSource } from "./kernel-contract.ts";
 import { type JavaScriptKernelOptions, localBridgeConnection } from "./local-module-loader.ts";
+import { resolveJsProcessEntryUrl, spawnProcessWorker } from "./process-worker.ts";
 import { spawnNodeWorker, WorkerStartupCancelledError, waitForReady } from "./worker-host.ts";
 
 export interface JavaScriptWorkerEntryUrlOptions extends CodemodeRuntimeAssetEnvironment {
@@ -15,6 +17,21 @@ export function resolveJsWorkerEntryUrl(options: JavaScriptWorkerEntryUrlOptions
 	return pathToFileURL(requireCodemodeRuntimeAsset(localPath, join("kernels", "js", "worker-entry.js"), options));
 }
 
+/**
+ * How long a process-mode kernel child gets to report ready. A child that a starved host never schedules would
+ * otherwise hold every queued cell forever: no cell's own timeout is armed until the kernel is up.
+ */
+export const PROCESS_STARTUP_DEADLINE_MS = 30_000;
+
+export class ProcessKernelStartupTimeoutError extends Error {
+	constructor(deadlineMs: number) {
+		super(
+			`JavaScript kernel process did not become ready within ${deadlineMs / 1000}s; it was stopped, and the next cell starts a fresh one`,
+		);
+		this.name = "ProcessKernelStartupTimeoutError";
+	}
+}
+
 export interface WorkerStartupHooks {
 	readonly options: JavaScriptKernelOptions;
 	readonly kernelGeneration: number;
@@ -36,6 +53,13 @@ export async function startWorkerWithInlineFallback(hooks: WorkerStartupHooks, s
 			await worker.terminate();
 			throw new WorkerStartupCancelledError();
 		}
+		// Process mode never falls back: the user asked for isolation, so a failed start stays visible. The child that
+		// failed to start is stopped (bounded), so a stuck one is not left behind.
+		if (worker.mode === "process") {
+			hooks.retire(worker);
+			await retireWorker(worker);
+			throw error;
+		}
 		if (worker.mode === "inline") throw error;
 		hooks.retire(worker);
 		await worker.terminate();
@@ -47,6 +71,15 @@ export async function startWorkerWithInlineFallback(hooks: WorkerStartupHooks, s
 }
 
 function spawnWorker(options: JavaScriptKernelOptions): WorkerLike {
+	if (options.isolation === "process") {
+		const url = resolveJsProcessEntryUrl();
+		return spawnProcessWorker(url, {
+			cwd: options.cwd,
+			parallelPoolWidth: options.parallelPoolWidth,
+			...(options.processCommandPath === undefined ? {} : { searchPath: options.processCommandPath }),
+			...(options.processExecPath === undefined ? {} : { execPath: options.processExecPath }),
+		});
+	}
 	try {
 		const url = options.workerEntryUrl ?? resolveJsWorkerEntryUrl();
 		return spawnNodeWorker(url, options.cwd, options.parallelPoolWidth);
@@ -57,7 +90,10 @@ function spawnWorker(options: JavaScriptKernelOptions): WorkerLike {
 }
 
 async function initializeWorker(worker: WorkerLike, hooks: WorkerStartupHooks, signal: AbortSignal): Promise<void> {
-	const ready = waitForReady(worker, signal);
+	const ready =
+		worker.mode === "process"
+			? withStartupDeadline(waitForReady(worker, signal), hooks.options)
+			: waitForReady(worker, signal);
 	const options = hooks.options;
 	worker.postMessage({
 		type: "init",
@@ -72,3 +108,14 @@ async function initializeWorker(worker: WorkerLike, hooks: WorkerStartupHooks, s
 	});
 	await ready;
 }
+
+function withStartupDeadline(ready: Promise<void>, options: JavaScriptKernelOptions): Promise<void> {
+	const deadlineMs = options.processStartupDeadlineMs ?? PROCESS_STARTUP_DEADLINE_MS;
+	let timer: NodeJS.Timeout | undefined;
+	const expired = new Promise<never>((_resolve, reject) => {
+		timer = setTimeout(() => reject(new ProcessKernelStartupTimeoutError(deadlineMs)), deadlineMs);
+	});
+	// When the deadline wins, the stopped child's readiness promise rejects later; that outcome is already reported.
+	ready.catch(() => {});
+	return Promise.race([ready, expired]).finally(() => clearTimeout(timer));
+}

package/src/kernels/js/worker-webview.js

@@ -5,6 +5,7 @@ import { DELIVER_EVENT, WebViewPortClient, webViewError } from "./worker-webview
 // `Bun` parameter bound to a stand-in whose `WebView` forwards Chrome-backed views to the
 // main-thread service over a private port; every other `Bun.*` member is the real one.
 const KERNEL_BUN = Symbol.for("senpi.kernel.bun");
+const KERNEL_PROCESS_MODE = Symbol.for("senpi.kernel.processMode");
 
 export function bindKernelBun(source) {
 	if (!globalThis[KERNEL_BUN]) return source;
@@ -17,6 +18,10 @@ export function installKernelWebView(requestPort) {
 	globalThis[KERNEL_BUN] = shadowBun(bun, createKernelWebView(bun.WebView, requestPort));
 }
 
+export function markKernelProcessMode() {
+	globalThis[KERNEL_PROCESS_MODE] = true;
+}
+
 function shadowBun(real, WebView) {
 	return new Proxy(
 		{},
@@ -35,7 +40,10 @@ function shadowBun(real, WebView) {
 }
 
 // The macOS default (WebKit) stays a native worker view: its host process serves any thread.
+// A process-mode kernel already runs its cells on the child's main thread, so the native
+// WebView constructs there directly and no MessagePort proxy is ever needed.
 function needsMainThread(options) {
+	if (globalThis[KERNEL_PROCESS_MODE]) return false;
 	const backend = options?.backend;
 	if (backend === undefined) return process.platform !== "darwin";
 	return backend === "chrome" || (typeof backend === "object" && backend !== null && backend.type === "chrome");

package/src/kernels/shared/subprocess-process.ts

@@ -151,6 +151,11 @@ export class SubprocessProcess {
 	}
 
 	private kill(signal: NodeJS.Signals): void {
+		if (globalThis.process.platform === "win32") {
+			if (this.child.pid !== undefined) killProcessTree(this.child.pid);
+			else this.child.kill(signal);
+			return;
+		}
 		if (this.child.pid !== undefined) {
 			try {
 				globalThis.process.kill(-this.child.pid, signal);
@@ -163,6 +168,15 @@ export class SubprocessProcess {
 	}
 }
 
+// Windows has no process-group signal: taskkill /T /F walks the tree rooted at the child.
+function killProcessTree(pid: number): void {
+	try {
+		nodeSpawn("taskkill", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore" });
+	} catch (error) {
+		if (!(error instanceof Error)) throw error;
+	}
+}
+
 export function spawnSubprocess(spawn: SubprocessSpawn | undefined, request: SubprocessSpawnRequest): SubprocessLike {
 	if (spawn) return spawn(request.command, request.args, { cwd: request.cwd, env: request.env });
 	const child = nodeSpawn(request.command, [...request.args], {

package/src/tool/AGENTS.md

@@ -17,6 +17,7 @@ anchor most suites).
 | Code preview layout | `code-preview.ts` -> `display-code.ts` (JS: `display-js*.ts` Bun-only masked `Bun.Transpiler`; Python: `display-python*.ts` user interpreter, background + repaint) |
 | Status events, execution events | `status-events.ts`, `eval-execution-event.ts` |
 | Interrupt, capture | `interrupt-note.ts`, `call-capture.ts` |
+| Magic cells | `magic-cells.ts` (parsing), `magic-cell-host.ts` (`%pip`, `%bun`/`%npm`, `%environment`), `load-cell.ts` (`%load`); installs live in `../environments/` |
 
 ## CONVENTIONS
 

package/src/tool/runtime-label.ts

@@ -10,7 +10,8 @@ const ELLIPSIS = "\u2026";
  * runtime name because node and bun are otherwise indistinguishable.
  */
 export function formatRuntimeBadge(language: EvalLanguage, runtime: EvalRuntimeInfo, home: string = homedir()): string {
-	const label = language === "js" ? `${runtime.name} ${runtime.version}` : runtime.version;
+	const base = language === "js" ? `${runtime.name} ${runtime.version}` : runtime.version;
+	const label = runtime.isolation === "process" ? `${base}, process` : base;
 	if (runtime.path === undefined || runtime.path.length === 0) return label;
 	return `${label}, ${minifyPath(runtime.path, home)}`;
 }

package/src/tool/types.ts

@@ -279,6 +279,8 @@ export interface EvalRuntimeInfo {
 	readonly name: string;
 	readonly version: string;
 	readonly path?: string;
+	/** JS only: the kernel runs in a child process instead of a worker thread. */
+	readonly isolation?: "process";
 }
 
 export type EvalRuntimes = Readonly<Partial<Record<EvalLanguage, EvalRuntimeInfo>>>;