nebula-notebook 0.1.0

package/node-server/dist/kernel/kernel-service.js

@@ -0,0 +1,1714 @@
+"use strict";
+/**
+ * Kernel Service
+ *
+ * Manages Jupyter kernel sessions - spawning, execution, and lifecycle.
+ * Uses ZeroMQ for kernel communication following the Jupyter messaging protocol.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.kernelService = exports.KernelService = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const crypto = __importStar(require("crypto"));
+const net = __importStar(require("net"));
+const uuid_1 = require("uuid");
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const execAsync = (0, util_1.promisify)(child_process_1.exec);
+const types_1 = require("./types");
+const display_data_1 = require("../output/display-data");
+const output_limits_1 = require("../config/output-limits");
+const session_store_1 = require("./session-store");
+const kernelspec_1 = require("./kernelspec");
+class KernelService {
+    sessions = new Map();
+    fileToSession = new Map();
+    kernelProcesses = new Map();
+    processLifecycleHandlers = new WeakMap();
+    zmqSockets = new Map();
+    sessionStore;
+    config;
+    kernelSpecsCache = null;
+    ready = false;
+    zmq = null;
+    executionQueues = new Map();
+    executionQueueSizes = new Map();
+    shellRequestQueues = new Map();
+    reattachInProgress = false;
+    serverId;
+    serverInstanceId;
+    legacyCleanupWarned = new Set();
+    // Cell-indexed output buffer: sessionId -> cellId -> outputs
+    cellOutputBuffers = new Map();
+    // Per-cell truncation tracking: sessionId -> cellId -> tracking state
+    cellOutputTracking = new Map();
+    executingCellIds = new Map();
+    constructor(config, sessionStore) {
+        this.config = { ...types_1.DEFAULT_CONFIG, ...config };
+        this.sessionStore = sessionStore || new session_store_1.SessionStore();
+        this.serverId = process.env.NEBULA_SERVER_ID || 'local';
+        this.serverInstanceId = process.env.NEBULA_SERVER_INSTANCE_ID || (0, uuid_1.v4)();
+    }
+    setServerIdentity(serverId, serverInstanceId) {
+        this.serverId = serverId;
+        if (serverInstanceId) {
+            this.serverInstanceId = serverInstanceId;
+        }
+    }
+    /**
+     * Check if a PID is still alive.
+     */
+    isPidAlive(pid) {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    attachProcessLifecycle(sessionId, proc, session) {
+        const onError = (err) => {
+            if (this.kernelProcesses.get(sessionId) !== proc) {
+                return;
+            }
+            console.error(`Kernel ${sessionId} error:`, err);
+            session.status = 'dead';
+        };
+        const onExit = (code) => {
+            if (this.kernelProcesses.get(sessionId) !== proc) {
+                return;
+            }
+            console.log(`Kernel ${sessionId} exited with code ${code}`);
+            session.status = 'dead';
+            this.cleanupKernelResources(sessionId);
+        };
+        this.processLifecycleHandlers.set(proc, { onError, onExit });
+        proc.on('error', onError);
+        proc.on('exit', onExit);
+    }
+    detachProcessLifecycle(proc) {
+        if (!proc) {
+            return;
+        }
+        const handlers = this.processLifecycleHandlers.get(proc);
+        if (!handlers) {
+            return;
+        }
+        proc.off('error', handlers.onError);
+        proc.off('exit', handlers.onExit);
+        this.processLifecycleHandlers.delete(proc);
+    }
+    /**
+     * Load a Jupyter connection file.
+     */
+    loadConnectionFile(connFile) {
+        try {
+            if (!connFile || !fs.existsSync(connFile)) {
+                return null;
+            }
+            const raw = JSON.parse(fs.readFileSync(connFile, 'utf-8'));
+            return {
+                ip: raw.ip,
+                transport: raw.transport,
+                signatureScheme: raw.signature_scheme,
+                key: raw.key,
+                shellPort: raw.shell_port,
+                stdinPort: raw.stdin_port,
+                controlPort: raw.control_port,
+                iopubPort: raw.iopub_port,
+                hbPort: raw.hb_port,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Initialize the service (lazy load ZeroMQ and discover kernels)
+     */
+    async initialize() {
+        if (this.ready)
+            return;
+        // Try to load ZeroMQ
+        try {
+            this.zmq = await Promise.resolve().then(() => __importStar(require('zeromq')));
+        }
+        catch (err) {
+            console.warn('ZeroMQ not available, kernel execution will be limited:', err);
+        }
+        // Discover kernels in background
+        this.kernelSpecsCache = (0, kernelspec_1.discoverKernelSpecs)();
+        this.ready = true;
+        console.log(`Kernel service initialized. Found ${this.kernelSpecsCache.length} kernels.`);
+    }
+    /**
+     * Attempt to reattach to orphaned kernel sessions from a previous server run.
+     */
+    async reattachOrphanedSessions() {
+        if (this.reattachInProgress) {
+            return { attempted: 0, reattached: 0, failed: 0, skipped: 0 };
+        }
+        this.reattachInProgress = true;
+        try {
+            await this.initialize();
+            // Mark any previously active sessions (for this server) as orphaned
+            this.sessionStore.markAllOrphaned(this.serverId, this.serverInstanceId);
+            const orphanedSessions = this.sessionStore.getOrphanedSessions(this.serverId);
+            if (orphanedSessions.length === 0) {
+                return { attempted: 0, reattached: 0, failed: 0, skipped: 0 };
+            }
+            let reattached = 0;
+            let failed = 0;
+            let skipped = 0;
+            for (const session of orphanedSessions) {
+                const sessionId = session.sessionId;
+                // Check if kernel process is still alive and matches recorded start time (if available)
+                if (session.kernelPid) {
+                    if (!this.isPidAlive(session.kernelPid)) {
+                        this.sessionStore.updateStatus(sessionId, 'terminated');
+                        skipped++;
+                        continue;
+                    }
+                    if (session.kernelStartTime) {
+                        const currentStartTime = await this.getProcessStartTime(session.kernelPid);
+                        if (!currentStartTime || currentStartTime !== session.kernelStartTime) {
+                            this.sessionStore.updateStatus(sessionId, 'terminated');
+                            skipped++;
+                            continue;
+                        }
+                    }
+                }
+                // Try to get connection config: from file first, then from DB
+                let connectionConfig = null;
+                if (session.connectionFile) {
+                    connectionConfig = this.loadConnectionFile(session.connectionFile);
+                }
+                // Fall back to DB-stored config if file is missing (e.g., temp cleanup)
+                if (!connectionConfig && session.connectionConfig) {
+                    try {
+                        connectionConfig = JSON.parse(session.connectionConfig);
+                    }
+                    catch {
+                        // Invalid JSON in DB
+                    }
+                }
+                if (!connectionConfig) {
+                    console.log(`[Kernel] Skipping session ${sessionId}: no connection config available`);
+                    this.sessionStore.updateStatus(sessionId, 'terminated');
+                    skipped++;
+                    continue;
+                }
+                const normalizedFilePath = session.filePath ? this.normalizePath(session.filePath) : null;
+                const now = Date.now() / 1000;
+                const kernelSession = {
+                    id: sessionId,
+                    kernelName: session.kernelName,
+                    filePath: normalizedFilePath,
+                    status: 'starting',
+                    executionCount: 0,
+                    pid: session.kernelPid ?? null,
+                    connectionFile: session.connectionFile,
+                    connectionConfig,
+                    createdAt: session.createdAt,
+                    lastActivity: now,
+                };
+                this.sessions.set(sessionId, kernelSession);
+                if (normalizedFilePath) {
+                    this.fileToSession.set(normalizedFilePath, sessionId);
+                }
+                try {
+                    // Use shorter timeout for reattach — kernel should already be running.
+                    // Pass PID so waitForReady can distinguish "busy" from "dead" on timeout.
+                    const detectedStatus = await this.waitForReady(sessionId, 10, session.kernelPid);
+                    kernelSession.status = detectedStatus;
+                    if (detectedStatus === 'busy') {
+                        // Kernel is alive but mid-execution. Monitor iopub in background
+                        // so we can flip to 'idle' when the execution finishes.
+                        this.monitorBusyKernel(sessionId);
+                    }
+                    const kernelStartTime = session.kernelStartTime
+                        ?? (session.kernelPid ? await this.getProcessStartTime(session.kernelPid) : null);
+                    this.sessionStore.saveSession({
+                        sessionId,
+                        kernelName: session.kernelName,
+                        filePath: normalizedFilePath,
+                        kernelPid: session.kernelPid ?? null,
+                        serverId: this.serverId,
+                        serverInstanceId: this.serverInstanceId,
+                        kernelStartTime,
+                        status: 'active',
+                        createdAt: session.createdAt,
+                        lastHeartbeat: now,
+                        connectionFile: session.connectionFile,
+                        connectionConfig: JSON.stringify(connectionConfig),
+                    });
+                    reattached++;
+                    console.log(`[Kernel] Reattached session ${sessionId} for ${normalizedFilePath || 'no file'}`);
+                }
+                catch (err) {
+                    failed++;
+                    kernelSession.status = 'dead';
+                    this.cleanupInMemorySession(sessionId);
+                    this.sessionStore.updateStatus(sessionId, 'terminated');
+                    console.log(`[Kernel] Failed to reattach session ${sessionId}: ${err instanceof Error ? err.message : err}`);
+                }
+            }
+            return {
+                attempted: orphanedSessions.length,
+                reattached,
+                failed,
+                skipped,
+            };
+        }
+        finally {
+            this.reattachInProgress = false;
+        }
+    }
+    /**
+     * Check if service is ready
+     */
+    get isReady() {
+        return this.ready;
+    }
+    /**
+     * Get available kernelspecs
+     */
+    getAvailableKernels() {
+        if (this.kernelSpecsCache) {
+            return this.kernelSpecsCache;
+        }
+        return (0, kernelspec_1.discoverKernelSpecs)();
+    }
+    /**
+     * Re-run kernelspec discovery and refresh the in-memory cache.
+     *
+     * `getAvailableKernels()` caches once at startup and never expires, so a kernel
+     * registered while the server is running would otherwise stay invisible until a
+     * restart. Call this after registering/installing a kernel.
+     */
+    refreshKernelSpecs() {
+        this.kernelSpecsCache = (0, kernelspec_1.discoverKernelSpecs)(true);
+        return this.kernelSpecsCache;
+    }
+    /**
+     * Normalize file path for consistent lookup
+     */
+    normalizePath(filePath) {
+        return path.resolve(filePath.replace(/^~/, os.homedir()));
+    }
+    /**
+     * Normalize notebook path for external callers (e.g., routes).
+     */
+    normalizeNotebookPath(filePath) {
+        return this.normalizePath(filePath);
+    }
+    /**
+     * Save kernel preference for a notebook file.
+     */
+    saveNotebookKernelPreference(filePath, kernelName, serverId) {
+        const normalizedPath = this.normalizePath(filePath);
+        this.sessionStore.saveNotebookKernelPreference(normalizedPath, kernelName, serverId);
+    }
+    /**
+     * Get kernel preference for a notebook file.
+     */
+    getNotebookKernelPreference(filePath) {
+        const normalizedPath = this.normalizePath(filePath);
+        return this.sessionStore.getNotebookKernelPreference(normalizedPath);
+    }
+    /**
+     * Generate a connection file for the kernel
+     */
+    async allocateEphemeralPort() {
+        return new Promise((resolve, reject) => {
+            const server = net.createServer();
+            server.unref();
+            server.once('error', reject);
+            server.listen(0, '127.0.0.1', () => {
+                const addr = server.address();
+                if (!addr || typeof addr === 'string') {
+                    server.close(() => reject(new Error('Failed to allocate ephemeral port')));
+                    return;
+                }
+                const port = addr.port;
+                server.close(() => resolve(port));
+            });
+        });
+    }
+    async generateConnectionFile(sessionId) {
+        // Avoid random collisions by asking the OS for currently-free ephemeral ports.
+        // There's still a small TOCTOU window between close() and kernel bind, but this
+        // is far more reliable than picking random ports blindly.
+        const ports = [];
+        const seen = new Set();
+        while (ports.length < 5) {
+            const port = await this.allocateEphemeralPort();
+            if (seen.has(port))
+                continue;
+            seen.add(port);
+            ports.push(port);
+        }
+        const [shellPort, stdinPort, controlPort, iopubPort, hbPort] = ports;
+        const config = {
+            ip: '127.0.0.1',
+            transport: 'tcp',
+            signatureScheme: 'hmac-sha256',
+            key: crypto.randomBytes(16).toString('hex'),
+            shellPort,
+            stdinPort,
+            controlPort,
+            iopubPort,
+            hbPort,
+        };
+        // Write connection file
+        const connDir = path.join(os.tmpdir(), 'nebula-kernels');
+        fs.mkdirSync(connDir, { recursive: true });
+        const connFile = path.join(connDir, `kernel-${sessionId}.json`);
+        const connData = {
+            ip: config.ip,
+            transport: config.transport,
+            signature_scheme: config.signatureScheme,
+            key: config.key,
+            shell_port: config.shellPort,
+            stdin_port: config.stdinPort,
+            control_port: config.controlPort,
+            iopub_port: config.iopubPort,
+            hb_port: config.hbPort,
+        };
+        fs.writeFileSync(connFile, JSON.stringify(connData, null, 2));
+        return { config, filePath: connFile };
+    }
+    /**
+     * Start a new kernel session
+     */
+    async startKernel(options = {}) {
+        const kernelName = options.kernelName || 'python3';
+        const spec = (0, kernelspec_1.getKernelSpec)(kernelName);
+        if (!spec) {
+            throw new Error(`Kernel '${kernelName}' not found`);
+        }
+        const sessionId = (0, uuid_1.v4)();
+        const normalizedFilePath = options.filePath ? this.normalizePath(options.filePath) : null;
+        // Generate connection file
+        const { config: connConfig, filePath: connFile } = await this.generateConnectionFile(sessionId);
+        // Build kernel command
+        const argv = (spec.argv || []).map(arg => arg.replace('{connection_file}', connFile));
+        if (argv.length === 0) {
+            throw new Error(`Kernel '${kernelName}' has no argv defined`);
+        }
+        // Spawn the kernel process
+        const cwd = options.cwd || (normalizedFilePath ? path.dirname(normalizedFilePath) : process.cwd());
+        const proc = (0, child_process_1.spawn)(argv[0], argv.slice(1), {
+            cwd,
+            env: { ...process.env, ...spec.env },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        // Log kernel stdout/stderr for debugging
+        proc.stdout?.on('data', (data) => {
+            console.log(`[Kernel ${sessionId.slice(0, 8)}] stdout: ${data.toString().trim()}`);
+        });
+        proc.stderr?.on('data', (data) => {
+            console.error(`[Kernel ${sessionId.slice(0, 8)}] stderr: ${data.toString().trim()}`);
+        });
+        const now = Date.now() / 1000;
+        const session = {
+            id: sessionId,
+            kernelName,
+            filePath: normalizedFilePath,
+            status: 'starting',
+            executionCount: 0,
+            pid: proc.pid || null,
+            connectionFile: connFile,
+            connectionConfig: connConfig,
+            createdAt: now,
+            lastActivity: now,
+        };
+        this.sessions.set(sessionId, session);
+        this.kernelProcesses.set(sessionId, proc);
+        if (normalizedFilePath) {
+            this.fileToSession.set(normalizedFilePath, sessionId);
+        }
+        // Handle process events
+        this.attachProcessLifecycle(sessionId, proc, session);
+        // Wait for kernel to be ready. If startup fails, clean up aggressively so we
+        // don't leave behind orphaned sessions/processes/connection files.
+        try {
+            await this.waitForReady(sessionId);
+        }
+        catch (err) {
+            await this.stopKernel(sessionId).catch(() => undefined);
+            throw err;
+        }
+        const kernelStartTime = proc.pid ? await this.getProcessStartTime(proc.pid) : null;
+        // Save to persistence store (include connection config for reattach if file is deleted)
+        this.sessionStore.saveSession({
+            sessionId,
+            kernelName,
+            filePath: normalizedFilePath,
+            kernelPid: proc.pid || null,
+            serverId: this.serverId,
+            serverInstanceId: this.serverInstanceId,
+            kernelStartTime,
+            status: 'active',
+            createdAt: now,
+            lastHeartbeat: now,
+            connectionFile: connFile,
+            connectionConfig: JSON.stringify(session.connectionConfig),
+        });
+        session.status = 'idle';
+        return sessionId;
+    }
+    /**
+     * Wait for kernel to be ready by connecting to ZeroMQ channels.
+     *
+     * Returns the detected kernel execution state:
+     * - 'idle': kernel responded to kernel_info_request (ready for work)
+     * - 'busy': kernel PID is alive but shell channel is blocked (mid-execution)
+     *
+     * @param timeoutSeconds Optional override for startup timeout (default: use config)
+     * @param pid Optional kernel PID — used to distinguish "busy" from "dead" on timeout
+     */
+    async waitForReady(sessionId, timeoutSeconds, pid) {
+        const session = this.sessions.get(sessionId);
+        if (!session || !session.connectionConfig) {
+            throw new Error('Session or connection config not found');
+        }
+        if (!this.zmq) {
+            // No ZeroMQ available, just wait a bit and hope the kernel starts
+            await this.sleep(1000);
+            return 'idle';
+        }
+        const config = session.connectionConfig;
+        const shellEndpoint = `tcp://${config.ip}:${config.shellPort}`;
+        const iopubEndpoint = `tcp://${config.ip}:${config.iopubPort}`;
+        // Create ZeroMQ sockets
+        const shell = new this.zmq.Dealer();
+        const iopub = new this.zmq.Subscriber();
+        shell.connect(shellEndpoint);
+        iopub.connect(iopubEndpoint);
+        iopub.subscribe('');
+        this.zmqSockets.set(sessionId, { shell, iopub });
+        // Send kernel_info_request to verify connectivity
+        const startTime = Date.now();
+        const actualTimeout = timeoutSeconds ?? this.config.startupTimeoutSeconds;
+        const timeout = actualTimeout * 1000;
+        while (Date.now() - startTime < timeout) {
+            try {
+                await this.sendKernelInfoRequest(sessionId);
+                // If we get here without error, kernel is ready
+                return 'idle';
+            }
+            catch {
+                await this.sleep(100);
+            }
+        }
+        // Shell channel didn't respond within timeout.
+        // If the kernel PID is alive, it's likely busy executing code
+        // (shell requests queue behind the current execution in Jupyter protocol).
+        if (pid && this.isPidAlive(pid)) {
+            return 'busy';
+        }
+        throw new Error(`Kernel did not start within ${actualTimeout} seconds`);
+    }
+    /**
+     * Monitor a busy reattached kernel on iopub. When its current execution
+     * finishes (status: idle on iopub), verify shell connectivity and update
+     * the in-memory session status.
+     */
+    monitorBusyKernel(sessionId) {
+        const session = this.sessions.get(sessionId);
+        const sockets = this.zmqSockets.get(sessionId);
+        if (!session || !sockets)
+            return;
+        console.log(`[Kernel] Monitoring busy kernel ${sessionId} for idle transition...`);
+        const poll = async () => {
+            try {
+                while (session.status === 'busy') {
+                    const receivePromise = sockets.iopub.receive();
+                    const timeoutPromise = new Promise((resolve) => {
+                        setTimeout(() => resolve(null), 5000);
+                    });
+                    const frames = await Promise.race([receivePromise, timeoutPromise]);
+                    if (!frames) {
+                        // Periodic liveness check
+                        if (session.pid && !this.isPidAlive(session.pid)) {
+                            console.log(`[Kernel] Busy kernel ${sessionId} PID ${session.pid} died`);
+                            session.status = 'dead';
+                            return;
+                        }
+                        continue;
+                    }
+                    const { msgType, content } = this.parseJupyterMessage(frames);
+                    if (msgType === 'status' && content.execution_state === 'idle') {
+                        break;
+                    }
+                }
+                // Prior execution finished — verify shell connectivity
+                try {
+                    await this.sendKernelInfoRequest(sessionId);
+                }
+                catch {
+                    // Non-fatal; next executeCode will detect issues
+                }
+                session.status = 'idle';
+                session.lastActivity = Date.now() / 1000;
+                console.log(`[Kernel] Busy kernel ${sessionId} is now idle`);
+            }
+            catch (err) {
+                console.error(`[Kernel] Error monitoring busy kernel ${sessionId}:`, err);
+                session.status = 'idle'; // Assume idle — next operation will detect real issues
+            }
+        };
+        void poll();
+    }
+    /**
+     * Send kernel_info_request and wait for reply to verify kernel is ready
+     * Throws if no reply received within timeout
+     */
+    async sendKernelInfoRequest(sessionId) {
+        const sockets = this.zmqSockets.get(sessionId);
+        const session = this.sessions.get(sessionId);
+        if (!sockets || !session) {
+            throw new Error('Session or sockets not found');
+        }
+        const msgId = (0, uuid_1.v4)();
+        const header = {
+            msg_id: msgId,
+            session: sessionId,
+            username: 'nebula',
+            msg_type: 'kernel_info_request',
+            version: '5.3',
+            date: new Date().toISOString(),
+        };
+        const message = this.createJupyterMessage(header, {}, {}, session.connectionConfig.key);
+        await sockets.shell.send(message);
+        // Wait for kernel_info_reply with timeout
+        const receivePromise = sockets.shell.receive();
+        const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => reject(new Error('Kernel not responding')), 1000);
+        });
+        const frames = await Promise.race([receivePromise, timeoutPromise]);
+        const { msgType } = this.parseJupyterMessage(frames);
+        if (msgType !== 'kernel_info_reply') {
+            throw new Error(`Unexpected message type: ${msgType}`);
+        }
+        // Kernel is ready!
+    }
+    /**
+     * Create a Jupyter protocol message
+     */
+    createJupyterMessage(header, parentHeader, content, key) {
+        const headerJson = JSON.stringify(header);
+        const parentHeaderJson = JSON.stringify(parentHeader);
+        const metadataJson = JSON.stringify({});
+        const contentJson = JSON.stringify(content);
+        // Create HMAC signature
+        const hmac = crypto.createHmac('sha256', key);
+        hmac.update(headerJson);
+        hmac.update(parentHeaderJson);
+        hmac.update(metadataJson);
+        hmac.update(contentJson);
+        const signature = hmac.digest('hex');
+        // Build multipart message
+        return [
+            Buffer.from('<IDS|MSG>'),
+            Buffer.from(signature),
+            Buffer.from(headerJson),
+            Buffer.from(parentHeaderJson),
+            Buffer.from(metadataJson),
+            Buffer.from(contentJson),
+        ];
+    }
+    /**
+     * Get or create kernel for a file (one notebook = one kernel).
+     * Returns whether a new session was created.
+     */
+    async getOrCreateKernel(filePath, kernelName = 'python3') {
+        const normalizedPath = this.normalizePath(filePath);
+        // Check for existing session in fileToSession map
+        let existingSessionId = this.fileToSession.get(normalizedPath);
+        // Fallback: search all sessions for matching filePath (handles race after server restart)
+        if (!existingSessionId) {
+            for (const [sessionId, session] of this.sessions.entries()) {
+                if (session.filePath === normalizedPath && session.status !== 'dead') {
+                    console.log(`[Kernel] Found orphaned session ${sessionId} for ${normalizedPath}, restoring fileToSession mapping`);
+                    this.fileToSession.set(normalizedPath, sessionId);
+                    existingSessionId = sessionId;
+                    break;
+                }
+            }
+        }
+        if (existingSessionId) {
+            const session = this.sessions.get(existingSessionId);
+            if (session && session.status !== 'dead') {
+                // If session is stuck in 'starting' for too long, treat as dead
+                if (session.status === 'starting') {
+                    const startingDuration = Date.now() / 1000 - session.lastActivity;
+                    // Allow a longer grace period for slow environments before declaring it stuck
+                    if (startingDuration > 120) {
+                        console.log(`[Kernel] Session ${existingSessionId} stuck in 'starting' for ${Math.round(startingDuration)}s, restarting`);
+                        await this.stopKernel(existingSessionId);
+                    }
+                    else {
+                        // Wait a bit and check if it becomes ready
+                        for (let i = 0; i < 20; i++) {
+                            await this.sleep(500);
+                            const updated = this.sessions.get(existingSessionId);
+                            if (!updated || updated.status === 'dead')
+                                break;
+                            if (updated.status === 'idle' || updated.status === 'busy') {
+                                if (updated.kernelName === kernelName) {
+                                    return { sessionId: existingSessionId, created: false };
+                                }
+                                break;
+                            }
+                        }
+                        // Still starting after wait; keep it rather than restarting unless it exceeds grace
+                        const stillStarting = this.sessions.get(existingSessionId);
+                        if (stillStarting?.status === 'starting') {
+                            console.log(`[Kernel] Session ${existingSessionId} still starting after wait; keeping it alive`);
+                            return { sessionId: existingSessionId, created: false };
+                        }
+                    }
+                }
+                else {
+                    // Session is idle or busy
+                    if (session.kernelName === kernelName) {
+                        return { sessionId: existingSessionId, created: false };
+                    }
+                    // Kernel type changed, stop old and start new
+                    await this.stopKernel(existingSessionId);
+                }
+            }
+        }
+        // Start new kernel
+        const sessionId = await this.startKernel({
+            kernelName,
+            filePath: normalizedPath,
+            cwd: path.dirname(normalizedPath),
+        });
+        return { sessionId, created: true };
+    }
+    /**
+     * Get existing kernel session ID for a notebook file (if any).
+     * Returns null if no live session is associated with the file.
+     */
+    getSessionIdForFile(filePath) {
+        const normalizedPath = this.normalizePath(filePath);
+        let existingSessionId = this.fileToSession.get(normalizedPath);
+        if (existingSessionId) {
+            const session = this.sessions.get(existingSessionId);
+            if (session && session.status !== 'dead') {
+                return existingSessionId;
+            }
+        }
+        for (const [sessionId, session] of this.sessions.entries()) {
+            if (session.filePath === normalizedPath && session.status !== 'dead') {
+                this.fileToSession.set(normalizedPath, sessionId);
+                existingSessionId = sessionId;
+                break;
+            }
+        }
+        return existingSessionId || null;
+    }
+    /**
+     * Check if a kernel session exists.
+     */
+    hasSession(sessionId) {
+        return this.sessions.has(sessionId);
+    }
+    /**
+     * Get the notebook file path associated with a session (if any).
+     * Used for output persistence when no UI is connected.
+     */
+    getSessionFilePath(sessionId) {
+        return this.sessions.get(sessionId)?.filePath ?? null;
+    }
+    /**
+     * Get the kernel name associated with a session (if any).
+     */
+    getSessionKernelName(sessionId) {
+        return this.sessions.get(sessionId)?.kernelName ?? null;
+    }
+    /**
+     * Execute code in a kernel session
+     */
+    async executeCode(sessionId, code, onOutput, onQueueInfo, cellId) {
+        const queueInfo = this.reserveExecutionSlot(sessionId);
+        if (onQueueInfo) {
+            onQueueInfo(queueInfo);
+        }
+        return this.enqueueExecution(sessionId, async () => {
+            // Clear previous outputs for this cell before starting new execution
+            if (cellId) {
+                this.clearCellOutputs(sessionId, cellId);
+            }
+            this.executingCellIds.set(sessionId, cellId ?? null);
+            try {
+                const result = await this.executeCodeInternal(sessionId, code, async (output) => {
+                    const stored = this.bufferOutput(sessionId, output, cellId);
+                    for (const o of stored) {
+                        await onOutput(o, cellId);
+                    }
+                });
+                return { ...result, ...queueInfo };
+            }
+            catch (err) {
+                const errorMsg = this.formatExecutionError(err);
+                const stored = this.bufferOutput(sessionId, { type: 'error', content: errorMsg }, cellId);
+                for (const o of stored) {
+                    await onOutput(o, cellId);
+                }
+                return { status: 'error', executionCount: null, error: errorMsg, ...queueInfo };
+            }
+            finally {
+                this.executingCellIds.delete(sessionId);
+                this.releaseExecutionSlot(sessionId);
+            }
+        });
+    }
+    enqueueExecution(sessionId, task) {
+        const previous = this.executionQueues.get(sessionId) || Promise.resolve();
+        const run = previous.catch(() => undefined).then(task);
+        const chain = run.catch(() => undefined);
+        this.executionQueues.set(sessionId, chain);
+        chain.finally(() => {
+            if (this.executionQueues.get(sessionId) === chain) {
+                this.executionQueues.delete(sessionId);
+            }
+        });
+        return run;
+    }
+    /**
+     * Queue shell socket requests to prevent concurrent receive operations
+     */
+    enqueueShellRequest(sessionId, task) {
+        const previous = this.shellRequestQueues.get(sessionId) || Promise.resolve();
+        const run = previous.catch(() => undefined).then(task);
+        const chain = run.catch(() => undefined);
+        this.shellRequestQueues.set(sessionId, chain);
+        chain.finally(() => {
+            if (this.shellRequestQueues.get(sessionId) === chain) {
+                this.shellRequestQueues.delete(sessionId);
+            }
+        });
+        return run;
+    }
+    reserveExecutionSlot(sessionId) {
+        const currentSize = this.executionQueueSizes.get(sessionId) ?? 0;
+        const info = {
+            queuePosition: currentSize,
+            queueLength: currentSize + 1,
+        };
+        this.executionQueueSizes.set(sessionId, currentSize + 1);
+        return info;
+    }
+    releaseExecutionSlot(sessionId) {
+        const currentSize = this.executionQueueSizes.get(sessionId) ?? 0;
+        if (currentSize <= 1) {
+            this.executionQueueSizes.delete(sessionId);
+        }
+        else {
+            this.executionQueueSizes.set(sessionId, currentSize - 1);
+        }
+    }
+    formatExecutionError(error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes('Socket is busy reading')) {
+            return 'Kernel output stream is busy because another execution is running. Wait for it to finish or poll with read_output before starting a new execute_cell.';
+        }
+        return message;
+    }
+    async executeCodeInternal(sessionId, code, onOutput) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            throw new Error(`Session ${sessionId} not found`);
+        }
+        if (!this.zmq || !this.zmqSockets.has(sessionId)) {
+            // Fallback: no ZeroMQ, cannot execute
+            const errorMsg = 'ZeroMQ not available for kernel communication';
+            await onOutput({ type: 'error', content: errorMsg });
+            return { status: 'error', executionCount: null, error: errorMsg };
+        }
+        session.status = 'busy';
+        const sockets = this.zmqSockets.get(sessionId);
+        let execCount = null;
+        try {
+            // Create execute_request message
+            const msgId = (0, uuid_1.v4)();
+            const header = {
+                msg_id: msgId,
+                session: sessionId,
+                username: 'nebula',
+                msg_type: 'execute_request',
+                version: '5.3',
+                date: new Date().toISOString(),
+            };
+            const content = {
+                code,
+                silent: false,
+                store_history: true,
+                user_expressions: {},
+                allow_stdin: false,
+                stop_on_error: true,
+            };
+            const message = this.createJupyterMessage(header, {}, content, session.connectionConfig.key);
+            await sockets.shell.send(message);
+            // Process iopub messages
+            while (true) {
+                const frames = await sockets.iopub.receive();
+                const { msgType, content: msgContent, parentMsgId } = this.parseJupyterMessage(frames);
+                // Only process messages for our execution
+                if (parentMsgId !== msgId) {
+                    continue;
+                }
+                // Handle different message types
+                if (msgType === 'execute_input') {
+                    execCount = msgContent.execution_count;
+                }
+                else if (msgType === 'stream') {
+                    const streamName = msgContent.name;
+                    await onOutput({
+                        type: streamName === 'stderr' ? 'stderr' : 'stdout',
+                        content: msgContent.text,
+                    });
+                }
+                else if (msgType === 'execute_result' || msgType === 'display_data') {
+                    const output = this.formatDisplayData(msgContent.data || {}, msgContent.metadata || undefined);
+                    if (output) {
+                        await onOutput(output);
+                    }
+                }
+                else if (msgType === 'error') {
+                    const traceback = msgContent.traceback || [];
+                    const cleanTb = traceback.map(line => this.stripAnsi(line)).join('\n');
+                    await onOutput({ type: 'error', content: cleanTb });
+                }
+                else if (msgType === 'status') {
+                    if (msgContent.execution_state === 'idle') {
+                        break;
+                    }
+                }
+            }
+            session.executionCount = execCount || session.executionCount;
+            session.status = 'idle';
+            session.lastActivity = Date.now() / 1000;
+            return { status: 'ok', executionCount: execCount };
+        }
+        catch (err) {
+            session.status = 'idle';
+            const errorMsg = this.formatExecutionError(err);
+            await onOutput({ type: 'error', content: errorMsg });
+            return { status: 'error', executionCount: null, error: errorMsg };
+        }
+    }
+    /**
+     * Request code completion from the kernel
+     * Uses a separate queue for shell socket operations to avoid "socket busy" errors
+     */
+    async complete(sessionId, code, cursorPos) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            return { status: 'error', matches: [], cursor_start: cursorPos, cursor_end: cursorPos };
+        }
+        if (!this.zmq || !this.zmqSockets.has(sessionId)) {
+            return { status: 'error', matches: [], cursor_start: cursorPos, cursor_end: cursorPos };
+        }
+        // Queue completion requests to avoid "socket busy" errors
+        return this.enqueueShellRequest(sessionId, () => this.completeInternal(sessionId, code, cursorPos));
+    }
+    /**
+     * Internal completion implementation (runs within shell queue)
+     */
+    async completeInternal(sessionId, code, cursorPos) {
+        const session = this.sessions.get(sessionId);
+        const sockets = this.zmqSockets.get(sessionId);
+        if (!session || !sockets) {
+            return { status: 'error', matches: [], cursor_start: cursorPos, cursor_end: cursorPos };
+        }
+        try {
+            // Create complete_request message
+            const msgId = (0, uuid_1.v4)();
+            const header = {
+                msg_id: msgId,
+                session: sessionId,
+                username: 'nebula',
+                msg_type: 'complete_request',
+                version: '5.3',
+                date: new Date().toISOString(),
+            };
+            const content = {
+                code,
+                cursor_pos: cursorPos,
+            };
+            const message = this.createJupyterMessage(header, {}, content, session.connectionConfig.key);
+            await sockets.shell.send(message);
+            // Wait for complete_reply with timeout
+            const timeoutPromise = new Promise((resolve) => {
+                setTimeout(() => resolve(null), 3000);
+            });
+            const receivePromise = (async () => {
+                while (true) {
+                    const frames = await sockets.shell.receive();
+                    const { msgType, content: msgContent, parentMsgId } = this.parseJupyterMessage(frames);
+                    if (parentMsgId === msgId && msgType === 'complete_reply') {
+                        return {
+                            status: msgContent.status || 'ok',
+                            matches: msgContent.matches || [],
+                            cursor_start: msgContent.cursor_start ?? cursorPos,
+                            cursor_end: msgContent.cursor_end ?? cursorPos,
+                        };
+                    }
+                }
+            })();
+            const result = await Promise.race([receivePromise, timeoutPromise]);
+            if (result === null) {
+                return { status: 'timeout', matches: [], cursor_start: cursorPos, cursor_end: cursorPos };
+            }
+            return result;
+        }
+        catch (err) {
+            console.error('[KernelService] Completion error:', err);
+            return { status: 'error', matches: [], cursor_start: cursorPos, cursor_end: cursorPos };
+        }
+    }
+    /**
+     * Parse a Jupyter protocol message
+     */
+    parseJupyterMessage(frames) {
+        // Find delimiter
+        let delimIdx = -1;
+        for (let i = 0; i < frames.length; i++) {
+            if (frames[i].toString() === '<IDS|MSG>') {
+                delimIdx = i;
+                break;
+            }
+        }
+        if (delimIdx === -1) {
+            throw new Error('Invalid Jupyter message: no delimiter found');
+        }
+        // Parse message parts after delimiter
+        const signature = frames[delimIdx + 1].toString();
+        const header = JSON.parse(frames[delimIdx + 2].toString());
+        const parentHeader = JSON.parse(frames[delimIdx + 3].toString());
+        const metadata = JSON.parse(frames[delimIdx + 4].toString());
+        const content = JSON.parse(frames[delimIdx + 5].toString());
+        return {
+            msgType: header.msg_type,
+            content,
+            parentMsgId: parentHeader.msg_id || '',
+        };
+    }
+    /**
+     * Format display data for output
+     */
+    formatDisplayData(data, metadata) {
+        const normalizedOutput = (0, display_data_1.buildDisplayOutput)(data, metadata);
+        if (!normalizedOutput) {
+            return null;
+        }
+        return {
+            type: normalizedOutput.type,
+            content: normalizedOutput.content,
+            mimeBundle: normalizedOutput.mimeBundle,
+            metadata: normalizedOutput.metadata,
+            preferredMimeType: normalizedOutput.preferredMimeType,
+        };
+    }
+    /**
+     * Strip ANSI escape codes from text
+     */
+    stripAnsi(text) {
+        return text.replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, '');
+    }
+    getOutputStats(output) {
+        const isError = output.type === 'error';
+        const chars = output.content?.length || 0;
+        const lines = output.type === 'image' || output.type === 'html' || output.type === 'display_data'
+            ? 0
+            : (output.content?.match(/\n/g) || []).length + 1;
+        return { lines, chars, isError };
+    }
+    ensureCellBuffers(sessionId) {
+        let buffers = this.cellOutputBuffers.get(sessionId);
+        if (!buffers) {
+            buffers = new Map();
+            this.cellOutputBuffers.set(sessionId, buffers);
+        }
+        return buffers;
+    }
+    ensureCellTracking(sessionId, cellId) {
+        let tracking = this.cellOutputTracking.get(sessionId);
+        if (!tracking) {
+            tracking = new Map();
+            this.cellOutputTracking.set(sessionId, tracking);
+        }
+        let cellTrack = tracking.get(cellId);
+        if (!cellTrack) {
+            cellTrack = { lines: 0, chars: 0, truncated: false };
+            tracking.set(cellId, cellTrack);
+        }
+        return cellTrack;
+    }
+    /**
+     * Buffer an output for a cell. Returns the outputs actually stored (0 if truncated, 1 normally).
+     */
+    bufferOutput(sessionId, output, cellId) {
+        const effectiveCellId = cellId ?? '__unknown__';
+        const buffers = this.ensureCellBuffers(sessionId);
+        const cellTrack = this.ensureCellTracking(sessionId, effectiveCellId);
+        const stats = this.getOutputStats(output);
+        if (cellTrack.lines + stats.lines > output_limits_1.MAX_OUTPUT_LINES || cellTrack.chars + stats.chars > output_limits_1.MAX_OUTPUT_CHARS) {
+            if (!cellTrack.truncated) {
+                cellTrack.truncated = true;
+                const warning = {
+                    type: 'stderr',
+                    content: `\n⚠️ Output limit reached. Additional output not displayed.`,
+                };
+                let arr = buffers.get(effectiveCellId);
+                if (!arr) {
+                    arr = [];
+                    buffers.set(effectiveCellId, arr);
+                }
+                arr.push(warning);
+                return [warning];
+            }
+            return [];
+        }
+        cellTrack.lines += stats.lines;
+        cellTrack.chars += stats.chars;
+        let arr = buffers.get(effectiveCellId);
+        if (!arr) {
+            arr = [];
+            buffers.set(effectiveCellId, arr);
+        }
+        arr.push(output);
+        return [output];
+    }
+    /**
+     * Clear outputs for a specific cell (called on re-execute).
+     */
+    clearCellOutputs(sessionId, cellId) {
+        this.cellOutputBuffers.get(sessionId)?.delete(cellId);
+        this.cellOutputTracking.get(sessionId)?.delete(cellId);
+    }
+    /**
+     * Get all cell outputs for a session, grouped by cellId.
+     */
+    getAllCellOutputs(sessionId) {
+        return this.cellOutputBuffers.get(sessionId) || new Map();
+    }
+    getExecutingCellId(sessionId) {
+        return this.executingCellIds.get(sessionId) ?? null;
+    }
+    /**
+     * Stop a kernel session
+     */
+    async stopKernel(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            return false;
+        }
+        // Close ZeroMQ sockets
+        const sockets = this.zmqSockets.get(sessionId);
+        if (sockets) {
+            try {
+                sockets.shell.close();
+                sockets.iopub.close();
+            }
+            catch {
+                // Ignore close errors
+            }
+            this.zmqSockets.delete(sessionId);
+        }
+        // Kill kernel process
+        const proc = this.kernelProcesses.get(sessionId);
+        if (proc) {
+            this.detachProcessLifecycle(proc);
+            try {
+                proc.kill('SIGTERM');
+                // Wait for graceful shutdown
+                await this.sleep(1000);
+                if (!proc.killed) {
+                    proc.kill('SIGKILL');
+                }
+            }
+            catch {
+                // Ignore kill errors
+            }
+            this.kernelProcesses.delete(sessionId);
+        }
+        else if (session.pid) {
+            try {
+                process.kill(session.pid, 'SIGTERM');
+                await this.sleep(1000);
+                if (this.isPidAlive(session.pid)) {
+                    process.kill(session.pid, 'SIGKILL');
+                }
+            }
+            catch {
+                // Ignore kill errors
+            }
+        }
+        // Cleanup resources
+        this.cleanupKernelResources(sessionId);
+        return true;
+    }
+    /**
+     * Check command line for a PID (best-effort).
+     */
+    async getPidCommand(pid) {
+        try {
+            if (process.platform === 'linux') {
+                const raw = fs.readFileSync(`/proc/${pid}/cmdline`);
+                const cmdline = raw.toString('utf8').replace(/\0/g, ' ').trim();
+                return cmdline || null;
+            }
+            const { stdout } = await execAsync(`ps -o command= -p ${pid}`, { timeout: 500 });
+            const cmd = stdout.trim();
+            return cmd.length > 0 ? cmd : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Get process start time (best-effort), used to prevent PID reuse mistakes.
+     */
+    async getProcessStartTime(pid) {
+        try {
+            const { stdout } = await execAsync(`ps -o lstart= -p ${pid}`, { timeout: 500 });
+            const startTime = stdout.trim();
+            return startTime.length > 0 ? startTime : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Best-effort check to ensure the PID is a kernel process we started.
+     */
+    async isExpectedKernelProcess(pid, connectionFile, expectedStartTime) {
+        if (expectedStartTime) {
+            const currentStartTime = await this.getProcessStartTime(pid);
+            if (currentStartTime && currentStartTime === expectedStartTime) {
+                return true;
+            }
+            return false;
+        }
+        const cmd = await this.getPidCommand(pid);
+        if (!cmd)
+            return false;
+        if (connectionFile && cmd.includes(connectionFile)) {
+            return true;
+        }
+        // Fallback: ensure it's an ipykernel process before killing
+        return cmd.includes('ipykernel_launcher') || cmd.includes('ipykernel');
+    }
+    /**
+     * Attempt to terminate a PID gracefully, then force kill.
+     */
+    async terminatePid(pid) {
+        if (!this.isPidAlive(pid))
+            return true;
+        try {
+            process.kill(pid, 'SIGTERM');
+        }
+        catch {
+            // Ignore kill errors
+        }
+        await this.sleep(500);
+        if (this.isPidAlive(pid)) {
+            try {
+                process.kill(pid, 'SIGKILL');
+            }
+            catch {
+                // Ignore kill errors
+            }
+        }
+        await this.sleep(200);
+        return !this.isPidAlive(pid);
+    }
+    cleanupPersistedSessionArtifacts(session) {
+        if (session.connectionFile && fs.existsSync(session.connectionFile)) {
+            try {
+                fs.unlinkSync(session.connectionFile);
+            }
+            catch {
+                // Ignore delete errors
+            }
+        }
+    }
+    /**
+     * Cleanup kernel resources
+     */
+    cleanupKernelResources(sessionId) {
+        // stopKernel() already handles these, but unexpected process exits and failed startups
+        // may call cleanup directly. Ensure we don't leak sockets or stale ChildProcess handles.
+        this.detachProcessLifecycle(this.kernelProcesses.get(sessionId));
+        const sockets = this.zmqSockets.get(sessionId);
+        if (sockets) {
+            try {
+                sockets.shell.close();
+                sockets.iopub.close();
+            }
+            catch {
+                // Ignore close errors
+            }
+            this.zmqSockets.delete(sessionId);
+        }
+        this.kernelProcesses.delete(sessionId);
+        const session = this.sessions.get(sessionId);
+        if (session) {
+            // Remove file mapping
+            if (session.filePath) {
+                this.fileToSession.delete(session.filePath);
+            }
+            // Delete connection file
+            if (session.connectionFile && fs.existsSync(session.connectionFile)) {
+                try {
+                    fs.unlinkSync(session.connectionFile);
+                }
+                catch {
+                    // Ignore delete errors
+                }
+            }
+            // Remove from sessions
+            this.sessions.delete(sessionId);
+            // Update persistence store
+            this.sessionStore.deleteSession(sessionId);
+        }
+        this.executionQueues.delete(sessionId);
+        this.executionQueueSizes.delete(sessionId);
+        this.shellRequestQueues.delete(sessionId);
+        this.cellOutputBuffers.delete(sessionId);
+        this.cellOutputTracking.delete(sessionId);
+        this.executingCellIds.delete(sessionId);
+    }
+    /**
+     * Cleanup only in-memory tracking for a session (keeps connection file and session store).
+     */
+    cleanupInMemorySession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (session?.filePath) {
+            this.fileToSession.delete(session.filePath);
+        }
+        this.detachProcessLifecycle(this.kernelProcesses.get(sessionId));
+        const sockets = this.zmqSockets.get(sessionId);
+        if (sockets) {
+            try {
+                sockets.shell.close();
+                sockets.iopub.close();
+            }
+            catch {
+                // Ignore close errors
+            }
+            this.zmqSockets.delete(sessionId);
+        }
+        this.sessions.delete(sessionId);
+        this.kernelProcesses.delete(sessionId);
+        this.executionQueues.delete(sessionId);
+        this.executionQueueSizes.delete(sessionId);
+        this.shellRequestQueues.delete(sessionId);
+    }
+    /**
+     * Interrupt kernel execution
+     */
+    async interruptKernel(sessionId) {
+        const proc = this.kernelProcesses.get(sessionId);
+        if (proc) {
+            try {
+                proc.kill('SIGINT');
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        const session = this.sessions.get(sessionId);
+        const pid = session?.pid ?? null;
+        if (!pid)
+            return false;
+        try {
+            // Best-effort: validate PID still matches the kernel we started/reattached to.
+            // This matters when a server restarts and we no longer have a ChildProcess handle.
+            const persisted = this.sessionStore.getSession(sessionId);
+            const expectedStartTime = persisted?.kernelStartTime ?? null;
+            const connectionFile = session?.connectionFile ?? persisted?.connectionFile ?? null;
+            const ok = await this.isExpectedKernelProcess(pid, connectionFile, expectedStartTime);
+            if (!ok) {
+                console.warn(`[Kernel] Refusing to interrupt PID ${pid} for session ${sessionId}: unexpected process`);
+                return false;
+            }
+            process.kill(pid, 'SIGINT');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Restart a kernel (in-place, preserving session ID like Python)
+     */
+    async restartKernel(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            return false;
+        }
+        const { kernelName, filePath, connectionFile: oldConnFile } = session;
+        // Set status to restarting
+        session.status = 'starting';
+        // Close ZeroMQ sockets
+        const sockets = this.zmqSockets.get(sessionId);
+        if (sockets) {
+            try {
+                sockets.shell.close();
+                sockets.iopub.close();
+            }
+            catch {
+                // Ignore close errors
+            }
+            this.zmqSockets.delete(sessionId);
+        }
+        // Kill existing kernel process
+        const proc = this.kernelProcesses.get(sessionId);
+        if (proc) {
+            this.detachProcessLifecycle(proc);
+            try {
+                proc.kill('SIGTERM');
+                await this.sleep(500);
+                if (!proc.killed) {
+                    proc.kill('SIGKILL');
+                }
+            }
+            catch {
+                // Ignore kill errors
+            }
+            this.kernelProcesses.delete(sessionId);
+        }
+        else if (session.pid) {
+            // Reattached session: no ChildProcess handle, but we may still have a PID.
+            // Validate before terminating to avoid PID reuse mistakes.
+            const persisted = this.sessionStore.getSession(sessionId);
+            const expectedStartTime = persisted?.kernelStartTime ?? null;
+            const connectionFile = oldConnFile ?? persisted?.connectionFile ?? null;
+            const ok = await this.isExpectedKernelProcess(session.pid, connectionFile, expectedStartTime);
+            if (!ok) {
+                console.warn(`[Kernel] Refusing to restart PID ${session.pid} for session ${sessionId}: unexpected process`);
+                session.status = 'dead';
+                return false;
+            }
+            await this.terminatePid(session.pid);
+            session.pid = null;
+        }
+        // Delete old connection file
+        if (oldConnFile && fs.existsSync(oldConnFile)) {
+            try {
+                fs.unlinkSync(oldConnFile);
+            }
+            catch {
+                // Ignore delete errors
+            }
+        }
+        // Get kernel spec
+        const spec = (0, kernelspec_1.getKernelSpec)(kernelName);
+        if (!spec) {
+            session.status = 'dead';
+            return false;
+        }
+        try {
+            // Generate new connection file (reusing same session ID)
+            const { config: connConfig, filePath: connFile } = await this.generateConnectionFile(sessionId);
+            // Build kernel command
+            const argv = (spec.argv || []).map(arg => arg.replace('{connection_file}', connFile));
+            // Spawn new kernel process
+            const cwd = filePath ? path.dirname(filePath) : process.cwd();
+            const newProc = (0, child_process_1.spawn)(argv[0], argv.slice(1), {
+                cwd,
+                env: { ...process.env, ...spec.env },
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            // Log kernel stdout/stderr
+            newProc.stdout?.on('data', (data) => {
+                console.log(`[Kernel ${sessionId.slice(0, 8)}] stdout: ${data.toString().trim()}`);
+            });
+            newProc.stderr?.on('data', (data) => {
+                console.error(`[Kernel ${sessionId.slice(0, 8)}] stderr: ${data.toString().trim()}`);
+            });
+            // Update session in-place
+            session.connectionFile = connFile;
+            session.connectionConfig = connConfig;
+            session.pid = newProc.pid || null;
+            session.executionCount = 0;
+            session.lastActivity = Date.now() / 1000;
+            this.kernelProcesses.set(sessionId, newProc);
+            // Handle process events
+            this.attachProcessLifecycle(sessionId, newProc, session);
+            // Wait for kernel to be ready
+            await this.waitForReady(sessionId);
+            const kernelStartTime = newProc.pid ? await this.getProcessStartTime(newProc.pid) : null;
+            // Update persistence store
+            this.sessionStore.saveSession({
+                sessionId,
+                kernelName,
+                filePath,
+                kernelPid: newProc.pid || null,
+                serverId: this.serverId,
+                serverInstanceId: this.serverInstanceId,
+                kernelStartTime,
+                status: 'active',
+                createdAt: session.createdAt,
+                lastHeartbeat: Date.now() / 1000,
+                connectionFile: connFile,
+                connectionConfig: JSON.stringify(session.connectionConfig),
+            });
+            session.status = 'idle';
+            return true;
+        }
+        catch (err) {
+            console.error(`Failed to restart kernel ${sessionId}:`, err);
+            await this.stopKernel(sessionId).catch(() => undefined);
+            return false;
+        }
+    }
+    /**
+     * Get session status
+     */
+    getSessionStatusFast(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            return null;
+        }
+        return {
+            id: session.id,
+            kernelName: session.kernelName,
+            filePath: session.filePath,
+            status: session.status,
+            executionCount: session.executionCount,
+            memoryMb: null,
+            pid: session.pid,
+            createdAt: session.createdAt,
+        };
+    }
+    async getSessionStatus(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            return null;
+        }
+        const memoryMap = session.pid ? await this.getProcessMemoryMap([session.pid]) : new Map();
+        return {
+            id: session.id,
+            kernelName: session.kernelName,
+            filePath: session.filePath,
+            status: session.status,
+            executionCount: session.executionCount,
+            pid: session.pid,
+            memoryMb: session.pid ? (memoryMap.get(session.pid) ?? null) : null,
+            createdAt: session.createdAt,
+        };
+    }
+    /**
+     * Get all sessions
+     */
+    async getAllSessions() {
+        // Collect all PIDs for batch memory lookup
+        const pids = [];
+        for (const session of this.sessions.values()) {
+            if (session.pid)
+                pids.push(session.pid);
+        }
+        // Single ps call for all PIDs
+        const memoryMap = await this.getProcessMemoryMap(pids);
+        const sessions = [];
+        for (const [_, session] of this.sessions) {
+            sessions.push({
+                id: session.id,
+                kernelName: session.kernelName,
+                filePath: session.filePath,
+                status: session.status,
+                executionCount: session.executionCount,
+                pid: session.pid,
+                memoryMb: session.pid ? (memoryMap.get(session.pid) ?? null) : null,
+                createdAt: session.createdAt,
+            });
+        }
+        return sessions;
+    }
+    /**
+     * Get dead sessions (orphaned or terminated) that can be cleaned up
+     */
+    getDeadSessions() {
+        const deadSessions = this.sessionStore.getDeadSessions(this.serverId);
+        return deadSessions.map(s => ({
+            sessionId: s.sessionId,
+            kernelName: s.kernelName,
+            filePath: s.filePath,
+            status: s.status,
+            lastHeartbeat: s.lastHeartbeat,
+        }));
+    }
+    /**
+     * Cleanup dead sessions by deleting them from the database
+     */
+    async cleanupDeadSessions(sessionIds) {
+        const deadSessions = this.sessionStore.getDeadSessions(this.serverId);
+        const targets = sessionIds && sessionIds.length > 0
+            ? deadSessions.filter(s => sessionIds.includes(s.sessionId))
+            : deadSessions;
+        const deletableIds = [];
+        for (const session of targets) {
+            let canDelete = true;
+            if (session.kernelPid && this.isPidAlive(session.kernelPid)) {
+                if (!session.kernelStartTime && !this.legacyCleanupWarned.has(session.sessionId)) {
+                    console.warn(`[Kernel] Deprecated cleanup fallback for session ${session.sessionId}: kernel_start_time missing. ` +
+                        'This fallback will be removed after legacy sessions are cleaned up.');
+                    this.legacyCleanupWarned.add(session.sessionId);
+                }
+                const expected = await this.isExpectedKernelProcess(session.kernelPid, session.connectionFile, session.kernelStartTime);
+                if (!expected) {
+                    canDelete = false;
+                }
+                else {
+                    const killed = await this.terminatePid(session.kernelPid);
+                    if (!killed) {
+                        canDelete = false;
+                    }
+                }
+            }
+            if (canDelete) {
+                this.cleanupPersistedSessionArtifacts(session);
+                deletableIds.push(session.sessionId);
+            }
+        }
+        if (deletableIds.length === 0) {
+            return 0;
+        }
+        return this.sessionStore.deleteSessions(deletableIds);
+    }
+    /**
+     * Cleanup all sessions
+     */
+    async cleanup() {
+        const sessionIds = Array.from(this.sessions.keys());
+        for (const sessionId of sessionIds) {
+            await this.stopKernel(sessionId);
+        }
+        this.sessionStore.close();
+    }
+    /**
+     * Shutdown kernel service.
+     * If preserveKernels is true, keep kernel processes running and close the session store.
+     */
+    async shutdown(options) {
+        if (options?.preserveKernels) {
+            try {
+                this.sessionStore.markAllOrphaned(this.serverId, this.serverInstanceId);
+            }
+            catch {
+                // Ignore errors marking orphaned
+            }
+            this.sessionStore.close();
+            return;
+        }
+        await this.cleanup();
+    }
+    /**
+     * Helper: sleep for ms milliseconds
+     */
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /**
+     * Get memory usage (RSS) for multiple processes in MB
+     * Returns a map of pid -> memoryMb
+     * Cross-platform: uses /proc on Linux, ps on macOS
+     */
+    async getProcessMemoryMap(pids) {
+        const result = new Map();
+        if (pids.length === 0)
+            return result;
+        const isLinux = process.platform === 'linux';
+        if (isLinux) {
+            // On Linux, read directly from /proc/{pid}/statm (more reliable)
+            // statm format: size resident shared text lib data dt (all in pages)
+            // resident (2nd field) * page_size = RSS in bytes
+            const pageSize = 4096; // Standard page size, could use os.constants.POSIX.PAGE_SIZE
+            const fs = await Promise.resolve().then(() => __importStar(require('fs/promises')));
+            await Promise.all(pids.map(async (pid) => {
+                try {
+                    const statm = await fs.readFile(`/proc/${pid}/statm`, 'utf8');
+                    const fields = statm.trim().split(/\s+/);
+                    if (fields.length >= 2) {
+                        const residentPages = parseInt(fields[1], 10);
+                        if (!isNaN(residentPages)) {
+                            const rssBytes = residentPages * pageSize;
+                            result.set(pid, Math.round(rssBytes / 1024 / 1024 * 10) / 10);
+                        }
+                    }
+                }
+                catch {
+                    // Process may have exited or permission denied
+                }
+            }));
+        }
+        else {
+            // macOS/BSD: use ps command with comma-separated PIDs
+            try {
+                const pidList = pids.join(',');
+                const { stdout } = await execAsync(`ps -o pid=,rss= -p ${pidList}`, { timeout: 500 });
+                for (const line of stdout.trim().split('\n')) {
+                    const parts = line.trim().split(/\s+/);
+                    if (parts.length >= 2) {
+                        const pid = parseInt(parts[0], 10);
+                        const rssKb = parseInt(parts[1], 10);
+                        if (!isNaN(pid) && !isNaN(rssKb)) {
+                            result.set(pid, Math.round(rssKb / 1024 * 10) / 10);
+                        }
+                    }
+                }
+            }
+            catch {
+                // ps command failed or timed out
+            }
+        }
+        return result;
+    }
+}
+exports.KernelService = KernelService;
+// Global instance
+exports.kernelService = new KernelService();