@code-yeongyu/senpi-codemode 2026.9.13-2 → 2026.9.15-2

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

@@ -154,7 +154,7 @@ function capturedSpawn(originalSpawn, options, pinEnv) {
 					? originalSpawn(...args)
 					: originalSpawn(effective);
 		}
-		options.onChild?.(child);
+		options.onChild?.(child, Array.isArray(first) ? second : first);
 		return child;
 	};
 }

package/src/kernels/py/prelude.py

@@ -23,7 +23,7 @@ import uuid
 from collections.abc import Iterable
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from pathlib import Path
-from threading import Lock
+from threading import Lock, Thread
 from typing import Any, Callable
 from urllib.parse import unquote
 
@@ -1022,14 +1022,48 @@ def handle(message: dict[str, Any]) -> bool:
     return True
 
 
+def _terminate_process_group() -> None:
+    # The kernel is spawned into its own session (setsid), so its pid is its process
+    # group id and a cell's subprocesses inherit that group. Killing the group takes
+    # those children down with the kernel instead of orphaning them to init.
+    if os.name != "posix":
+        return
+    with contextlib.suppress(OSError):
+        os.killpg(os.getpgrp(), signal.SIGKILL)
+
+
+def _watch_parent(initial_ppid: int) -> None:
+    # A cell blocked in the main thread (for example a multiprocessing pool) never
+    # returns to the stdin loop, so it cannot notice the host closing its pipe. This
+    # daemon thread notices the reparenting instead and takes the whole group down.
+    while True:
+        time.sleep(1.0)
+        if os.getppid() != initial_ppid:
+            _terminate_process_group()
+            return
+
+
+def _start_parent_watch() -> None:
+    if os.name != "posix":
+        return
+    Thread(target=_watch_parent, args=(os.getppid(),), name="senpi-parent-watch", daemon=True).start()
+
+
 def main() -> None:
     signal.signal(signal.SIGINT, signal.SIG_IGN)
+    _start_parent_watch()
+    host_closed = False
     for raw in sys.stdin:
         try:
             if not handle(json.loads(raw)):
+                host_closed = True
                 break
         except BaseException as exc:  # noqa: BROAD_EXCEPT_OK — process boundary serializes malformed input and interrupts.
             emit({"type": "init-failed", "error": bridge_error(exc)})
+    # Reaching here without a close frame means the host's pipe hit EOF: it is gone,
+    # so retire any subprocess the last cell left running before the interpreter exits.
+    if not host_closed:
+        _terminate_process_group()
 
 
 if __name__ == "__main__":

package/src/kernels/py/process.ts

@@ -45,6 +45,12 @@ export function splitCommand(commandLine: string): { readonly command: string; r
 	return { command, args };
 }
 
+function errorCode(error: unknown): string | undefined {
+	if (typeof error !== "object" || error === null) return undefined;
+	const code = Reflect.get(error, "code");
+	return typeof code === "string" ? code : undefined;
+}
+
 export function numberOrNull(value: unknown): number | null {
 	return typeof value === "number" ? value : null;
 }
@@ -80,6 +86,20 @@ export async function waitForExit(child: KernelChild, timeoutMs: number): Promis
 	});
 }
 
