@code-yeongyu/senpi-codemode 2026.9.5 → 2026.9.7-2

package/src/kernels/js/interrupt-bounds.ts

@@ -0,0 +1,66 @@
+import type { WorkerLike } from "./inline-worker.ts";
+import type { PendingJavaScriptRun } from "./run-queue.ts";
+
+/** How long the worker gets to acknowledge `interrupt`; silence means its event loop is blocked in synchronous code. */
+export const INTERRUPT_ACK_MS = 500;
+/** How long an acknowledged cell gets to settle before the VM is replaced. */
+export const JS_INTERRUPT_GRACE_MS = 2_000;
+/** How long `worker.terminate()` may take before the worker is abandoned as blocked in a synchronous call. */
+export const WORKER_TERMINATE_DEADLINE_MS = 3_000;
+
+export type CooperativeSettlement = "settled" | "unresponsive";
+export type WorkerRetirement = "terminated" | "abandoned";
+
+export interface CooperativeSettlementBounds {
+	readonly ackMs: number;
+	readonly graceMs: number;
+}
+
+const DEFAULT_SETTLEMENT_BOUNDS: CooperativeSettlementBounds = {
+	ackMs: INTERRUPT_ACK_MS,
+	graceMs: JS_INTERRUPT_GRACE_MS,
+};
+
+export async function awaitCooperativeSettlement(
+	run: PendingJavaScriptRun,
+	bounds = DEFAULT_SETTLEMENT_BOUNDS,
+): Promise<CooperativeSettlement> {
+	if (run.settled) return "settled";
+	const settled = run.settlement.then((): "settled" => "settled");
+	const acked = run.interruptAck?.promise.then((): "acked" => "acked") ?? Promise.resolve<"acked">("acked");
+	const first = await raceDeadline(Promise.race([settled, acked]), bounds.ackMs, "unresponsive");
+	if (first !== "acked") return first;
+	return await raceDeadline(settled, bounds.graceMs, "unresponsive");
+}
+
+export async function retireWorker(
+	worker: WorkerLike,
+	deadlineMs = WORKER_TERMINATE_DEADLINE_MS,
+): Promise<WorkerRetirement> {
+	const termination = worker.terminate().then((): WorkerRetirement => "terminated");
+	const outcome = await raceDeadline(termination, deadlineMs, "abandoned");
+	if (outcome === "abandoned") void termination.then(undefined, ignoreLateTerminationFailure);
+	return outcome;
+}
+
+export function abandonedWorkerNote(deadlineMs = WORKER_TERMINATE_DEADLINE_MS): string {
+	return `JavaScript worker did not stop within ${deadlineMs}ms: a synchronous call (for example Bun.spawnSync or child_process.spawnSync) is blocking it. A fresh worker replaced it; the blocked call keeps running until it returns.\n`;
+}
+
+async function raceDeadline<T extends string, Fallback extends string>(
+	operation: Promise<T>,
+	deadlineMs: number,
+	fallback: Fallback,
+): Promise<T | Fallback> {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const deadline = new Promise<Fallback>((resolve) => {
+		timer = setTimeout(() => resolve(fallback), deadlineMs);
+	});
+	try {
+		return await Promise.race([operation, deadline]);
+	} finally {
+		if (timer !== undefined) clearTimeout(timer);
+	}
+}
+
+function ignoreLateTerminationFailure(): void {}

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

@@ -1,4 +1,5 @@
 import type { KernelToHostMessage } from "../../bridge/protocol.ts";
+import type { SessionEnvironment } from "../session-env.ts";
 
 export type ResultMessage = Extract<KernelToHostMessage, { type: "result" }>;
 export type ToolCallMessage = Extract<KernelToHostMessage, { type: "tool-call" }>;
