@code-yeongyu/senpi-codemode 2026.10.7 → 2026.10.9

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

@@ -1,6 +1,7 @@
 import type { ExtensionContext } from "@code-yeongyu/senpi";
 import type { KernelToHostMessage } from "../bridge/protocol.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
+import type { KernelToolsCapability } from "../kernels/js/kernel-tools-types.ts";
 import type { EvalKernel, EvalLanguage } from "../tool/types.ts";
 import {
 	CodemodeSessionDisposedError,
@@ -106,6 +107,11 @@ export class SessionManagerProxy implements CodemodeSessionManager, EvalExecutio
 		this.#current?.releaseKernelListener?.(language, onMessage);
 	}
 
+	bindCellKernelTools(token: string, capability: KernelToolsCapability): () => void {
+		// Bound to the generation that runs the cell: a later generation never serves that cell's host calls.
+		return this.#current?.bindCellKernelTools?.(token, capability) ?? (() => undefined);
+	}
+
 	async complete(request: CompletionRequest, ctx: ExtensionContext): Promise<CompletionResult> {
 		this.assertEvalExecutionAllowed();
 		const current = this.#current;

package/src/extension/session-manager.ts

@@ -6,10 +6,12 @@ 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 { KernelToolsCapability, 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 { CellKernelTools } from "./cell-kernel-tools.ts";
 import { parkWhenIdle } from "./idle-parking-kernel.ts";
 import {
 	javaScriptKernelMemory,
@@ -64,6 +66,7 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 	readonly #registrations: SessionKernelRegistrations;
 	#kernelCreations = new Map<EvalLanguage, Promise<EvalKernel>>();
 	#onMessageRefs = new Map<EvalLanguage, (message: KernelToHostMessage) => void>();
+	readonly #cellKernelTools = new CellKernelTools();
 	#context: ExtensionContext | undefined;
 	#generation = 0;
 	#disposePromise: Promise<void> | undefined;
@@ -90,7 +93,13 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 	}
 
 	async #call(request: BridgeToolCallRequest): Promise<unknown> {
-		return await routeBridgeToolCall(this.#options, request, this.#context?.evalHandleHost);
+		return await this.#cellKernelTools.run(request.cellToken, () =>
+			routeBridgeToolCall(this.#options, request, this.#context?.evalHandleHost),
+		);
+	}
+
+	bindCellKernelTools(token: string, capability: KernelToolsCapability): () => void {
+		return this.#cellKernelTools.bind(token, capability);
 	}
 
 	async getKernel(language: EvalLanguage, onMessage: (message: KernelToHostMessage) => void): Promise<EvalKernel> {
@@ -276,7 +285,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[] {

package/src/index.ts

@@ -157,6 +157,7 @@ export default function senpiCodemode(pi: CodemodeExtensionAPI, options: SenpiCo
 					complete,
 					settings: runtime.settings,
 					artifactsDir: runtime.artifactsDir,
+					...(runtime.pythonEnvironments === undefined ? {} : { pythonEnvironments: runtime.pythonEnvironments }),
 					cellManager,
 					handles,
 					executionTracker: manager,

package/src/kernels/jl/prelude.jl

@@ -210,9 +210,14 @@ function Base.getproperty(pool::SenpiWorkpool, name::Symbol)
     getfield(pool, name)
 end
 
-function workpool(agent::AbstractDict, name::AbstractString; mode=nothing)
+function workpool(agent::AbstractDict, name::AbstractString; mode=nothing, tools=nothing)
     args = Dict{String, Any}("op" => "create", "agent" => agent, "name" => name)
     mode !== nothing && (args["mode"] = mode)
+    if tools !== nothing
+        (tools isa AbstractVector && all(name -> name isa AbstractString, tools)) ||
+            throw(SenpiBridgeError("workpool(tools=...) takes a vector of tool names; got $(typeof(tools))", "invalid_tools"))
+        args["tools"] = collect(String, tools)
+    end
     result = senpi_workpool_call(args)
     details = get(result, "details", nothing)
     if details isa AbstractDict

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

@@ -1,6 +1,7 @@
 import type { HostToKernelMessage, KernelToHostMessage } from "../../bridge/protocol.ts";
 import { CHILD_LIFECYCLE_OP, INTERRUPT_ACK_OP } from "../../bridge/reserved.ts";
 import type { KernelInterruptHandle } from "../../tool/types.ts";
+import { inputAtStart } from "../shared/cell-source-at-start.ts";
 import { KernelToolHostPump } from "../shared/kernel-tools-pump.ts";
 import { ActiveCellControl } from "./active-cell-control.ts";
 import { DEFAULT_INTERRUPT_BOUNDS, type WorkerRetirement } from "./interrupt-bounds.ts";
@@ -195,6 +196,19 @@ export class JavaScriptKernel {
 		if (this.#lifecycle !== "open" || this.#runs.active || !this.#slot.present) return;
 		const next = this.#runs.startNext(performance.now());
 		if (!next) return;
+		const input = inputAtStart(next.input);
+		if ("refused" in input) {
+			this.#runs.releaseActive(next);
+			this.#runs.settle(next, {
+				type: "result",
+				cellId: next.input.cellId,
+				ok: false,
+				error: { message: input.refused },
+				durationMs: 0,
+			});
+			this.#startNext();
+			return;
+		}
 		this.#activeCell.arm(next);
 		this.#slot.postMessage({
 			type: "kernel-tools-names",
@@ -204,7 +218,7 @@ export class JavaScriptKernel {
 		this.#slot.postMessage({
 			type: "run",
 			cellId: next.input.cellId,
-			code: this.#moduleLoader.prepareCell(next.input.code, next.input.kernelPreludes),
+			code: this.#moduleLoader.prepareCell(input.code, input.kernelPreludes, input.sourceFile),
 			timeoutMs: next.input.timeoutMs,
 		});
 	}

package/src/kernels/js/kernel-tools-errors.js

@@ -8,6 +8,8 @@ export const KERNEL_TOOL_ERROR_CODES = Object.freeze([
 	"kernel_tool_failed",
 	"kernel_tool_recursion",
 	"kernel_tool_host_denied",
+	"kernel_tool_cancelled",
+	"kernel_tool_loop_mismatch",
 ]);
 
 export class KernelToolError extends Error {

package/src/kernels/js/kernel-tools-errors.ts

@@ -8,6 +8,8 @@ export const KERNEL_TOOL_ERROR_CODES = [
 	"kernel_tool_failed",
 	"kernel_tool_recursion",
 	"kernel_tool_host_denied",
+	"kernel_tool_cancelled",
+	"kernel_tool_loop_mismatch",
 ] as const;
 
 export type KernelToolErrorCode = (typeof KERNEL_TOOL_ERROR_CODES)[number];

package/src/kernels/js/local-module-loader.ts

@@ -1,4 +1,4 @@
-import { join, resolve, sep } from "node:path";
+import { dirname, join, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 import type { KernelPreludeContribution } from "@code-yeongyu/senpi";
 import type { BridgeConnectionConfig } from "../../bridge/protocol.ts";
@@ -121,8 +121,13 @@ export class LocalModuleLoader {
 		this.#prelude = loaderPrelude(runtimeContext(options));
 	}
 
-	prepareCell(code: string, contributions: readonly KernelPreludeContribution[] = []): string {
-		const prelude = `${this.#prelude}\n${contributionPrelude(this.#contributions.plan(contributions))}`;
-		return `${PREPARED_CELL_PREFIX}${JSON.stringify({ prelude, code: rewriteImports(code) })}`;
+	prepareCell(code: string, contributions: readonly KernelPreludeContribution[] = [], sourceFile?: string): string {
+		// A %load cell resolves its relative imports from its own file's directory for that cell only.
+		const base =
+			sourceFile === undefined
+				? ""
+				: `\nglobalThis.__senpi_module_context__ = { ...globalThis.__senpi_module_context__, cwdUrl: ${JSON.stringify(directoryUrl(dirname(sourceFile)))} };`;
+		const prelude = `${this.#prelude}${base}\n${contributionPrelude(this.#contributions.plan(contributions))}`;
+		return `${PREPARED_CELL_PREFIX}${JSON.stringify({ prelude, code: rewriteImports(code), ...(sourceFile === undefined ? {} : { sourceFile }) })}`;
 	}
 }

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

@@ -65,13 +65,15 @@ export class JsWorkerRuntime {
 		try {
 			let prelude = "";
 			let cellCode = code;
+			let sourceName = cellId;
 			if (code.startsWith(PREPARED_CELL_PREFIX)) {
 				const prepared = JSON.parse(code.slice(PREPARED_CELL_PREFIX.length));
 				if (!isPlainObject(prepared) || typeof prepared.prelude !== "string" || typeof prepared.code !== "string") throw new Error("Invalid prepared JavaScript cell payload");
 				({ prelude, code: cellCode } = prepared);
+				if (typeof prepared.sourceFile === "string") sourceName = prepared.sourceFile;
 			}
 			if (prelude) indirectEval(prelude, PRELUDE_SOURCE_URL);
-			const value = await awaitMaybePromise(indirectEval(bindKernelBun(wrapUserCode(cellCode)), cellId));
+			const value = await awaitMaybePromise(indirectEval(bindKernelBun(wrapUserCode(cellCode)), sourceName));
 			await this.#drainPendingDisplays();
 			return value;
 		} finally {

package/src/kernels/js/workpool.js

@@ -4,8 +4,11 @@ import { kernelToolError } from "./kernel-tools-errors.js";
 // Only host-tool sugar: no admission, worker, or queue state belongs to the kernel.
 export async function createWorkpool(callTool, agent, name, options = {}) {
 	if (inKernelToolInvoke()) throw kernelToolError("kernel_tool_recursion", "kernel tools may not invoke workpool()");
-	if (options === null || typeof options !== "object" || Array.isArray(options) || Object.keys(options).some(key => key !== "mode")) {
-		throw new TypeError("workpool() options only accept mode");
+	if (options === null || typeof options !== "object" || Array.isArray(options) || Object.keys(options).some(key => key !== "mode" && key !== "tools")) {
+		throw new TypeError("workpool() options only accept mode and tools");
+	}
+	if (options.tools !== undefined && (!Array.isArray(options.tools) || !options.tools.every(name => typeof name === "string"))) {
+		throw workpoolError("invalid_tools", `workpool() tools takes an array of tool names; got ${Array.isArray(options.tools) ? "an array with a non-string" : typeof options.tools}`);
 	}
 	const call = async args => {
 		try {

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

@@ -3,7 +3,8 @@ import type { BridgeConnectionConfig, KernelToHostMessage } from "../../bridge/p
 import type { EvalKernelRunInput } from "../../tool/types.ts";
 import type { SessionEnvironment } from "../session-env.ts";
 import type { KernelLifecycle } from "../shared/kernel-death.ts";
-import type { KernelSpawnProcess } from "./process.ts";
+import type { PeerKernelToolsDescribe } from "./kernel-tools-host.ts";
+import type { KernelSpawnProcess, KillProcessGroup } from "./process.ts";
 import type { PythonStartupStage } from "./startup.ts";
 import type { PythonTransportResult } from "./transport.ts";
 
@@ -15,14 +16,22 @@ export interface PythonKernelStartOptions extends KernelLifecycle {
 	readonly env?: NodeJS.ProcessEnv;
 	/** Per-session PI_* values merged into the interpreter environment at spawn. */
 	readonly sessionEnv?: SessionEnvironment;
-	/** Python bootstrap inactivity guard per advancing stage, not a total readiness deadline. */
+	/** How long a starting interpreter may show no stage change, output or CPU use before startup fails. */
 	readonly startupTimeoutMs?: number;
+	/** Total startup backstop for an interpreter that stays busy but never becomes ready. */
+	readonly startupCeilingMs?: number;
+	/** Reads the interpreter's CPU time; the default reads the process group (Unix) or the process (Windows). */
+	readonly readCpuTime?: (pid: number | undefined) => bigint | undefined;
+	/** Signals the interpreter's process group when it is retired; the default is `process.kill(-pid, signal)`. */
+	readonly killProcessGroup?: KillProcessGroup;
 	/** Observes bootstrap control events without mixing them into cell output callbacks. */
 	readonly onStartupProgress?: (stage: PythonStartupStage) => void;
 	readonly onMessage?: (message: KernelToHostMessage) => void;
 	readonly spawnProcess?: KernelSpawnProcess;
 	/** Post-cell collection, notice, and ceiling thresholds sent on `init`; absent leaves memory unmanaged. */
 	readonly memory?: KernelMemoryThresholds;
+	/** The JavaScript kernel's describe, so a name defined in both languages is a describe-time collision. */
+	readonly peerKernelToolsDescribe?: PeerKernelToolsDescribe;
 }
 
 export type PythonKernelRunOptions = EvalKernelRunInput;

package/src/kernels/py/kernel-tools-host.ts

@@ -0,0 +1,97 @@
+import type { HostToKernelMessage, KernelToHostMessage } from "../../bridge/protocol.ts";
+import { kernelToolError } from "../js/kernel-tools-errors.ts";
+import type {
+	KernelToolsDescribeResult,
+	KernelToolsInvokeOptions,
+	KernelToolsInvokeRequest,
+} from "../js/kernel-tools-types.ts";
+import { KernelToolHostPump } from "../shared/kernel-tools-pump.ts";
+
+export type KernelToolReplyEvent = {
+	readonly requestId: string;
+	readonly ok: boolean;
+	readonly code?: string;
+	readonly message?: string;
+	readonly output?: string;
+};
+
+function replyEvent(message: Extract<KernelToHostMessage, { type: "kernel-tool-invoke-reply" }>): KernelToolReplyEvent {
+	return {
+		requestId: message.requestId,
+		ok: message.ok,
+		...(message.ok ? {} : { message: message.error.message }),
+		...(!message.ok && message.error.code !== undefined ? { code: message.error.code } : {}),
+		...(message.output === undefined ? {} : { output: message.output }),
+	};
+}
+
+export type PeerKernelToolsDescribe = (names: readonly string[]) => Promise<KernelToolsDescribeResult> | undefined;
+
+/** The host half of Python kernel tools: frames over the live transport, names, and generation fencing. */
+export class PythonKernelTools {
+	readonly #pump: KernelToolHostPump;
+	readonly #peerDescribe: PeerKernelToolsDescribe | undefined;
+	#names: readonly string[] = [];
+
+	constructor(options: {
+		readonly post: (message: HostToKernelMessage) => void;
+		readonly isOpen: () => boolean;
+		readonly peerDescribe?: PeerKernelToolsDescribe;
+	}) {
+		this.#pump = new KernelToolHostPump(options.post, options.isOpen);
+		this.#peerDescribe = options.peerDescribe;
+	}
+
+	get events(): EventTarget {
+		return this.#pump.events;
+	}
+
+	listNames(): readonly string[] {
+		return this.#names;
+	}
+
+	consume(message: KernelToHostMessage): boolean {
+		if (message.type === "kernel-tools-defined") {
+			this.#names = [...message.names];
+			return true;
+		}
+		if (message.type === "kernel-tool-invoke-reply") {
+			// Published even when the waiter is gone (a cancelled call), so its explicit outcome stays observable.
+			this.#pump.events.dispatchEvent(
+				new CustomEvent<KernelToolReplyEvent>("kernelToolReply", { detail: replyEvent(message) }),
+			);
+		}
+		return this.#pump.consume(message);
+	}
+
+	/** The interpreter is gone (restart, reset, close, death): its definitions and in-flight calls are too. */
+	retire(reason: "kernel_tool_stale" | "tools_unavailable", message: string): void {
+		this.#names = [];
+		this.#pump.rejectAll(kernelToolError(reason, message));
+	}
+
+	async describe(names: readonly string[]): Promise<KernelToolsDescribeResult> {
+		const own = await this.#pump.describe(names);
+		const peer = await this.#peerDescribe?.(names)?.catch(() => undefined);
+		if (!peer) return own;
+		const definedInJs = new Set(peer.results.filter((entry) => entry.ok).map((entry) => entry.name));
+		return {
+			results: own.results.map((entry) =>
+				entry.ok && definedInJs.has(entry.name)
+					? {
+							name: entry.name,
+							ok: false,
+							error: {
+								code: "tool_name_collision",
+								message: `Kernel tool ${entry.name} is defined in both js and py`,
+							},
+						}
+					: entry,
+			),
+		};
+	}
+
+	async invoke(request: KernelToolsInvokeRequest, options?: AbortSignal | KernelToolsInvokeOptions): Promise<unknown> {
+		return await this.#pump.invoke(request, options);
+	}
+}

package/src/kernels/py/kernel.ts

@@ -1,13 +1,18 @@
 // allow: SIZE_OK — one persistent Python lifecycle state machine owns queue, generation, and retirement.
 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 type {
+	KernelToolsDescribeResult,
+	KernelToolsInvokeOptions,
+	KernelToolsInvokeRequest,
+} from "../js/kernel-tools-types.ts";
+import { inputAtStart } from "../shared/cell-source-at-start.ts";
 import { describeExit } from "../shared/kernel-death.ts";
 import { KernelMemoryHost } from "../shared/kernel-memory-host.ts";
 import { KernelPreludeTracker } from "../shared/kernel-prelude-plan.ts";
 import { runHostCell } from "./host-cell.ts";
 import type { PendingRun, PythonKernelRunOptions, PythonKernelStartOptions, ResultMessage } from "./kernel-contract.ts";
-import { pythonStartupHangGuardMs } from "./startup.ts";
+import { PythonKernelTools } from "./kernel-tools-host.ts";
+import { pythonStartupCeilingMs, pythonStartupHangGuardMs } from "./startup.ts";
 import { failedPythonResult, PythonKernelTransport } from "./transport.ts";
 
 export type { PythonKernelRunOptions, PythonKernelStartOptions } from "./kernel-contract.ts";
@@ -15,6 +20,15 @@ export type { KernelChild, KernelSpawnOptions, KernelSpawnProcess } from "./proc
 
 const interruptEscalationMs = 5_000;
 
+// Every interpreter this process starts gets its own generation, so a kernel tool descriptor taken from one
+// never resolves in another, whether it was replaced by reset, by a lazy restart after a crash, or by a new
+// kernel instance an owner created.
+let lastInterpreterGeneration = 0;
+function nextInterpreterGeneration(): number {
+	lastInterpreterGeneration += 1;
+	return lastInterpreterGeneration;
+}
+
 export class PythonKernel {
 	readonly #options: PythonKernelStartOptions;
 	#transport: PythonKernelTransport | null = null;
@@ -29,11 +43,17 @@ export class PythonKernel {
 	readonly #memory: KernelMemoryHost | null;
 	#generation = 0;
 	#closed = false;
+	readonly #tools: PythonKernelTools;
 	#dead = false;
 
 	private constructor(options: PythonKernelStartOptions) {
 		this.#options = options;
 		this.#memory = options.memory === undefined ? null : new KernelMemoryHost("py", options.memory);
+		this.#tools = new PythonKernelTools({
+			post: (message) => this.#transport?.post(message),
+			isOpen: () => this.#transport !== null && !this.#closed,
+			...(options.peerKernelToolsDescribe === undefined ? {} : { peerDescribe: options.peerKernelToolsDescribe }),
+		});
 	}
 
 	static async start(options: PythonKernelStartOptions): Promise<PythonKernel> {
@@ -43,7 +63,11 @@ export class PythonKernel {
 	}
 
 	listKernelToolNames(): readonly string[] {
-		return [];
+		return this.#tools.listNames();
+	}
+
+	get kernelToolEvents(): EventTarget {
+		return this.#tools.events;
 	}
 
 	isAlive(): boolean {
@@ -58,12 +82,15 @@ export class PythonKernel {
 		});
 	}
 
-	describeKernelTools(_names: readonly string[]): Promise<never> {
-		return rejectKernelToolsUnavailable();
+	describeKernelTools(names: readonly string[]): Promise<KernelToolsDescribeResult> {
+		return this.#tools.describe(names);
 	}
 
-	invokeKernelTool(_request: unknown, _options?: AbortSignal | KernelToolsInvokeOptions): Promise<never> {
-		return rejectKernelToolsUnavailable();
+	invokeKernelTool(
+		request: KernelToolsInvokeRequest,
+		options?: AbortSignal | KernelToolsInvokeOptions,
+	): Promise<unknown> {
+		return this.#tools.invoke(request, options);
 	}
 
 	run(input: PythonKernelRunOptions): Promise<ResultMessage> {
@@ -131,6 +158,7 @@ export class PythonKernel {
 		if (this.#failure) throw this.#failure;
 		if (this.#closed) throw new Error("Python kernel is closed");
 		const generation = ++this.#generation;
+		this.#tools.retire("kernel_tool_stale", "Python kernel was reset; its kernel tools are gone");
 		const prior = this.#starting;
 		const operation = (async () => {
 			await prior?.catch(() => undefined);
@@ -156,6 +184,7 @@ export class PythonKernel {
 		if (this.#closePromise) return await this.#closePromise;
 		this.#closed = true;
 		this.#generation += 1;
+		this.#tools.retire("tools_unavailable", "Python kernel is closed");
 		this.#settleAllPending("Python kernel closed");
 		const starting = this.#starting;
 		this.#closePromise = (async () => {
@@ -215,10 +244,15 @@ export class PythonKernel {
 			});
 			return;
 		}
+		const input = inputAtStart(pending.input);
+		if ("refused" in input) {
+			this.#settleRun(pending, failedPythonResult(pending.input.cellId, input.refused));
+			return;
+		}
 		try {
 			this.#transport?.run({
-				...pending.input,
-				preludePlan: this.#preludes.plan(pending.input.kernelPreludes ?? []),
+				...input,
+				preludePlan: this.#preludes.plan(input.kernelPreludes ?? []),
 			});
 		} catch (error) {
 			const failure = error instanceof Error ? error : new Error(String(error));
@@ -283,6 +317,7 @@ export class PythonKernel {
 			...this.#options,
 			onMessage: (message) => {
 				if (message.type === "result") return;
+				if (generation === this.#generation && this.#tools.consume(message)) return;
 				const callback =
 					message.type === "ready" || message.type === "init-failed" || message.type === "closed"
 						? this.#options.onMessage
@@ -290,6 +325,8 @@ export class PythonKernel {
 				callback?.(message);
 			},
 			startupTimeoutMs: this.#options.startupTimeoutMs ?? pythonStartupHangGuardMs,
+			startupCeilingMs: this.#options.startupCeilingMs ?? pythonStartupCeilingMs,
+			kernelGeneration: nextInterpreterGeneration(),
 			isOwned: () => !this.#closed && generation === this.#generation,
 			onRetirementFailure: (transport, error) => {
 				if (!this.#transport) this.#transport = transport;
@@ -324,6 +361,7 @@ export class PythonKernel {
 	#onExit(transport: PythonKernelTransport, error: Error, reason: string): void {
 		if (this.#transport !== transport) return;
 		this.#transport = null;
+		this.#tools.retire("kernel_tool_stale", "Python kernel died; its kernel tools are gone");
 		// With an owner listening, a death is final for this instance: the cells that never started stay
 		// queued for `drainPending` and the owner replaces it. Without one it respawns lazily, as before.
 		const onDeath = this.#options.onDeath;