@code-yeongyu/senpi-codemode 2026.10.6 → 2026.10.8

package/src/environments/revision-store.ts

@@ -0,0 +1,95 @@
+import { randomUUID } from "node:crypto";
+import { cp, mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { type LockWaitNotice, withRootLock } from "./install-lock.ts";
+import { EnvironmentError } from "./py-installer.ts";
+
+const POINTER = "active";
+const REVISION = /^rev-(\d+)$/;
+
+export interface Revision {
+	readonly number: number;
+	readonly dir: string;
+}
+
+export async function readActiveRevision(base: string): Promise<Revision | undefined> {
+	try {
+		const name = (await readFile(join(base, POINTER), "utf8")).trim();
+		const match = REVISION.exec(name);
+		return match?.[1] === undefined ? undefined : { number: Number(match[1]), dir: join(base, name) };
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+/**
+ * Builds the next revision under the root's lock: a staging copy of the active revision (so packages
+ * accumulate) is handed to `build`, renamed to `rev-<n>` only after `build` succeeds, and published by an
+ * atomic replace of the `active` pointer. A failed, cancelled or interrupted build is deleted; the
+ * previous revision stays active and is never modified, so a running kernel never sees a partial install.
+ */
+export async function publishNextRevision(
+	base: string,
+	build: (staging: string, previous: Revision | undefined) => Promise<void>,
+	signal?: AbortSignal,
+	onLockWait?: (notice: LockWaitNotice) => void,
+): Promise<{ readonly revision: Revision; readonly previous: Revision | undefined }> {
+	await mkdir(base, { recursive: true });
+	return withRootLock(
+		base,
+		async () => {
+			const previous = await readActiveRevision(base);
+			const number = Math.max(previous?.number ?? 0, await highestRevision(base)) + 1;
+			const staging = join(base, `.staging-rev-${number}-${process.pid}-${randomUUID()}`);
+			const dir = join(base, `rev-${number}`);
+			try {
+				if (previous === undefined) await mkdir(staging, { recursive: true });
+				else await cp(previous.dir, staging, { recursive: true, verbatimSymlinks: true });
+				await build(staging, previous);
+				signal?.throwIfAborted();
+				await renameRetrying(staging, dir);
+				const pointer = join(base, `.${POINTER}-${process.pid}-${randomUUID()}`);
+				await writeFile(pointer, `rev-${number}\n`);
+				await renameRetrying(pointer, join(base, POINTER));
+			} catch (error) {
+				await rm(staging, { recursive: true, force: true });
+				throw error;
+			}
+			return { revision: { number, dir }, previous };
+		},
+		signal,
+		onLockWait,
+	);
+}
+
+const RENAME_RETRY_DELAYS_MS = [20, 50, 100, 200, 400, 800];
+
+// On Windows a rename fails with EPERM/EBUSY/EACCES while another process (an indexer, antivirus) holds a
+// handle on the source or the replaced file; those holds are brief, so the rename is retried before failing.
+async function renameRetrying(from: string, to: string): Promise<void> {
+	for (let attempt = 0; ; attempt++) {
+		try {
+			await rename(from, to);
+			return;
+		} catch (error) {
+			const code = error instanceof Error && "code" in error ? error.code : undefined;
+			const transient = code === "EPERM" || code === "EBUSY" || code === "EACCES";
+			const delay = RENAME_RETRY_DELAYS_MS[attempt];
+			if (!transient || delay === undefined) {
+				const reason = error instanceof Error ? error.message : String(error);
+				throw new EnvironmentError("environment_install_failed", `could not publish the new revision: ${reason}`);
+			}
+			await new Promise((resolve) => setTimeout(resolve, delay));
+		}
+	}
+}
+
+async function highestRevision(base: string): Promise<number> {
+	let highest = 0;
+	for (const entry of await readdir(base)) {
+		const match = REVISION.exec(entry);
+		if (match?.[1] !== undefined) highest = Math.max(highest, Number(match[1]));
+	}
+	return highest;
+}

package/src/extension/bridge-dispatch.ts

@@ -0,0 +1,41 @@
+import type { ExtensionContext } from "@code-yeongyu/senpi";
+import type { BridgeHttpCompletionRequest } from "../bridge/http-server.ts";
+import { startCompletionHandle, wantsCompletionHandle } from "../completion/handle.ts";
+import type { CompletionRequest } from "../completion/handler.ts";
+import { resolveHardLimitSeconds } from "../config/settings.ts";
+import type { CreateCodemodeSessionManagerOptions } from "./session-manager-contract.ts";
+
+export interface BridgeDispatchContext {
+	/** The context of the cell that last reached the manager; the handle host and completion owner are read from it. */
+	readonly context: ExtensionContext | undefined;
+	readonly contextFor: (signal: AbortSignal) => ExtensionContext;
+	readonly requireContext: () => ExtensionContext;
+}
+
+/**
+ * `completion(prompt, handle=True)` from a subprocess kernel: the handle lives in the session registry and is
+ * bounded by the hard limit measured from this request, the tightest bound the bridge knows for its cell.
+ */
+export async function dispatchBridgeCompletion(
+	options: CreateCodemodeSessionManagerOptions,
+	request: BridgeHttpCompletionRequest,
+	dispatch: BridgeDispatchContext,
+): Promise<unknown> {
+	const completion: CompletionRequest = { prompt: request.prompt, opts: request.opts };
+	if (!wantsCompletionHandle(request.opts)) {
+		return await options.complete(completion, dispatch.contextFor(request.signal));
+	}
+	const registry = options.handles;
+	if (registry === undefined) {
+		throw Object.assign(new Error("eval_wait_unavailable: completion handles are not available in this session"), {
+			code: "eval_wait_unavailable",
+		});
+	}
+	return startCompletionHandle({
+		registry,
+		request: completion,
+		complete: options.complete,
+		ctx: dispatch.requireContext(),
+		deadlineMs: Date.now() + resolveHardLimitSeconds(options.settings) * 1_000,
+	});
+}

package/src/extension/bridge-tool-call.ts

@@ -1,3 +1,4 @@
+import type { EvalHandleHost } from "@code-yeongyu/senpi";
 import { isReservedToolName, runReservedTool } from "../bridges/reserved-dispatch.ts";
 import { defaultCodemodeSettings } from "../config/settings.ts";
 import { marshalToolResult } from "../tool/image.ts";
@@ -16,8 +17,9 @@ export interface BridgeToolCallRequest {
 // and ordinary tool results are marshalled to { text, images, details, hasError } — the raw
 // { content } shape left python cells unable to reach tool.read image blocks.
 export async function routeBridgeToolCall(
-	options: Pick<CreateCodemodeSessionManagerOptions, "executeTool" | "listTools" | "settings">,
+	options: Pick<CreateCodemodeSessionManagerOptions, "executeTool" | "listTools" | "settings" | "handles">,
 	request: BridgeToolCallRequest,
+	evalHandleHost?: EvalHandleHost,
 ): Promise<unknown> {
 	if (!isReservedToolName(request.toolName)) {
 		return marshalToolResult(await options.executeTool(request.toolName, request.args, { signal: request.signal }));
@@ -33,5 +35,7 @@ export async function routeBridgeToolCall(
 		signal: request.signal,
 		emitStatus: () => {},
 		marshalToolResult,
+		...(options.handles === undefined ? {} : { handles: options.handles }),
+		...(evalHandleHost === undefined ? {} : { evalHandleHost }),
 	});
 }

package/src/extension/host-facts.ts

@@ -0,0 +1,18 @@
+import * as os from "node:os";
+import { jsRuntimeLabel } from "./runtime-info.ts";
+
+/** The one-line host description the eval prompt shows (platform, CPU, cores, JS runtime). */
+export function hostLine(): string {
+	const cpu = os.cpus()[0]?.model?.trim();
+	return [`${os.platform()} ${os.arch()}`, cpu, `${os.availableParallelism()} cores`, jsRuntimeLabel()]
+		.filter((part): part is string => !!part)
+		.join(" \u00b7 ");
+}
+
+/** The model id carried by a `model_select` event, when it has one. */
+export function modelIdFrom(event: unknown): string | undefined {
+	if (typeof event !== "object" || event === null || !("model" in event)) return undefined;
+	const model = event.model;
+	if (typeof model !== "object" || model === null || !("id" in model)) return undefined;
+	return typeof model.id === "string" ? model.id : undefined;
+}

package/src/extension/kernel-registration.ts

@@ -4,6 +4,7 @@ import type { BridgeConnectionConfig, KernelToHostMessage } from "../bridge/prot
 import { JuliaKernel } from "../kernels/jl/kernel.ts";
 import type { JavaScriptKernel } from "../kernels/js/context-manager.ts";
 import { PythonKernel } from "../kernels/py/kernel.ts";
+import type { PeerKernelToolsDescribe } from "../kernels/py/kernel-tools-host.ts";
 import { defaultSpawn } from "../kernels/py/process.ts";
 import { RubyKernel } from "../kernels/rb/kernel.ts";
 import type { SessionEnvironment } from "../kernels/session-env.ts";
@@ -27,6 +28,7 @@ export interface SubprocessKernelStart {
 		readonly connection: BridgeConnectionConfig;
 		readonly onMessage: (message: KernelToHostMessage) => void;
 	};
+	readonly peerKernelToolsDescribe?: PeerKernelToolsDescribe;
 }
 
 export function registerKernel(sessionId: string, language: EvalLanguage, memory: RegisteredKernelSource): string {
@@ -82,6 +84,9 @@ export async function startSubprocessKernel(start: SubprocessKernelStart): Promi
 			...shared,
 			interpreterPath: start.interpreterPath,
 			memory,
+			...(start.peerKernelToolsDescribe === undefined
+				? {}
+				: { peerKernelToolsDescribe: start.peerKernelToolsDescribe }),
 			spawnProcess: (options) => {
 				const child = defaultSpawn(options);
 				pid = child.pid;

package/src/extension/removed-tool-hints.ts

@@ -0,0 +1,15 @@
+/** Migration guidance for the tools eval replaced; the host returns it when a model calls them. */
+export interface RemovedToolHintRegistrar {
+	registerRemovedToolHint(name: string, hint: string): void;
+}
+
+export const WAIT_REMOVED_TOOL_HINT =
+	"wait is not a tool; inside a cell use the wait(handles) helper (tool_schema('eval:wait')), or let detached cells notify.";
+
+export function registerRemovedToolHints(pi: RemovedToolHintRegistrar): void {
+	pi.registerRemovedToolHint(
+		"exec",
+		'exec was removed; use eval({ language: "js", code }) instead. Long eval cells detach on their own and notify when complete.',
+	);
+	pi.registerRemovedToolHint("wait", WAIT_REMOVED_TOOL_HINT);
+}

package/src/extension/runtime-factory.ts

@@ -8,6 +8,7 @@ import {
 	type ResolvedCodemodeSettings,
 	resolveEnabledLanguages,
 } from "../config/settings.ts";
+import type { HandleRegistry } from "../handles/handle-registry.ts";
 import {
 	createInterpreterDetector,
 	getInterpreterAvailability,
@@ -54,6 +55,7 @@ export async function createRuntime(
 	event: unknown,
 	complete: (request: CompletionRequest, ctx: ExtensionContext) => Promise<CompletionResult>,
 	options: RuntimeFactoryOptions,
+	handles?: HandleRegistry,
 ): Promise<SessionRuntime> {
 	const loaded = await loadCodemodeSettings({ cwd: ctx.cwd });
 	const settings: ResolvedCodemodeSettings = {
@@ -81,6 +83,7 @@ export async function createRuntime(
 		executeTool,
 		listTools: () => pi.getAllTools(),
 		complete,
+		...(handles === undefined ? {} : { handles }),
 	});
 	return {
 		sessionId,

package/src/extension/session-manager-contract.ts

@@ -2,6 +2,7 @@ import type { ExtensionContext } from "@code-yeongyu/senpi";
 import type { EvalSchemaToolInfo } from "../bridges/schema-bridge.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
 import type { CodemodeSettings } from "../config/settings.ts";
+import type { HandleRegistry } from "../handles/handle-registry.ts";
 import type { InterpreterAvailability } from "../interpreters/detect.ts";
 import type { SessionEnvironment } from "../kernels/session-env.ts";
 import type { EvalKernelManager, ExecuteTool } from "../tool/types.ts";
@@ -39,4 +40,6 @@ export interface CreateCodemodeSessionManagerOptions {
 	readonly executeTool: ExecuteTool;
 	readonly listTools?: () => readonly EvalSchemaToolInfo[];
 	readonly complete: (request: CompletionRequest, ctx: ExtensionContext) => Promise<CompletionResult>;
+	/** The session generation's handle registry; subprocess kernels reach `wait()`/`handle()` through the bridge. */
+	readonly handles?: HandleRegistry;
 }

package/src/extension/session-manager.ts

@@ -6,8 +6,10 @@ import type { CompletionRequest, CompletionResult } from "../completion/handler.
 import { resolveKernelMemoryThresholds } from "../config/memory-settings.ts";
 import { collectOrphanedChildren } from "../host-sdk.ts";
 import { JavaScriptKernel } from "../kernels/js/context-manager.ts";
+import type { KernelToolsDescribeResult } from "../kernels/js/kernel-tools-types.ts";
 import type { KernelLifecycle } from "../kernels/shared/kernel-death.ts";
 import type { EvalKernel, EvalLanguage } from "../tool/types.ts";
+import { type BridgeDispatchContext, dispatchBridgeCompletion } from "./bridge-dispatch.ts";
 import { type BridgeToolCallRequest, routeBridgeToolCall } from "./bridge-tool-call.ts";
 import { parkWhenIdle } from "./idle-parking-kernel.ts";
 import {
@@ -73,16 +75,23 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 	}
 
 	async start(): Promise<void> {
+		const manager = this;
+		const dispatch: BridgeDispatchContext = {
+			get context() {
+				return manager.#context;
+			},
+			contextFor: (signal) => this.#contextFor(signal),
+			requireContext: () => this.#requireContext(),
+		};
 		this.#bridge = await startBridgeServer({
 			onCall: async (request) => await this.#call(request),
 			onEmit: async () => undefined,
-			onCompletion: async (request) =>
-				this.#options.complete({ prompt: request.prompt, opts: request.opts }, this.#contextFor(request.signal)),
+			onCompletion: async (request) => await dispatchBridgeCompletion(this.#options, request, dispatch),
 		});
 	}
 
 	async #call(request: BridgeToolCallRequest): Promise<unknown> {
-		return await routeBridgeToolCall(this.#options, request);
+		return await routeBridgeToolCall(this.#options, request, this.#context?.evalHandleHost);
 	}
 
 	async getKernel(language: EvalLanguage, onMessage: (message: KernelToHostMessage) => void): Promise<EvalKernel> {
@@ -268,7 +277,20 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 			...lifecycle,
 		};
 		const memory = resolveKernelMemoryThresholds(this.#options.settings.memory);
-		return await startSubprocessKernel({ language, interpreterPath: detected.path, memory, shared });
+		return await startSubprocessKernel({
+			language,
+			interpreterPath: detected.path,
+			memory,
+			shared,
+			peerKernelToolsDescribe: (names) => this.#javaScriptKernelToolsDescribe(names),
+		});
+	}
+
+	/** Only an already running JavaScript kernel can define a colliding name; none is started for this. */
+	#javaScriptKernelToolsDescribe(names: readonly string[]): Promise<KernelToolsDescribeResult> | undefined {
+		const js = this.#kernels.get("js");
+		if (!js || !("describeKernelTools" in js) || typeof js.describeKernelTools !== "function") return undefined;
+		return (js.describeKernelTools as (names: readonly string[]) => Promise<KernelToolsDescribeResult>)(names);
 	}
 
 	#foreignKernelToolNames(): string[] {
@@ -280,9 +302,14 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 		return names;
 	}
 
-	#contextFor(signal: AbortSignal): ExtensionContext {
+	#requireContext(): ExtensionContext {
 		const ctx = this.#context;
 		if (!ctx) throw new CodemodeContextUnavailableError();
+		return ctx;
+	}
+
+	#contextFor(signal: AbortSignal): ExtensionContext {
+		const ctx = this.#requireContext();
 		return { ...ctx, signal: ctx.signal ? AbortSignal.any([ctx.signal, signal]) : signal };
 	}
 }

package/src/extension/start-recovery.ts

@@ -0,0 +1,111 @@
+import { createHash } from "node:crypto";
+import type { ExtensionContext } from "@code-yeongyu/senpi";
+import type { createEvalTool } from "../tool/eval-tool.ts";
+import { CodemodeSessionDisposedError } from "./session-manager.ts";
+import { CodemodeSessionNotStartedError } from "./session-manager-proxy.ts";
+
+export class CodemodeRuntimeRecreationError extends Error {
+	readonly name = "CodemodeRuntimeRecreationError";
+
+	constructor(reason: string) {
+		super(`codemode runtime could not be re-created: ${reason}. Start a new session or reload to bring eval back.`);
+	}
+}
+
+type StartSession = (event: unknown, ctx: ExtensionContext) => Promise<void>;
+
+/**
+ * A session_start whose runtime could not be created leaves the session running with no usable manager. The
+ * next eval re-creates the runtime once for that failed start (concurrent evals share the attempt) and runs; a
+ * failed re-creation is reported to every later eval until the next session_start. One stderr line names the
+ * failed start with a hashed session id so a recurrence stays visible. A session that ended is never recovered.
+ */
+export class StartRecovery {
+	readonly #startSession: StartSession;
+	readonly #report: (line: string) => void;
+	#failedStartEvent: { readonly event: unknown } | undefined;
+	#recreation: Promise<void> | undefined;
+	#recreationFailure: CodemodeRuntimeRecreationError | undefined;
+
+	constructor(
+		startSession: StartSession,
+		report: (line: string) => void = (line) => globalThis.process.stderr.write(`${line}\n`),
+	) {
+		this.#startSession = startSession;
+		this.#report = report;
+	}
+
+	async runStart(event: unknown, ctx: ExtensionContext): Promise<void> {
+		try {
+			await this.#startSession(event, ctx);
+			this.#reset();
+		} catch (error) {
+			this.#reset();
+			this.#failedStartEvent = { event };
+			throw error;
+		}
+	}
+
+	sessionEnded(): void {
+		this.#reset();
+	}
+
+	wrapExecute<Args extends unknown[], Result>(
+		execute: (...args: Args) => Promise<Result>,
+		contextOf: (args: Args) => ExtensionContext,
+	): (...args: Args) => Promise<Result> {
+		return async (...args) => {
+			try {
+				return await execute(...args);
+			} catch (error) {
+				if (!(error instanceof CodemodeSessionDisposedError || error instanceof CodemodeSessionNotStartedError)) {
+					throw error;
+				}
+				if (this.#recreationFailure !== undefined) throw this.#recreationFailure;
+				const recreation = this.#recreation ?? this.#beginRecreation(contextOf(args));
+				if (recreation === undefined) throw error;
+				await recreation;
+				return await execute(...args);
+			}
+		};
+	}
+
+	#beginRecreation(ctx: ExtensionContext): Promise<void> | undefined {
+		const failed = this.#failedStartEvent;
+		if (failed === undefined) return undefined;
+		this.#report(
+			`[senpi-codemode] eval re-created a runtime left disposed by a failed session_start (session ${sessionHash(ctx)})`,
+		);
+		const recreation = this.#startSession(failed.event, ctx).then(
+			() => {
+				this.#recreation = undefined;
+				this.#reset();
+			},
+			(error: unknown) => {
+				this.#recreation = undefined;
+				this.#recreationFailure = new CodemodeRuntimeRecreationError(
+					error instanceof Error ? error.message : String(error),
+				);
+				throw this.#recreationFailure;
+			},
+		);
+		this.#recreation = recreation;
+		return recreation;
+	}
+
+	#reset(): void {
+		this.#failedStartEvent = undefined;
+		this.#recreationFailure = undefined;
+	}
+}
+
+export function withStartRecovery<Tool extends ReturnType<typeof createEvalTool>>(
+	recovery: StartRecovery,
+	tool: Tool,
+): Tool {
+	return { ...tool, execute: recovery.wrapExecute(tool.execute, (args) => args[4]) };
+}
+
+function sessionHash(ctx: ExtensionContext): string {
+	return createHash("sha256").update(ctx.sessionManager.getSessionId()).digest("hex").slice(0, 12);
+}

