@tlockney/cdp-kernel 0.4.0 → 0.6.0

package/dist/bun-target.d.ts

@@ -1,4 +1,4 @@
-import type { CdpParams, EvaluateResult, RemoteObject } from "./cdp.ts";
+import { type CdpParams, type EvaluateResult, type RemoteObject } from "./cdp.ts";
 import { transformCellForEval } from "./transform.ts";
 import { type KernelTarget, type TargetEvents } from "./target.ts";
 /**
@@ -55,6 +55,6 @@ export declare class BunTarget implements KernelTarget {
     inspect(path: string, detail: number): Promise<string | null>;
     /** None: top-level declarations here are properties of globalThis. */
     lexicalNames(): Promise<string[]>;
-    replyInput(value: string | null): void;
+    replyInput(value: string | null, interrupted?: boolean): void;
     kill(): void;
 }

package/dist/bun-target.js

@@ -9,9 +9,11 @@ import { Buffer } from "node:buffer";
 import process from "node:process";
 import { spawn } from "node:child_process";
 import { join } from "node:path";
+import { asEvaluateResult } from "./cdp.js";
 import { transformCellForEval } from "./transform.js";
 import { runtimeDir } from "./package.js";
-import { Gates, Interrupted, isTargetMessage, PipeDemux } from "./target.js";
+import { killOnExit } from "./children.js";
+import { Gates, Interrupted, isTargetMessage, parseJson, PipeDemux } from "./target.js";
 /**
  * How long an interrupted target has to answer a ping. A cell waiting on a
  * promise leaves the event loop free, so the answer is near-instant; a busy
@@ -45,6 +47,9 @@ export class BunTarget {
     #gates = new Gates();
     #pending = new Map();
     #nextId = 0;
+    /** Ids of requests interrupt() may cut short: eval and comm. */
+    #interruptibleIds = new Set();
+    #exitedOnce = false;
     #messages = Promise.resolve();
     #interrupted = false;
     #stopNote;
