@code-yeongyu/senpi-codemode 2026.10.4 → 2026.10.6

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

@@ -2,8 +2,10 @@ import type { KernelMemoryThresholds } from "../../bridge/memory-protocol.ts";
 import type { BridgeConnectionConfig, KernelToHostMessage } from "../../bridge/protocol.ts";
 import type { EvalKernelRunInput, EvalLanguage } from "../../tool/types.ts";
 import type { SessionEnvironment } from "../session-env.ts";
+import type { KernelLifecycle } from "./kernel-death.ts";
 import type { FootprintReader } from "./kernel-memory-host.ts";
 import type { SubprocessSpawn } from "./subprocess-process.ts";
+import type { SubprocessStartupOptions } from "./subprocess-startup.ts";
 
 export type KernelRunInput = EvalKernelRunInput;
 
@@ -16,7 +18,7 @@ export interface SubprocessKernelMemory {
 	readonly readFootprint: FootprintReader;
 }
 
-export interface SubprocessKernelOptions {
+export interface SubprocessKernelOptions extends KernelLifecycle {
 	readonly command: string;
 	readonly args: readonly string[];
 	readonly cwd?: string;
@@ -28,4 +30,6 @@ export interface SubprocessKernelOptions {
 	readonly spawn?: SubprocessSpawn;
 	readonly onMessage?: (message: KernelToHostMessage) => void;
 	readonly memory?: SubprocessKernelMemory & { readonly language: EvalLanguage };
+	/** Fails a start that stops making progress before `ready`; absent, the kernel waits for `ready` indefinitely. */
+	readonly startup?: SubprocessStartupOptions;
 }

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

@@ -1,9 +1,10 @@
 import type { HostToKernelMessage, KernelToHostMessage } from "../../bridge/protocol.ts";
 import { decodeBridgeFrame, encodeBridgeFrame, isKernelToHostMessage } from "../../bridge/protocol.ts";
-import type { KernelInterruptHandle } from "../../tool/types.ts";
+import type { KernelInterruptHandle, PendingCell } from "../../tool/types.ts";
 import type { KernelToolsInvokeOptions } from "../js/kernel-tools-types.ts";
 import { rejectKernelToolsUnavailable } from "../kernel-tools-unavailable.ts";
 import { applySessionEnvironment } from "../session-env.ts";
+import { describeExit } from "./kernel-death.ts";
 import { KernelMemoryHost } from "./kernel-memory-host.ts";
 import type { KernelResult, KernelRunInput, SubprocessKernelOptions, ToolCallMessage } from "./subprocess-contract.ts";
 import { type SubprocessLike, SubprocessProcess, type SubprocessSpawn, spawnSubprocess } from "./subprocess-process.ts";
@@ -19,8 +20,10 @@ import {
 	KernelRetirementError,
 	KernelStartupError,
 	type PendingRun,
+	settlePendingRun,
 	timeoutResult,
 } from "./subprocess-run.ts";
+import { SubprocessStartupWatchdog } from "./subprocess-startup.ts";
 
 export type {
 	KernelResult,
@@ -38,11 +41,13 @@ export class SubprocessKernel {
 	private readonly memory: KernelMemoryHost | null;
 	private process: SubprocessProcess | null = null;
 	private processReady = false;
+	private startup: SubprocessStartupWatchdog | null = null;
 	private retirementPromise: Promise<void> | null = null;
 	private retirementProcess: SubprocessProcess | null = null;
 	private retirementFailure: Error | null = null;
 	private failure: Error | null = null;
 	private closed = false;
+	private dead = false;
 
 	constructor(options: SubprocessKernelOptions) {
 		this.options = options;
@@ -52,6 +57,14 @@ export class SubprocessKernel {
 		this.spawnProcess();
 	}
 
+	isAlive(): boolean {
+		return !this.dead;
+	}
+
+	drainPending(): readonly PendingCell[] {
+		return this.runs.drain().map((run) => ({ input: run.input, settle: (result) => settlePendingRun(run, result) }));
+	}
+
 	run(input: KernelRunInput): Promise<KernelResult> {
 		if (this.closed) throw new KernelClosedError();
 		const run = this.runs.enqueue(input);
@@ -122,6 +135,7 @@ export class SubprocessKernel {
 	async close(): Promise<void> {
 		const wasClosed = this.closed;
 		this.closed = true;
+		this.startup?.stop();
 		if (!wasClosed) {
 			this.settleAll(new KernelClosingError());
 			this.runs.clearToolCalls();
@@ -186,10 +200,21 @@ export class SubprocessKernel {
 		});
 		this.process = process;
 		this.processReady = false;
+		this.startup?.stop();
+		const startup = this.options.startup;
+		this.startup = startup
+			? new SubprocessStartupWatchdog(startup, child.pid, (message) => this.stalled(process, message))
+			: null;
 		this.memory?.processReplaced();
 		try {
+			const thresholds = this.options.memory?.thresholds;
 			process.send(
-				encodeBridgeFrame({ type: "init", sessionId: this.options.sessionId, connection: this.options.connection }),
+				encodeBridgeFrame({
+					type: "init",
+					sessionId: this.options.sessionId,
+					connection: this.options.connection,
+					...(thresholds === undefined ? {} : { memory: thresholds }),
+				}),
 			);
 		} catch (error) {
 			const failure = new KernelStartupError(error instanceof Error ? error.message : String(error));
@@ -210,7 +235,9 @@ export class SubprocessKernel {
 
 	private handleMessage(process: SubprocessProcess, message: KernelToHostMessage): void {
 		if (!this.accepts(process)) return;
+		if (!this.processReady) this.startup?.observe(message);
 		if (message.type === "ready") {
+			this.startup?.stop();
 			this.processReady = true;
 			this.runs.handleMessage(message, this.onMessage);
 			this.pumpRuns();
@@ -236,6 +263,7 @@ export class SubprocessKernel {
 
 	private handleExit(process: SubprocessProcess, code: number | null, signal: NodeJS.Signals | null): void {
 		if (this.process !== process) return;
+		this.startup?.stop();
 		if (process.isRetiring) {
 			this.process = null;
 			this.retirementFailure = null;
@@ -243,7 +271,41 @@ export class SubprocessKernel {
 		}
 		this.process = null;
 		this.processReady = false;
-		this.failClosed(new KernelExitedError(signal ?? code ?? "unknown"));
+		const error = new KernelExitedError(signal ?? code ?? "unknown");
+		if (this.options.onDeath) this.die(error, describeExit(code, signal), this.options.onDeath);
+		else this.failClosed(error);
+	}
+
+	/**
+	 * The interpreter exited on its own and is gone: the running cell fails once (its side effects may
+	 * already have happened), the cells that never started stay queued for `drainPending`, and the owner
+	 * replaces this instance. `run()` is never reached on it again.
+	 */
+	private die(error: Error, reason: string, onDeath: (reason: string) => void): void {
+		this.failure = error;
+		this.closed = true;
+		this.dead = true;
+		this.runs.clearToolCalls();
+		const active = this.runs.active;
+		if (active) {
+			this.runs.releaseActive(active);
+			this.runs.settle(active, failureResult(active, new Error(`${error.message}; every global is lost`)));
+		}
+		onDeath(reason);
+	}
+
+	/** A stalled start is a death: the owner replaces the kernel and the cells that never started run there. */
+	private stalled(process: SubprocessProcess, message: string): void {
+		if (!this.accepts(process)) return;
+		const error = new KernelStartupError(message);
+		const onDeath = this.options.onDeath;
+		if (!onDeath) {
+			this.failClosed(error);
+			return;
+		}
+		process.retire();
+		this.trackRetirement(process, this.terminateOwnedProcess(process));
+		this.die(error, message, onDeath);
 	}
 
 	private accepts(process: SubprocessProcess): boolean {
@@ -299,6 +361,7 @@ export class SubprocessKernel {
 	}
 
 	private failClosed(error: Error): void {
+		this.startup?.stop();
 		const process = this.process;
 		this.failure = error;
 		this.closed = true;

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

@@ -44,6 +44,11 @@ export class SubprocessRunQueue {
 		};
 	}
 
+	/** Removes every queued run that has not started, oldest first. */
+	drain(): PendingRun[] {
+		return this.#queue.splice(0);
+	}
+
 	releaseActive(run: PendingRun): boolean {
 		if (this.#active !== run) return false;
 		this.#active = null;

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

@@ -0,0 +1,90 @@
+import type { KernelToHostMessage } from "../../bridge/protocol.ts";
+
+/**
+ * How long a starting interpreter may stay completely still - no output line, no new startup stage, and
+ * no CPU used by its process group - before startup fails. A cold Julia compiling its prelude prints
+ * nothing for seconds but keeps the CPU busy, so it never trips; only a runner that is silent AND idle
+ * (blocked on a lock, a pipe or a stopped process) does. It restarts on every sign of progress, so it is
+ * not a total startup budget. Where the group's CPU cannot be read it never fires.
+ */
+export const subprocessStartupNoProgressMs = 30_000;
+
+const STDERR_TAIL_CHARS = 2_000;
+const stages = ["interpreter-launch", "stdlib-imports", "runtime-init", "host-init"] as const;
+export type SubprocessStartupStage = (typeof stages)[number];
+
+export interface SubprocessStartupOptions {
+	readonly label: string;
+	readonly noProgressMs?: number;
+	/** CPU time used so far by a process group (any unit that only grows); `undefined` when unreadable. */
+	readonly readGroupCpuTime?: (pgid: number) => bigint | undefined;
+}
+
+export class SubprocessStartupWatchdog {
+	readonly #options: SubprocessStartupOptions;
+	readonly #pid: number | undefined;
+	readonly #onStall: (message: string) => void;
+	readonly #noProgressMs: number;
+	#stageIndex = 0;
+	#stderrTail = "";
+	#lastCpu: bigint | undefined;
+	#timer: ReturnType<typeof setTimeout> | undefined;
+	#stopped = false;
+
+	constructor(options: SubprocessStartupOptions, pid: number | undefined, onStall: (message: string) => void) {
+		this.#options = options;
+		this.#pid = pid;
+		this.#onStall = onStall;
+		this.#noProgressMs = options.noProgressMs ?? subprocessStartupNoProgressMs;
+		this.#lastCpu = this.#readCpu();
+		this.#arm();
+	}
+
+	/** Any message the runner sent before `ready` is progress; a later startup stage also moves the stage. */
+	observe(message: KernelToHostMessage): void {
+		if (this.#stopped) return;
+		if (message.type === "status" && message.event.op === "kernel-startup") {
+			const stage = stages.find((candidate) => candidate === message.event.stage);
+			const next = stage === undefined ? -1 : stages.indexOf(stage);
+			if (next > this.#stageIndex) this.#stageIndex = next;
+		}
+		if (message.type === "text" && message.stream === "stderr") {
+			this.#stderrTail = (this.#stderrTail + message.data).slice(-STDERR_TAIL_CHARS);
+		}
+		this.#arm();
+	}
+
+	stop(): void {
+		this.#stopped = true;
+		clearTimeout(this.#timer);
+		this.#timer = undefined;
+	}
+
+	#arm(): void {
+		clearTimeout(this.#timer);
+		this.#timer = setTimeout(() => this.#expire(), this.#noProgressMs);
+	}
+
+	#expire(): void {
+		if (this.#stopped) return;
+		const cpu = this.#readCpu();
+		// Unreadable CPU means busy and idle look the same: never cut a start off on silence alone.
+		// Any change counts, a drop included: a member of the group exited, which is activity.
+		if (cpu === undefined || cpu !== this.#lastCpu) {
+			this.#lastCpu = cpu;
+			this.#arm();
+			return;
+		}
+		this.stop();
+		const stage = stages[this.#stageIndex] ?? "interpreter-launch";
+		const seconds = Math.round(this.#noProgressMs / 1000);
+		const tail = this.#stderrTail.trim();
+		this.#onStall(
+			`${this.#options.label} kernel stalled at ${stage}: no output, stage change or CPU use for ${seconds} s${tail ? `; stderr: ${tail}` : ""}`,
+		);
+	}
+
+	#readCpu(): bigint | undefined {
+		return this.#pid === undefined ? undefined : this.#options.readGroupCpuTime?.(this.#pid);
+	}
+}

package/src/tool/cell-runtime.ts

@@ -5,7 +5,14 @@ import { formatModelTruncationNotice } from "../output/output-meta.ts";
 import { DEFAULT_MAX_BYTES, TailLineRing } from "../output/streaming-output.ts";
 import type { EvalToolCallMetric } from "./call-capture.ts";
 import { type EvalImageResizer, EvalOutputCollector, type EvalOutputResult } from "./image.ts";
-import type { EvalMemoryDetails, EvalRuntimeInfo, EvalStatusEvent, EvalToolDetails, EvalToolInput } from "./types.ts";
+import type {
+	EvalKernelState,
+	EvalMemoryDetails,
+	EvalRuntimeInfo,
+	EvalStatusEvent,
+	EvalToolDetails,
+	EvalToolInput,
+} from "./types.ts";
 
 const LIVE_UPDATE_LINES = 8;
 /** Same cadence as the core bash tool's streaming updates (BASH_UPDATE_THROTTLE_MS). */
@@ -48,6 +55,8 @@ export class CellResultBuilder {
 	readonly #output: EvalOutputCollector;
 	readonly #state: CellState;
 	#memory: KernelMemoryReport | undefined;
+	#restartNotice: string | undefined;
+	#kernelState: EvalKernelState | undefined;
 	readonly #liveLines = new TailLineRing({ maxBytes: DEFAULT_MAX_BYTES * 2, maxLines: LIVE_UPDATE_LINES });
 	#lastOutputUpdateAt = 0;
 	#outputUpdateTimer: ReturnType<typeof setTimeout> | undefined;
@@ -85,6 +94,8 @@ export class CellResultBuilder {
 	async finalize(result: KernelResult): Promise<AgentToolResult<EvalToolDetails>> {
 		this.#state.durationMs = result.durationMs;
 		this.#memory = result.memory;
+		this.#restartNotice = result.notice;
+		this.#kernelState = result.kernelState;
 		if (result.ok) {
 			if (result.valueRepr) this.#output.pushValue(`${result.valueRepr}\n`);
 			this.#state.status = "complete";
@@ -160,9 +171,10 @@ export class CellResultBuilder {
 				? `(displayed ${output.images.length} image${output.images.length === 1 ? "" : "s"}; no text output)`
 				: "(no output)");
 		const text = output.meta === undefined ? shown : `${shown}\n${formatModelTruncationNotice(output.meta)}`;
-		const notice = this.#memory?.notice;
-		const noticePart = notice === undefined ? [] : [{ type: "text" as const, text: notice }];
-		return { content: [{ type: "text", text }, ...noticePart, ...output.images], details };
+		const noticeParts = [this.#restartNotice, this.#memory?.notice].flatMap((notice) =>
+			notice === undefined ? [] : [{ type: "text" as const, text: notice }],
+		);
+		return { content: [{ type: "text", text }, ...noticeParts, ...output.images], details };
 	}
 
 	#details(output: EvalOutputResult | undefined, isError: boolean): EvalToolDetails {
@@ -202,6 +214,7 @@ export class CellResultBuilder {
 			...(output?.notice === undefined ? {} : { notice: output.notice }),
 			...(output?.meta === undefined ? {} : { meta: output.meta }),
 			...(output === undefined || this.#memory === undefined ? {} : { memory: memoryDetails(this.#memory) }),
+			...(this.#kernelState === undefined ? {} : { kernelState: this.#kernelState }),
 		};
 	}
 

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

@@ -2,7 +2,7 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type { EvalDetachedCellNotification, EvalDetachedCellSnapshot } from "./detached-cell-manager.ts";
 import { interruptionStateNote, unknownInterruptionStateNote } from "./interrupt-note.ts";
-import type { EvalMemoryDetails } from "./types.ts";
+import type { EvalKernelState, EvalMemoryDetails } from "./types.ts";
 
 const NOTIFICATION_TAIL_BYTES = 512;
 
@@ -78,11 +78,22 @@ function outcomeOf(cell: EvalDetachedCellSnapshot): string {
 }
 
 function stateNoteOf(cell: EvalDetachedCellSnapshot): string {
-	if (cell.state !== "cancelled") return memoryStateNote(cell.result.details?.memory);
+	if (cell.state !== "cancelled") {
+		const kernelState = cell.result.details?.kernelState;
+		return kernelState === undefined ? memoryStateNote(cell.result.details?.memory) : KERNEL_STATE_NOTES[kernelState];
+	}
 	const note = interruptionStateNote(cell.language, cell.stateRetained) ?? unknownInterruptionStateNote(cell.language);
 	return cell.interruptNote === undefined ? note : `${note} ${cell.interruptNote.trim()}`;
 }
 
+/** A kernel death decides what survived, whatever the memory report says. */
+const KERNEL_STATE_NOTES: Readonly<Record<EvalKernelState, string>> = {
+	lost: "The kernel died while this cell ran - every global is lost; the next eval cell runs on a fresh kernel.",
+	restarted:
+		"The kernel was restarted before this cell ran - globals from earlier cells are gone; this cell's variables are available to the next eval cell.",
+	"not-run": "This cell never ran and changed no kernel state.",
+};
+
 export function memoryStateNote(memory: EvalMemoryDetails | undefined): string {
 	if (memory?.overCeiling === true)
 		return "Kernel memory is over its ceiling - the kernel restarts before the next eval cell and every global is lost.";

package/src/tool/run-eval-cell.ts

@@ -209,7 +209,7 @@ async function executeCell(
 		const kernel = await execution.wait(options.kernelManager.getKernel(invocation.input.language, onMessage));
 		// Computed before the handler so its construction-time snapshot captures this cell's capability.
 		// Worker messages later restore that snapshot before calling host tools (#1754, #2512).
-		const kernelTools = jsKernelTools(kernel, invocation.input.language);
+		const kernelTools = kernelToolsFor(kernel);
 		const runBound = async (): Promise<AgentToolResult<EvalToolDetails>> => {
 			const queue = kernel.queueSnapshot();
 			state.queuedBehind = [...(queue.activeCellId === null ? [] : [queue.activeCellId]), ...queue.queuedCellIds];
@@ -292,16 +292,15 @@ async function executeCell(
 	}
 }
 
-function jsKernelTools(kernel: EvalKernel, language: string): KernelToolsCapability | undefined {
-	if (language !== "js") return undefined;
+function kernelToolsFor(kernel: EvalKernel): KernelToolsCapability | undefined {
 	if (!("describeKernelTools" in kernel) || typeof kernel.describeKernelTools !== "function") return undefined;
-	const js = kernel as EvalKernel & {
+	const withTools = kernel as EvalKernel & {
 		describeKernelTools: (names: readonly string[]) => Promise<KernelToolsDescribeResult>;
 		invokeKernelTool: ExtensionKernelTools["invoke"];
 	};
 	return {
 		capabilities: KERNEL_TOOLS_CAPABILITIES,
-		describe: (names) => js.describeKernelTools(names),
-		invoke: (request, options) => js.invokeKernelTool(request, options),
+		describe: (names) => withTools.describeKernelTools(names),
+		invoke: (request, options) => withTools.invokeKernelTool(request, options),
 	} satisfies ExtensionKernelTools;
 }

package/src/tool/types.ts

@@ -161,6 +161,12 @@ export interface KernelInterruptHandle {
 	readonly note?: string;
 }
 
+/** An unstarted cell a dead kernel hands back, so its replacement runs it with the same input and callbacks. */
+export interface PendingCell {
+	readonly input: EvalKernelRunInput;
+	readonly settle: (result: EvalKernelResult) => void;
+}
+
 export interface EvalKernel {
 	run(input: EvalKernelRunInput): Promise<EvalKernelResult>;
 	cancelQueued(cellId: string, reason: string): boolean;
@@ -171,6 +177,10 @@ export interface EvalKernel {
 	close(): Promise<void>;
 	/** Names this kernel has registered; JS collides with other languages in the same session. */
 	listKernelToolNames?(): readonly string[];
+	/** False once the interpreter died on its own; the session manager then replaces the instance. */
+	isAlive?(): boolean;
+	/** Hands over, and forgets, every queued cell of a dead kernel that never started. */
+	drainPending?(): readonly PendingCell[];
 }
 
 export interface EvalKernelManager {
@@ -273,6 +283,10 @@ export interface EvalToolDetails {
 	readonly meta?: TruncationMeta;
 	/** Kernel memory after the cell; its notice text is delivered as its own content part. */
 	readonly memory?: EvalMemoryDetails;
+	/** What a kernel death did to this cell's state, when one did. */
+	readonly kernelState?: EvalKernelState;
 }
 
+export type EvalKernelState = NonNullable<EvalKernelResult["kernelState"]>;
+
 export type EvalMemoryDetails = Omit<KernelMemoryReport, "notice">;