@code-yeongyu/senpi-codemode 2026.9.28-3 → 2026.9.28-5

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

@@ -1,7 +1,14 @@
 import type { EvalStatusEvent, HostToKernelMessage, KernelToHostMessage } from "../../bridge/protocol.ts";
-import { CHILD_LIFECYCLE_OP, INTERRUPT_ACK_OP } from "../../bridge/reserved.ts";
+import { CHILD_LIFECYCLE_OP, INTERRUPT_ACK_OP, MEMORY_COLLECTED_OP } from "../../bridge/reserved.ts";
 import type { KernelInterruptHandle } from "../../tool/types.ts";
-import { abandonedWorkerNote, awaitCooperativeSettlement, type WorkerRetirement } from "./interrupt-bounds.ts";
+import { KernelMemoryPolicy } from "../shared/kernel-memory.ts";
+import {
+	abandonedWorkerNote,
+	awaitCooperativeSettlement,
+	DEFAULT_INTERRUPT_BOUNDS,
+	type JavaScriptInterruptBounds,
+	type WorkerRetirement,
+} from "./interrupt-bounds.ts";
 import {
 	assertJavaScriptKernelOpen,
 	type JavaScriptKernelMode,
@@ -53,9 +60,13 @@ export class JavaScriptKernel {
 	#pendingToolCalls: ToolCallMessage[] = [];
 	/** Live cell children the worker reported; retired by the host when the worker itself is lost. */
 	readonly #childPids = new Set<number>();
+	readonly #memory: KernelMemoryPolicy | null;
+	readonly #interruptBounds: JavaScriptInterruptBounds;
 
 	constructor(options: JavaScriptKernelOptions) {
 		this.#options = options;
+		this.#interruptBounds = options.interruptBounds ?? DEFAULT_INTERRUPT_BOUNDS;
+		this.#memory = options.memory === undefined ? null : new KernelMemoryPolicy("js", options.memory);
 		this.#moduleLoader = new LocalModuleLoader(options);
 		this.#slot = new WorkerSlot(options, {
 			isOpen: () => this.#lifecycle === "open",
@@ -226,12 +237,16 @@ export class JavaScriptKernel {
 			run.interruptResult = { type: "result", cellId: run.input.cellId, ok: false, error: { message }, durationMs };
 			run.interruptAck ??= Promise.withResolvers<void>();
 			this.#slot.postMessage({ type: "interrupt", reason });
-			if ((await awaitCooperativeSettlement(run)) === "settled") return { retained: run.settledByWorker };
+			if ((await awaitCooperativeSettlement(run, this.#interruptBounds)) === "settled") {
+				return { retained: run.settledByWorker };
+			}
 			if (!this.#runs.releaseActive(run)) return { retained: run.settledByWorker };
 			const retirement = await this.#terminate();
 			this.#runs.settle(run, run.interruptResult ?? stoppedResult(run.input.cellId, message));
 			void this.#recover(() => Promise.resolve());
-			return retirement === "abandoned" ? { retained: false, note: abandonedWorkerNote() } : { retained: false };
+			return retirement === "abandoned"
+				? { retained: false, note: abandonedWorkerNote(this.#interruptBounds.terminateDeadlineMs) }
+				: { retained: false };
 		} finally {
 			this.#clearToolCalls();
 		}
@@ -275,6 +290,13 @@ export class JavaScriptKernel {
 			this.#trackChildEvent(message.event);
 			return;
 		}
+		if (message.type === "status" && message.event.op === MEMORY_COLLECTED_OP) {
+			const liveBytes = message.event.liveBytes;
+			if (typeof liveBytes !== "number") return;
+			this.#memory?.observeLive(liveBytes);
+			this.#options.onMemoryCollected?.(liveBytes);
+			return;
+		}
 		(this.#runs.active?.input.onMessage ?? this.#options.onMessage)?.(message);
 		if (message.type === "tool-call") {
 			const waiter = this.#toolWaiters.shift();
@@ -291,8 +313,21 @@ export class JavaScriptKernel {
 		this.#clearTimeout();
 		this.#runs.releaseActive(active);
 		active.settledByWorker = true;
-		this.#runs.settle(active, active.interruptResult ?? message);
+		this.#runs.settle(active, active.interruptResult ?? this.#withMemoryPolicy(message));
 		this.#startNext();
+		this.#recycleOverCeilingWhenIdle();
+	}
+
+	#withMemoryPolicy(message: ResultMessage): ResultMessage {
+		if (this.#memory === null || message.memory === undefined) return message;
+		return { ...message, memory: this.#memory.annotate(message.memory) };
+	}
+
+	/** A kernel over its memory ceiling restarts only once no cell is running or queued on it. */
+	#recycleOverCeilingWhenIdle(): void {
+		if (this.#memory?.recyclePending !== true || this.#runs.active || this.#runs.hasWaiting) return;
+		this.#memory.recycleStarted();
+		void this.#restartAfterStop();
 	}
 
 	#handleCrash(error: Error): void {
@@ -338,6 +373,7 @@ export class JavaScriptKernel {
 	async #terminate(): Promise<WorkerRetirement> {
 		this.#clearTimeout();
 		this.#kernelTools.rejectAll(kernelToolError("kernel_tool_stale", "JavaScript worker reset"));
+		this.#memory?.kernelRetired();
 		const retirement = await this.#slot.retire();
 		await this.#retireWorkerChildren();
 		return retirement;
@@ -348,5 +384,7 @@ export class JavaScriptKernel {
 		const pids = [...this.#childPids];
 		this.#childPids.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.#options.collectOrphanedChildren?.(pids);
 	}
 }

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

@@ -16,14 +16,20 @@ export interface CooperativeSettlementBounds {
 	readonly graceMs: number;
 }
 
-const DEFAULT_SETTLEMENT_BOUNDS: CooperativeSettlementBounds = {
+/** Every deadline an interrupt can hit; a kernel built with its own bounds chooses which stop path a slow cell takes. */
+export interface JavaScriptInterruptBounds extends CooperativeSettlementBounds {
+	readonly terminateDeadlineMs: number;
+}
+
+export const DEFAULT_INTERRUPT_BOUNDS: JavaScriptInterruptBounds = {
 	ackMs: INTERRUPT_ACK_MS,
 	graceMs: JS_INTERRUPT_GRACE_MS,
+	terminateDeadlineMs: WORKER_TERMINATE_DEADLINE_MS,
 };
 
 export async function awaitCooperativeSettlement(
 	run: PendingJavaScriptRun,
-	bounds = DEFAULT_SETTLEMENT_BOUNDS,
+	bounds: CooperativeSettlementBounds = DEFAULT_INTERRUPT_BOUNDS,
 ): Promise<CooperativeSettlement> {
 	if (run.settled) return "settled";
 	const settled = run.settlement.then((): "settled" => "settled");

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

@@ -1,6 +1,8 @@
+import type { KernelMemoryThresholds } from "../../bridge/memory-protocol.ts";
 import type { KernelToHostMessage } from "../../bridge/protocol.ts";
 import type { EvalKernelRunInput } from "../../tool/types.ts";
 import type { SessionEnvironment } from "../session-env.ts";
+import type { JavaScriptInterruptBounds } from "./interrupt-bounds.ts";
 
 export type ResultMessage = Extract<KernelToHostMessage, { type: "result" }>;
 export type ToolCallMessage = Extract<KernelToHostMessage, { type: "tool-call" }>;
@@ -18,6 +20,11 @@ export function resolveKernelToolNameSource(names?: KernelToolNameSource): strin
 export interface JavaScriptKernelOptions {
 	readonly sessionId: string;
 	readonly cwd: string;
+	/**
+	 * Collects the exit status of a retired worker's children once they are killed (#1962): no thread is left to
+	 * wait on them. Absent, they stay zombies until the host's child reaper or process exit collects them.
+	 */
+	readonly collectOrphanedChildren?: (pids: readonly number[]) => Promise<unknown>;
 	readonly parallelPoolWidth: number;
 	readonly onMessage?: (message: KernelToHostMessage) => void;
 	readonly workerEntryUrl?: URL;
@@ -27,6 +34,12 @@ export interface JavaScriptKernelOptions {
 	readonly hostToolNames?: KernelToolNameSource;
 	/** 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. */
+	readonly memory?: KernelMemoryThresholds;
+	/** Live heap bytes measured by an idle collection the worker ran between cells. */
+	readonly onMemoryCollected?: (liveBytes: number) => void;
+	/** Interrupt acknowledgement, settle grace, and worker-termination deadlines; absent uses `DEFAULT_INTERRUPT_BOUNDS`. */
+	readonly interruptBounds?: JavaScriptInterruptBounds;
 }
 
 export type JavaScriptRunInput = EvalKernelRunInput;

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

@@ -2,12 +2,14 @@ import { kernelToolCallContext } from "./kernel-tools-context.js";
 import { kernelToolError } from "./kernel-tools-errors.js";
 import { createKernelToolPump } from "./kernel-tools-pump.js";
 import { hostDeniedError, hostToolRefusal } from "./kernel-tools-scope.js";
+import { createWorkerMemory } from "./worker-memory.js";
 import { JsWorkerRuntime } from "./worker-runtime.js";
 import { installKernelWebView } from "./worker-webview.js";
 
-// Mirrors INTERRUPT_ACK_OP and CHILD_LIFECYCLE_OP in src/bridge/reserved.ts (this worker file cannot import TypeScript).
+// Mirrors INTERRUPT_ACK_OP, CHILD_LIFECYCLE_OP, and MEMORY_COLLECTED_OP in src/bridge/reserved.ts (this worker file cannot import TypeScript).
 const INTERRUPT_ACK_OP = "interrupt-ack";
 const CHILD_LIFECYCLE_OP = "child";
+const MEMORY_COLLECTED_OP = "memory-collected";
 
 // 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
@@ -24,6 +26,7 @@ const SESSION_ENVIRONMENT_KEYS = [
 
 export function createWorkerCore(transport, options) {
 	let runtime = null;
+	let memory = null;
 	let activeCell = null;
 	const pendingTools = new Map();
 	const pendingWebViewPorts = new Map();
@@ -50,14 +53,18 @@ export function createWorkerCore(transport, options) {
 				emit,
 				callTool: async (toolName, args) => await callTool(toolName, args),
 			});
-			emit({ type: "result", cellId: message.cellId, ok: true, valueRepr: valueRepr(value), durationMs: durationMs(startedAtMs) });
+			emit({ type: "result", cellId: message.cellId, ok: true, valueRepr: valueRepr(value), durationMs: durationMs(startedAtMs), ...memoryReport() });
 		} catch (error) {
-			emit({ type: "result", cellId: message.cellId, ok: false, error: bridgeError(error), durationMs: durationMs(startedAtMs) });
+			emit({ type: "result", cellId: message.cellId, ok: false, error: bridgeError(error), durationMs: durationMs(startedAtMs), ...memoryReport() });
 		} finally {
 			activeCell = null;
 		}
 	}
 
+	function memoryReport() {
+		return memory === null ? {} : { memory: memory.afterCell() };
+	}
+
 	async function callTool(toolName, args) {
 		const nested = kernelToolCallContext.getStore();
 		if (!nested && activeCell?.interruption) throw activeCell.interruption;
@@ -96,6 +103,7 @@ export function createWorkerCore(transport, options) {
 	}
 
 	function onMessage(message) {
+		if (message.type === "run" || message.type === "interrupt" || message.type === "close") memory?.cancelIdle();
 		if (kernelTools.handle(message)) return;
 		if (message.type === "kernel-tools-names") {
 			runtime?.kernelTools.setCollisionNames(message.hostToolNames ?? [], message.foreignLanguageNames ?? []);
@@ -121,6 +129,10 @@ export function createWorkerCore(transport, options) {
 				foreignLanguageNames: message.foreignLanguageNames ?? [],
 				onChildEvent: (event) => emit({ type: "status", event: { op: CHILD_LIFECYCLE_OP, ...event } }),
 			});
+			if (message.memory) {
+				memory = createWorkerMemory(message.memory, (report) => emit({ type: "status", event: { op: MEMORY_COLLECTED_OP, ...report } }));
+				memory.captureBaseline();
+			}
 			emit({ type: "ready" });
 			return;
 		}

package/src/kernels/js/worker-global-sizes.js

@@ -0,0 +1,123 @@
+import { types } from "node:util";
+
+const SAMPLED_ELEMENTS = 1_000;
+const NODE_BUDGET = 200_000;
+const MAX_DEPTH = 64;
+const POINTER_BYTES = 8;
+const OBJECT_BYTES = 16;
+const FUNCTION_BYTES = 64;
+const INTERNAL_GLOBAL_PREFIX = "__senpi";
+const MIN_REPORTED_BYTES = 1024 * 1024;
+
+export function captureGlobalBaseline() {
+	return new Set(Object.getOwnPropertyNames(globalThis));
+}
+
+/**
+ * Estimated retained size of each user global, largest first. Collections are sized from their length and
+ * a sample of up to 1,000 evenly spaced elements, so a huge array is not under-reported; a shared visited
+ * set counts shared objects once, and one node budget bounds the whole walk. A sampled or cut-short
+ * estimate is marked `approximate`. Accessors and proxies are never invoked.
+ */
+export function largestGlobals(baseline, limit) {
+	const sizer = createSizer();
+	const sized = [];
+	for (const name of Object.getOwnPropertyNames(globalThis)) {
+		if (baseline.has(name) || name.startsWith(INTERNAL_GLOBAL_PREFIX)) continue;
+		const descriptor = Object.getOwnPropertyDescriptor(globalThis, name);
+		if (descriptor === undefined || !("value" in descriptor)) continue;
+		const measured = sizer.measure(descriptor.value);
+		if (measured === undefined) continue;
+		const { bytes, approximate } = measured;
+		sized.push({ name, bytes: Math.round(bytes), ...(approximate ? { approximate: true } : {}) });
+	}
+	return sized
+		.filter((global) => global.bytes >= MIN_REPORTED_BYTES)
+		.sort((left, right) => right.bytes - left.bytes)
+		.slice(0, limit);
+}
+
+function createSizer() {
+	const seen = new WeakSet();
+	let nodes = 0;
+	let approximate = false;
+
+	function sampled(length, at, depth) {
+		if (length <= SAMPLED_ELEMENTS) {
+			let total = 0;
+			for (let index = 0; index < length; index += 1) total += size(at(index), depth);
+			return total;
+		}
+		approximate = true;
+		const step = length / SAMPLED_ELEMENTS;
+		let total = 0;
+		for (let sample = 0; sample < SAMPLED_ELEMENTS; sample += 1) total += size(at(Math.floor(sample * step)), depth);
+		return (total / SAMPLED_ELEMENTS) * length;
+	}
+
+	function entriesOf(iterable, count, depth, sizeOf) {
+		const taken = [];
+		for (const entry of iterable) {
+			taken.push(entry);
+			if (taken.length >= SAMPLED_ELEMENTS) break;
+		}
+		if (taken.length < count) approximate = true;
+		let total = 0;
+		for (const entry of taken) total += sizeOf(entry, depth);
+		return total * (count / Math.max(1, taken.length));
+	}
+
+	function objectSize(value, depth) {
+		if (types.isProxy(value)) return OBJECT_BYTES;
+		if (ArrayBuffer.isView(value)) return value.byteLength;
+		if (types.isAnyArrayBuffer(value)) return value.byteLength;
+		if (typeof Blob === "function" && value instanceof Blob) return value.size;
+		if (Array.isArray(value)) return OBJECT_BYTES + value.length * POINTER_BYTES + sampled(value.length, (index) => value[index], depth);
+		if (value instanceof Map) {
+			const entries = Map.prototype.entries.call(value);
+			return OBJECT_BYTES + value.size * 2 * POINTER_BYTES + entriesOf(entries, value.size, depth, ([key, item], at) => size(key, at) + size(item, at));
+		}
+		if (value instanceof Set) return OBJECT_BYTES + value.size * POINTER_BYTES + entriesOf(Set.prototype.values.call(value), value.size, depth, size);
+		const keys = Object.keys(value);
+		const propertyValue = (index) => {
+			const descriptor = Object.getOwnPropertyDescriptor(value, keys[index]);
+			return descriptor !== undefined && "value" in descriptor ? descriptor.value : undefined;
+		};
+		return OBJECT_BYTES + keys.length * POINTER_BYTES + sampled(keys.length, propertyValue, depth);
+	}
+
+	// Bytes a value owns beyond the pointer-sized slot its container already charged for it.
+	function size(value, depth) {
+		switch (typeof value) {
+			case "string":
+				return OBJECT_BYTES + value.length * 2;
+			case "function":
+				return FUNCTION_BYTES;
+			case "object":
+				break;
+			default:
+				return 0;
+		}
+		if (value === null || seen.has(value)) return 0;
+		if (depth >= MAX_DEPTH || nodes >= NODE_BUDGET) {
+			approximate = true;
+			return 0;
+		}
+		seen.add(value);
+		nodes += 1;
+		return objectSize(value, depth + 1);
+	}
+
+	return {
+		measure(value) {
+			approximate = false;
+			try {
+				return { bytes: POINTER_BYTES + size(value, 0), approximate };
+			} catch (error) {
+				// A user value can still throw from an exotic element read (an index getter); it is left unsized.
+				if (error instanceof Error) return undefined;
+				throw error;
+			}
+		},
+	};
+}

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

@@ -0,0 +1,59 @@
+import { getHeapStatistics, setFlagsFromString } from "node:v8";
+import { runInNewContext } from "node:vm";
+
+// Bun 1.4.3 ships its own idle collections (oven-sh/bun#43174, #43681), run by every JS thread including
+// Workers; the kernel's idle collection only fills that gap on older Bun and must not compete with it.
+const BUN_WITHOUT_IDLE_COLLECTIONS = "<1.4.3";
+
+/**
+ * Reads and collects this worker's own heap (a worker thread owns its VM on both runtimes).
+ *
+ * Bun: `heapStats()` refreshes only at collections and walks the whole heap, and `Bun.gc(false)` only
+ * requests an asynchronous collection, so the estimate runs a synchronous eden collection (`edenGC()`, a
+ * few ms) that accounts fresh ArrayBuffers, then reads `heapSize()` (it includes `extraMemorySize`). Node: the isolate's used heap plus external memory (ArrayBuffer backing stores); `Worker`
+ * rejects `--expose-gc` in `execArgv`, so the gc function comes from one new context created while the
+ * flag is briefly on, and the second call releases backing stores V8 frees one cycle late.
+ */
+export function createHeapProbe() {
+	const jsc = typeof globalThis.Bun?.gc === "function" ? process.getBuiltinModule?.("bun:jsc") : undefined;
+	if (jsc !== undefined && typeof jsc.heapSize === "function" && typeof jsc.edenGC === "function") {
+		return {
+			canCollect: true,
+			idleCollection: globalThis.Bun.semver.satisfies(globalThis.Bun.version, BUN_WITHOUT_IDLE_COLLECTIONS),
+			estimate() {
+				jsc.edenGC();
+				return jsc.heapSize();
+			},
+			collect() {
+				globalThis.Bun.gc(true);
+				return jsc.heapSize();
+			},
+		};
+	}
+	const gc = exposedGc();
+	const read = () => {
+		const stats = getHeapStatistics();
+		return stats.used_heap_size + (stats.external_memory ?? 0);
+	};
+	return {
+		canCollect: gc !== undefined,
+		idleCollection: gc !== undefined,
+		estimate: read,
+		collect() {
+			gc?.();
+			gc?.();
+			return read();
+		},
+	};
+}
+
+function exposedGc() {
+	if (typeof globalThis.gc === "function") return globalThis.gc;
+	setFlagsFromString("--expose-gc");
+	try {
+		const gc = runInNewContext("typeof gc === 'function' ? gc : undefined");
+		return typeof gc === "function" ? gc : undefined;
+	} finally {
+		setFlagsFromString("--no-expose-gc");
+	}
+}

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

@@ -0,0 +1,94 @@
+import { captureGlobalBaseline, largestGlobals } from "./worker-global-sizes.js";
+import { createHeapProbe } from "./worker-heap.js";
+
+const MIB = 1024 * 1024;
+const MIN_GROWTH_BYTES = 64 * MIB;
+const GROWTH_RATIO = 0.25;
+const NOTICE_GROWTH_RATIO = 1.25;
+const IDLE_COLLECT_DELAY_MS = 1_000;
+// A full collection costs at most 1/20 of the time since the previous one.
+const COLLECT_RATE_FLOOR = 20;
+const REPORTED_GLOBALS = 5;
+
+/**
+ * Post-cell memory policy of one JS kernel worker (thresholds come from `init`):
+ * - a settled cell whose heap estimate reached the ceiling, grew past the watermark by more than
+ *   max(64 MiB, 25%) since the last measurement, or crossed the notice line upward (or grew 25% past it)
+ *   gets a synchronous full collection before its result is sent, and the result reports the live size;
+ * - after any cell that leaves at least the watermark live, an idle full collection runs about a second
+ *   later unless the next run, interrupt, or close arrives first: a cell that only drops a global
+ *   allocates nothing, so nothing else would ever notice the garbage. Runtimes that collect idle
+ *   threads themselves (Bun 1.4.3+) skip this; the post-cell measurement above still runs everywhere.
+ */
+export function createWorkerMemory(thresholds, onIdleCollected, { heap = createHeapProbe(), now = () => performance.now() } = {}) {
+	let baseline = new Set();
+	let lastLive = 0;
+	let noticeRef = 0;
+	let lastCollectEnd = Number.NEGATIVE_INFINITY;
+	let lastCollectMs = 0;
+	let idleTimer = null;
+
+	function collect() {
+		const startedAt = now();
+		const live = heap.collect();
+		lastCollectEnd = now();
+		lastCollectMs = lastCollectEnd - startedAt;
+		lastLive = live;
+		if (live < thresholds.noticeBytes / 2) noticeRef = 0;
+		return live;
+	}
+
+	function needsCollection(estimate) {
+		const { gcWatermarkBytes, noticeBytes, ceilingBytes } = thresholds;
+		if (ceilingBytes > 0 && estimate >= ceilingBytes) return true;
+		if (gcWatermarkBytes > 0 && estimate >= gcWatermarkBytes) {
+			if (estimate > lastLive + Math.max(MIN_GROWTH_BYTES, lastLive * GROWTH_RATIO)) return true;
+		}
+		if (noticeBytes === 0 || estimate < noticeBytes) return false;
+		return lastLive < noticeBytes || noticeRef === 0 || estimate >= noticeRef * NOTICE_GROWTH_RATIO;
+	}
+
+	function worthNaming(live) {
+		const { noticeBytes, ceilingBytes } = thresholds;
+		return (noticeBytes > 0 && live >= noticeBytes) || (ceilingBytes > 0 && live >= ceilingBytes);
+	}
+
+	function cancelIdle() {
+		if (idleTimer !== null) clearTimeout(idleTimer);
+		idleTimer = null;
+	}
+
+	function scheduleIdle() {
+		if (!heap.idleCollection || thresholds.gcWatermarkBytes === 0 || lastLive < thresholds.gcWatermarkBytes) return;
+		const floorEnd = lastCollectEnd + COLLECT_RATE_FLOOR * lastCollectMs;
+		const delayMs = Math.max(IDLE_COLLECT_DELAY_MS, floorEnd - now());
+		idleTimer = setTimeout(() => {
+			idleTimer = null;
+			onIdleCollected({ liveBytes: Math.round(collect()), measure: "heap" });
+		}, delayMs);
+		idleTimer.unref?.();
+	}
+
+	return {
+		captureBaseline() {
+			baseline = captureGlobalBaseline();
+		},
+		cancelIdle,
+		afterCell() {
+			cancelIdle();
+			let liveBytes = heap.estimate();
+			const gcRan = heap.canCollect && needsCollection(liveBytes);
+			if (gcRan) liveBytes = collect();
+			const noticeLevel = gcRan && thresholds.noticeBytes > 0 && liveBytes >= thresholds.noticeBytes;
+			if (noticeLevel && (noticeRef === 0 || liveBytes >= noticeRef * NOTICE_GROWTH_RATIO)) noticeRef = liveBytes;
+			const globals = gcRan && worthNaming(liveBytes) ? largestGlobals(baseline, REPORTED_GLOBALS) : [];
+			scheduleIdle();
+			return {
+				liveBytes: Math.round(liveBytes),
+				measure: "heap",
+				...(gcRan ? { gcRan: true } : {}),
+				...(globals.length > 0 ? { globals } : {}),
+			};
+		},
+	};
+}

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

@@ -13,6 +13,10 @@ import { kernelToolError } from "./kernel-tools-errors.js";
 import { createKernelToolRegistry, createToolNamespace } from "./kernel-tools-registry.js";
 
 const PREPARED_CELL_PREFIX = "/*senpi:prepared-cell*/";
+// One stable source URL for the loader/contribution prelude: a per-cell URL makes
+// every cell a distinct eval source string, so the code cache gains one entry
+// per cell for text that is identical until contributions change.
+const PRELUDE_SOURCE_URL = "senpi:kernel-prelude";
 // How long a child gets to honour SIGTERM before SIGKILL. Short, because the
 // cell has already produced its value and the caller is waiting on settle.
 const CHILD_TERMINATION_GRACE_MS = 1_000;
@@ -57,7 +61,7 @@ export class JsWorkerRuntime {
 				if (!isPlainObject(prepared) || typeof prepared.prelude !== "string" || typeof prepared.code !== "string") throw new Error("Invalid prepared JavaScript cell payload");
 				({ prelude, code: cellCode } = prepared);
 			}
-			if (prelude) indirectEval(prelude, `${cellId}:prelude`);
+			if (prelude) indirectEval(prelude, PRELUDE_SOURCE_URL);
 			const value = await awaitMaybePromise(indirectEval(bindKernelBun(wrapUserCode(cellCode)), cellId));
 			await this.#drainPendingDisplays();
 			return value;

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

@@ -95,7 +95,9 @@ export class WorkerSlot {
 		const webViews = this.#webViews;
 		this.#worker = null;
 		this.#webViews = null;
-		const retirement = worker ? await retireWorker(worker) : "terminated";
+		const retirement = worker
+			? await retireWorker(worker, this.#options.interruptBounds?.terminateDeadlineMs)
+			: "terminated";
 		await webViews?.release();
 		return retirement;
 	}

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

@@ -67,6 +67,7 @@ async function initializeWorker(worker: WorkerLike, hooks: WorkerStartupHooks, s
 		hostToolNames: resolveKernelToolNameSource(options.hostToolNames),
 		foreignLanguageNames: resolveKernelToolNameSource(options.foreignLanguageNames),
 		...(options.sessionEnv === undefined ? {} : { sessionEnv: options.sessionEnv }),
+		...(options.memory === undefined ? {} : { memory: options.memory }),
 	});
 	await ready;
 }

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

@@ -1,3 +1,4 @@
+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";
@@ -15,6 +16,8 @@ export interface PythonKernelStartOptions {
 	readonly startupTimeoutMs?: number;
 	readonly onMessage?: (message: KernelToHostMessage) => void;
 	readonly spawnProcess?: KernelSpawnProcess;
+	/** Post-cell collection, notice, and ceiling thresholds sent on `init`; absent leaves memory unmanaged. */
+	readonly memory?: KernelMemoryThresholds;
 }
 
 export type PythonKernelRunOptions = EvalKernelRunInput;

package/src/kernels/py/kernel.ts

@@ -1,6 +1,7 @@
 import type { KernelInterruptHandle } from "../../tool/types.ts";
 import type { KernelToolsInvokeOptions } from "../js/kernel-tools-types.ts";
 import { rejectKernelToolsUnavailable } from "../kernel-tools-unavailable.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";
 import { failedPythonResult, PythonKernelTransport } from "./transport.ts";
@@ -22,11 +23,13 @@ export class PythonKernel {
 	#closePromise: Promise<void> | null = null;
 	#failure: Error | null = null;
 	readonly #preludes = new KernelPreludeTracker();
+	readonly #memory: KernelMemoryHost | null;
 	#generation = 0;
 	#closed = false;
 
 	private constructor(options: PythonKernelStartOptions) {
 		this.#options = options;
+		this.#memory = options.memory === undefined ? null : new KernelMemoryHost("py", options.memory);
 	}
 
 	static async start(options: PythonKernelStartOptions): Promise<PythonKernel> {
@@ -215,6 +218,7 @@ export class PythonKernel {
 
 	async #spawn(generation: number): Promise<void> {
 		if (this.#closed || generation !== this.#generation) throw new Error("Python kernel startup was superseded");
+		this.#memory?.processReplaced();
 		this.#transport = await PythonKernelTransport.start({
 			...this.#options,
 			onMessage: (message) => {
@@ -241,11 +245,20 @@ export class PythonKernel {
 		if (this.#transport !== transport) return;
 		const pending = this.#pending.get(result.cellId);
 		if (pending) {
-			(pending.input.onMessage ?? this.#options.onMessage)?.(result);
-			this.#settleRun(pending, result);
+			const annotated = this.#memory?.annotate(result) ?? result;
+			(pending.input.onMessage ?? this.#options.onMessage)?.(annotated);
+			this.#settleRun(pending, annotated);
 		}
 		// A result frame from the live runner proves the process survived the interrupt.
 		if (pending?.resolveStateRetained) pending.resolveStateRetained(true);
+		this.#recycleOverCeilingWhenIdle();
+	}
+
+	/** An over-ceiling kernel restarts only once no cell is running or queued on it. */
+	#recycleOverCeilingWhenIdle(): void {
+		if (!this.#memory?.claimRecycle(this.#active === null && this.#queue.length === 0)) return;
+		// A failed restart is recorded in #failure and rejects the next run; a superseded one lost to close/reset.
+		void this.reset().catch(() => undefined);
 	}
 
 	#onExit(transport: PythonKernelTransport, error: Error): void {