@code-yeongyu/senpi-codemode 2026.9.5 → 2026.9.7

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

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

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

@@ -2,9 +2,18 @@ export type ShellCaptureStream = "stdout" | "stderr";
 
 export type ShellCaptureRestore = () => void;
 
+export interface ShellCaptureChild {
+	readonly exitCode: number | null;
+	readonly signalCode: string | null;
+	readonly exited: Promise<number>;
+	kill(): void;
+}
+
 export interface ShellCaptureOptions {
 	readonly isActive: () => boolean;
 	readonly emitText: (stream: ShellCaptureStream, data: string) => void;
+	/** Receives every `Bun.spawn` child created while a cell is active so the runtime can kill it on interrupt. */
+	readonly onChild?: (child: ShellCaptureChild) => void;
 }
 
 export function installShellCapture(options: ShellCaptureOptions): ShellCaptureRestore;

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

@@ -1,5 +1,12 @@
 const SHELL_CONFIG_METHODS = ["env", "cwd", "nothrow", "throws"];
 const SHELL_READ_METHODS = ["text", "json", "lines", "arrayBuffer", "bytes", "blob"];
+// `true | ( … )` hands every command in the template an empty pipe as stdin. The worker thread shares
+// the host process's fd 0 (the TUI's terminal), which Bun.$ would otherwise inherit, so a stdin
+// reader would wait on the user's keyboard forever. The newline before `)` keeps a trailing comment
+// from swallowing the closing paren; the Bun shell has no other stdin control (no `$.stdin`, no
+// redirect on a subshell).
+const STDIN_ISOLATION_HEAD = "true | (\n";
+const STDIN_ISOLATION_TAIL = "\n)";
 
 export function installShellCapture(options) {
 	const bun = globalThis.Bun;
@@ -20,8 +27,9 @@ function isBunRuntime(bun) {
 
 function capturedShell(originalShell, options) {
 	const shell = (strings, ...expressions) => {
-		const promise = originalShell(strings, ...expressions);
-		return options.isActive() ? captureShellPromise(promise, options.emitText) : promise;
+		if (!options.isActive()) return originalShell(strings, ...expressions);
+		const promise = originalShell(isolateStdin(strings), ...expressions);
+		return captureShellPromise(promise, options.emitText);
 	};
 	for (const key of Object.keys(originalShell)) shell[key] = originalShell[key];
 	for (const method of SHELL_CONFIG_METHODS) {
@@ -33,6 +41,18 @@ function capturedShell(originalShell, options) {
 	return shell;
 }
 
+function isolateStdin(strings) {
+	if (!Array.isArray(strings) || !Array.isArray(strings.raw)) return strings;
+	const cooked = [...strings];
+	const raw = [...strings.raw];
+	const last = cooked.length - 1;
+	cooked[0] = `${STDIN_ISOLATION_HEAD}${cooked[0]}`;
+	raw[0] = `${STDIN_ISOLATION_HEAD}${raw[0]}`;
+	cooked[last] = `${cooked[last]}${STDIN_ISOLATION_TAIL}`;
+	raw[last] = `${raw[last]}${STDIN_ISOLATION_TAIL}`;
+	return Object.freeze(Object.assign(cooked, { raw: Object.freeze(raw) }));
+}
+
 function captureShellPromise(promise, emitText) {
 	const prototype = Object.getPrototypeOf(promise);
 	let echo = true;
@@ -87,13 +107,19 @@ function capturedSpawn(originalSpawn, options) {
 	return (...args) => {
 		if (!options.isActive()) return originalSpawn(...args);
 		const [first, second] = args;
+		let child;
 		if (Array.isArray(first)) {
 			const spawnOptions = second === undefined ? {} : second;
-			if (!needsStderrCapture(spawnOptions)) return originalSpawn(...args);
-			return drainStderr(originalSpawn(first, { ...spawnOptions, stderr: "pipe" }), options.emitText);
+			child = needsStderrCapture(spawnOptions)
+				? drainStderr(originalSpawn(first, { ...spawnOptions, stderr: "pipe" }), options.emitText)
+				: originalSpawn(...args);
+		} else {
+			child = needsStderrCapture(first)
+				? drainStderr(originalSpawn({ ...first, stderr: "pipe" }), options.emitText)
+				: originalSpawn(...args);
 		}
-		if (!needsStderrCapture(first)) return originalSpawn(...args);
-		return drainStderr(originalSpawn({ ...first, stderr: "pipe" }), options.emitText);
+		options.onChild?.(child);
+		return child;
 	};
 }
 

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

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

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

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

package/src/kernels/py/transport.ts

@@ -8,7 +8,7 @@ import {
 	isKernelToHostMessage,
 	type KernelToHostMessage,
 } from "../../bridge/protocol.ts";
-import { type CodemodeRuntimeAssetEnvironment, resolveCodemodeRuntimeAsset } from "../shared/runtime-asset.ts";
+import { type CodemodeRuntimeAssetEnvironment, requireCodemodeRuntimeAsset } from "../shared/runtime-asset.ts";
 import {
 	defaultSpawn,
 	hardKill,
@@ -53,7 +53,7 @@ export interface PythonPreludePathOptions extends CodemodeRuntimeAssetEnvironmen
 }
 
 export function resolvePythonPreludePath(options: PythonPreludePathOptions = {}): string {
-	return resolveCodemodeRuntimeAsset(
+	return requireCodemodeRuntimeAsset(
 		options.localPath ?? join(dirname(fileURLToPath(import.meta.url)), "prelude.py"),
 		join("kernels", "py", "prelude.py"),
 		options,

package/src/kernels/rb/kernel.ts

@@ -1,6 +1,6 @@
 import { join } from "node:path";
 import type { BridgeConnectionConfig, KernelToHostMessage } from "../../bridge/protocol.ts";
-import { type CodemodeRuntimeAssetEnvironment, resolveCodemodeRuntimeAsset } from "../shared/runtime-asset.ts";
+import { type CodemodeRuntimeAssetEnvironment, requireCodemodeRuntimeAsset } from "../shared/runtime-asset.ts";
 import { SubprocessKernel, type SubprocessSpawn } from "../shared/subprocess-kernel.ts";
 
 export interface RubyKernelStartOptions {
@@ -17,7 +17,7 @@ export interface RubyRunnerPathOptions extends CodemodeRuntimeAssetEnvironment {
 }
 
 export function resolveRubyRunnerPath(options: RubyRunnerPathOptions = {}): string {
-	return resolveCodemodeRuntimeAsset(
+	return requireCodemodeRuntimeAsset(
 		options.localPath ?? join(import.meta.dirname, "runner.rb"),
 		join("kernels", "rb", "runner.rb"),
 		options,

package/src/kernels/shared/runtime-asset.ts

@@ -6,26 +6,52 @@ export interface CodemodeRuntimeAssetEnvironment {
 	readonly executablePath?: string;
 }
 
+export class CodemodeRuntimeAssetMissingError extends Error {
+	readonly packageRelativePath: string;
+	readonly localPath: string;
+	readonly sidecarPath: string;
+	readonly executablePath: string;
+
+	constructor(packageRelativePath: string, localPath: string, sidecarPath: string, executablePath: string) {
+		super(
+			`codemode runtime asset ${packageRelativePath} is unavailable: module-relative path ${localPath} is not readable and the codemode sidecar is missing beside the executable ${executablePath} (expected ${sidecarPath}). Ship node_modules/@code-yeongyu/senpi-codemode next to the executable.`,
+		);
+		this.name = "CodemodeRuntimeAssetMissingError";
+		this.packageRelativePath = packageRelativePath;
+		this.localPath = localPath;
+		this.sidecarPath = sidecarPath;
+		this.executablePath = executablePath;
+	}
+}
+
+export function isBunVirtualPath(path: string): boolean {
+	return path.includes("/$bunfs/") || path.includes("~BUN") || path.includes("%7EBUN");
+}
+
+function sidecarPathFor(packageRelativePath: string, executablePath: string): string {
+	return join(dirname(executablePath), "node_modules", "@code-yeongyu", "senpi-codemode", "src", packageRelativePath);
+}
+
+export function requireCodemodeRuntimeAsset(
+	localPath: string,
+	packageRelativePath: string,
+	{ executablePath = process.execPath }: CodemodeRuntimeAssetEnvironment = {},
+): string {
+	const sidecarPath = sidecarPathFor(packageRelativePath, executablePath);
+	if (!isBunVirtualPath(localPath) && existsSync(localPath)) return localPath;
+	if (existsSync(sidecarPath)) return sidecarPath;
+	throw new CodemodeRuntimeAssetMissingError(packageRelativePath, localPath, sidecarPath, executablePath);
+}
+
 export function resolveCodemodeRuntimeAsset(
 	localPath: string,
 	packageRelativePath: string,
 	{ bunVersion = process.versions.bun, executablePath = process.execPath }: CodemodeRuntimeAssetEnvironment = {},
 ): string {
-	if (existsSync(localPath)) {
-		return localPath;
-	}
+	if (existsSync(localPath)) return localPath;
 	if (bunVersion) {
-		const sidecarPath = join(
-			dirname(executablePath),
-			"node_modules",
-			"@code-yeongyu",
-			"senpi-codemode",
-			"src",
-			packageRelativePath,
-		);
-		if (existsSync(sidecarPath)) {
-			return sidecarPath;
-		}
+		const sidecarPath = sidecarPathFor(packageRelativePath, executablePath);
+		if (existsSync(sidecarPath)) return sidecarPath;
 	}
 	return localPath;
 }

package/src/prompt/eval-prompt.ts

@@ -77,9 +77,9 @@ const EVAL_PROMPT_TEMPLATE = `Run one step of code in a persistent kernel.
 {{#if monitor}}- Start long-running work (build, test run, deploy, or watch) through \`tool.monitor({ command, filter })\`, putting the decisive-line filter inside the same cell, then keep working until its event wakes the turn.{{/if}}
 </eval_first_batching>{{/if}}{{#if styleGpt}}<gpt_eval_dialect>
 GPT eval: compose multi-tool work inside one cell with \`tool.<name>(args)\` and \`parallel(thunks)\`; do not split a planned step into serial tool calls.
-- Long cells detach on timeout and notify on completion; do not poll or re-run them.
+{{#if monitor}}- A wait or a long run (build, test run, deploy, watch) starts through \`tool.monitor({ command, filter })\` in that same cell with the decisive-line filter; its event wakes the turn, so no cell sits on the wait and no child is spawned for it.
+{{/if}}- Long cells detach on timeout and notify on completion; do not poll or re-run them.
 - Filter, join, and aggregate tool results in the cell; return only decision-relevant facts.
-{{#if monitor}}- For long-running build, test run, deploy, or watch work, start \`tool.monitor({ command, filter })\` with the decisive-line filter in the same cell; keep working until its event wakes the turn.{{/if}}
 </gpt_eval_dialect>{{/if}}{{#if styleCodex}}Route multi-call steps through eval: one cell per step, independent lookups dispatched together via \`parallel(thunks)\`; keep work sequential only when one result determines the next action.
 - Loop or comprehend over file sets with \`read()\`/stdlib instead of reading files one call at a time; post-process \`tool.<name>()\` results programmatically — filter, join, aggregate.
 - Wrap failable calls in try/except inside the cell; a failed item degrades only itself. After two distinct failed strategies for the same fact, fall back to direct tool calls.
@@ -102,7 +102,7 @@ Host: {{hostLine}} — cells execute here. Size \`parallel(thunks)\` pools to it
 A cell that outlives the foreground window detaches: it keeps its language kernel busy (another language can continue) and completes as one notification with its value or error and buffered output. Do not re-run a detached cell; read or cancel it with \`eval({ action: "peek", cell_id })\` / \`eval({ action: "stop", cell_id })\`.
 
 {{#if py}}Python runs on a live event loop: use top-level \`await\`; \`asyncio.run(…)\` raises.{{/if}}
-{{#if js}}{{#if jsBun}}JS runs in-process on Bun {{jsVersion}}: top-level \`await\`/\`return\` work; \`Bun.*\` builtins available, including \`new Bun.WebView()\` — a headless browser (navigate/click/evaluate/screenshot) to reach for before \`curl\` or a browser CLI when a page needs JS, a login, or a screenshot.{{#if bunSkillPath}} MUST READ the bun-1-4 skill at {{bunSkillPath}} before your first js cell — its builtins replace the npm packages you would otherwise install.{{/if}}{{else}}JS runs under Node.js worker: top-level \`await\`/\`return\` work; \`fetch\`/\`Buffer\` available.{{/if}}{{/if}}
+{{#if js}}{{#if jsBun}}JS runs in-process on Bun {{jsVersion}}: top-level \`await\`/\`return\` work; \`Bun.*\` builtins available, including \`new Bun.WebView()\` — a headless browser (navigate/click/evaluate/screenshot) to reach for before \`curl\` or a browser CLI when a page needs JS, a login, or a screenshot. Shell out through \`Bun.$\` or \`Bun.spawn\`, never \`Bun.spawnSync\`: a synchronous child blocks the worker, so a stop or timeout then loses every variable.{{#if bunSkillPath}} MUST READ the bun-1-4 skill at {{bunSkillPath}} before your first js cell — its builtins replace the npm packages you would otherwise install.{{/if}}{{else}}JS runs under Node.js worker: top-level \`await\`/\`return\` work; \`fetch\`/\`Buffer\` available.{{/if}}{{/if}}
 {{#if rb}}Ruby: synchronous; helper options are keyword args{{#if spawns}} (e.g. \`output("id", limit: 2)\`){{/if}}; the last expression auto-displays unless it is \`nil\`, an assignment, or a definition (like IRB).{{/if}}
 {{#if jl}}Julia: synchronous; helper options are standard keyword args{{#if spawns}} (e.g. \`output("id", limit=2)\`){{/if}}; the last expression auto-displays unless it is an assignment or a definition (like the Julia REPL).{{/if}}
 On error, fix and re-run only the failing step; a normal error keeps state, while a timeout or stop message says whether the kernel restarted.
@@ -182,7 +182,7 @@ export function buildEvalPrompt(
 		description,
 		promptSnippet: "Run one incremental code cell in a persistent language kernel.",
 		promptGuidelines: [
-			BATCHING_GUIDELINES[style],
+			style === "gpt" && context.monitor === true ? GPT_MONITOR_BATCHING_GUIDELINE : BATCHING_GUIDELINES[style],
 			"Use eval reset only when a language kernel must be wiped; reset is scoped to the selected language.",
 		],
 	};
@@ -191,8 +191,13 @@ export function buildEvalPrompt(
 /**
  * System-prompt guideline per emphasis dialect. The default dialect carries
  * maximum emphasis so unmapped models still batch through eval; the others are
- * tuned to what steers that family reliably.
+ * tuned to what steers that family reliably. The GPT line routes waits to the
+ * subscription when `monitor` is reachable, because a GPT model that reads
+ * "long cells detach" as the way to wait awaits a `--watch` inside a cell.
  */
+const GPT_MONITOR_BATCHING_GUIDELINE =
+	"Use eval to compose tool work in one cell; a wait or a long run starts through `tool.monitor` in that cell, so no cell sits on it and nothing polls.";
+
 const BATCHING_GUIDELINES: Record<EvalEmphasisStyle, string> = {
 	default:
 		"**EVAL FIRST.** Any step needing MORE THAN ONE tool call MUST be ONE eval cell: run independent calls in parallel, wrap risky calls in try/except, and return distilled facts — NEVER a chain of single tool calls.",

package/src/tool/cell-execution.ts

@@ -1,5 +1,5 @@
 import { IdleTimeout, type IdleTimeoutOptions, type TimeoutPauseHandle } from "../timeouts/idle-timeout.ts";
-import type { EvalKernel } from "./types.ts";
+import type { EvalKernel, KernelInterruptHandle } from "./types.ts";
 
 const INTERRUPT_DELIVERY_GRACE_MS = 100;
 
@@ -104,7 +104,8 @@ export class CellExecution {
 		this.#abort(this.#callerSignal.reason);
 	};
 
-	interruptStateRetained: Promise<boolean> | undefined;
+	/** Resolves with the kernel's interrupt handle once the abort reached it; undefined when no kernel was bound. */
+	interruptHandle: Promise<KernelInterruptHandle> | undefined;
 
 	#abort(reason: unknown): void {
 		if (!this.#active) return;
@@ -118,15 +119,12 @@ export class CellExecution {
 			return;
 		}
 		this.#interruptDeadline = setTimeout(() => this.#settleAbort(error), INTERRUPT_DELIVERY_GRACE_MS);
-		void Promise.resolve()
-			.then(async () => {
-				const handle = await kernel.interrupt(error.message);
-				this.interruptStateRetained = handle?.stateRetained;
-			})
-			.then(
-				() => this.#settleAbort(error),
-				(interruptError: unknown) => this.#settleAbort(interruptError),
-			);
+		const handle = Promise.resolve().then(async () => await kernel.interrupt(error.message));
+		this.interruptHandle = handle;
+		void handle.then(
+			() => this.#settleAbort(error),
+			(interruptError: unknown) => this.#settleAbort(interruptError),
+		);
 	}
 
 	#settleAbort(reason: unknown): void {

package/src/tool/detached-cell-contract.ts

@@ -0,0 +1,45 @@
+import type { AgentToolResult } from "@code-yeongyu/senpi";
+import type { WakeSourceState } from "../extension/wake-source-state.ts";
+import type { EvalLanguage, EvalToolDetails } from "./types.ts";
+
+export type EvalDetachedCellState = "running" | "detached" | "completed" | "failed" | "cancelled";
+
+export interface EvalDetachedCellSnapshot {
+	readonly cellId: string;
+	readonly language: EvalLanguage;
+	readonly state: EvalDetachedCellState;
+	readonly outputTail: string;
+	readonly result: AgentToolResult<EvalToolDetails>;
+	readonly stateRetained: boolean | undefined;
+	/** Kernel-supplied detail about the interrupt outcome, e.g. an abandoned blocked worker. */
+	readonly interruptNote?: string;
+	/** Set only when the wall-clock kill deadline ended this cell. */
+	readonly hardLimitSeconds?: number;
+}
+
+export interface EvalDetachedCellNotification {
+	readonly cellId: string;
+	readonly content: string;
+}
+
+export interface EvalDetachedCellNotifier {
+	notify(cells: readonly EvalDetachedCellNotification[]): void;
+}
+
+export interface EvalDetachedCellStatusEntry {
+	readonly cellId: string;
+	readonly language: EvalLanguage;
+	readonly summary?: string;
+	readonly startedAtMs: number;
+}
+
+export interface EvalDetachedCellManagerOptions {
+	readonly artifactsDir?: string;
+	readonly notifier?: EvalDetachedCellNotifier;
+	/** Wall-clock kill deadline in seconds; defaults to the bash-parity 1800s. */
+	readonly hardLimitSeconds?: number;
+	readonly onStatusChange?: (entries: readonly EvalDetachedCellStatusEntry[]) => void;
+	/** Receives a full per-source liveness snapshot on every detached-cell transition; used by the goal builtin. */
+	readonly onWakeSourceState?: (state: WakeSourceState) => void;
+	readonly now?: () => number;
+}