@@ -60,6 +65,7 @@ export class BunTarget {
         const env = { ...process.env, FORCE_COLOR: "1" };
         delete env.NO_COLOR;
         const child = spawn(cmd, args, { cwd: options.cwd, stdio: ["pipe", "pipe", "pipe", "pipe"], env });
+        killOnExit(child);
         const channel = child.stdio[3];
         if (!child.stdout || !child.stderr || !isDuplex(channel)) {
             child.kill();
@@ -97,7 +103,8 @@ export class BunTarget {
         this.#channel.on("data", (chunk) => {
             buffer += chunk;
             for (let nl = buffer.indexOf("\n"); nl !== -1; nl = buffer.indexOf("\n")) {
-                const msg = JSON.parse(buffer.slice(0, nl));
+                // Cells can write here through __cdpk_send too (#122).
+                const msg = parseJson(buffer.slice(0, nl));
                 buffer = buffer.slice(nl + 1);
                 if (isTargetMessage(msg))
                     this.#deliver(msg, events);
@@ -116,12 +123,14 @@ export class BunTarget {
         if (!pending)
             return; // abandoned
         this.#pending.delete(id);
+        this.#interruptibleIds.delete(id);
         if (typeof reply.failure === "string")
             pending.reject(new Error(reply.failure));
         else
             pending.resolve(reply);
     }
     #exited(code, events) {
+        this.#exitedOnce = true;
         this.#gates.openAll();
         this.#stdout.close();
         this.#stderr.close();
@@ -132,6 +141,7 @@ export class BunTarget {
         for (const pending of this.#pending.values())
             pending.reject(new Abandoned(reason));
         this.#pending.clear();
+        this.#interruptibleIds.clear();
     }
     // Binding messages wait until both pipes have caught up to their marker,
     // and are delivered strictly in order (as in Target).
@@ -142,10 +152,15 @@ export class BunTarget {
             this.#gates.open(msg.barrier);
         });
     }
-    #request(op, params = {}) {
+    #request(op, params = {}, interruptible = false) {
+        // Bun is gone; a write to its channel would never be answered.
+        if (this.#exitedOnce)
+            return Promise.reject(new Abandoned("the bun session is closed"));
         const id = ++this.#nextId;
         return new Promise((resolve, reject) => {
             this.#pending.set(id, { resolve, reject });
+            if (interruptible)
+                this.#interruptibleIds.add(id);
             this.#channel.write(JSON.stringify({ id, op, ...params }) + "\n");
         });
     }
@@ -153,7 +168,7 @@ export class BunTarget {
     async #interruptible(op, params, what) {
         this.#interrupted = false;
         try {
-            return await this.#request(op, params);
+            return await this.#request(op, params, true);
         }
         catch (err) {
             if (err instanceof Abandoned || this.#interrupted)
@@ -162,7 +177,7 @@ export class BunTarget {
         }
     }
     async evaluate(script) {
-        return (await this.#interruptible("eval", { code: script }, "Execution"));
+        return asEvaluateResult(await this.#interruptible("eval", { code: script }, "Execution"));
     }
     /**
      * There's no terminateExecution, but a cell that's waiting on a promise
@@ -173,12 +188,19 @@ export class BunTarget {
      */
     async interrupt() {
         this.#interrupted = true;
+        const running = [...this.#interruptibleIds];
         const answered = await Promise.race([
             this.#request("ping").then(() => true, () => false),
             new Promise((resolve) => setTimeout(() => resolve(false), INTERRUPT_GRACE_MS)),
         ]);
         if (answered) {
-            this.#abandonPending("interrupted");
+            // Only the cell or comm handler: a barrier or broadcast request in
+            // flight would otherwise fail as a KernelError (#135).
+            for (const id of running) {
+                this.#pending.get(id)?.reject(new Abandoned("interrupted"));
+                this.#pending.delete(id);
+                this.#interruptibleIds.delete(id);
+            }
             return;
         }
         this.#stopNote = RESTART_NOTE;
@@ -227,8 +249,8 @@ export class BunTarget {
     lexicalNames() {
         return Promise.resolve([]);
     }
-    replyInput(value) {
-        this.#child.stdin?.write(JSON.stringify({ value }) + "\n");
+    replyInput(value, interrupted = false) {
+        this.#child.stdin?.write(JSON.stringify({ value, interrupted }) + "\n");
     }
     kill() {
         this.#child.kill();

package/dist/cdp.d.ts

@@ -29,13 +29,20 @@ export declare class CdpAbandoned extends Error {
 }
 export declare class CdpSession {
     #private;
-    readonly closed: Promise<void>;
     private constructor();
     static connect(url: string): Promise<CdpSession>;
     on(method: string, listener: (params: CdpParams) => void): void;
     send(method: string, params?: CdpParams): Promise<CdpParams>;
+    /** In-flight calls, oldest first, with how long each has waited: for a state dump (#237). */
+    pendingCalls(): string[];
     /** Reject every in-flight call; their late responses are then ignored. */
     abandonPending(): void;
     close(): void;
 }
+export declare function isRecord(value: unknown): value is CdpParams;
+export declare function isRemoteObject(value: unknown): value is RemoteObject;
+/**
+ * A Runtime.evaluate-shaped reply, checked: a value, or exceptionDetails.
+ * The Bun and workerd drivers send no `result` with a thrown exception.
+ */
 export declare function asEvaluateResult(raw: CdpParams): EvaluateResult;

package/dist/cdp.js

@@ -21,7 +21,6 @@ export class CdpSession {
     #nextId = 0;
     #pending = new Map();
     #listeners = new Map();
-    closed;
     constructor(ws) {
         this.#ws = ws;
         ws.addEventListener("message", (event) => {
@@ -43,14 +42,11 @@ export class CdpSession {
                     listener(msg.params);
             }
         });
-        this.closed = new Promise((resolve) => {
-            ws.addEventListener("close", () => {
-                for (const pending of this.#pending.values()) {
-                    pending.reject(new Error("CDP connection closed"));
-                }
-                this.#pending.clear();
-                resolve();
-            });
+        ws.addEventListener("close", () => {
+            for (const pending of this.#pending.values()) {
+                pending.reject(new Error("CDP connection closed"));
+            }
+            this.#pending.clear();
         });
     }
     static async connect(url) {
@@ -67,12 +63,21 @@ export class CdpSession {
         this.#listeners.set(method, list);
     }
     send(method, params = {}) {
+        // send() on a closing or closed socket drops the frame silently, so
+        // nothing would ever settle the call (#133).
+        if (this.#ws.readyState !== WebSocket.OPEN)
+            return Promise.reject(new Error("CDP connection closed"));
         const id = ++this.#nextId;
         return new Promise((resolve, reject) => {
-            this.#pending.set(id, { method, resolve, reject });
+            this.#pending.set(id, { method, sent: Date.now(), resolve, reject });
             this.#ws.send(JSON.stringify({ id, method, params }));
         });
     }
+    /** In-flight calls, oldest first, with how long each has waited: for a state dump (#237). */
+    pendingCalls() {
+        const now = Date.now();
+        return [...this.#pending.values()].map((p) => `${p.method} (${now - p.sent} ms)`);
+    }
     /** Reject every in-flight call; their late responses are then ignored. */
     abandonPending() {
         for (const pending of this.#pending.values()) {
@@ -84,6 +89,21 @@ export class CdpSession {
         this.#ws.close();
     }
 }
+export function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+export function isRemoteObject(value) {
+    return isRecord(value) && typeof value.type === "string";
+}
+/**
+ * A Runtime.evaluate-shaped reply, checked: a value, or exceptionDetails.
+ * The Bun and workerd drivers send no `result` with a thrown exception.
+ */
 export function asEvaluateResult(raw) {
-    return raw;
+    const details = raw.exceptionDetails;
+    if (details !== undefined ? !isRecord(details) || typeof details.text !== "string" : !isRemoteObject(raw.result)) {
+        throw new Error(`the target sent a malformed evaluate result: ${JSON.stringify(raw).slice(0, 200)}`);
+    }
+    const result = isRemoteObject(raw.result) ? raw.result : { type: "undefined" };
+    return details === undefined ? { result } : { result, exceptionDetails: details };
 }

package/dist/celld-target.d.ts

@@ -1,4 +1,4 @@
-import type { CdpParams } from "./cdp.ts";
+import { type CdpParams } from "./cdp.ts";
 import type { TargetEvents } from "./target.ts";
 import { WorkerdTarget } from "./workerd-target.ts";
 /** The project keys the generated config keeps: bindings and compatibility. */

package/dist/celld-target.js

@@ -21,8 +21,10 @@ import { createServer } from "node:net";
 import { homedir, tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { build } from "esbuild";
+import { isRecord } from "./cdp.js";
 import { parseJsonc } from "./deno-config.js";
 import { runtimeDir } from "./package.js";
+import { childPids, killOnExit, reapWith } from "./children.js";
 import { cellMeta, WorkerdTarget } from "./workerd-target.js";
 import { builtinAliases, findWranglerConfig } from "./workers-project.js";
 /** The project keys the generated config keeps: bindings and compatibility. */
@@ -120,16 +122,10 @@ function channelOf(ws) {
         },
     };
 }
-/** celld dev's own children, which run in their own process groups. */
-function childPids(pid) {
-    try {
-        return execFileSync("pgrep", ["-P", String(pid)], { encoding: "utf8" }).split(/\s+/).filter(Boolean).map(Number);
-    }
-    catch {
-        return []; // none
-    }
-}
-/** Kills celld dev's node, then the supervisor itself. */
+/**
+ * Kills celld dev's own children, which run in their own process groups,
+ * then the supervisor itself.
+ */
 function killTree(child) {
     for (const pid of childPids(child.pid ?? -1)) {
         try {
@@ -141,6 +137,8 @@ function killTree(child) {
     }
     child.kill("SIGKILL");
 }
+/** Starts tried when a port is taken (see CelldHost.start). */
+const PORT_ATTEMPTS = 3;
 /** The driver on `celld dev`. */
 class CelldHost {
     runtime;
@@ -153,7 +151,23 @@ class CelldHost {
         this.runtime = runtime;
         this.project = project;
     }
+    /**
+     * celld dev, retried when a port is taken: both its --port (from
+     * freePort) and its node's own listener are picked free and bound later,
+     * so another process can take one in between (#54).
+     */
     static async start(cwd, projectConfig, executable) {
+        for (let attempt = 1;; attempt++) {
+            try {
+                return await CelldHost.#start(cwd, projectConfig, executable);
+            }
+            catch (err) {
+                if (attempt >= PORT_ATTEMPTS || !(err instanceof Error && /Address already in use/.test(err.message)))
+                    throw err;
+            }
+        }
+    }
+    static async #start(cwd, projectConfig, executable) {
         const celld = executable ?? findCelld();
         const version = celldVersionOf(execFileSync(celld, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }));
         const source = await runtimeDir(new URL("../runtime/", import.meta.url).href);
@@ -163,7 +177,7 @@ class CelldHost {
             if (projectConfig.endsWith(".toml"))
                 throw new Error("celld reads wrangler.jsonc or wrangler.json, not wrangler.toml");
             const parsed = parseJsonc(readFileSync(projectConfig, "utf8"));
-            if (typeof parsed !== "object" || parsed === null)
+            if (!isRecord(parsed) || Array.isArray(parsed))
                 throw new Error(`${projectConfig} is not an object`);
             project = parsed;
             dir = join(dirname(projectConfig), ".celld", "cdp-kernel");
@@ -173,9 +187,14 @@ class CelldHost {
             dir = mkdtempSync(join(tmpdir(), "cdpk-celld-"));
         }
         const main = project && typeof project.main === "string" ? resolve(dirname(projectConfig ?? cwd), project.main) : undefined;
-        const define = project && typeof project.define === "object" && project.define !== null
-            ? project.define
-            : {};
+        const define = {};
+        if (project && isRecord(project.define)) {
+            for (const [name, value] of Object.entries(project.define)) {
+                if (typeof value !== "string")
+                    throw new Error(`define.${name} in ${projectConfig} must be a string`);
+                define[name] = value;
+            }
+        }
         const token = randomBytes(32).toString("hex");
         // 0600: the config carries this launch's token.
         writeFileSync(join(dir, "driver.mjs"), await bundleDriver(source, main, define));
@@ -186,25 +205,35 @@ class CelldHost {
         const child = spawn(celld, ["dev", dir, "--host", "127.0.0.1", "--port", String(port), "--no-watch"], {
             stdio: ["ignore", "pipe", "pipe"],
         });
-        child.once("exit", () => {
+        const removeFiles = () => {
             if (projectConfig === null)
                 rmSync(dir, { recursive: true, force: true });
             else
                 for (const name of ["driver.mjs", "wrangler.jsonc"])
                     rmSync(join(dir, name), { force: true });
-        });
+        };
+        child.once("exit", removeFiles);
+        killOnExit(child, () => {
+            killTree(child);
+            removeFiles();
+        }, { dir: projectConfig === null ? dir : undefined });
         // Cell output is captured in the driver; celld's own lines go to the
         // server log.
+        // `early` keeps that output for a startup error only, and stops growing
+        // once the session is open.
         let early = "";
+        let starting = true;
         const log = (chunk) => {
-            early += chunk.toString();
+            if (starting)
+                early += chunk.toString();
             process.stderr.write(`[cdp-kernel celld] ${chunk}`);
         };
         child.stdout?.on("data", log);
         child.stderr?.on("data", log);
         const exited = new Promise((_, reject) => {
             child.once("error", reject);
-            child.once("exit", (code) => reject(new Error(`celld exited (${code}) before it was ready:\n${early}`)));
+            // On close, not exit, so its last output is in the message.
+            child.once("close", (code) => reject(new Error(`celld exited (${code}) before it was ready:\n${early}`)));
         });
         exited.catch(() => { });
         const url = `127.0.0.1:${port}/?token=${token}`;
@@ -226,7 +255,13 @@ class CelldHost {
             return channelOf(ws);
         })();
         try {
-            return new CelldHost(child, await Promise.race([ready, exited]), `celld ${version}`.trim(), projectConfig ?? undefined);
+            const host = new CelldHost(child, await Promise.race([ready, exited]), `celld ${version}`.trim(), projectConfig ?? undefined);
+            // Its server, in its own process group, outlives a SIGKILLed celld dev.
+            for (const pid of childPids(child.pid ?? -1))
+                reapWith(pid, child);
+            starting = false;
+            early = "";
+            return host;
         }
         catch (err) {
             killTree(child);

package/dist/children.d.ts

@@ -0,0 +1,29 @@
+import { type ChildProcess } from "node:child_process";
+/**
+ * The helper's script. Lines on stdin: `+pid` registers a pid, `-pid`
+ * forgets it (it exited, and the pid may be reused), `d<path>` registers a
+ * directory. In its own session, so a killpg of this process's group (as
+ * Jupyter's kill does) doesn't take it down first.
+ */
+export declare const REAPER_SCRIPT = "trap '' HUP INT\npids=\" \"\ndirs=\"\"\nwhile IFS= read -r line; do\n  case $line in\n    +*) pids=\"$pids${line#?} \" ;;\n    -*) pids=$(printf '%s' \"$pids\" | sed \"s/ ${line#?} / /\") ;;\n    d*) dirs=\"$dirs${line#?}\n\" ;;\n  esac\ndone\nkill -9 $pids 2>/dev/null\nprintf '%s' \"$dirs\" | while IFS= read -r dir; do rm -rf -- \"$dir\"; done\n";
+/**
+ * Kills `pid` if this process dies, until the returned function is called
+ * (when the process is known to have exited: its pid may be reused).
+ */
+export declare function reap(pid: number): () => void;
+/**
+ * Kills `pid`, which isn't this process's child (a runtime's own child in
+ * its own process group), if this process dies while `owner` runs.
+ */
+export declare function reapWith(pid: number, owner: ChildProcess): void;
+/** `pid`'s children whose command line matches `pattern` (pgrep's -f). */
+export declare function childPids(pid: number, pattern?: string): number[];
+/**
+ * Kills `child` if it's still running when this process exits. `cleanup`
+ * replaces the default SIGKILL; it must be synchronous, as exit hooks are,
+ * and do whatever the child's own exit listener would have done. If this
+ * process is SIGKILLed, the helper kills `child` and removes `dir`.
+ */
+export declare function killOnExit(child: ChildProcess, cleanup?: () => void, { dir }?: {
+    dir?: string;
+}): void;

package/dist/children.js

@@ -0,0 +1,114 @@
+// Runtimes this process started, killed when it exits however it exits
+// short of SIGKILL: a target left behind keeps running, reparented to pid 1,
+// with whatever temp directory it uses (#127, #218).
+//
+// SIGKILL runs no exit hook, so a helper outside this process also knows the
+// runtimes' pids (#240): a detached sh reading this process's pipe, which
+// kills whatever is still registered, and removes the registered temp
+// directories, once the pipe closes. That covers what nothing in a runtime
+// can notice: celld dev and its server, and a Node or Deno runtime stuck in
+// a cell's synchronous loop, where the #219 watchdog never gets to run.
+import process from "node:process";
+import { execFileSync, spawn } from "node:child_process";
+const cleanups = new Set();
+function runAll() {
+    for (const cleanup of cleanups) {
+        try {
+            cleanup();
+        }
+        catch {
+            // Best effort: the process is exiting.
+        }
+    }
+    cleanups.clear();
+}
+let hooked = false;
+/**
+ * The helper's script. Lines on stdin: `+pid` registers a pid, `-pid`
+ * forgets it (it exited, and the pid may be reused), `d<path>` registers a
+ * directory. In its own session, so a killpg of this process's group (as
+ * Jupyter's kill does) doesn't take it down first.
+ */
+export const REAPER_SCRIPT = `trap '' HUP INT
+pids=" "
+dirs=""
+while IFS= read -r line; do
+  case $line in
+    +*) pids="$pids\${line#?} " ;;
+    -*) pids=$(printf '%s' "$pids" | sed "s/ \${line#?} / /") ;;
+    d*) dirs="$dirs\${line#?}
+" ;;
+  esac
+done
+kill -9 $pids 2>/dev/null
+printf '%s' "$dirs" | while IFS= read -r dir; do rm -rf -- "$dir"; done
+`;
+let reaper;
+/** Sends `line` to the helper, starting it first; a no-op on Windows. */
+function tellReaper(line) {
+    if (reaper === undefined) {
+        reaper = null;
+        if (process.platform === "win32")
+            return;
+        try {
+            const child = spawn("/bin/sh", ["-c", REAPER_SCRIPT], { cwd: "/", detached: true, stdio: ["pipe", "ignore", "ignore"] });
+            child.once("error", () => (reaper = null));
+            child.stdin?.on("error", () => (reaper = null));
+            // Neither the helper nor its pipe keeps this process running.
+            child.unref();
+            child.stdin?.unref?.();
+            reaper = child;
+        }
+        catch {
+            return;
+        }
+    }
+    reaper?.stdin?.write(`${line}\n`);
+}
+/**
+ * Kills `pid` if this process dies, until the returned function is called
+ * (when the process is known to have exited: its pid may be reused).
+ */
+export function reap(pid) {
+    tellReaper(`+${pid}`);
+    return () => tellReaper(`-${pid}`);
+}
+/**
+ * Kills `pid`, which isn't this process's child (a runtime's own child in
+ * its own process group), if this process dies while `owner` runs.
+ */
+export function reapWith(pid, owner) {
+    if (owner.exitCode !== null || owner.signalCode !== null)
+        return;
+    owner.once("exit", reap(pid));
+}
+/** `pid`'s children whose command line matches `pattern` (pgrep's -f). */
+export function childPids(pid, pattern) {
+    try {
+        const args = ["-P", String(pid), ...(pattern === undefined ? [] : ["-f", pattern])];
+        return execFileSync("pgrep", args, { encoding: "utf8" }).split(/\s+/).filter(Boolean).map(Number);
+    }
+    catch {
+        return []; // none, or no pgrep
+    }
+}
+/**
+ * Kills `child` if it's still running when this process exits. `cleanup`
+ * replaces the default SIGKILL; it must be synchronous, as exit hooks are,
+ * and do whatever the child's own exit listener would have done. If this
+ * process is SIGKILLed, the helper kills `child` and removes `dir`.
+ */
+export function killOnExit(child, cleanup = () => child.kill("SIGKILL"), { dir } = {}) {
+    if (!hooked) {
+        hooked = true;
+        process.on("exit", runAll);
+    }
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    cleanups.add(cleanup);
+    child.once("exit", () => cleanups.delete(cleanup));
+    if (dir !== undefined)
+        tellReaper(`d${dir}`);
+    if (child.pid !== undefined)
+        reapWith(child.pid, child);
+}

package/dist/debugger.d.ts

@@ -1,4 +1,4 @@
-import type { CdpParams, RemoteObject } from "./cdp.ts";
+import { type CdpParams, type RemoteObject } from "./cdp.ts";
 import { type CellTransformOptions } from "./transform.ts";
 /** What the debugger needs from a CDP target: its session, with the Debugger domain. */
 export interface DebugChannel {

package/dist/debugger.js

@@ -8,13 +8,14 @@
 // as their //# sourceURL, so breakpoints bind and frames point at the cell.
 // Lines go through the cell's source map (src/sourcemap.ts), since esbuild
 // rewrites TypeScript.
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, sep } from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
+import { isRecord, isRemoteObject } from "./cdp.js";
 import { murmur2 } from "./murmur2.js";
-import { transformCellWithLines } from "./transform.js";
+import { SETTLE, transformCellWithLines } from "./transform.js";
 /** ipykernel's seed, so a kernel switch doesn't move JupyterLab's breakpoints. */
 export const HASH_SEED = 0xc70f6907;
 export const THREAD_ID = 1;
@@ -35,9 +36,6 @@ const SCOPE_NAMES = {
     eval: "Eval",
     global: "Globals",
 };
-function isRecord(value) {
-    return typeof value === "object" && value !== null;
-}
 /**
  * CDPK_DEBUG_TRACE=1 logs every debug request, reply and event to stderr
  * (the Jupyter server's log), for diagnosing a frontend.
@@ -48,8 +46,11 @@ function trace(kind, ...parts) {
     const text = parts.map((p) => JSON.stringify(p)).join(" -> ");
     process.stderr.write(`[cdp-kernel debugger] ${kind} ${text.length > 600 ? `${text.slice(0, 600)}…` : text}\n`);
 }
-function isRemoteObject(value) {
-    return isRecord(value) && typeof value.type === "string";
+function isCallFrame(value) {
+    return isRecord(value) && typeof value.callFrameId === "string" && typeof value.functionName === "string" &&
+        isRecord(value.location) && typeof value.location.scriptId === "string" &&
+        typeof value.location.lineNumber === "number" && Array.isArray(value.scopeChain) &&
+        value.scopeChain.every((scope) => isRecord(scope) && typeof scope.type === "string" && isRemoteObject(scope.object));
 }
 /** A DAP value string for a CDP RemoteObject. */
 export function describeRemote(object) {
@@ -88,6 +89,7 @@ export class Debugger {
     #pauseWaiters = [];
     #emit;
     #transformOptions;
+    #cleanupRegistered = false;
     constructor(emit, transformOptions = () => ({})) {
         this.#emit = emit;
         this.#transformOptions = transformOptions;
@@ -330,7 +332,7 @@ export class Debugger {
     }
     // --- stopped state ----------------------------------------------------------
     #onPaused(params) {
-        this.#frames = Array.isArray(params.callFrames) ? params.callFrames : [];
+        this.#frames = Array.isArray(params.callFrames) ? params.callFrames.filter(isCallFrame) : [];
         this.#stopped = true;
         for (const notify of this.#pauseWaiters.splice(0))
             notify();
@@ -453,7 +455,6 @@ export class Debugger {
             const res = await this.#unlessPaused(channel.send("Runtime.evaluate", {
                 expression: name,
                 contextId: channel.contextId,
-                replMode: true,
                 throwOnSideEffect: true,
             }));
             if (res === null)
@@ -470,9 +471,14 @@ export class Debugger {
             throw new Error("no target to debug");
         // While paused, only a frame can evaluate: use the top one if none was named.
         const frame = typeof frameId === "number" ? this.#frames[frameId] : this.#stopped ? this.#frames[0] : undefined;
+        // replMode (for the console's `await`) returns a promise the inspector
+        // holds only weakly: SETTLE closes that window, as for cells (#55). A
+        // side-effect-free lookup can't await, so it uses a plain evaluate.
         const res = frame
             ? await channel.send("Debugger.evaluateOnCallFrame", { callFrameId: frame.callFrameId, expression, throwOnSideEffect: pure })
-            : await channel.send("Runtime.evaluate", { expression, contextId: channel.contextId, replMode: true, throwOnSideEffect: pure });
+            : pure
+                ? await channel.send("Runtime.evaluate", { expression, contextId: channel.contextId, throwOnSideEffect: true })
+                : await channel.send("Runtime.evaluate", { expression: expression + SETTLE, contextId: channel.contextId, replMode: true });
         if (isRecord(res.exceptionDetails)) {
             const exception = res.exceptionDetails.exception;
             throw new Error(exception ? describeRemote(exception) : String(res.exceptionDetails.text ?? "evaluation failed"));
@@ -519,6 +525,11 @@ export class Debugger {
     }
     #writeCell(path, code) {
         try {
+            if (!this.#cleanupRegistered) {
+                // The files only serve this kernel's frontend: remove them with it.
+                process.once("exit", () => rmSync(this.prefix, { recursive: true, force: true }));
+                this.#cleanupRegistered = true;
+            }
             mkdirSync(this.prefix, { recursive: true });
             writeFileSync(path, code);
         }

package/dist/deno-types.d.ts

@@ -0,0 +1,30 @@
+export type DenoResolution = {
+    kind: "npm";
+    dir: string;
+    subpath: string;
+} | {
+    kind: "remote";
+    path: string;
+};
+export type RunDeno = (args: string[]) => {
+    status: number | null;
+    stdout: string;
+};
+export declare class DenoResolver {
+    #private;
+    /** Where remote modules appear to the language service. */
+    readonly root: string;
+    constructor({ deno, config, root }: {
+        deno?: string;
+        config?: string | null;
+        root: string;
+    }, run?: RunDeno);
+    /** The virtual path for a remote module's URL, e.g. <root>/https/jsr.io/@std/path/1.1.6/mod.ts. */
+    pathFor(url: string): string | null;
+    /** The cached file behind a virtual path, if a lookup has found it. */
+    localFile(path: string): string | undefined;
+    /** Where `specifier` resolves for Deno, from what's already in its cache. */
+    lookup(specifier: string): DenoResolution | null;
+}
+/** `deno types`: declarations for the Deno namespace and its web globals. */
+export declare function denoTypes(run?: RunDeno): string | null;