@code-yeongyu/senpi-codemode 2026.10.3 → 2026.10.5

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

@@ -0,0 +1,110 @@
+import type { KernelMemoryThresholds } from "../../bridge/memory-protocol.ts";
+import type { HostToKernelMessage, KernelToHostMessage } from "../../bridge/protocol.ts";
+import { MEMORY_COLLECTED_OP } from "../../bridge/reserved.ts";
+import { KernelMemoryPolicy } from "../shared/kernel-memory.ts";
+import type { ResultMessage } from "./kernel-contract.ts";
+
+export interface JavaScriptMemoryReading {
+	readonly liveBytes: number;
+	readonly measure: "heap";
+}
+
+/** A query waits at most this long: the worker answers between cells, never inside one. */
+const MEMORY_QUERY_TIMEOUT_MS = 5_000;
+
+type QueryResult = Extract<KernelToHostMessage, { type: "memory-query-result" }>;
+
+/**
+ * The host half of one JS kernel's memory: the post-cell policy (notice, ceiling, recycle), the last
+ * heap reading the worker sent (result frames, idle collections, queries), and the on-demand queries
+ * still waiting for the worker. Losing the worker forgets the reading and rejects every waiting query.
+ */
+export class KernelMemoryBridge {
+	readonly #policy: KernelMemoryPolicy | null;
+	readonly #onCollected: ((liveBytes: number) => void) | undefined;
+	readonly #queries = new Map<
+		string,
+		{ pending: PromiseWithResolvers<JavaScriptMemoryReading>; timer: ReturnType<typeof setTimeout> }
+	>();
+	#lastLiveBytes: number | undefined;
+
+	constructor(thresholds: KernelMemoryThresholds | undefined, onCollected?: (liveBytes: number) => void) {
+		this.#policy = thresholds === undefined ? null : new KernelMemoryPolicy("js", thresholds);
+		this.#onCollected = onCollected;
+	}
+
+	get lastLiveBytes(): number | undefined {
+		return this.#lastLiveBytes;
+	}
+
+	/** Consumes the worker's memory messages (idle collections, query results); false for anything else. */
+	consume(message: KernelToHostMessage): boolean {
+		if (message.type === "memory-query-result") {
+			this.#answered(message);
+			return true;
+		}
+		if (message.type !== "status" || message.event.op !== MEMORY_COLLECTED_OP) return false;
+		const liveBytes = message.event.liveBytes;
+		if (typeof liveBytes !== "number") return true;
+		this.#lastLiveBytes = liveBytes;
+		this.#policy?.observeLive(liveBytes);
+		this.#onCollected?.(liveBytes);
+		return true;
+	}
+
+	settled(message: ResultMessage): ResultMessage {
+		if (message.memory === undefined) return message;
+		this.#lastLiveBytes = message.memory.liveBytes;
+		if (this.#policy === null) return message;
+		return { ...message, memory: this.#policy.annotate(message.memory) };
+	}
+
+	/** True when an over-ceiling kernel must restart now: it is `idle` (nothing running or queued). */
+	claimRecycle(idle: boolean): boolean {
+		if (!idle || this.#policy?.recyclePending !== true) return false;
+		this.#policy.recycleStarted();
+		return true;
+	}
+
+	/**
+	 * A fresh reading from the worker. The worker answers between cells, so the wait is bounded:
+	 * a kernel whose cell never yields (a sync loop) cannot answer until that cell settles, and the
+	 * query rejects after {@link MEMORY_QUERY_TIMEOUT_MS} instead of hanging its caller forever.
+	 */
+	query(post: (message: HostToKernelMessage) => void): Promise<JavaScriptMemoryReading> {
+		const requestId = crypto.randomUUID();
+		const pending = Promise.withResolvers<JavaScriptMemoryReading>();
+		const timer = setTimeout(() => {
+			if (!this.#queries.delete(requestId)) return;
+			pending.reject(
+				new Error(
+					`memory-query timed out after ${MEMORY_QUERY_TIMEOUT_MS}ms (a cell is running; queries answer between cells)`,
+				),
+			);
+		}, MEMORY_QUERY_TIMEOUT_MS);
+		this.#queries.set(requestId, { pending, timer });
+		post({ type: "memory-query", requestId });
+		return pending.promise;
+	}
+
+	/** The worker is gone (reset, crash, stop, recycle): its memory and its unanswered queries went with it. */
+	workerLost(error: Error): void {
+		this.#policy?.kernelRetired();
+		this.#lastLiveBytes = undefined;
+		const waiting = [...this.#queries.values()];
+		this.#queries.clear();
+		for (const { pending, timer } of waiting) {
+			clearTimeout(timer);
+			pending.reject(error);
+		}
+	}
+
+	#answered(result: QueryResult): void {
+		const waiting = this.#queries.get(result.requestId);
+		if (waiting === undefined) return;
+		this.#queries.delete(result.requestId);
+		clearTimeout(waiting.timer);
+		this.#lastLiveBytes = result.liveBytes;
+		waiting.pending.resolve({ liveBytes: result.liveBytes, measure: result.measure });
+	}
+}

package/src/kernels/js/tool-call-queue.ts

@@ -0,0 +1,32 @@
+import type { ToolCallMessage } from "./kernel-contract.ts";
+
+// Pull-API fallback queue bound: a nextToolCall consumer this far behind is already stalled, and the
+// normal push path (onMessage) never reads the queue, so unbounded growth only pins tool args (#1695).
+const MAX_PENDING_TOOL_CALLS = 256;
+
+/** Tool calls for `nextToolCall()` consumers: handed to a waiting consumer, else queued up to the bound. */
+export class ToolCallQueue {
+	readonly #waiters: Array<(message: ToolCallMessage) => void> = [];
+	readonly #pending: ToolCallMessage[] = [];
+
+	push(message: ToolCallMessage): void {
+		const waiter = this.#waiters.shift();
+		if (waiter) {
+			waiter(message);
+			return;
+		}
+		this.#pending.push(message);
+		if (this.#pending.length > MAX_PENDING_TOOL_CALLS) this.#pending.shift();
+	}
+
+	async next(): Promise<ToolCallMessage> {
+		const pending = this.#pending.shift();
+		if (pending) return pending;
+		return await new Promise((resolve) => this.#waiters.push(resolve));
+	}
+
+	clear(): void {
+		this.#pending.length = 0;
+		this.#waiters.length = 0;
+	}
+}

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

@@ -0,0 +1,35 @@
+import type { EvalStatusEvent } from "../../bridge/protocol.ts";
+import { terminateProcessTrees } from "./process-tree-host.ts";
+
+/** How long a lost worker's children get to honour SIGTERM before the host sends SIGKILL. */
+const WORKER_LOSS_CHILD_GRACE_MS = 1_000;
+
+/** Live cell children the worker reported; retired by the host when the worker itself is lost. */
+export class WorkerChildren {
+	readonly #pids = new Set<number>();
+	readonly #collectOrphanedChildren: ((pids: readonly number[]) => Promise<unknown>) | undefined;
+
+	constructor(collectOrphanedChildren?: (pids: readonly number[]) => Promise<unknown>) {
+		this.#collectOrphanedChildren = collectOrphanedChildren;
+	}
+
+	track(event: EvalStatusEvent): void {
+		const pid = event.pid;
+		if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) return;
+		if (event.state === "spawned") this.#pids.add(pid);
+		else if (event.state === "exited") this.#pids.delete(pid);
+	}
+
+	/**
+	 * A terminated or crashed worker never reaches its own cell-end cleanup, so the host retires the
+	 * children it still owned; a pid `ps` no longer lists as our child was reused and is skipped.
+	 */
+	async retire(): Promise<void> {
+		if (this.#pids.size === 0) return;
+		const pids = [...this.#pids];
+		this.#pids.clear();
+		await terminateProcessTrees(pids, { graceMs: WORKER_LOSS_CHILD_GRACE_MS, ownerPid: process.pid });
+		// The worker that owned these children and their exit watchers is gone, so nothing else will wait on them.
+		await this.#collectOrphanedChildren?.(pids);
+	}
+}

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

@@ -3,6 +3,7 @@ import { kernelToolError } from "./kernel-tools-errors.js";
 import { createKernelToolPump } from "./kernel-tools-pump.js";
 import { hostDeniedError, hostToolRefusal } from "./kernel-tools-scope.js";
 import { installSessionCwd } from "./worker-cwd.js";
+import { createHeapProbe } from "./worker-heap.js";
 import { createWorkerMemory } from "./worker-memory.js";
 import { JsWorkerRuntime } from "./worker-runtime.js";
 import { installKernelWebView } from "./worker-webview.js";
@@ -23,11 +24,13 @@ const SESSION_ENVIRONMENT_KEYS = [
 	"PI_PROVIDER",
 	"PI_MODEL",
 	"PI_REASONING_LEVEL",
+	"OMO_BROWSER_ENGINE",
 ];
 
 export function createWorkerCore(transport, options) {
 	let runtime = null;
 	let memory = null;
+	let heapProbe = null;
 	let activeCell = null;
 	const pendingTools = new Map();
 	const pendingWebViewPorts = new Map();
@@ -146,6 +149,11 @@ export function createWorkerCore(transport, options) {
 			emit({ type: "ready" });
 			return;
 		}
+		if (message.type === "memory-query") {
+			heapProbe ??= createHeapProbe();
+			emit({ type: "memory-query-result", requestId: message.requestId, liveBytes: Math.round(heapProbe.estimate()), measure: "heap" });
+			return;
+		}
 		if (message.type === "run") {
 			void runCell(message);
 			return;

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

@@ -90,6 +90,15 @@ export function bridgeError(error: Error): {
 	return { message: error.message, name: error.name, stack: error.stack };
 }
 
+/** The result a cell settles with when its worker crashed under it. */
+export function crashedResult(
+	cellId: string,
+	error: Error,
+	durationMs: number,
+): Extract<KernelToHostMessage, { type: "result" }> {
+	return { type: "result", cellId, ok: false, error: bridgeError(error), durationMs };
+}
+
 function wrapNodeWorker(worker: Worker, mode: JavaScriptKernelMode): WorkerLike {
 	return {
 		mode,

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

@@ -0,0 +1,60 @@
+import type { JavaScriptRunQueue } from "./run-queue.ts";
+import { WorkerStartupCancelledError } from "./worker-host.ts";
+
+export interface WorkerRecoveryHost {
+	readonly runs: JavaScriptRunQueue;
+	isOpen(): boolean;
+	ensureReady(): Promise<void>;
+	startNext(): void;
+}
+
+/** Brings a worker up for waiting cells, and replaces a lost or retired worker one recovery at a time. */
+export class WorkerRecovery {
+	readonly #host: WorkerRecoveryHost;
+	#recovery: Promise<void> | null = null;
+
+	constructor(host: WorkerRecoveryHost) {
+		this.#host = host;
+	}
+
+	get inFlight(): Promise<void> | null {
+		return this.#recovery;
+	}
+
+	/** Starts a worker when none is live and hands it the next waiting cell; a failed start fails the waiting cells. */
+	async bringUp(): Promise<void> {
+		try {
+			await this.#host.ensureReady();
+			if (this.#host.isOpen()) this.#host.startNext();
+		} catch (error) {
+			this.#failWaiting(error);
+		}
+	}
+
+	/** Retires through `retire` (a no-op when the worker is already gone), then brings a fresh worker up. */
+	async recover(retire: () => Promise<unknown>): Promise<void> {
+		if (this.#recovery) return await this.#recovery;
+		const recovery = this.#perform(retire);
+		this.#recovery = recovery;
+		try {
+			await recovery;
+		} finally {
+			if (this.#recovery === recovery) this.#recovery = null;
+		}
+	}
+
+	async #perform(retire: () => Promise<unknown>): Promise<void> {
+		try {
+			await retire();
+		} catch (error) {
+			this.#failWaiting(error);
+			return;
+		}
+		if (this.#host.isOpen()) await this.bringUp();
+	}
+
+	#failWaiting(error: unknown): void {
+		if (error instanceof WorkerStartupCancelledError) return;
+		this.#host.runs.rejectWaiting(error instanceof Error ? error : new Error(String(error)));
+	}
+}

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

@@ -2,11 +2,12 @@ import type { KernelMemoryThresholds } from "../../bridge/memory-protocol.ts";
 import type { BridgeConnectionConfig, KernelToHostMessage } from "../../bridge/protocol.ts";
 import type { EvalKernelRunInput } from "../../tool/types.ts";
 import type { SessionEnvironment } from "../session-env.ts";
+import type { KernelLifecycle } from "../shared/kernel-death.ts";
 import type { KernelSpawnProcess } from "./process.ts";
 import type { PythonStartupStage } from "./startup.ts";
 import type { PythonTransportResult } from "./transport.ts";
 
-export interface PythonKernelStartOptions {
+export interface PythonKernelStartOptions extends KernelLifecycle {
 	readonly interpreterPath: string;
 	readonly sessionId: string;
 	readonly cwd: string;

package/src/kernels/py/kernel.ts

@@ -1,7 +1,8 @@
 // allow: SIZE_OK — one persistent Python lifecycle state machine owns queue, generation, and retirement.
-import type { KernelInterruptHandle } from "../../tool/types.ts";
+import type { KernelInterruptHandle, PendingCell } from "../../tool/types.ts";
 import type { KernelToolsInvokeOptions } from "../js/kernel-tools-types.ts";
 import { rejectKernelToolsUnavailable } from "../kernel-tools-unavailable.ts";
+import { describeExit } from "../shared/kernel-death.ts";
 import { KernelMemoryHost } from "../shared/kernel-memory-host.ts";
 import { KernelPreludeTracker } from "../shared/kernel-prelude-plan.ts";
 import type { PendingRun, PythonKernelRunOptions, PythonKernelStartOptions, ResultMessage } from "./kernel-contract.ts";
@@ -27,6 +28,7 @@ export class PythonKernel {
 	readonly #memory: KernelMemoryHost | null;
 	#generation = 0;
 	#closed = false;
+	#dead = false;
 
 	private constructor(options: PythonKernelStartOptions) {
 		this.#options = options;
@@ -43,6 +45,18 @@ export class PythonKernel {
 		return [];
 	}
 
+	isAlive(): boolean {
+		return !this.#dead;
+	}
+
+	drainPending(): readonly PendingCell[] {
+		return [...this.#queue].map((pending) => {
+			this.#pending.delete(pending.input.cellId);
+			this.#removePending(pending);
+			return { input: pending.input, settle: pending.resolve };
+		});
+	}
+
 	describeKernelTools(_names: readonly string[]): Promise<never> {
 		return rejectKernelToolsUnavailable();
 	}
@@ -54,6 +68,7 @@ export class PythonKernel {
 	run(input: PythonKernelRunOptions): Promise<ResultMessage> {
 		if (this.#failure) return Promise.reject(this.#failure);
 		if (this.#closed) return Promise.reject(new Error("Python kernel is closed"));
+		if (this.#dead) return Promise.reject(new Error("Python kernel died"));
 		return new Promise<ResultMessage>((resolve, reject) => {
 			const pending: PendingRun = { input, resolve, reject, startedAt: null, timeoutTimer: null };
 			this.#pending.set(input.cellId, pending);
@@ -156,6 +171,7 @@ export class PythonKernel {
 	#startNext(): void {
 		if (
 			this.#closed ||
+			this.#dead ||
 			this.#failure ||
 			this.#active ||
 			this.#starting ||
@@ -234,11 +250,11 @@ export class PythonKernel {
 			isOwned: () => !this.#closed && generation === this.#generation,
 			onRetirementFailure: (transport, error) => {
 				if (!this.#transport) this.#transport = transport;
-				this.#recordFailure(error);
+				this.#recoverWhenGone(transport, this.#recordFailure(error));
 			},
 			onResult: (transport, result) => this.#onResult(transport, result),
 			onError: (transport, error) => this.#onError(transport, error),
-			onExit: (transport, error) => this.#onExit(transport, error),
+			onExit: (transport, error, exit) => this.#onExit(transport, error, describeExit(exit.code, exit.signal)),
 		});
 	}
 
@@ -262,15 +278,37 @@ export class PythonKernel {
 		void this.reset().catch(() => undefined);
 	}
 
-	#onExit(transport: PythonKernelTransport, error: Error): void {
+	#onExit(transport: PythonKernelTransport, error: Error, reason: string): void {
 		if (this.#transport !== transport) return;
 		this.#transport = null;
+		// With an owner listening, a death is final for this instance: the cells that never started stay
+		// queued for `drainPending` and the owner replaces it. Without one it respawns lazily, as before.
+		const onDeath = this.#options.onDeath;
+		if (onDeath) this.#dead = true;
 		const active = this.#active;
 		if (active) {
 			if (active.resolveStateRetained) active.resolveStateRetained(false);
-			this.#settleRun(active, failedPythonResult(active.input.cellId, "Python kernel died", error.message));
+			const message = onDeath ? "Python kernel died; every global is lost" : "Python kernel died";
+			this.#settleRun(active, failedPythonResult(active.input.cellId, message, error.message));
 		}
-		this.#startNext();
+		if (onDeath) onDeath(reason);
+		else this.#startNext();
+	}
+
+	/**
+	 * A retirement that timed out is reported, and no second interpreter starts while the first may live.
+	 * Once that process is seen to exit after all, the failure is over: this instance is dead, not broken.
+	 */
+	#recoverWhenGone(transport: PythonKernelTransport, failure: Error): void {
+		const onDeath = this.#options.onDeath;
+		if (!onDeath) return;
+		void transport.whenGone().then(() => {
+			if (this.#closed || this.#failure !== failure) return;
+			this.#failure = null;
+			this.#dead = true;
+			if (this.#transport === transport) this.#transport = null;
+			onDeath("an interpreter that outlived its SIGKILL grace");
+		});
 	}
 
 	#onError(transport: PythonKernelTransport, error: Error): void {
@@ -349,8 +387,10 @@ export class PythonKernel {
 			try {
 				await transport.retire();
 			} catch (error) {
-				if (error instanceof Error) throw this.#recordFailure(error);
-				throw error;
+				if (!(error instanceof Error)) throw error;
+				const failure = this.#recordFailure(error);
+				this.#recoverWhenGone(transport, failure);
+				throw failure;
 			}
 			if (this.#transport === transport) this.#transport = null;
 		})();

package/src/kernels/py/transport.ts

@@ -52,7 +52,11 @@ export interface PythonTransportOptions {
 	readonly onRetirementFailure: (transport: PythonKernelTransport, error: Error) => void;
 	readonly onResult: (transport: PythonKernelTransport, result: PythonTransportResult) => void;
 	readonly onError: (transport: PythonKernelTransport, error: Error) => void;
-	readonly onExit: (transport: PythonKernelTransport, error: Error) => void;
+	readonly onExit: (
+		transport: PythonKernelTransport,
+		error: Error,
+		exit: { readonly code: number | null; readonly signal: string | null },
+	) => void;
 }
 
 const hardKillWaitMs = 500;
@@ -79,12 +83,29 @@ export class PythonKernelTransport {
 	#active = true;
 	#exited = false;
 	#retirement: Promise<void> | null = null;
+	#gone: Promise<void> | null = null;
+	#isGone = false;
 
 	private constructor(options: PythonTransportOptions, child: KernelChild) {
 		this.#options = options;
 		this.#child = child;
 	}
 
+	/**
+	 * A retirement that timed out is confirmed only by this: the process really exited after all. The
+	 * watch is attached on demand, so a transport nobody asks this of leaves no listener on its child.
+	 */
+	whenGone(): Promise<void> {
+		if (this.#exited || this.#isGone) return Promise.resolve();
+		this.#gone ??= new Promise<void>((resolve) => {
+			this.#child.once("exit", () => {
+				this.#isGone = true;
+				resolve();
+			});
+		});
+		return this.#gone;
+	}
+
 	static async start(options: PythonTransportOptions): Promise<PythonKernelTransport> {
 		const scriptPath = resolvePythonPreludePath();
 		const invocation = splitCommand(options.interpreterPath);
@@ -139,7 +160,7 @@ export class PythonKernelTransport {
 	}
 
 	async close(): Promise<void> {
-		if (this.#exited) return;
+		if (this.#exited || this.#isGone) return;
 		if (this.#retirement) {
 			await this.#retirement;
 			return;
@@ -162,7 +183,7 @@ export class PythonKernelTransport {
 	}
 
 	retire(): Promise<void> {
-		if (this.#exited) return Promise.resolve();
+		if (this.#exited || this.#isGone) return Promise.resolve();
 		if (this.#retirement) return this.#retirement;
 		this.#active = false;
 		const retirement = hardKill(this.#child, hardKillWaitMs).finally(() => {
@@ -244,7 +265,7 @@ export class PythonKernelTransport {
 		const error = new Error(this.#stderrTail.trim() || `Python kernel exited (${code ?? signal ?? "unknown"})`);
 		this.#detachListeners();
 		if (!active) return;
-		if (!this.#settleStartup(error)) this.#options.onExit(this, error);
+		if (!this.#settleStartup(error)) this.#options.onExit(this, error, { code, signal });
 	}
 
 	#onError(error: Error): void {

package/src/kernels/rb/kernel.ts

@@ -1,10 +1,11 @@
 import { join } from "node:path";
 import type { BridgeConnectionConfig, KernelToHostMessage } from "../../bridge/protocol.ts";
 import type { SessionEnvironment } from "../session-env.ts";
+import type { KernelLifecycle } from "../shared/kernel-death.ts";
 import { type CodemodeRuntimeAssetEnvironment, requireCodemodeRuntimeAsset } from "../shared/runtime-asset.ts";
 import { SubprocessKernel, type SubprocessKernelMemory, type SubprocessSpawn } from "../shared/subprocess-kernel.ts";
 
-export interface RubyKernelStartOptions {
+export interface RubyKernelStartOptions extends KernelLifecycle {
 	readonly cwd: string;
 	readonly sessionId: string;
 	readonly connection: BridgeConnectionConfig;
@@ -41,6 +42,7 @@ export class RubyKernel extends SubprocessKernel {
 			spawn: options.spawn,
 			onMessage: options.onMessage,
 			memory: options.memory && { language: "rb", ...options.memory },
+			onDeath: options.onDeath,
 		});
 	}
 }

package/src/kernels/session-env.ts

@@ -17,6 +17,7 @@ export const SESSION_ENVIRONMENT_KEYS = [
 	"PI_PROVIDER",
 	"PI_MODEL",
 	"PI_REASONING_LEVEL",
+	"OMO_BROWSER_ENGINE",
 ] as const;
 
 /** Resolved per-session values for {@link SESSION_ENVIRONMENT_KEYS}; absent keys stay unset. */
@@ -32,6 +33,7 @@ export interface SessionEnvironmentSource {
 	};
 	readonly model?: { readonly provider: string; readonly id: string } | undefined;
 	readonly thinkingLevel?: string | undefined;
+	readonly browserEngine?: string | undefined;
 }
 
 export function sessionEnvironmentFrom(source: SessionEnvironmentSource): SessionEnvironment {
@@ -47,6 +49,7 @@ export function sessionEnvironmentFrom(source: SessionEnvironmentSource): Sessio
 		env.PI_MODEL = model.id;
 	}
 	if (source.thinkingLevel) env.PI_REASONING_LEVEL = source.thinkingLevel;
+	if (source.browserEngine) env.OMO_BROWSER_ENGINE = source.browserEngine;
 	return env;
 }
 

package/src/kernels/shared/kernel-death.ts

@@ -0,0 +1,39 @@
+import { constants } from "node:os";
+import type { EvalKernelResult, EvalLanguage } from "../../tool/types.ts";
+
+/** How the session manager hears that a kernel's interpreter died. */
+export interface KernelLifecycle {
+	/** Called once when the interpreter died on its own; the kernel then keeps its unstarted cells for `drainPending`. */
+	readonly onDeath?: (reason: string) => void;
+}
+
+/** The wording a restart notice uses for an exit nobody asked for: "signal 9", "exit code 1". */
+export function describeExit(code: number | null, signal: string | null): string {
+	if (signal !== null) {
+		const number = Object.entries(constants.signals).find(([name]) => name === signal)?.[1];
+		return `signal ${number ?? signal}`;
+	}
+	return code === null ? "an exit with no status" : `exit code ${code}`;
+}
+
+export function restartNotice(language: EvalLanguage, reason: string): string {
+	return `[${language} kernel was restarted after ${reason}; every global is lost]`;
+}
+
+export const EVAL_KERNEL_UNAVAILABLE = "eval_kernel_unavailable";
+
+/** A queued cell that never ran: its kernel died again before the replacement finished one cell. */
+export class KernelUnavailableError extends Error {
+	readonly name = "KernelUnavailableError";
+	readonly code = EVAL_KERNEL_UNAVAILABLE;
+
+	constructor(language: EvalLanguage, reason: string) {
+		super(
+			`${EVAL_KERNEL_UNAVAILABLE}: the ${language} kernel died again (${reason}) before its replacement finished a cell; this cell never ran. Run it again to start a fresh kernel.`,
+		);
+	}
+}
+
+export function unstartedResult(cellId: string, message: string): EvalKernelResult {
+	return { type: "result", cellId, ok: false, error: { message }, durationMs: 0, kernelState: "not-run" };
+}

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

@@ -2,6 +2,7 @@ import type { KernelMemoryThresholds } from "../../bridge/memory-protocol.ts";
 import type { BridgeConnectionConfig, KernelToHostMessage } from "../../bridge/protocol.ts";
 import type { EvalKernelRunInput, EvalLanguage } from "../../tool/types.ts";
 import type { SessionEnvironment } from "../session-env.ts";
+import type { KernelLifecycle } from "./kernel-death.ts";
 import type { FootprintReader } from "./kernel-memory-host.ts";
 import type { SubprocessSpawn } from "./subprocess-process.ts";
 
@@ -16,7 +17,7 @@ export interface SubprocessKernelMemory {
 	readonly readFootprint: FootprintReader;
 }
 
-export interface SubprocessKernelOptions {
+export interface SubprocessKernelOptions extends KernelLifecycle {
 	readonly command: string;
 	readonly args: readonly string[];
 	readonly cwd?: string;

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

@@ -1,9 +1,10 @@
 import type { HostToKernelMessage, KernelToHostMessage } from "../../bridge/protocol.ts";
 import { decodeBridgeFrame, encodeBridgeFrame, isKernelToHostMessage } from "../../bridge/protocol.ts";
-import type { KernelInterruptHandle } from "../../tool/types.ts";
+import type { KernelInterruptHandle, PendingCell } from "../../tool/types.ts";
 import type { KernelToolsInvokeOptions } from "../js/kernel-tools-types.ts";
 import { rejectKernelToolsUnavailable } from "../kernel-tools-unavailable.ts";
 import { applySessionEnvironment } from "../session-env.ts";
+import { describeExit } from "./kernel-death.ts";
 import { KernelMemoryHost } from "./kernel-memory-host.ts";
 import type { KernelResult, KernelRunInput, SubprocessKernelOptions, ToolCallMessage } from "./subprocess-contract.ts";
 import { type SubprocessLike, SubprocessProcess, type SubprocessSpawn, spawnSubprocess } from "./subprocess-process.ts";
@@ -19,6 +20,7 @@ import {
 	KernelRetirementError,
 	KernelStartupError,
 	type PendingRun,
+	settlePendingRun,
 	timeoutResult,
 } from "./subprocess-run.ts";
 
@@ -43,6 +45,7 @@ export class SubprocessKernel {
 	private retirementFailure: Error | null = null;
 	private failure: Error | null = null;
 	private closed = false;
+	private dead = false;
 
 	constructor(options: SubprocessKernelOptions) {
 		this.options = options;
@@ -52,6 +55,14 @@ export class SubprocessKernel {
 		this.spawnProcess();
 	}
 
+	isAlive(): boolean {
+		return !this.dead;
+	}
+
+	drainPending(): readonly PendingCell[] {
+		return this.runs.drain().map((run) => ({ input: run.input, settle: (result) => settlePendingRun(run, result) }));
+	}
+
 	run(input: KernelRunInput): Promise<KernelResult> {
 		if (this.closed) throw new KernelClosedError();
 		const run = this.runs.enqueue(input);
@@ -243,7 +254,27 @@ export class SubprocessKernel {
 		}
 		this.process = null;
 		this.processReady = false;
-		this.failClosed(new KernelExitedError(signal ?? code ?? "unknown"));
+		const error = new KernelExitedError(signal ?? code ?? "unknown");
+		if (this.options.onDeath) this.die(error, describeExit(code, signal), this.options.onDeath);
+		else this.failClosed(error);
+	}
+
+	/**
+	 * The interpreter exited on its own and is gone: the running cell fails once (its side effects may
+	 * already have happened), the cells that never started stay queued for `drainPending`, and the owner
+	 * replaces this instance. `run()` is never reached on it again.
+	 */
+	private die(error: Error, reason: string, onDeath: (reason: string) => void): void {
+		this.failure = error;
+		this.closed = true;
+		this.dead = true;
+		this.runs.clearToolCalls();
+		const active = this.runs.active;
+		if (active) {
+			this.runs.releaseActive(active);
+			this.runs.settle(active, failureResult(active, new Error(`${error.message}; every global is lost`)));
+		}
+		onDeath(reason);
 	}
 
 	private accepts(process: SubprocessProcess): boolean {