+// A cell's own subprocess is spawned into the detached kernel's process group. When the
+// leader exits gracefully on close, kill the group so a Popen the cell left running does
+// not outlive the kernel; the group is addressed by the leader pid (== pgid) while members live.
+export function sweepProcessGroup(child: KernelChild): void {
+	if (child.pid === undefined || process.platform === "win32") return;
+	try {
+		process.kill(-child.pid, "SIGKILL");
+	} catch (error) {
+		// ESRCH means the group is already gone (the success case). Any other error
+		// (for example EPERM on a member we cannot signal) must not fail a graceful close.
+		if (errorCode(error) !== "ESRCH") return;
+	}
+}
+
 export async function hardKill(child: KernelChild, timeoutMs: number): Promise<void> {
 	await new Promise<void>((resolve, reject) => {
 		let timer: NodeJS.Timeout | undefined;

package/src/kernels/py/transport.ts

@@ -19,6 +19,7 @@ import {
 	numberOrNull,
 	signalOrNull,
 	splitCommand,
+	sweepProcessGroup,
 	waitForExit,
 	withTimeout,
 } from "./process.ts";
@@ -145,7 +146,10 @@ export class PythonKernelTransport {
 		} catch (error) {
 			if (!(error instanceof Error)) throw error;
 		}
-		if (!(await exited)) await hardKill(this.#child, hardKillWaitMs);
+		// hardKill kills the whole group; a graceful leader exit does not, so sweep it
+		// to retire any subprocess the cell left running in the kernel's process group.
+		if (await exited) sweepProcessGroup(this.#child);
+		else await hardKill(this.#child, hardKillWaitMs);
 	}
 
 	retire(): Promise<void> {

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

@@ -2,6 +2,9 @@ import type { KernelToHostMessage } from "../../bridge/protocol.ts";
 import type { KernelResult, KernelRunInput, ToolCallMessage } from "./subprocess-contract.ts";
 import { createPendingRun, failureResult, type PendingRun, settlePendingRun } from "./subprocess-run.ts";
 
+// Same bound as the JS kernel's pull-API fallback queue (context-manager.ts); clears happen at run teardown.
+const MAX_PENDING_TOOL_CALLS = 256;
+
 export class SubprocessRunQueue {
 	readonly #queue: PendingRun[] = [];
 	readonly #pendingCalls: ToolCallMessage[] = [];
@@ -59,7 +62,10 @@ export class SubprocessRunQueue {
 	pushToolCall(message: ToolCallMessage): void {
 		const waiter = this.#callWaiters.shift();
 		if (waiter) waiter(message);
-		else this.#pendingCalls.push(message);
+		else {
+			this.#pendingCalls.push(message);
+			if (this.#pendingCalls.length > MAX_PENDING_TOOL_CALLS) this.#pendingCalls.shift();
+		}
 	}
 
 	handleMessage(

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

@@ -1,14 +1,12 @@
 import type { AgentToolResult } from "@code-yeongyu/senpi";
 import { DEFAULT_HARD_LIMIT_SECONDS, DEFAULT_RUN_BUDGET_SECONDS } from "../config/settings.ts";
 import type { WakeSourceState } from "../extension/wake-source-state.ts";
-import { type CellDeadlineExpiry, CellDeadlines } from "./cell-deadlines.ts";
+import type { CellDeadlineExpiry } from "./cell-deadlines.ts";
 import type {
 	EvalDetachedCellManagerOptions,
 	EvalDetachedCellSnapshot,
-	EvalDetachedCellState,
 	EvalDetachedCellStatusEntry,
 } from "./detached-cell-contract.ts";
-import { detachedNotificationSpillPath } from "./detached-cell-notification.ts";
 import { currentDetachedResult, detachedErrorResult, snapshotDetachedCell } from "./detached-cell-snapshot.ts";
 import {
 	activeDetachedCellReuseError,
@@ -17,6 +15,8 @@ import {
 } from "./detached-cell-state.ts";
 import { detachedStatusEntries, detachedWakeSourceState } from "./detached-cell-status.ts";
 import { DetachedNotificationQueue } from "./detached-notification-queue.ts";
+import { createManagedCell, type LiveResultProvider, type ManagedCell } from "./managed-cell.ts";
+import { TerminalSnapshotStore } from "./terminal-snapshot-store.ts";
 import type { EvalKernel, EvalLanguage, EvalToolDetails, EvalToolInput } from "./types.ts";
 
 export type {
@@ -28,40 +28,13 @@ export type {
 	EvalDetachedCellStatusEntry,
 } from "./detached-cell-contract.ts";
 
-type LiveResultProvider = () => AgentToolResult<EvalToolDetails>;
-
-type ManagedCell = {
-	readonly cellId: string;
-	readonly input: EvalToolInput;
-	readonly spillPath: string | undefined;
-	readonly startedAtMs: number;
-	readonly terminal: PromiseWithResolvers<EvalDetachedCellSnapshot>;
-	state: EvalDetachedCellState;
-	canDetach: boolean;
-	wasDetached: boolean;
-	kernel: EvalKernel | undefined;
-	stateRetained: boolean | undefined;
-	interruptNote: string | undefined;
-	/** Holds the completion notification until the interrupt has reported whether kernel state survived. */
-	interruptOutcome: PromiseWithResolvers<void> | undefined;
-	liveResult: LiveResultProvider | undefined;
-	terminalResult: AgentToolResult<EvalToolDetails> | undefined;
-	notificationQueued: boolean;
-	readonly deadlines: CellDeadlines;
-	readonly hardLimitSeconds: number;
-	readonly runBudgetSeconds: number;
-	hardLimited: boolean;
-	runBudgetExhausted: boolean;
-	/** Foreground killer: the still-awaited CellExecution owns interrupting and rejecting its own call; bound from creation so a deadline firing during kernel boot still ends it. */
-	onKill: ((error: Error) => void) | undefined;
-};
-
 export class EvalDetachedCellManager {
 	readonly #artifactsDir: string | undefined;
 	readonly #onStatusChange: ((entries: readonly EvalDetachedCellStatusEntry[]) => void) | undefined;
 	readonly #onWakeSourceState: ((state: WakeSourceState) => void) | undefined;
 	readonly #cells = new Map<string, ManagedCell>();
 	readonly #detachedByLanguage = new Map<EvalLanguage, ManagedCell>();
+	readonly #terminalSnapshots = new TerminalSnapshotStore();
 	readonly #notificationQueue: DetachedNotificationQueue;
 	readonly #now: () => number;
 	readonly #hardLimitSeconds: number;
@@ -83,40 +56,20 @@ export class EvalDetachedCellManager {
 			if (detachedCellIsActive(existing.state)) throw activeDetachedCellReuseError(existing);
 			this.#cells.delete(cellId);
 		}
-		// An explicit longer per-call timeout raises the deadline, mirroring bash keeping explicit timeouts.
-		const hardLimitSeconds = Math.max(this.#hardLimitSeconds, input.timeout ?? 0);
-		const runBudgetSeconds = input.timeout ?? this.#runBudgetSeconds;
-		const cell: ManagedCell = {
+		this.#terminalSnapshots.delete(cellId);
+		const cell = createManagedCell({
 			cellId,
 			input,
-			spillPath: detachedNotificationSpillPath(this.#artifactsDir, cellId),
-			startedAtMs: this.#now(),
-			state: "running",
-			canDetach: false,
-			wasDetached: false,
-			kernel: undefined,
-			stateRetained: undefined,
-			interruptNote: undefined,
-			interruptOutcome: undefined,
-			liveResult: undefined,
-			terminalResult: undefined,
-			notificationQueued: false,
-			deadlines: new CellDeadlines({
-				cellId,
-				hardLimitSeconds,
-				runBudgetSeconds,
-				onExpire: (expiry) => {
-					const managed = this.#cells.get(cellId);
-					if (managed !== undefined) void this.#expireDeadline(managed, expiry);
-				},
-			}),
-			hardLimitSeconds,
-			runBudgetSeconds,
-			hardLimited: false,
-			runBudgetExhausted: false,
+			artifactsDir: this.#artifactsDir,
+			now: this.#now,
+			defaultHardLimitSeconds: this.#hardLimitSeconds,
+			defaultRunBudgetSeconds: this.#runBudgetSeconds,
 			onKill,
-			terminal: Promise.withResolvers<EvalDetachedCellSnapshot>(),
-		};
+			onExpire: (expiredId, expiry) => {
+				const managed = this.#cells.get(expiredId);
+				if (managed !== undefined) void this.#expireDeadline(managed, expiry);
+			},
+		});
 		this.#cells.set(cellId, cell);
 		return cell;
 	}
@@ -166,13 +119,15 @@ export class EvalDetachedCellManager {
 	}
 
 	async stop(cellId: string, reason = "Stopped detached eval cell"): Promise<EvalDetachedCellSnapshot> {
-		const cell = this.#get(cellId);
-		if (cell.state === "detached") await this.#cancel(cell, reason);
-		return this.#snapshot(cell);
+		const live = this.#cells.get(cellId);
+		if (live === undefined) return this.#terminal(cellId);
+		if (live.state === "detached") await this.#cancel(live, reason);
+		return this.#snapshot(live);
 	}
 
 	peek(cellId: string): EvalDetachedCellSnapshot {
-		return this.#snapshot(this.#get(cellId));
+		const live = this.#cells.get(cellId);
+		return live === undefined ? this.#terminal(cellId) : this.#snapshot(live);
 	}
 
 	busyFor(language: EvalLanguage): EvalDetachedCellSnapshot | undefined {
@@ -181,7 +136,8 @@ export class EvalDetachedCellManager {
 	}
 
 	async waitForTerminal(cellId: string): Promise<EvalDetachedCellSnapshot> {
-		return await this.#get(cellId).terminal.promise;
+		const live = this.#cells.get(cellId);
+		return live === undefined ? this.#terminal(cellId) : await live.terminal.promise;
 	}
 
 	async dispose(): Promise<void> {
@@ -191,6 +147,8 @@ export class EvalDetachedCellManager {
 		);
 		if (detached.length === 0) this.#emitWakeSourceState([]);
 		await this.#notificationQueue.flush();
+		this.#cells.clear();
+		this.#terminalSnapshots.clear();
 	}
 
 	async flushNotifications(): Promise<void> {
@@ -213,6 +171,8 @@ export class EvalDetachedCellManager {
 		cell.terminalResult = result;
 		cell.liveResult = undefined;
 		cell.terminal.resolve(this.#snapshot(cell));
+		this.#cells.delete(cell.cellId);
+		this.#refreshTerminalSnapshot(cell);
 		if (cell.wasDetached) {
 			if (this.#detachedByLanguage.get(cell.input.language) === cell)
 				this.#detachedByLanguage.delete(cell.input.language);
@@ -257,9 +217,14 @@ export class EvalDetachedCellManager {
 			cell.stateRetained = await handle.stateRetained;
 		} finally {
 			outcome.resolve();
+			this.#refreshTerminalSnapshot(cell);
 		}
 	}
 
+	#refreshTerminalSnapshot(cell: ManagedCell): void {
+		if (!this.#cells.has(cell.cellId)) this.#terminalSnapshots.remember(this.#snapshot(cell));
+	}
+
 	#emitStatus(): void {
 		const liveCells = [...this.#detachedByLanguage.values()];
 		this.#onStatusChange?.(detachedStatusEntries(liveCells));
@@ -274,9 +239,9 @@ export class EvalDetachedCellManager {
 		return snapshotDetachedCell(cell, this.#now());
 	}
 
-	#get(cellId: string): ManagedCell {
-		const cell = this.#cells.get(cellId);
-		if (cell === undefined) throw new Error(`Unknown detached eval cell "${cellId}"`);
-		return cell;
+	#terminal(cellId: string): EvalDetachedCellSnapshot {
+		const snapshot = this.#terminalSnapshots.get(cellId);
+		if (snapshot === undefined) throw new Error(`Unknown detached eval cell "${cellId}"`);
+		return snapshot;
 	}
 }

package/src/tool/image-resize.ts

@@ -0,0 +1,52 @@
+import type { ExtensionContext } from "@code-yeongyu/senpi";
+import { convertToPng, formatDimensionNote, resizeImage } from "@code-yeongyu/senpi";
+
+export interface EvalImageContent {
+	readonly type: "image";
+	readonly data: string;
+	readonly mimeType: string;
+}
+
+export interface EvalImageResizeResult {
+	readonly image: EvalImageContent;
+	readonly dimensionNote?: string;
+}
+
+export type EvalImageResizer = (
+	image: EvalImageContent,
+	model: ExtensionContext["model"],
+) => Promise<EvalImageResizeResult>;
+
+type WebpModel = { readonly provider: string; readonly api: string } | undefined;
+
+export function webpExclusionForModel(model: WebpModel): true | undefined {
+	if (model === undefined) return undefined;
+	return model.provider === "ollama" ||
+		model.provider === "ollama-cloud" ||
+		model.provider === "llama.cpp" ||
+		model.provider === "lm-studio" ||
+		model.provider === "local-server" ||
+		model.api === "ollama-chat"
+		? true
+		: undefined;
+}
+
+export const resizeEvalImage: EvalImageResizer = async (image, model) => {
+	const excludeWebP = webpExclusionForModel(model);
+	const forceWebpConversion = excludeWebP === true && image.mimeType === "image/webp";
+	const resized = await resizeImage(
+		Buffer.from(image.data, "base64"),
+		image.mimeType,
+		forceWebpConversion ? { maxBytes: Buffer.byteLength(image.data, "utf8") } : undefined,
+	);
+	let output: EvalImageContent =
+		resized === null ? image : { type: "image", data: resized.data, mimeType: resized.mimeType };
+	if (excludeWebP === true && output.mimeType === "image/webp") {
+		const converted = await convertToPng(output.data, output.mimeType);
+		if (converted === null)
+			throw new TypeError(`Unable to convert ${output.mimeType} display output for the active model`);
+		output = { type: "image", data: converted.data, mimeType: converted.mimeType };
+	}
+	const dimensionNote = resized === null ? undefined : formatDimensionNote(resized);
+	return { image: output, ...(dimensionNote === undefined ? {} : { dimensionNote }) };
+};

package/src/tool/image.ts

@@ -1,6 +1,5 @@
 import { writeFile } from "node:fs/promises";
-import type { AgentToolResult, ExtensionContext } from "@code-yeongyu/senpi";
-import { convertToPng, formatDimensionNote, resizeImage } from "@code-yeongyu/senpi";
+import type { ExtensionContext } from "@code-yeongyu/senpi";
 import type { KernelToHostMessage } from "../bridge/protocol.ts";
 import type { TruncationMeta } from "../output/output-meta.ts";
 import {
@@ -12,24 +11,24 @@ import {
 	TailBuffer,
 	truncateTail,
 } from "../output/streaming-output.ts";
+import { type EvalImageContent, type EvalImageResizer, resizeEvalImage } from "./image-resize.ts";
 
-const MAX_DISPLAY_TEXT_BYTES = 8_000;
-
-export interface EvalImageContent {
-	readonly type: "image";
-	readonly data: string;
-	readonly mimeType: string;
-}
+export {
+	type EvalImageContent,
+	type EvalImageResizeResult,
+	type EvalImageResizer,
+	resizeEvalImage,
+	webpExclusionForModel,
+} from "./image-resize.ts";
+export { marshalToolResult, toolResultIsError } from "./tool-result-marshal.ts";
 
-export interface EvalImageResizeResult {
-	readonly image: EvalImageContent;
-	readonly dimensionNote?: string;
-}
+const MAX_DISPLAY_TEXT_BYTES = 8_000;
 
-export type EvalImageResizer = (
-	image: EvalImageContent,
-	model: ExtensionContext["model"],
-) => Promise<EvalImageResizeResult>;
+// Per-cell display caps: display payloads are retained for the whole result lifetime, so an unbounded
+// burst pins base64 originals plus resized copies on the session heap (#1695).
+const MAX_DISPLAY_IMAGES_PER_CELL = 8;
+const MAX_DISPLAY_IMAGE_BYTES_PER_CELL = 24 * 1024 * 1024;
+const MAX_JSON_OUTPUTS_PER_CELL = 64;
 
 export interface EvalOutputOptions {
 	readonly artifactPath?: string;
@@ -51,7 +50,6 @@ export interface EvalOutputResult {
 }
 
 type DisplayMessage = Extract<KernelToHostMessage, { type: "display" }>;
-type WebpModel = { readonly provider: string; readonly api: string } | undefined;
 
 class DisplayPayloadError extends Error {
 	readonly name = "DisplayPayloadError";
@@ -69,6 +67,9 @@ export class EvalOutputCollector {
 	readonly #displayImages: EvalImageContent[] = [];
 	readonly #images: EvalImageContent[] = [];
 	readonly #jsonOutputs: unknown[] = [];
+	#displayImageBytes = 0;
+	#displayImagesElided = 0;
+	#jsonOutputsElided = 0;
 	#hasMarkdown = false;
 	#imagesProcessed = false;
 
@@ -92,11 +93,23 @@ export class EvalOutputCollector {
 
 	display(message: DisplayMessage): void {
 		if (message.mimeType.startsWith("image/")) {
+			if (
+				this.#displayImages.length >= MAX_DISPLAY_IMAGES_PER_CELL ||
+				this.#displayImageBytes + message.dataBase64.length > MAX_DISPLAY_IMAGE_BYTES_PER_CELL
+			) {
+				this.#displayImagesElided++;
+				return;
+			}
 			this.#displayImages.push({ type: "image", mimeType: message.mimeType, data: message.dataBase64 });
+			this.#displayImageBytes += message.dataBase64.length;
 			return;
 		}
 		const text = Buffer.from(message.dataBase64, "base64").toString("utf8");
 		if (message.mimeType === "application/json") {
+			if (this.#jsonOutputs.length >= MAX_JSON_OUTPUTS_PER_CELL) {
+				this.#jsonOutputsElided++;
+				return;
+			}
 			let value: unknown;
 			try {
 				value = JSON.parse(text);
@@ -118,6 +131,12 @@ export class EvalOutputCollector {
 
 	async finish(): Promise<EvalOutputResult> {
 		await this.#processImages();
+		const elided = this.#displayImagesElided + this.#jsonOutputsElided;
+		if (elided > 0) {
+			this.#sink.push(
+				`[${this.#displayImagesElided} display image(s) and ${this.#jsonOutputsElided} JSON output(s) elided beyond per-cell caps]\n`,
+			);
+		}
 		const summary = await this.#finalSummary();
 		const meta = truncationMetaFromSummary(summary, this.#options.maxColumns);
 		const notice = summary.artifactId === undefined ? undefined : artifactNotice(summary.artifactId);
@@ -171,38 +190,6 @@ export class EvalOutputCollector {
 	}
 }
 
-export function webpExclusionForModel(model: WebpModel): true | undefined {
-	if (model === undefined) return undefined;
-	return model.provider === "ollama" ||
-		model.provider === "ollama-cloud" ||
-		model.provider === "llama.cpp" ||
-		model.provider === "lm-studio" ||
-		model.provider === "local-server" ||
-		model.api === "ollama-chat"
-		? true
-		: undefined;
-}
-
-export const resizeEvalImage: EvalImageResizer = async (image, model) => {
-	const excludeWebP = webpExclusionForModel(model);
-	const forceWebpConversion = excludeWebP === true && image.mimeType === "image/webp";
-	const resized = await resizeImage(
-		Buffer.from(image.data, "base64"),
-		image.mimeType,
-		forceWebpConversion ? { maxBytes: Buffer.byteLength(image.data, "utf8") } : undefined,
-	);
-	let output: EvalImageContent =
-		resized === null ? image : { type: "image", data: resized.data, mimeType: resized.mimeType };
-	if (excludeWebP === true && output.mimeType === "image/webp") {
-		const converted = await convertToPng(output.data, output.mimeType);
-		if (converted === null)
-			throw new TypeError(`Unable to convert ${output.mimeType} display output for the active model`);
-		output = { type: "image", data: converted.data, mimeType: converted.mimeType };
-	}
-	const dimensionNote = resized === null ? undefined : formatDimensionNote(resized);
-	return { image: output, ...(dimensionNote === undefined ? {} : { dimensionNote }) };
-};
-
 function formatDisplayJson(value: unknown): string {
 	let text: string;
 	try {
@@ -259,25 +246,3 @@ function truncationMetaFromSummary(summary: OutputSummary, maxColumns: number):
 		...artifact,
 	};
 }
-
-export function marshalToolResult(result: AgentToolResult<unknown>) {
-	const texts = result.content.filter((part) => part.type === "text").map((part) => part.text);
-	const images = result.content
-		.filter((part) => part.type === "image")
-		.map((part) => ({ mimeType: part.mimeType, dataBase64: part.data }));
-	const details =
-		typeof result.details === "object" &&
-		result.details !== null &&
-		!Array.isArray(result.details) &&
-		Object.keys(result.details).length === 0
-			? undefined
-			: result.details;
-	const hasError = toolResultIsError(result);
-	const text = texts.join("\n");
-	return images.length === 0 && details === undefined && !hasError ? { text } : { text, details, images, hasError };
-}
-
-export function toolResultIsError(result: AgentToolResult<unknown>): boolean {
-	const details = result.details;
-	return typeof details === "object" && details !== null && "isError" in details && details.isError === true;
-}

package/src/tool/managed-cell.ts

@@ -0,0 +1,78 @@
+import type { AgentToolResult } from "@code-yeongyu/senpi";
+import { type CellDeadlineExpiry, CellDeadlines } from "./cell-deadlines.ts";
+import type { EvalDetachedCellSnapshot, EvalDetachedCellState } from "./detached-cell-contract.ts";
+import { detachedNotificationSpillPath } from "./detached-cell-notification.ts";
+import type { EvalKernel, EvalToolDetails, EvalToolInput } from "./types.ts";
+
+export type LiveResultProvider = () => AgentToolResult<EvalToolDetails>;
+
+export type ManagedCell = {
+	readonly cellId: string;
+	readonly input: EvalToolInput;
+	readonly spillPath: string | undefined;
+	readonly startedAtMs: number;
+	readonly terminal: PromiseWithResolvers<EvalDetachedCellSnapshot>;
+	state: EvalDetachedCellState;
+	canDetach: boolean;
+	wasDetached: boolean;
+	kernel: EvalKernel | undefined;
+	stateRetained: boolean | undefined;
+	interruptNote: string | undefined;
+	/** Holds the completion notification until the interrupt has reported whether kernel state survived. */
+	interruptOutcome: PromiseWithResolvers<void> | undefined;
+	liveResult: LiveResultProvider | undefined;
+	terminalResult: AgentToolResult<EvalToolDetails> | undefined;
+	notificationQueued: boolean;
+	readonly deadlines: CellDeadlines;
+	readonly hardLimitSeconds: number;
+	readonly runBudgetSeconds: number;
+	hardLimited: boolean;
+	runBudgetExhausted: boolean;
+	/** Foreground killer: the still-awaited CellExecution owns interrupting and rejecting its own call; bound from creation so a deadline firing during kernel boot still ends it. */
+	onKill: ((error: Error) => void) | undefined;
+};
+
+export interface ManagedCellInit {
+	readonly cellId: string;
+	readonly input: EvalToolInput;
+	readonly artifactsDir: string | undefined;
+	readonly now: () => number;
+	readonly defaultHardLimitSeconds: number;
+	readonly defaultRunBudgetSeconds: number;
+	readonly onKill: ((error: Error) => void) | undefined;
+	readonly onExpire: (cellId: string, expiry: CellDeadlineExpiry) => void;
+}
+
+export function createManagedCell(init: ManagedCellInit): ManagedCell {
+	// An explicit longer per-call timeout raises the deadline, mirroring bash keeping explicit timeouts.
+	const hardLimitSeconds = Math.max(init.defaultHardLimitSeconds, init.input.timeout ?? 0);
+	const runBudgetSeconds = init.input.timeout ?? init.defaultRunBudgetSeconds;
+	return {
+		cellId: init.cellId,
+		input: init.input,
+		spillPath: detachedNotificationSpillPath(init.artifactsDir, init.cellId),
+		startedAtMs: init.now(),
+		state: "running",
+		canDetach: false,
+		wasDetached: false,
+		kernel: undefined,
+		stateRetained: undefined,
+		interruptNote: undefined,
+		interruptOutcome: undefined,
+		liveResult: undefined,
+		terminalResult: undefined,
+		notificationQueued: false,
+		deadlines: new CellDeadlines({
+			cellId: init.cellId,
+			hardLimitSeconds,
+			runBudgetSeconds,
+			onExpire: (expiry) => init.onExpire(init.cellId, expiry),
+		}),
+		hardLimitSeconds,
+		runBudgetSeconds,
+		hardLimited: false,
+		runBudgetExhausted: false,
+		onKill: init.onKill,
+		terminal: Promise.withResolvers<EvalDetachedCellSnapshot>(),
+	};
+}