package/src/handles/completion-handles.ts

@@ -0,0 +1,202 @@
+import { randomBytes } from "node:crypto";
+import {
+	type CancelReceipt,
+	EvalHandleError,
+	type HandleError,
+	type HandleOutcome,
+	type HandlePhase,
+	type HandleRef,
+	type HandleSnapshot,
+	type HandleWatch,
+	type OutputRequest,
+	type OutputSnapshot,
+} from "@code-yeongyu/senpi";
+import { refKey } from "./handle-args.ts";
+import { WatchQueue } from "./watch-queue.ts";
+
+export interface CompletionStart {
+	/** Runs the host completion; the signal aborts on cancel, on the deadline, and when the session generation drops. */
+	readonly run: (signal: AbortSignal) => Promise<unknown>;
+	/** Absolute wall-clock deadline (ms), derived from the creating cell's hard deadline. */
+	readonly deadlineMs: number;
+}
+
+interface CompletionEntry {
+	readonly ref: HandleRef;
+	phase: HandlePhase;
+	hostStatus: string;
+	revision: number;
+	value?: unknown;
+	error?: HandleError;
+	readonly controller: AbortController;
+	timer: ReturnType<typeof setTimeout> | undefined;
+	deadlineHit: boolean;
+}
+
+const TERMINAL: ReadonlySet<HandlePhase> = new Set(["succeeded", "failed", "cancelled", "lost"]);
+const DEADLINE_MESSAGE = "completion handle exceeded its cell's hard deadline";
+const MAX_TIMER_MS = 2 ** 31 - 1;
+
+/**
+ * codemode-owned completion handles (`completion(prompt, {handle: true})`). They live in the session's
+ * registry, so they survive a kernel restart and need no host capability; once the session generation
+ * is dropped every ref fails closed with `eval_handle_stale`.
+ */
+export class CompletionHandles {
+	readonly #entries = new Map<string, CompletionEntry>();
+	readonly #watches = new Set<WatchQueue>();
+	readonly #now: () => number;
+	#disposed = false;
+
+	constructor(now: () => number = Date.now) {
+		this.#now = now;
+	}
+
+	start(input: CompletionStart): HandleRef {
+		this.#assertLive();
+		const ref: HandleRef = { kind: "completion", id: `cp_${randomBytes(16).toString("hex")}`, run_epoch: 0 };
+		const controller = new AbortController();
+		const entry: CompletionEntry = {
+			ref,
+			phase: "pending",
+			hostStatus: "running",
+			revision: 1,
+			controller,
+			timer: undefined,
+			deadlineHit: false,
+		};
+		this.#entries.set(ref.id, entry);
+		const remainingMs = Math.min(MAX_TIMER_MS, Math.max(0, input.deadlineMs - this.#now()));
+		if (Number.isFinite(remainingMs)) {
+			entry.timer = setTimeout(() => {
+				entry.deadlineHit = true;
+				controller.abort(new Error(DEADLINE_MESSAGE));
+			}, remainingMs);
+			entry.timer.unref?.();
+		}
+		input.run(controller.signal).then(
+			(value) => this.#settle(entry, { phase: "succeeded", hostStatus: "completed", value }),
+			(error: unknown) => {
+				// cancel() and dispose() settle the entry before aborting; their rejection is not an outcome.
+				if (TERMINAL.has(entry.phase)) return;
+				const hostStatus = entry.deadlineHit ? "deadline" : "failed";
+				this.#settle(entry, { phase: "failed", hostStatus, error: toHandleError(error, entry.deadlineHit) });
+			},
+		);
+		return ref;
+	}
+
+	get openWatches(): number {
+		return this.#watches.size;
+	}
+
+	owns(ref: HandleRef): boolean {
+		return ref.kind === "completion";
+	}
+
+	watch(refs: readonly HandleRef[]): HandleWatch {
+		const entries = refs.map((ref) => this.#fence(ref));
+		const queue = new WatchQueue(refs.map(refKey));
+		// Subscribe first, then snapshot: a settle between the two is queued and arrives in updates once.
+		this.#watches.add(queue);
+		const initial = entries.map((entry) => snapshotOf(entry));
+		return queue.toWatch(initial, () => this.#watches.delete(queue));
+	}
+
+	result(ref: HandleRef): HandleOutcome {
+		const entry = this.#fence(ref);
+		if (!TERMINAL.has(entry.phase)) throw new EvalHandleError("eval_handle_pending", `${ref.id} is still running`);
+		if (entry.phase === "succeeded") return { status: "fulfilled", ref: entry.ref, value: entry.value };
+		return {
+			status: "rejected",
+			ref: entry.ref,
+			error: entry.error ?? { code: "eval_handle_lost", message: `${ref.id} ended without an outcome` },
+		};
+	}
+
+	cancel(ref: HandleRef): CancelReceipt {
+		const entry = this.#fence(ref);
+		if (TERMINAL.has(entry.phase)) return { ref: entry.ref, cancelled: false, phase: entry.phase };
+		const error = { code: "eval_handle_cancelled", message: `${ref.id} was cancelled` };
+		this.#settle(entry, { phase: "cancelled", hostStatus: "cancelled", error });
+		entry.controller.abort(new Error(error.message));
+		return { ref: entry.ref, cancelled: true, phase: "cancelled" };
+	}
+
+	output(ref: HandleRef, request: OutputRequest): OutputSnapshot {
+		const entry = this.#fence(ref);
+		const text =
+			entry.phase === "succeeded"
+				? typeof entry.value === "string"
+					? entry.value
+					: JSON.stringify(entry.value)
+				: (entry.error?.message ?? "");
+		const lines = text.length === 0 ? [] : text.split("\n");
+		const total = lines.length;
+		const window =
+			request.format === "tail"
+				? lines.slice(-(request.limit ?? 20))
+				: lines.slice(request.offset ?? 0, (request.offset ?? 0) + (request.limit ?? total));
+		const offset = request.format === "tail" ? total - window.length : (request.offset ?? 0);
+		return { ref: entry.ref, text: window.join("\n"), offset, total, truncated: window.length < total };
+	}
+
+	/** Aborts every in-flight completion and closes every watch; afterwards every ref is stale. */
+	dispose(): void {
+		if (this.#disposed) return;
+		this.#disposed = true;
+		for (const entry of this.#entries.values()) {
+			if (entry.timer !== undefined) clearTimeout(entry.timer);
+			if (!TERMINAL.has(entry.phase)) {
+				entry.phase = "lost";
+				entry.hostStatus = "session-dropped";
+				entry.controller.abort(new Error("session generation dropped"));
+			}
+		}
+		for (const queue of this.#watches) queue.close();
+		this.#watches.clear();
+	}
+
+	#assertLive(): void {
+		if (this.#disposed) throw new EvalHandleError("eval_handle_stale", "this session generation was dropped");
+	}
+
+	#fence(ref: HandleRef): CompletionEntry {
+		this.#assertLive();
+		const entry = this.#entries.get(ref.id);
+		if (ref.kind !== "completion" || !entry)
+			throw new EvalHandleError("eval_handle_not_found", `no completion handle ${ref.id}`);
+		if (ref.run_epoch !== entry.ref.run_epoch)
+			throw new EvalHandleError("eval_handle_stale", `${ref.id} run epoch ${ref.run_epoch} is not live`);
+		return entry;
+	}
+
+	#settle(
+		entry: CompletionEntry,
+		next: { phase: HandlePhase; hostStatus: string; value?: unknown; error?: HandleError },
+	): void {
+		if (TERMINAL.has(entry.phase)) return;
+		if (entry.timer !== undefined) clearTimeout(entry.timer);
+		entry.timer = undefined;
+		entry.phase = next.phase;
+		entry.hostStatus = next.hostStatus;
+		if ("value" in next) entry.value = next.value;
+		if (next.error) entry.error = next.error;
+		entry.revision += 1;
+		const snapshot = snapshotOf(entry);
+		for (const queue of this.#watches) queue.push(snapshot);
+	}
+}
+
+function snapshotOf(entry: CompletionEntry): HandleSnapshot {
+	return { ref: entry.ref, phase: entry.phase, host_status: entry.hostStatus, revision: entry.revision };
+}
+
+function toHandleError(error: unknown, timedOut: boolean): HandleError {
+	if (timedOut) return { code: "completion_deadline", message: DEADLINE_MESSAGE };
+	if (error instanceof Error) {
+		const code = "code" in error && typeof error.code === "string" ? error.code : "completion_failed";
+		return { code, message: error.message };
+	}
+	return { code: "completion_failed", message: String(error) };
+}