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

package/CHANGELOG.md

@@ -12,6 +12,40 @@
 
 ### Removed
 
+## [2026.10.10-4] - 2026-10-06
+
+### Breaking Changes
+
+### Added
+
+### Changed
+
+### Fixed
+
+- A detached eval cell that waits for its kernel to start now says so (`waiting for the js kernel to be ready`) instead of `queued behind  in the js kernel` with an empty predecessor ([#2790](https://github.com/code-yeongyu/senpi/issues/2790)).
+
+- A stopped (or failed) detached cell's result and notification show its buffered output instead of the live `1/1 cells running` frame, so a cancelled cell no longer reads as still running. The kernel-state note now says plainly whether the kernel was restarted: `The JavaScript worker was not restarted; variables from earlier cells are kept.` instead of `... remains running; its existing variables are preserved.`, or `The JavaScript worker was restarted; variables from earlier cells are lost.` instead of `... was unresponsive to interrupt and was restarted ...` (the worker may have answered the interrupt and still needed a restart) ([#2791](https://github.com/code-yeongyu/senpi/issues/2791)).
+
+- An isolated (`isolate: true`) eval cell's result names QuickJS as its runtime (`quickjs <version>, sandbox`) instead of the persistent kernel's Bun or Node runtime ([#2811](https://github.com/code-yeongyu/senpi/issues/2811)).
+
+### Removed
+
+## [2026.10.10-3] - 2026-10-06
+
+### Breaking Changes
+
+### Added
+
+- An opt-in process-isolated JavaScript kernel (`isolation.js: "process"` or `SENPI_CODEMODE_JS_ISOLATION=process`) runs each JavaScript kernel in its own subprocess instead of a worker thread, so a kernel crash (`SIGSEGV`, out-of-memory, `process.exit`, an uncaught error) can no longer take down the host session; the next cell runs on a replacement child with a restart notice naming the crash. It isolates crashes, not hostile code: a cell is trusted as in worker mode, and hostile code belongs in `isolate: true` sandbox cells ([#2752](https://github.com/code-yeongyu/senpi/issues/2752) tracks hostile-cell isolation). The child runs on the host's own runtime, exits as soon as its host is gone (including `SIGKILL`), carries large output and `BigInt`/`undefined` values as worker mode does, and its frames carry a per-process token so stray output is never taken for a frame. The default stays `"worker"` and worker-mode behaviour is unchanged ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+
+### Changed
+
+- The README now documents every eval surface (helpers, magic cells, settings, JavaScript isolation modes and sandbox cells), and CI checks it against the helper census, so a new helper cannot ship undocumented ([#2787](https://github.com/code-yeongyu/senpi/pull/2787)).
+
+### Fixed
+
+### Removed
+
 ## [2026.10.10-2] - 2026-10-05
 
 ### Breaking Changes

package/README.md

@@ -59,6 +59,75 @@ task-tool names are known.
 A missing optional interpreter removes that language from the session's `eval`
 schema; it is not an installation failure.
 
+### JavaScript process isolation
+
+By default the JavaScript kernel runs as a worker thread on the host's own
+runtime (`isolation.js: "worker"`). Setting `isolation.js: "process"` (or
+`SENPI_CODEMODE_JS_ISOLATION=process`, which wins over the file) runs each
+JavaScript kernel in its own subprocess instead, so a kernel crash (a native
+`SIGSEGV`, an out-of-memory, `process.exit`, an uncaught error) cannot take down
+the host session. The next cell runs on a replacement child, and its result
+carries the restart notice and names the crash.
+
+**Trust model.** Process mode isolates crashes, not hostile code. A cell runs in
+the same process that talks to the host, so it can reach everything that process
+holds, exactly as a worker-mode cell can. The frame token described below guards
+only against accidental corruption of the channel. Hostile code belongs in
+`isolate: true` sandbox cells. Hostile-cell isolation for process mode is tracked
+in [#2752](https://github.com/code-yeongyu/senpi/issues/2752).
+
+**Core dumps (Linux).** The kernel child marks itself non-dumpable at start
+(`prctl(PR_SET_DUMPABLE, 0)`). A Linux system that pipes core dumps to
+`systemd-coredump` or apport otherwise holds a crashed child until its dump is
+read, which froze the cell for about 30 s; without the dump the crash is reported
+at once, still naming its signal. Two side effects: no core file is written for a
+crash of the kernel child itself, and a same-user debugger cannot attach to it
+(`ptrace` needs a dumpable process). A cell's own subprocesses are unaffected,
+because `exec` resets the flag. Set `SENPI_KERNEL_CORE_DUMPS=1` to keep dumps and
+debugger access while debugging the kernel.
+
+How it works:
+
+- **Runtime.** The child runs on the host's own runtime: bun when senpi runs on
+  Bun, node otherwise. A compiled binary whose executable is neither falls back to
+  `bun` or `node` on `PATH`, preferring the host's kind. The badge names the
+  runtime that actually runs the child, for example `js (bun 1.4.x, process)`.
+- **Frames.** The host writes a random token as the child's first line on fd 0,
+  and every frame the child sends carries it. The host parses only lines that
+  carry the token; any other line (a cell's raw fd write, a child process's
+  output) is delivered as text. Frames are written in full. Large text is split
+  below the 10 MiB frame limit, and a result too large to return fails its cell,
+  not the kernel. A `BigInt` or an `undefined` field reaches the host as it does
+  in worker mode.
+- **File descriptors.** Under Bun, the control channel moves to a private
+  duplicate of fd 0, fd 0 becomes `/dev/null`, and fd 1 is re-pointed at a
+  pipe that a reader thread turns into `text` frames as it is written. The pipe is kept
+  blocking (a child that switches it to non-blocking is undone before every cell and around
+  every child process a cell starts),
+  so output is never held in memory while a cell is busy. A cell's direct
+  `process.stdout.write` or fd 1 write (or a child process inheriting fd 1)
+  arrives before that cell's result. In a bun child, raw fd 1 bytes are not
+  interleaved with `console` output in the order they were written. A node
+  child cannot move its fds: cell output shares the channel, and fd 0 is the
+  channel. If libc cannot be loaded through `bun:ffi`, a bun child runs
+  the same way and still starts; the first cell's stderr says why.
+- **Lifetime.** The child exits as soon as its control channel closes. That
+  covers every way the host ends, including `SIGKILL`. A watchdog thread also
+  compares the parent pid with the one recorded at start, so a child whose cell
+  never yields (a busy loop, a blocking call) still ends with its host, including
+  under a Linux subreaper. A process-mode kernel never outlives its host.
+- **Failed start.** There is no inline fallback in process mode. A failed start
+  settles the waiting cell with a capability-gap result naming the missing
+  runtime (`Install bun or node, or use isolation.js: "worker"`). The result's
+  memory reading is the child's process footprint.
+
+The default stays `"worker"`, and worker-mode behaviour is unchanged.
+
+To run the `environments` suites with bun children (the runtime the product
+uses), run them under bun: `SENPI_CODEMODE_JS_ISOLATION=process bunx --bun vitest
+run test/environments`. Under plain `vitest` the children follow the test
+runner's runtime, which is node.
+
 Python startup waits for the interpreter's `ready` event. It reports progress
 through `stdlib-imports`, `runtime-init`, and `host-init`; advancing to the next
 stage resets an inactivity guard rather than consuming a total startup budget.
@@ -266,7 +335,7 @@ Configuration is loaded in this order:
 | `prompt.advertiseHelpers` | `false` | When `true`, one pointer line to `tool_schema('eval:helpers')` is appended to the eval description. |
 | `kernelTools.enabled` | `true` | Allows cells to define kernel tools. `false` makes JavaScript `tool(fn)` and Python `@tool` refuse with `tools_unavailable`, naming this setting. |
 
-Every key in the table takes the effect its row describes. The one exception is `isolation.js`: it is accepted and validated now and takes effect with process isolation ([#2706](https://github.com/code-yeongyu/senpi/pull/2706)); until then the JavaScript kernel stays a worker.
+Every key in the table takes the effect its row describes.
 
 `SENPI_CODEMODE_PY`, `SENPI_CODEMODE_JS`, `SENPI_CODEMODE_RB`, and
 `SENPI_CODEMODE_JL` override the corresponding file setting. `1` or `true`
@@ -288,6 +357,8 @@ options object and asynchronous helpers are `await`-able.
 | --- | --- |
 | `display(value)` | Emits text, structured JSON, markdown, or image display data. Images reach the model only through `display`: pass a figure, raw image bytes (PNG/JPEG/GIF/WebP/BMP sniffed), a `data:` URL, a `Blob`-like or `Bun.Image` value, a marshalled tool result, or one of its `images[i]` frames. |
 | `print(value, ...)` | Emits text output. |
+| `text(value)` (rb, jl) | Emits `value` as one text item without separators (`print` joins its arguments and calls it). |
+| `display_image(base64, mime_type)` (rb, jl) | Emits an image from base64 data; `mime_type` defaults to `image/png` (Ruby: `mime_type:` keyword). |
 | `read(path, offset?, limit?)` | Reads text with 1-indexed line slicing. `local://` paths resolve under the session artifact root. |
 | `write(path, content)` | Creates parent directories and writes text. `local://` paths persist in the session artifact root. |
 | `env(key?, value?)` | Reads all kernel environment values, one value, or sets one value. Includes the session's `PI_*` values (see [Session environment](#session-environment)). |
@@ -299,7 +370,7 @@ options object and asynchronous helpers are `await`-able.
 | `completion(prompt, model?, system?, schema?)` | Requests a one-shot host completion; `schema` asks the host to parse structured output. |
 | `agent(prompt, ...)` | Delegates to the configured active `taskTools.task` tool. Supports background handles and structured JSON results. |
 | `wait(handles, timeout?, mode?)` | Blocks the cell until the given handles settle (agent handle records, `handle()` views, completion handles, closed workpools, or saved `{kind, id, run_epoch}` references). `mode` is `all` (values in input order; the first failed, cancelled, or lost handle raises), `any` (`{index, ref, value}` of the first success), or `settled` (one outcome per input slot). `timeout` is wall-clock seconds from entry; on expiry `eval_wait_timeout` is raised and nothing is cancelled. Rides the bridge-call path, so the run budget pauses while parked. Agent and workpool handles need the host's `EvalHandleHost` capability (`eval_wait_unavailable` without it); completion handles always work. Julia extends `Base.wait` for handle views (`wait(handle(node))`). Details: `tool_schema("eval:wait")`. |
-| `handle(node \| ref \| {pool_id})` | Returns a rich view: the legacy record's fields plus a non-enumerable `control` (Python: attribute on a `dict` subclass; Ruby: singleton method) with `status()`, `output(format?, offset?, limit?)`, `send(message)` (agent handles only), `cancel()` (idempotent for that run epoch; never touches a successor run), and `wait(timeout?)`. Every control call is fenced by owner, id, and `run_epoch` inside the task owner (`eval_handle_stale`, `eval_handle_forbidden`). `completion(prompt, handle: true)` returns such a view for a host completion. The `agent(..., handle: true)` record itself is unchanged. Details: `tool_schema("eval:helpers")`. |
+| `handle(node \| ref \| {pool_id})` | Returns a rich view: the legacy record's fields plus a non-enumerable `control` (Python: attribute on a `dict` subclass; Ruby: singleton method) with `.status()`, `.output(format?, offset?, limit?)`, `.send(message)` (agent handles only), `.cancel()` (idempotent for that run epoch; never touches a successor run), and `.wait(timeout?)`. Every control call is fenced by owner, id, and `run_epoch` inside the task owner (`eval_handle_stale`, `eval_handle_forbidden`). `completion(prompt, handle: true)` returns such a view for a host completion. The `agent(..., handle: true)` record itself is unchanged. Details: `tool_schema("eval:helpers")`. |
 | `workpool(agent, name, mode?, tools?)` | Creates a thin adapter over the normal host `workpool` tool; exposes `pool_id`, `push(items)`, `close()`, `inspect()`, and `cancel()`. JS awaits creation and operations. `tools` is a list of kernel-tool names this cell defined; the pool's workers may call exactly those, the host refuses any name the caller doesn't hold, and a value that isn't a list of names raises `invalid_tools`. Ruby and Julia define no kernel tools, so they have nothing to grant. |
 | `output(ids, format?, offset?, limit?)` | Delegates transcript retrieval to the configured active `taskTools.output` tool. |
 | `parallel(thunks)` | Runs thunks through the configured bounded pool while preserving input order. |
@@ -491,6 +562,13 @@ original sizes, then a plain-path notice such as
   package.
 - Task transcript formats are limited to full (`raw`) and trailing (`tail`)
   output. Query, JSON, and stripped metadata formats are task-engine concerns.
+- There is no `pool.wait()`: a workpool's aggregate is delivered by the host after
+  `close()`, so a kernel never blocks on another engine's workers.
+- There is no `code_mode_only` mode and no speculative cell execution; both are
+  deferred to a separate design (omo#9232) rather than approximated here.
+- Kernels are never shared across owners: each session (and each in-process child
+  with its own eval tool) owns its kernels, and handles are fenced by owner, id and
+  run epoch.
 
 ## Security and lifecycle
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/senpi-codemode",
-	"version": "2026.10.10-2",
+	"version": "2026.10.10-4",
 	"description": "Source-only senpi extension package for codemode evaluation tools",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -33,15 +33,15 @@
 	},
 	"dependencies": {
 		"@babel/parser": "8.0.4",
-		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.10-2",
+		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.10-4",
 		"quickjs-wasi": "3.6.2",
 		"typebox": "1.3.34"
 	},
 	"peerDependencies": {
-		"@code-yeongyu/senpi": "2026.10.10-2"
+		"@code-yeongyu/senpi": "2026.10.10-4"
 	},
 	"devDependencies": {
-		"@code-yeongyu/senpi": "2026.10.10-2"
+		"@code-yeongyu/senpi": "2026.10.10-4"
 	},
 	"keywords": [
 		"senpi",

package/src/bridge/protocol.ts

@@ -237,10 +237,15 @@ export function parseBridgeJsonLine(line: string, options: BridgeFrameOptions =
 export function decodeBridgeFrame(line: string, options: BridgeFrameOptions = {}): BridgeMessageDecodeResult {
 	const parsed = parseBridgeJsonLine(line, options);
 	if (!parsed.ok) return parsed;
-	if (Value.Check(bridgeMessageSchema, parsed.value)) {
-		return { ok: true, message: parsed.value };
+	return validateBridgeMessage(parsed.value);
+}
+
+/** Checks an already-parsed frame against the bridge schema (for transports that transform values before checking). */
+export function validateBridgeMessage(value: unknown): BridgeMessageDecodeResult {
+	if (Value.Check(bridgeMessageSchema, value)) {
+		return { ok: true, message: value };
 	}
-	const firstError = Value.Errors(bridgeMessageSchema, parsed.value)[0];
+	const firstError = Value.Errors(bridgeMessageSchema, value)[0];
 	const message = firstError ? `Invalid bridge message: ${firstError.message}` : "Invalid bridge message";
 	return { ok: false, error: { code: "invalid_message", message } };
 }

package/src/extension/kernel-registration.ts

@@ -63,11 +63,16 @@ export class SessionKernelRegistrations {
 }
 
 export function javaScriptKernelMemory(kernel: JavaScriptKernel): RegisteredKernelSource {
+	const measure = kernel.mode === "process" ? "footprint" : "heap";
 	return {
-		measure: "heap",
+		measure,
 		lastLiveBytes: () => kernel.lastLiveBytes,
 		busy: () => kernel.queueSnapshot().activeCellId !== null,
-		queryMemory: () => kernel.queryMemory(),
+		queryMemory: async () => {
+			const reading = await kernel.queryMemory();
+			return reading === undefined ? undefined : { liveBytes: reading.liveBytes, measure: reading.measure };
+		},
+		...(measure === "footprint" ? { pid: () => kernel.processPid } : {}),
 	};
 }
 

package/src/extension/runtime-factory.ts

@@ -2,6 +2,7 @@ import { type ExtensionContext, withBundledBunCommands } from "@code-yeongyu/sen
 import type { AgentExecuteTool } from "../bridges/agent-bridge.ts";
 import type { EvalSchemaToolInfo } from "../bridges/schema-bridge.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
+import { resolveJsIsolation } from "../config/feature-settings.ts";
 import { withoutUntrustedInterpreter } from "../config/project-trust.ts";
 import {
 	type CodemodeSettings,
@@ -17,6 +18,7 @@ import {
 	getInterpreterAvailability,
 	type InterpreterAvailability,
 } from "../interpreters/detect.ts";
+import { processRuntimeInfo } from "../kernels/js/process-worker.ts";
 import { sessionEnvironmentFrom } from "../kernels/session-env.ts";
 import { resolveSessionArtifactsDir } from "../output/streaming-output.ts";
 import type { EnabledEvalLanguages, EvalLanguage, EvalRuntimes } from "../tool/types.ts";
@@ -81,6 +83,7 @@ export async function createRuntime(
 		...(pyReason === undefined ? [] : [pyReason]),
 	]);
 	const enabledLanguages = enabledLanguagesFrom(settings, availability);
+	const jsProcessIsolation = resolveJsIsolation(settings) === "process";
 	const artifacts = resolveSessionArtifactsDir(ctx.sessionManager.getSessionFile());
 	const activeTools = new Set(pi.getActiveTools());
 	const executeTool = createExecuteTool(pi, activeTools);
@@ -108,7 +111,11 @@ export async function createRuntime(
 		parallelPoolWidth,
 		manager,
 		enabledLanguages,
-		runtimes: runtimesFromAvailability(availability, jsRuntimeInfo()),
+		runtimes: runtimesFromAvailability(
+			availability,
+			(jsProcessIsolation ? processRuntimeInfo(undefined) : undefined) ??
+				jsRuntimeInfo(process.versions, process.execPath, jsProcessIsolation),
+		),
 		settings,
 		artifactsDir: artifacts.dir,
 		executeTool,

package/src/extension/runtime-info.ts

@@ -10,10 +10,14 @@ export interface JsRuntimeVersions {
 export function jsRuntimeInfo(
 	versions: JsRuntimeVersions = process.versions,
 	execPath: string = process.execPath,
+	processIsolation = false,
 ): EvalRuntimeInfo {
 	const bun = versions.bun;
-	if (bun !== undefined && bun.length > 0) return { name: "bun", version: bun, path: execPath };
-	return { name: "node", version: versions.node, path: execPath };
+	const base =
+		bun !== undefined && bun.length > 0
+			? { name: "bun", version: bun, path: execPath }
+			: { name: "node", version: versions.node, path: execPath };
+	return processIsolation ? { ...base, isolation: "process" } : base;
 }
 
 /** Short host-line segment, e.g. "node 26.7.0" or "bun 1.4.0". */

package/src/extension/session-manager.ts

@@ -1,9 +1,10 @@
 import { join } from "node:path";
 import type { ExtensionContext } from "@code-yeongyu/senpi";
+import { readProcessFootprint } from "@code-yeongyu/senpi";
 import { type BridgeServerHandle, startBridgeServer } from "../bridge/http-server.ts";
 import type { KernelToHostMessage } from "../bridge/protocol.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
-import { resolveKernelToolsEnabled } from "../config/feature-settings.ts";
+import { resolveJsIsolation, resolveKernelToolsEnabled } from "../config/feature-settings.ts";
 import { resolveKernelMemoryThresholds } from "../config/memory-settings.ts";
 import { collectOrphanedChildren } from "../host-sdk.ts";
 import { JavaScriptKernel } from "../kernels/js/context-manager.ts";
@@ -254,6 +255,8 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 			this.#options.localRoots ??
 			(this.#options.artifactsDir ? { local: join(this.#options.artifactsDir, "local") } : undefined);
 		if (language === "js") {
+			const memoryThresholds = resolveKernelMemoryThresholds(this.#options.settings.memory);
+			const processIsolation = resolveJsIsolation(this.#options.settings) === "process";
 			const kernel = new JavaScriptKernel({
 				sessionId: this.#options.sessionId,
 				cwd: this.#options.cwd,
@@ -261,8 +264,12 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 				onMessage,
 				hostToolNames: () => this.#options.listTools?.().map((tool) => tool.name) ?? [],
 				foreignLanguageNames: () => this.#foreignKernelToolNames(),
-				memory: resolveKernelMemoryThresholds(this.#options.settings.memory),
+				memory: memoryThresholds,
 				collectOrphanedChildren,
+				...(processIsolation ? { isolation: "process" as const } : {}),
+				...(processIsolation && memoryThresholds !== undefined
+					? { processMemory: { thresholds: memoryThresholds, readFootprint: readProcessFootprint } }
+					: {}),
 				...(resolveKernelToolsEnabled(this.#options.settings) ? {} : { kernelToolsEnabled: false }),
 				...(this.#options.sessionEnv ? { sessionEnv: this.#options.sessionEnv } : {}),
 				...(localRoots ? { localRoots: { ...localRoots } } : {}),

package/src/kernels/AGENTS.md

@@ -16,6 +16,8 @@ runner/prelude assets).
 | Julia kernel | `jl/kernel.ts` + `jl/prelude.jl`, `jl/runner.jl` |
 | Shared subprocess layer | `shared/subprocess-kernel.ts`, `subprocess-{contract,process,queue,run}.ts`, `runtime-asset.ts` |
 | Session environment | `session-env.ts` (PI_* contract shared by all kernels; mirrors the core bash tool) |
+| JS process isolation | `js/process-worker.ts` (host side), `js/process-entry.js` (child entry), `js/kernel-memory.ts`, `js/control-frames.ts` |
+| Sandbox cells | `sandbox/sandbox-cell.ts` (host executor); `sandbox/vendor/pi-codemode/**` (vendored runtime, see its `VENDORED.md`) |
 
 ## CONVENTIONS
 

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

@@ -1,9 +1,9 @@
 import type { HostToKernelMessage, KernelToHostMessage } from "../../bridge/protocol.ts";
-import { CHILD_LIFECYCLE_OP, INTERRUPT_ACK_OP } from "../../bridge/reserved.ts";
 import type { KernelInterruptHandle } from "../../tool/types.ts";
 import { KernelToolHostPump } from "../shared/kernel-tools-pump.ts";
 import { ActiveCellControl } from "./active-cell-control.ts";
 import { dispatchCell } from "./cell-dispatch.ts";
+import { consumeControlFrame } from "./control-frames.ts";
 import { HostEntries } from "./host-entries.ts";
 import { DEFAULT_INTERRUPT_BOUNDS, JS_INTERRUPT_GRACE_MS, type WorkerRetirement } from "./interrupt-bounds.ts";
 import {
@@ -14,7 +14,8 @@ import {
 	type ResultMessage,
 	type ToolCallMessage,
 } from "./kernel-contract.ts";
-import { type JavaScriptMemoryReading, KernelMemoryBridge } from "./kernel-memory-bridge.ts";
+import { JavaScriptKernelMemory } from "./kernel-memory.ts";
+import type { JavaScriptMemoryReading } from "./kernel-memory-bridge.ts";
 import { kernelToolError } from "./kernel-tools-errors.ts";
 import type {
 	KernelToolsDescribeResult,
@@ -25,7 +26,6 @@ import { type JavaScriptKernelOptions, LocalModuleLoader } from "./local-module-
 import { JavaScriptRunQueue, type PendingJavaScriptRun } from "./run-queue.ts";
 import { ToolCallQueue } from "./tool-call-queue.ts";
 import { WorkerChildren } from "./worker-children.ts";
-import { crashedResult } from "./worker-host.ts";
 import { WorkerRecovery } from "./worker-recovery.ts";
 import { WorkerSlot } from "./worker-slot.ts";
 
@@ -57,7 +57,7 @@ export class JavaScriptKernel {
 	);
 	readonly #toolCalls = new ToolCallQueue();
 	readonly #children: WorkerChildren;
-	readonly #memory: KernelMemoryBridge;
+	readonly #memory: JavaScriptKernelMemory;
 	readonly #activeCell: ActiveCellControl;
 	readonly #recovery = new WorkerRecovery({
 		runs: this.#runs,
@@ -76,7 +76,7 @@ export class JavaScriptKernel {
 			recover: () => void this.#recovery.recover(() => Promise.resolve()),
 			clearToolCalls: () => this.#toolCalls.clear(),
 		});
-		this.#memory = new KernelMemoryBridge(options.memory, options.onMemoryCollected);
+		this.#memory = new JavaScriptKernelMemory(options, () => this.#slot.processPid);
 		this.#children = new WorkerChildren(options.collectOrphanedChildren);
 		this.#moduleLoader = new LocalModuleLoader(options);
 		this.#slot = new WorkerSlot(options, {
@@ -90,15 +90,20 @@ export class JavaScriptKernel {
 		return this.#slot.mode;
 	}
 
-	/** The last heap reading the worker sent (a result, an idle collection, a query); none before the first. */
+	/** The kernel process's pid in process mode; none in worker mode or before it starts. */
+	get processPid(): number | undefined {
+		return this.#slot.processPid;
+	}
+
+	/** The last memory reading (a result, an idle collection, a query); none before the first. */
 	get lastLiveBytes(): number | undefined {
 		return this.#memory.lastLiveBytes;
 	}
 
 	/** A heap reading taken between cells without running one; nothing when no worker is live to ask. */
 	async queryMemory(): Promise<JavaScriptMemoryReading | undefined> {
-		if (this.#lifecycle !== "open" || !this.#slot.present || this.#slot.startingUp) return undefined;
-		return await this.#memory.query((message) => this.#slot.postMessage(message));
+		const ready = this.#lifecycle === "open" && this.#slot.present && !this.#slot.startingUp;
+		return await this.#memory.query(ready ? (message) => this.#slot.postMessage(message) : undefined);
 	}
 
 	get kernelToolEvents(): EventTarget {
@@ -202,7 +207,13 @@ export class JavaScriptKernel {
 
 	async #ensureReady(): Promise<void> {
 		assertJavaScriptKernelOpen(this.#lifecycle, "run");
-		await this.#slot.ensureReady();
+		try {
+			await this.#slot.ensureReady();
+		} catch (error) {
+			if (this.#options.isolation !== "process") throw error;
+			// Process mode reports a failed start on the waiting cell, never as a rejection of run().
+			if (this.#lifecycle === "open") this.#runs.settleAll(error instanceof Error ? error.message : String(error));
+		}
 	}
 
 	#startNext(): void {
@@ -224,15 +235,7 @@ export class JavaScriptKernel {
 
 	#handleMessage(message: KernelToHostMessage): void {
 		if (this.#kernelTools.consume(message) && message.type !== "tool-call") return;
-		if (this.#memory.consume(message)) return;
-		if (message.type === "status" && message.event.op === INTERRUPT_ACK_OP) {
-			this.#runs.acknowledgeInterrupt(message.event);
-			return;
-		}
-		if (message.type === "status" && message.event.op === CHILD_LIFECYCLE_OP) {
-			this.#children.track(message.event);
-			return;
-		}
+		if (consumeControlFrame(message, { memory: this.#memory, runs: this.#runs, children: this.#children })) return;
 		(this.#runs.active?.input.onMessage ?? this.#options.onMessage)?.(message);
 		if (message.type === "tool-call") {
 			this.#toolCalls.push(message);
@@ -255,14 +258,10 @@ export class JavaScriptKernel {
 		if (!active && this.#slot.startingUp) return;
 		this.#activeCell.disarm();
 		this.#kernelTools.rejectAll(kernelToolError("kernel_tool_stale", error.message));
-		this.#memory.workerLost(error);
+		this.#memory.crashed(error);
 		// A crash mid-install stops the install (process group killed, nothing published); it settles itself once stopped.
 		if (active && !this.#hostEntries.abort(active, `JavaScript worker crashed: ${error.message}`)) {
-			this.#runs.releaseActive(active);
-			this.#runs.settle(
-				active,
-				crashedResult(active.input.cellId, error, this.#runs.durationMs(active, performance.now())),
-			);
+			this.#runs.settleCrashed(active, error);
 		}
 		this.#toolCalls.clear();
 		void this.#restartAfterStop();

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

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

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

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

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

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

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

@@ -0,0 +1,79 @@
+import type { HostToKernelMessage, KernelToHostMessage } from "../../bridge/protocol.ts";
+import { restartNotice } from "../shared/kernel-death.ts";
+import type { ResultMessage } from "./kernel-contract.ts";
+import { type JavaScriptMemoryReading, KernelMemoryBridge } from "./kernel-memory-bridge.ts";
+import type { JavaScriptKernelOptions } from "./local-module-loader.ts";
+import { JavaScriptProcessMemoryHost } from "./process-memory-host.ts";
+
+/**
+ * The kernel's one view of memory: the worker's heap bridge, or in process mode the child process's footprint, plus
+ * the restart notice a crash leaves for the next result.
+ */
+export class JavaScriptKernelMemory {
+	readonly #bridge: KernelMemoryBridge;
+	readonly #process: JavaScriptProcessMemoryHost | null;
+	readonly #pid: () => number | undefined;
+	readonly #processMode: boolean;
+	#restartNotice: string | null = null;
+
+	constructor(options: JavaScriptKernelOptions, pid: () => number | undefined) {
+		const processMode = options.isolation === "process";
+		this.#bridge = new KernelMemoryBridge(processMode ? undefined : options.memory, options.onMemoryCollected);
+		this.#process =
+			processMode && options.processMemory !== undefined
+				? new JavaScriptProcessMemoryHost(options.processMemory.thresholds, options.processMemory.readFootprint)
+				: null;
+		this.#pid = pid;
+		this.#processMode = processMode;
+	}
+
+	get lastLiveBytes(): number | undefined {
+		return this.#process === null ? this.#bridge.lastLiveBytes : this.#process.lastLiveBytes(this.#pid);
+	}
+
+	/** A reading between cells. The worker is asked only through `post`, given when a worker is ready to answer. */
+	async query(
+		post: ((message: HostToKernelMessage) => void) | undefined,
+	): Promise<JavaScriptMemoryReading | undefined> {
+		if (this.#process !== null) return this.#process.query(this.#pid);
+		return post === undefined ? undefined : await this.#bridge.query(post);
+	}
+
+	consume(message: KernelToHostMessage): boolean {
+		return this.#bridge.consume(message);
+	}
+
+	settled(message: ResultMessage): ResultMessage {
+		if (this.#process !== null) return this.#process.settled(message, this.#pid);
+		const settled = this.#bridge.settled(message);
+		if (this.#restartNotice === null) return settled;
+		const notice = this.#restartNotice;
+		this.#restartNotice = null;
+		return { ...settled, notice, kernelState: "restarted" };
+	}
+
+	/** Whether the kernel should restart for memory now; only once nothing is running or queued (`idle`). */
+	claimRecycle(idle: boolean): boolean {
+		const worker = this.#bridge.claimRecycle(idle);
+		return this.#process?.claimRecycle(idle) === true || worker;
+	}
+
+	/** The worker was retired: pending readings fail. */
+	workerLost(error: Error): void {
+		this.#bridge.workerLost(error);
+	}
+
+	/**
+	 * The kernel crashed: pending readings fail. In process mode the next result also says the kernel restarted (a
+	 * crashed child loses every global); worker mode reports its crash as it always has, with no notice.
+	 */
+	crashed(error: Error): void {
+		this.#bridge.workerLost(error);
+		if (this.#process !== null) {
+			this.#process.workerLost();
+			this.#process.markRestarted(error);
+			return;
+		}
+		if (this.#processMode) this.#restartNotice = restartNotice("js", error.message);
+	}
+}

package/src/kernels/js/process-drain-scan.d.ts

@@ -0,0 +1,8 @@
+export type DrainPart = { readonly text: string } | { readonly key: string };
+
+export interface DrainScan {
+	readonly parts: DrainPart[];
+	readonly carry: string;
+}
+
+export function scanDrainText(carry: string, chunk: string, marker: string): DrainScan;

package/src/kernels/js/process-drain-scan.js

@@ -0,0 +1,28 @@
+/**
+ * Splits text read from the process kernel's fd 1 pipe into the output it carries and the result keys its drain
+ * markers name, in order. A read boundary can cut a marker, so a trailing prefix of one is handed back as `carry` for
+ * the next read rather than sent as output.
+ *
+ * Self-contained on purpose: its source also runs inside the pipe reader thread (process-entry.js `DRAINER`).
+ */
+export function scanDrainText(carry, chunk, marker) {
+	let text = carry + chunk;
+	const parts = [];
+	for (;;) {
+		const at = text.indexOf(marker);
+		if (at === -1) break;
+		const close = text.indexOf("\u0000", at + marker.length);
+		if (close === -1) break;
+		if (at > 0) parts.push({ text: text.slice(0, at) });
+		parts.push({ key: text.slice(at + marker.length, close) });
+		text = text.slice(close + 1);
+	}
+	let nextCarry = "";
+	const partial = text.lastIndexOf("\u0000");
+	if (partial !== -1 && marker.startsWith(text.slice(partial, partial + marker.length))) {
+		nextCarry = text.slice(partial);
+		text = text.slice(0, partial);
+	}
+	if (text.length > 0) parts.push({ text });
+	return { parts, carry: nextCarry };
+}