@@ -11,6 +12,8 @@ export interface JavaScriptKernelOptions {
 	readonly parallelPoolWidth: number;
 	readonly onMessage?: (message: KernelToHostMessage) => void;
 	readonly workerEntryUrl?: URL;
+	/** Per-session PI_* values applied to the worker environment before the first cell runs. */
+	readonly sessionEnv?: SessionEnvironment;
 }
 
 export interface JavaScriptRunInput {

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

@@ -7,8 +7,13 @@ export interface PendingJavaScriptRun {
 	readonly input: JavaScriptRunInput;
 	readonly resolve: (message: ResultMessage) => void;
 	readonly reject: (error: Error) => void;
+	readonly settlement: Promise<ResultMessage>;
 	startedAtMs: number | null;
 	settled: boolean;
+	/** Host-composed result that wins over whatever the worker reports once an interrupt is in flight. */
+	interruptResult: ResultMessage | null;
+	interruptAck: PromiseWithResolvers<void> | null;
+	settledByWorker: boolean;
 }
 
 export class JavaScriptRunQueue {
@@ -24,9 +29,19 @@ export class JavaScriptRunQueue {
 	}
 
 	enqueue(input: JavaScriptRunInput): Promise<ResultMessage> {
-		return new Promise((resolve, reject) => {
-			this.#queue.push({ input, resolve, reject, startedAtMs: null, settled: false });
+		const { promise, resolve, reject } = Promise.withResolvers<ResultMessage>();
+		this.#queue.push({
+			input,
+			resolve,
+			reject,
+			settlement: promise,
+			startedAtMs: null,
+			settled: false,
+			interruptResult: null,
+			interruptAck: null,
+			settledByWorker: false,
 		});
+		return promise;
 	}
 
 	startNext(startedAtMs: number): PendingJavaScriptRun | null {
@@ -64,7 +79,7 @@ export class JavaScriptRunQueue {
 	settleAll(message: string): void {
 		const active = this.#active;
 		this.#active = null;
-		if (active) this.settle(active, stoppedResult(active.input.cellId, message));
+		if (active) this.settle(active, active.interruptResult ?? stoppedResult(active.input.cellId, message));
 		for (const queued of this.#queue.splice(0)) this.settle(queued, stoppedResult(queued.input.cellId, message));
 	}
 

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

@@ -1,7 +1,22 @@
 import { JsWorkerRuntime } from "./worker-runtime.js";
 
+// Mirrors INTERRUPT_ACK_OP in src/bridge/reserved.ts (this worker file cannot import TypeScript).
+const INTERRUPT_ACK_OP = "interrupt-ack";
+
+// Mirrors SESSION_ENVIRONMENT_KEYS in src/kernels/session-env.ts (this worker file
+// cannot import TypeScript). Keys the active session does not set must be dropped so a
+// value inherited from the host environment never leaks into a cell or its children.
+const SESSION_ENVIRONMENT_KEYS = [
+	"PI_SESSION_ID",
+	"PI_SESSION_FILE",
+	"PI_PROVIDER",
+	"PI_MODEL",
+	"PI_REASONING_LEVEL",
+];
+
 export function createWorkerCore(transport, options) {
 	let runtime = null;
+	let activeCell = null;
 	const pendingTools = new Map();
 
 	function emit(message) {
@@ -14,6 +29,7 @@ export function createWorkerCore(transport, options) {
 			return;
 		}
 		const startedAtMs = performance.now();
+		activeCell = { cellId: message.cellId, interruption: null };
 		try {
 			const value = await runtime.run(message.code, message.cellId, {
 				emit,
@@ -22,18 +38,34 @@ export function createWorkerCore(transport, options) {
 			emit({ type: "result", cellId: message.cellId, ok: true, valueRepr: valueRepr(value), durationMs: durationMs(startedAtMs) });
 		} catch (error) {
 			emit({ type: "result", cellId: message.cellId, ok: false, error: bridgeError(error), durationMs: durationMs(startedAtMs) });
+		} finally {
+			activeCell = null;
 		}
 	}
 
 	async function callTool(toolName, args) {
+		if (activeCell?.interruption) throw activeCell.interruption;
 		const callId = `js-${crypto.randomUUID()}`;
 		const promise = new Promise((resolve, reject) => pendingTools.set(callId, { resolve, reject }));
 		emit({ type: "tool-call", callId, toolName, args });
 		return await promise;
 	}
 
+	function interruptCell(reason) {
+		if (!activeCell || !runtime) return;
+		emit({ type: "status", event: { op: INTERRUPT_ACK_OP, cellId: activeCell.cellId } });
+		const interruption = cellInterruptedError(reason);
+		activeCell.interruption = interruption;
+		for (const [callId, pending] of pendingTools) {
+			pendingTools.delete(callId);
+			pending.reject(interruption);
+		}
+		runtime.interrupt();
+	}
+
 	function onMessage(message) {
 		if (message.type === "init") {
+			applySessionEnvironment(message.sessionEnv);
 			runtime = new JsWorkerRuntime({
 				cwd: options.cwd,
 				parallelPoolWidth: options.parallelPoolWidth,
@@ -55,6 +87,10 @@ export function createWorkerCore(transport, options) {
 			else pending.reject(errorFromBridge(message.error));
 			return;
 		}
+		if (message.type === "interrupt") {
+			interruptCell(message.reason ?? "interrupted");
+			return;
+		}
 		if (message.type === "close") {
 			emit({ type: "closed" });
 			transport.close();
@@ -74,11 +110,34 @@ function durationMs(startedAtMs) {
 	return Math.max(0, Math.round(performance.now() - startedAtMs));
 }
 
+function applySessionEnvironment(sessionEnv) {
+	const provided = new Set(Object.keys(sessionEnv ?? {}));
+	const deleted = [];
+	for (const key of SESSION_ENVIRONMENT_KEYS) {
+		if (key in process.env && !provided.has(key)) deleted.push(key);
+		delete process.env[key];
+	}
+	const applied = Object.entries(sessionEnv ?? {});
+	for (const [key, value] of applied) process.env[key] = value;
+	// A worker's process.env is its own view: Bun.$ and node:child_process read it, but Bun.spawn
+	// without an explicit env inherits the OS environ, which also still holds deleted keys because
+	// `delete process.env.X` does not unsetenv under Bun. installShellCapture reads these flags and
+	// pins the worker's environment view for such children (see worker-shell-capture.js).
+	globalThis.__senpi_session_env_deletions__ = deleted;
+	globalThis.__senpi_session_env_applied__ = applied.length > 0 || deleted.length > 0;
+}
+
 function valueRepr(value) {
 	if (value === undefined) return undefined;
 	return JSON.stringify(value);
 }
 
+function cellInterruptedError(reason) {
+	const error = new Error(`JS cell interrupted: ${reason}`);
+	error.name = "CellInterruptedError";
+	return error;
+}
+
 function bridgeError(error) {
 	if (error instanceof Error) {
 		return { name: error.name, message: error.message, stack: error.stack };

package/src/kernels/js/worker-indirect-eval.js

@@ -11,7 +11,7 @@ export async function awaitMaybePromise(value) {
 
 export function wrapUserCode(code) {
 	const persistentCode = persistTopLevelDeclarations(code);
-	if (/\breturn\b/u.test(persistentCode)) return `(async () => {\n${persistentCode}\n})()`;
+	if (scanTopLevelStatements(persistentCode).hasTopLevelReturn) return `(async () => {\n${persistentCode}\n})()`;
 	return `(async () => {\n${captureLastExpression(persistentCode)}\n})()`;
 }
 
@@ -705,7 +705,7 @@ function skipBlockComment(code, start) {
 }
 
 function captureLastExpression(code) {
-	const start = findLastTopLevelStatementStart(code);
+	const start = scanTopLevelStatements(code).lastStatementStart;
 	const head = code.slice(0, start);
 	const tail = code.slice(start).trim();
 	if (!tail || isStatementOnly(tail)) return code;
@@ -726,7 +726,7 @@ function isStatementOnly(source) {
 
 const CONTROL_PAREN_KEYWORDS = new Set(["catch", "for", "if", "switch", "while", "with"]);
 
-function findLastTopLevelStatementStart(code) {
+function scanTopLevelStatements(code) {
 	let start = 0;
 	let round = 0;
 	let square = 0;
@@ -734,6 +734,7 @@ function findLastTopLevelStatementStart(code) {
 	let canStartRegex = true;
 	let lastSignificant = "";
 	let pendingControlParen = false;
+	let hasTopLevelReturn = false;
 	const controlParens = [];
 	for (let index = 0; index < code.length; index += 1) {
 		const char = code[index];
@@ -763,8 +764,11 @@ function findLastTopLevelStatementStart(code) {
 		if (isIdentifierStart(char)) {
 			const end = readIdentifier(code, index);
 			const token = code.slice(index, end);
-			canStartRegex = REGEX_PREFIX_KEYWORDS.has(token);
-			pendingControlParen = CONTROL_PAREN_KEYWORDS.has(token);
+			const isPropertyName = lastSignificant === ".";
+			const atTopLevel = round === 0 && square === 0 && curly === 0;
+			if (token === "return" && atTopLevel && !isPropertyName) hasTopLevelReturn = true;
+			canStartRegex = !isPropertyName && REGEX_PREFIX_KEYWORDS.has(token);
+			pendingControlParen = !isPropertyName && CONTROL_PAREN_KEYWORDS.has(token);
 			lastSignificant = code[end - 1];
 			index = end - 1;
 			continue;
@@ -828,7 +832,7 @@ function findLastTopLevelStatementStart(code) {
 			pendingControlParen = false;
 		}
 	}
-	return start;
+	return { lastStatementStart: start, hasTopLevelReturn };
 }
 
 const STATEMENT_CONTINUATION_KEYWORDS = new Set(["catch", "else", "finally"]);

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

@@ -16,6 +16,7 @@ export class JsWorkerRuntime {
 	#env = new Map();
 	#hooks = null;
 	#pendingDisplays = [];
+	#children = new Set();
 
 	constructor(options) {
 		this.#cwd = options.cwd;
@@ -41,10 +42,24 @@ export class JsWorkerRuntime {
 			return value;
 		} finally {
 			this.#pendingDisplays = [];
+			this.#children.clear();
 			this.#hooks = null;
 		}
 	}
 
+	interrupt() {
+		for (const child of this.#children) {
+			if (child.exitCode === null && child.signalCode === null) child.kill();
+		}
+	}
+
+	#trackChild(child) {
+		if (child === null || typeof child !== "object" || typeof child.kill !== "function") return;
+		this.#children.add(child);
+		const forget = () => this.#children.delete(child);
+		if (child.exited instanceof Promise) child.exited.then(forget, forget);
+	}
+
 	async #drainPendingDisplays() {
 		while (this.#pendingDisplays.length > 0) {
 			const pending = this.#pendingDisplays;
@@ -99,6 +114,7 @@ export class JsWorkerRuntime {
 		const restoreShellCapture = installShellCapture({
 			isActive: () => this.#hooks !== null,
 			emitText: (stream, data) => this.#emitText(stream, data),
+			onChild: (child) => this.#trackChild(child),
 		});
 		globalThis.__senpi_restore_console__ = () => {
 			console.log = originalLog;

package/src/kernels/js/worker-shell-capture.d.ts

@@ -2,9 +2,34 @@ export type ShellCaptureStream = "stdout" | "stderr";
 
 export type ShellCaptureRestore = () => void;
 
+export interface ShellCaptureChild {
+	readonly exitCode: number | null;
+	readonly signalCode: string | null;
+	readonly exited: Promise<number>;
+	kill(): void;
+}
+
 export interface ShellCaptureOptions {
 	readonly isActive: () => boolean;
 	readonly emitText: (stream: ShellCaptureStream, data: string) => void;
+	/** Receives every `Bun.spawn` child created while a cell is active so the runtime can kill it on interrupt. */
+	readonly onChild?: (child: ShellCaptureChild) => void;
 }
 
 export function installShellCapture(options: ShellCaptureOptions): ShellCaptureRestore;
+
+declare global {
+	/**
+	 * Set by the JS worker core when applying the session environment deleted inherited
+	 * `PI_*` keys (see worker-core.js). Under Bun a `delete process.env.X` does not
+	 * unsetenv, so shell capture pins the worker's environment view for spawned children
+	 * while this list is non-empty.
+	 */
+	var __senpi_session_env_deletions__: string[] | undefined;
+	/**
+	 * Set by the JS worker core once a session environment was applied (values set or inherited
+	 * keys deleted). Bun.spawn without an explicit env inherits the OS environ rather than the
+	 * worker's process.env, so shell capture pins the worker's view whenever this is true.
+	 */
+	var __senpi_session_env_applied__: boolean | undefined;
+}

package/src/kernels/js/worker-shell-capture.js

@@ -1,16 +1,35 @@
 const SHELL_CONFIG_METHODS = ["env", "cwd", "nothrow", "throws"];
 const SHELL_READ_METHODS = ["text", "json", "lines", "arrayBuffer", "bytes", "blob"];
+// `true | ( … )` hands every command in the template an empty pipe as stdin. The worker thread shares
+// the host process's fd 0 (the TUI's terminal), which Bun.$ would otherwise inherit, so a stdin
+// reader would wait on the user's keyboard forever. The newline before `)` keeps a trailing comment
+// from swallowing the closing paren; the Bun shell has no other stdin control (no `$.stdin`, no
+// redirect on a subshell).
+const STDIN_ISOLATION_HEAD = "true | (\n";
+const STDIN_ISOLATION_TAIL = "\n)";
 
 export function installShellCapture(options) {
 	const bun = globalThis.Bun;
 	if (!isBunRuntime(bun)) return () => {};
 	const originalShell = bun.$;
 	const originalSpawn = bun.spawn;
+	const originalSpawnSync = typeof bun.spawnSync === "function" ? bun.spawnSync : null;
+	const deletedKeys = globalThis.__senpi_session_env_deletions__;
+	const pinEnv =
+		globalThis.__senpi_session_env_applied__ === true || (Array.isArray(deletedKeys) && deletedKeys.length > 0);
+	if (pinEnv && typeof originalShell.env === "function") {
+		// Bun.spawn without an explicit env inherits the OS environ, not the worker's process.env,
+		// and deleting from process.env does not unsetenv under Bun. Pinning the worker's
+		// environment view mirrors the bash tool, which always spawns with an explicit env.
+		originalShell.env({ ...process.env });
+	}
 	bun.$ = capturedShell(originalShell, options);
-	bun.spawn = capturedSpawn(originalSpawn, options);
+	bun.spawn = capturedSpawn(originalSpawn, options, pinEnv);
+	if (originalSpawnSync !== null) bun.spawnSync = capturedSpawnSync(originalSpawnSync, pinEnv);
 	return () => {
 		bun.$ = originalShell;
 		bun.spawn = originalSpawn;
+		if (originalSpawnSync !== null) bun.spawnSync = originalSpawnSync;
 	};
 }
 
@@ -20,8 +39,9 @@ function isBunRuntime(bun) {
 
 function capturedShell(originalShell, options) {
 	const shell = (strings, ...expressions) => {
-		const promise = originalShell(strings, ...expressions);
-		return options.isActive() ? captureShellPromise(promise, options.emitText) : promise;
+		if (!options.isActive()) return originalShell(strings, ...expressions);
+		const promise = originalShell(isolateStdin(strings), ...expressions);
+		return captureShellPromise(promise, options.emitText);
 	};
 	for (const key of Object.keys(originalShell)) shell[key] = originalShell[key];
 	for (const method of SHELL_CONFIG_METHODS) {
@@ -33,6 +53,18 @@ function capturedShell(originalShell, options) {
 	return shell;
 }
 
+function isolateStdin(strings) {
+	if (!Array.isArray(strings) || !Array.isArray(strings.raw)) return strings;
+	const cooked = [...strings];
+	const raw = [...strings.raw];
+	const last = cooked.length - 1;
+	cooked[0] = `${STDIN_ISOLATION_HEAD}${cooked[0]}`;
+	raw[0] = `${STDIN_ISOLATION_HEAD}${raw[0]}`;
+	cooked[last] = `${cooked[last]}${STDIN_ISOLATION_TAIL}`;
+	raw[last] = `${raw[last]}${STDIN_ISOLATION_TAIL}`;
+	return Object.freeze(Object.assign(cooked, { raw: Object.freeze(raw) }));
+}
+
 function captureShellPromise(promise, emitText) {
 	const prototype = Object.getPrototypeOf(promise);
 	let echo = true;
@@ -83,17 +115,47 @@ function outputText(value) {
 	return typeof value === "string" ? value : "";
 }
 
-function capturedSpawn(originalSpawn, options) {
+// Bun.spawnSync inherits the OS environ the same way Bun.spawn does, so a cell calling it
+// without an explicit env must get the worker's view pinned too (measured on Bun 1.4.0).
+function capturedSpawnSync(originalSpawnSync, pinEnv) {
+	return (...args) => {
+		if (!pinEnv) return originalSpawnSync(...args);
+		const [first, second] = args;
+		if (Array.isArray(first)) {
+			const spawnOptions = second === undefined ? {} : second;
+			if (spawnOptions === null || typeof spawnOptions !== "object" || spawnOptions.env !== undefined)
+				return originalSpawnSync(...args);
+			return originalSpawnSync(first, { ...spawnOptions, env: { ...process.env } });
+		}
+		if (first !== null && typeof first === "object" && first.env === undefined)
+			return originalSpawnSync({ ...first, env: { ...process.env } });
+		return originalSpawnSync(...args);
+	};
+}
+
+function capturedSpawn(originalSpawn, options, pinEnv) {
 	return (...args) => {
 		if (!options.isActive()) return originalSpawn(...args);
 		const [first, second] = args;
+		let child;
 		if (Array.isArray(first)) {
 			const spawnOptions = second === undefined ? {} : second;
-			if (!needsStderrCapture(spawnOptions)) return originalSpawn(...args);
-			return drainStderr(originalSpawn(first, { ...spawnOptions, stderr: "pipe" }), options.emitText);
+			const effective = pinEnv && spawnOptions.env === undefined ? { ...spawnOptions, env: { ...process.env } } : spawnOptions;
+			child = needsStderrCapture(effective)
+				? drainStderr(originalSpawn(first, { ...effective, stderr: "pipe" }), options.emitText)
+				: effective === spawnOptions
+					? originalSpawn(...args)
+					: originalSpawn(first, effective);
+		} else {
+			const effective = pinEnv && first !== null && typeof first === "object" && first.env === undefined ? { ...first, env: { ...process.env } } : first;
+			child = needsStderrCapture(effective)
+				? drainStderr(originalSpawn({ ...effective, stderr: "pipe" }), options.emitText)
+				: effective === first
+					? originalSpawn(...args)
+					: originalSpawn(effective);
 		}
-		if (!needsStderrCapture(first)) return originalSpawn(...args);
-		return drainStderr(originalSpawn({ ...first, stderr: "pipe" }), options.emitText);
+		options.onChild?.(child);
+		return child;
 	};
 }
 

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

@@ -0,0 +1,106 @@
+import type { HostToKernelMessage, KernelToHostMessage } from "../../bridge/protocol.ts";
+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 { WorkerStartupCancelledError } from "./worker-host.ts";
+import { startWorkerWithInlineFallback } from "./worker-startup.ts";
+
+export interface WorkerSlotListeners {
+	isOpen(): boolean;
+	onMessage(message: KernelToHostMessage): void;
+	onCrash(error: Error): void;
+}
+
+/** The kernel's current worker generation: startup with inline fallback, message fencing, bounded retirement. */
+export class WorkerSlot {
+	readonly #options: JavaScriptKernelOptions;
+	readonly #listeners: WorkerSlotListeners;
+	#worker: WorkerLike | null = null;
+	#mode: JavaScriptKernelMode = "worker";
+	#generation = 0;
+	#ready: Promise<void> | null = null;
+	#startupAbort: AbortController | null = null;
+
+	constructor(options: JavaScriptKernelOptions, listeners: WorkerSlotListeners) {
+		this.#options = options;
+		this.#listeners = listeners;
+	}
+
+	get mode(): JavaScriptKernelMode {
+		return this.#mode;
+	}
+
+	get present(): boolean {
+		return this.#worker !== null;
+	}
+
+	get startingUp(): boolean {
+		return this.#startupAbort !== null;
+	}
+
+	postMessage(message: HostToKernelMessage): void {
+		this.#worker?.postMessage(message);
+	}
+
+	async ensureReady(): Promise<void> {
+		if (!this.#ready) {
+			const generation = ++this.#generation;
+			const controller = new AbortController();
+			this.#startupAbort = controller;
+			const ready = startWorkerWithInlineFallback(
+				{
+					options: this.#options,
+					publish: (worker) => this.#publish(worker, generation),
+					isCurrent: (worker) => this.#isCurrent(worker, generation),
+					retire: (worker) => {
+						if (this.#worker === worker) this.#worker = null;
+					},
+					canFallBackInline: () => this.#listeners.isOpen() && generation === this.#generation,
+				},
+				controller.signal,
+			);
+			this.#ready = ready;
+			void ready.then(
+				() => {
+					if (this.#ready !== ready) return;
+					this.#startupAbort = null;
+					this.#mode = this.#worker?.mode ?? this.#mode;
+				},
+				() => {
+					if (this.#ready === ready) {
+						this.#ready = null;
+						this.#startupAbort = null;
+					}
+				},
+			);
+		}
+		return await this.#ready;
+	}
+
+	async retire(): Promise<WorkerRetirement> {
+		this.#generation += 1;
+		this.#startupAbort?.abort();
+		this.#startupAbort = null;
+		this.#ready = null;
+		const worker = this.#worker;
+		this.#worker = null;
+		if (!worker) return "terminated";
+		return await retireWorker(worker);
+	}
+
+	#publish(worker: WorkerLike, generation: number): void {
+		if (!this.#listeners.isOpen() || generation !== this.#generation) throw new WorkerStartupCancelledError();
+		this.#worker = worker;
+		worker.onMessage((message) => {
+			if (this.#isCurrent(worker, generation)) this.#listeners.onMessage(message);
+		});
+		worker.onError((error) => {
+			if (this.#isCurrent(worker, generation)) this.#listeners.onCrash(error);
+		});
+	}
+
+	#isCurrent(worker: WorkerLike, generation: number): boolean {
+		return this.#listeners.isOpen() && this.#worker === worker && this.#generation === generation;
+	}
+}

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

@@ -0,0 +1,70 @@
+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 { type JavaScriptKernelOptions, localBridgeConnection } from "./local-module-loader.ts";
+import { spawnNodeWorker, WorkerStartupCancelledError, waitForReady } from "./worker-host.ts";
+
+export interface JavaScriptWorkerEntryUrlOptions extends CodemodeRuntimeAssetEnvironment {
+	readonly localPath?: string;
+}
+
+export function resolveJsWorkerEntryUrl(options: JavaScriptWorkerEntryUrlOptions = {}): URL {
+	const localPath = options.localPath ?? join(dirname(fileURLToPath(import.meta.url)), "worker-entry.js");
+	return pathToFileURL(requireCodemodeRuntimeAsset(localPath, join("kernels", "js", "worker-entry.js"), options));
+}
+
+export interface WorkerStartupHooks {
+	readonly options: JavaScriptKernelOptions;
+	/** Wires the worker into the kernel; throws `WorkerStartupCancelledError` once the generation is stale. */
+	publish(worker: WorkerLike): void;
+	isCurrent(worker: WorkerLike): boolean;
+	retire(worker: WorkerLike): void;
+	canFallBackInline(): boolean;
+}
+
+export async function startWorkerWithInlineFallback(hooks: WorkerStartupHooks, signal: AbortSignal): Promise<void> {
+	let worker = spawnWorker(hooks.options);
+	hooks.publish(worker);
+	try {
+		await initializeWorker(worker, hooks.options, signal);
+		return;
+	} catch (error) {
+		if (!hooks.isCurrent(worker) || error instanceof WorkerStartupCancelledError) {
+			await worker.terminate();
+			throw new WorkerStartupCancelledError();
+		}
+		if (worker.mode === "inline") throw error;
+		hooks.retire(worker);
+		await worker.terminate();
+	}
+	if (!hooks.canFallBackInline()) throw new WorkerStartupCancelledError();
+	worker = createInlineWorker(hooks.options.cwd, hooks.options.parallelPoolWidth);
+	hooks.publish(worker);
+	await initializeWorker(worker, hooks.options, signal);
+}
+
+function spawnWorker(options: JavaScriptKernelOptions): WorkerLike {
+	try {
+		const url = options.workerEntryUrl ?? resolveJsWorkerEntryUrl();
+		return spawnNodeWorker(url, options.cwd, options.parallelPoolWidth);
+	} catch (error) {
+		if (!(error instanceof Error)) throw error;
+		return createInlineWorker(options.cwd, options.parallelPoolWidth);
+	}
+}
+
+async function initializeWorker(
+	worker: WorkerLike,
+	options: JavaScriptKernelOptions,
+	signal: AbortSignal,
+): Promise<void> {
+	const ready = waitForReady(worker, signal);
+	worker.postMessage({
+		type: "init",
+		sessionId: options.sessionId,
+		connection: localBridgeConnection(options),
+		...(options.sessionEnv === undefined ? {} : { sessionEnv: options.sessionEnv }),
+	});
+	await ready;
+}

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

@@ -1,4 +1,5 @@
 import type { BridgeConnectionConfig, KernelToHostMessage } from "../../bridge/protocol.ts";
+import type { SessionEnvironment } from "../session-env.ts";
 import type { KernelSpawnProcess } from "./process.ts";
 import type { PythonTransportResult } from "./transport.ts";
 
@@ -8,6 +9,8 @@ export interface PythonKernelStartOptions {
 	readonly cwd: string;
 	readonly connection: BridgeConnectionConfig;
 	readonly env?: NodeJS.ProcessEnv;
+	/** Per-session PI_* values merged into the interpreter environment at spawn. */
+	readonly sessionEnv?: SessionEnvironment;
 	readonly startupTimeoutMs?: number;
 	readonly onMessage?: (message: KernelToHostMessage) => void;
 	readonly spawnProcess?: KernelSpawnProcess;