nebula-notebook 0.1.0 → 0.2.0

package/node-server/dist/fs/notebook-formats/registry.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * Registry for plain-text notebook format adapters.
+ *
+ * .ipynb is intentionally NOT registered here: dispatch sites check .ipynb
+ * first and fall through to the existing Jupyter JSON code path untouched.
+ */
+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.getFormatAdapter = getFormatAdapter;
+exports.defaultKernelForPath = defaultKernelForPath;
+exports.isTextNotebookPath = isTextNotebookPath;
+exports.isNotebookPath = isNotebookPath;
+const path = __importStar(require("path"));
+const percent_1 = require("./percent");
+const qmd_1 = require("./qmd");
+const ADAPTERS = [percent_1.percentAdapter, qmd_1.qmdAdapter];
+const BY_EXTENSION = new Map();
+for (const adapter of ADAPTERS) {
+    for (const ext of adapter.extensions)
+        BY_EXTENSION.set(ext, adapter);
+}
+function getFormatAdapter(filePath) {
+    return BY_EXTENSION.get(path.extname(filePath).toLowerCase()) ?? null;
+}
+/**
+ * Default kernel for a text-notebook file that does not declare one in its
+ * header, keyed by extension. Falls back to python3 for unknown extensions.
+ * (.qmd resolves its kernel from the first code fence's language instead.)
+ */
+const DEFAULT_KERNEL_BY_EXTENSION = {
+    '.py': 'python3',
+    '.r': 'ir',
+    '.jl': 'julia',
+};
+function defaultKernelForPath(filePath) {
+    return DEFAULT_KERNEL_BY_EXTENSION[path.extname(filePath).toLowerCase()] ?? 'python3';
+}
+function isTextNotebookPath(filePath) {
+    return BY_EXTENSION.has(path.extname(filePath).toLowerCase());
+}
+/** True for any path Nebula can treat as a notebook (.ipynb or text format). */
+function isNotebookPath(filePath) {
+    return path.extname(filePath).toLowerCase() === '.ipynb' || isTextNotebookPath(filePath);
+}

package/node-server/dist/fs/notebook-formats/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Plain-text notebook format adapters (jupytext percent .py, Quarto .qmd).
+ *
+ * These formats are "notebooks that don't serialize outputs": the in-memory
+ * model is the same NebulaCell[] the rest of the system uses; only the
+ * on-disk representation differs. Outputs, execution counts, and UI state
+ * are never written to disk for these formats — that is the point of them.
+ *
+ * .ipynb is deliberately NOT an adapter: every dispatch site checks .ipynb
+ * first and falls into the existing, unmodified Jupyter JSON code path.
+ */
+import { NebulaCell } from '../types';
+export interface ParsedTextNotebook {
+    /** Cells with outputs: [], executionCount: null. Ids come from in-file
+     *  markers when present, else the positional `cell-${i}` fallback (the
+     *  same degraded mode legacy .ipynb files without nebula_id use). */
+    cells: NebulaCell[];
+    /** Normalized notebook metadata: kernelspec?, nebula?, plus opaque
+     *  format-specific keys the serializer round-trips. */
+    metadata: Record<string, unknown>;
+    /** Kernelspec name if the file declares one, else null (caller falls back
+     *  to the existing env-default resolution). */
+    kernelspecName: string | null;
+}
+export interface NotebookFormatAdapter {
+    name: 'percent' | 'qmd';
+    /** Lowercased extensions including the dot, e.g. ['.py']. */
+    extensions: string[];
+    capabilities: {
+        storesOutputs: false;
+        /** Whether cell ids can persist in the file for ALL cell types.
+         *  percent: true. qmd: code cells only (prose has no metadata slot). */
+        storesCellIds: boolean;
+    };
+    parse(text: string): ParsedTextNotebook;
+    serialize(cells: NebulaCell[], metadata: Record<string, unknown>, kernelName?: string): string;
+}

package/node-server/dist/fs/notebook-formats/types.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Plain-text notebook format adapters (jupytext percent .py, Quarto .qmd).
+ *
+ * These formats are "notebooks that don't serialize outputs": the in-memory
+ * model is the same NebulaCell[] the rest of the system uses; only the
+ * on-disk representation differs. Outputs, execution counts, and UI state
+ * are never written to disk for these formats — that is the point of them.
+ *
+ * .ipynb is deliberately NOT an adapter: every dispatch site checks .ipynb
+ * first and falls into the existing, unmodified Jupyter JSON code path.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/node-server/dist/idle-exit.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Idle auto-release for scheduler-launched client servers.
+ *
+ * Opt-in per allocation: when the compute-node client server is started with
+ * NEBULA_IDLE_EXIT_MINUTES=<n>, it watches its own kernel and terminal
+ * activity and exits its process after n idle minutes. The batch job then
+ * completes and the allocation ends naturally — no scancel plumbing, no
+ * scheduler-side state.
+ *
+ * "Idle" means all of:
+ *   - no kernel session is busy (or still starting up), AND
+ *   - the most recent kernel activity (execution start/finish, restart) is
+ *     older than the timeout, AND
+ *   - the most recent terminal (pty) activity is older than the timeout.
+ *
+ * The monitor's own start time is the initial activity baseline, so a fresh
+ * allocation gets the full timeout before anything has run on it.
+ */
+/**
+ * Pure idleness decision — should the client server exit now?
+ *
+ * @param nowMs current time (ms since epoch)
+ * @param lastKernelActivityMs most recent kernel activity (ms), or null if no signal
+ * @param anyKernelBusy true when any kernel session is 'busy' or 'starting'
+ * @param lastPtyActivityMs most recent terminal activity (ms), or null if no signal
+ * @param timeoutMinutes idle timeout; <= 0 disables (never exit)
+ */
+export declare function shouldIdleExit(nowMs: number, lastKernelActivityMs: number | null, anyKernelBusy: boolean, lastPtyActivityMs: number | null, timeoutMinutes: number): boolean;
+export interface IdleExitMonitorOptions {
+    /** Idle minutes before self-exit (from NEBULA_IDLE_EXIT_MINUTES). */
+    timeoutMinutes: number;
+    /** Kernel-side activity snapshot (kernelService.getIdleSnapshot). */
+    getKernelSnapshot: () => {
+        anyBusy: boolean;
+        lastActivityMs: number | null;
+    };
+    /** Most recent terminal activity across pty sessions (null = none). */
+    getLastPtyActivityMs: () => number | null;
+    /** Called once when ~WARN_LEAD_MINUTES remain (re-armed if activity resumes). */
+    onWarn: (minutesLeft: number) => void;
+    /** Called once when the idle timeout is reached. */
+    onIdleExit: () => void | Promise<void>;
+    /** Check interval; default 60s. Exposed for tests. */
+    intervalMs?: number;
+    /** Activity baseline; default Date.now() (start of monitoring). */
+    startedAtMs?: number;
+}
+/**
+ * Start the periodic idleness check. Returns a stop function.
+ * The interval is unref()ed so it never keeps an exiting process alive.
+ */
+export declare function startIdleExitMonitor(opts: IdleExitMonitorOptions): () => void;

package/node-server/dist/idle-exit.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * Idle auto-release for scheduler-launched client servers.
+ *
+ * Opt-in per allocation: when the compute-node client server is started with
+ * NEBULA_IDLE_EXIT_MINUTES=<n>, it watches its own kernel and terminal
+ * activity and exits its process after n idle minutes. The batch job then
+ * completes and the allocation ends naturally — no scancel plumbing, no
+ * scheduler-side state.
+ *
+ * "Idle" means all of:
+ *   - no kernel session is busy (or still starting up), AND
+ *   - the most recent kernel activity (execution start/finish, restart) is
+ *     older than the timeout, AND
+ *   - the most recent terminal (pty) activity is older than the timeout.
+ *
+ * The monitor's own start time is the initial activity baseline, so a fresh
+ * allocation gets the full timeout before anything has run on it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldIdleExit = shouldIdleExit;
+exports.startIdleExitMonitor = startIdleExitMonitor;
+/** How far before the exit we log the "run anything to keep it" warning. */
+const WARN_LEAD_MINUTES = 5;
+/**
+ * Pure idleness decision — should the client server exit now?
+ *
+ * @param nowMs current time (ms since epoch)
+ * @param lastKernelActivityMs most recent kernel activity (ms), or null if no signal
+ * @param anyKernelBusy true when any kernel session is 'busy' or 'starting'
+ * @param lastPtyActivityMs most recent terminal activity (ms), or null if no signal
+ * @param timeoutMinutes idle timeout; <= 0 disables (never exit)
+ */
+function shouldIdleExit(nowMs, lastKernelActivityMs, anyKernelBusy, lastPtyActivityMs, timeoutMinutes) {
+    if (!Number.isFinite(timeoutMinutes) || timeoutMinutes <= 0)
+        return false;
+    if (anyKernelBusy)
+        return false;
+    const last = Math.max(lastKernelActivityMs ?? 0, lastPtyActivityMs ?? 0);
+    if (last <= 0)
+        return false; // no baseline at all — never guess
+    return nowMs - last >= timeoutMinutes * 60_000;
+}
+/**
+ * Start the periodic idleness check. Returns a stop function.
+ * The interval is unref()ed so it never keeps an exiting process alive.
+ */
+function startIdleExitMonitor(opts) {
+    const intervalMs = opts.intervalMs ?? 60_000;
+    const startedAt = opts.startedAtMs ?? Date.now();
+    let warned = false;
+    let exiting = false;
+    const tick = () => {
+        if (exiting)
+            return;
+        const now = Date.now();
+        const kernel = opts.getKernelSnapshot();
+        // The monitor start counts as activity so a fresh, never-used allocation
+        // still gets the full timeout before releasing itself.
+        const lastKernel = Math.max(kernel.lastActivityMs ?? 0, startedAt);
+        const lastPty = opts.getLastPtyActivityMs();
+        if (shouldIdleExit(now, lastKernel, kernel.anyBusy, lastPty, opts.timeoutMinutes)) {
+            exiting = true;
+            clearInterval(timer);
+            void opts.onIdleExit();
+            return;
+        }
+        // Warn once when within WARN_LEAD_MINUTES of the cutoff; re-arm on activity.
+        const last = Math.max(lastKernel, lastPty ?? 0);
+        const idleMinutes = (now - last) / 60_000;
+        const warnAt = opts.timeoutMinutes - WARN_LEAD_MINUTES;
+        if (kernel.anyBusy || idleMinutes < warnAt) {
+            warned = false;
+        }
+        else if (!warned && warnAt > 0) {
+            warned = true;
+            opts.onWarn(Math.max(1, Math.round(opts.timeoutMinutes - idleMinutes)));
+        }
+    };
+    const timer = setInterval(tick, intervalMs);
+    timer.unref?.();
+    return () => clearInterval(timer);
+}

package/node-server/dist/index.js

@@ -61,24 +61,32 @@ const crypto = __importStar(require("crypto"));
 const crypto_1 = require("crypto");
 // Import routes
 const kernel_1 = __importStar(require("./routes/kernel"));
-const llm_1 = __importStar(require("./routes/llm"));
 const fs_1 = __importDefault(require("./routes/fs"));
 const notebook_1 = __importDefault(require("./routes/notebook"));
 const python_1 = __importDefault(require("./routes/python"));
 const auth_1 = __importDefault(require("./routes/auth"));
 const cluster_1 = __importDefault(require("./routes/cluster"));
 const resources_1 = __importDefault(require("./routes/resources"));
+const compute_1 = __importDefault(require("./routes/compute"));
 // Import cluster
 const server_registry_1 = require("./cluster/server-registry");
 const cluster_secret_1 = require("./cluster/cluster-secret");
 const client_registration_1 = require("./cluster/client-registration");
+// Import scheduler (SLURM-backed compute allocations)
+const allocation_service_1 = require("./scheduler/allocation-service");
+const slurm_scheduler_1 = require("./scheduler/slurm-scheduler");
+const mock_scheduler_1 = require("./scheduler/mock-scheduler");
 // Import auth
 const auth_2 = require("./auth");
 const fs_service_1 = require("./fs/fs-service");
+const update_check_1 = require("./update-check");
 // Import terminal routes (existing)
 const server_1 = require("./terminal/server");
 // Import notebook WebSocket
 const notebook_websocket_1 = require("./notebook/notebook-websocket");
+// Idle auto-release (client mode, opt-in via NEBULA_IDLE_EXIT_MINUTES)
+const idle_exit_1 = require("./idle-exit");
+const pty_manager_1 = require("./terminal/pty-manager");
 const PORT = process.env.PORT || process.env.NODE_SERVER_PORT || 3000;
 const DEV_MODE = process.env.DEV_MODE === 'true' || process.argv.includes('--dev');
 const BODY_LIMIT = process.env.NEBULA_BODY_LIMIT ||
@@ -272,12 +280,13 @@ async function createApp() {
     fastify.get('/api/health', async (_request, reply) => {
         // Use configured root directory (from .nebula-config.json or fallback to cwd)
         const rootDir = fs_service_1.fsService.normalizePath('~');
+        const update = (0, update_check_1.getUpdateInfo)();
         return reply.send({
             status: 'ok',
-            version: '1.0.0',
+            version: update.current,
             ready: kernel_1.kernelService.isReady,
-            llm_providers: Object.keys(llm_1.llmService.getAvailableProviders()),
             cwd: rootDir,
+            update,
         });
     });
     fastify.get('/api/ready', async (_request, reply) => {
@@ -309,11 +318,11 @@ async function createApp() {
     });
     // API routes (protected)
     await fastify.register(kernel_1.default, { prefix: '/api' });
-    await fastify.register(llm_1.default, { prefix: '/api' });
     await fastify.register(fs_1.default, { prefix: '/api' });
     await fastify.register(notebook_1.default, { prefix: '/api' });
     await fastify.register(python_1.default, { prefix: '/api' });
     await fastify.register(cluster_1.default, { prefix: '/api' });
+    await fastify.register(compute_1.default, { prefix: '/api' });
     await fastify.register(resources_1.default, { prefix: '/api/resources' });
     // Terminal routes (registered directly on the app, not under /api prefix)
     await fastify.register(server_1.setupTerminalRoutes);
@@ -449,8 +458,9 @@ async function main() {
     else {
         console.log('[Auth] 2FA configured and ready');
     }
-    // Set local server ID from hostname
-    const localServerId = `${os.hostname()}:${PORT}`;
+    // Set local server ID from hostname (NEBULA_HOST overrides the advertised name
+    // when the OS hostname isn't the reachable/desired identity — e.g. demos).
+    const localServerId = `${process.env.NEBULA_HOST || os.hostname()}:${PORT}`;
     server_registry_1.serverRegistry.setLocalServerId(localServerId);
     console.log(`[Cluster] Local server ID: ${localServerId}`);
     const serverInstanceId = (0, crypto_1.randomUUID)();
@@ -471,6 +481,35 @@ async function main() {
     (0, server_1.setupTerminalWebSocket)(server);
     // Setup notebook operations WebSocket
     (0, notebook_websocket_1.setupNotebookWebSocket)(server);
+    // Scheduler-backed compute allocations (main server only; detection-gated)
+    let schedulerDetected = false;
+    if (!CLIENT_MODE) {
+        try {
+            // NEBULA_SCHEDULER=mock enables a fabricated-data scheduler (no real cluster)
+            // for demos/tests; otherwise use the real SLURM scheduler (detection-gated).
+            const scheduler = process.env.NEBULA_SCHEDULER === 'mock' ? new mock_scheduler_1.MockScheduler() : new slurm_scheduler_1.SlurmScheduler();
+            if (await scheduler.detect()) {
+                schedulerDetected = true;
+                const ctx = {
+                    mainUrl: process.env.NEBULA_SCHEDULER_MAIN_URL || `http://${os.hostname()}:${PORT}`,
+                    secret: process.env.NEBULA_CLUSTER_SECRET,
+                    nodeBin: process.execPath,
+                    execArgv: process.execArgv,
+                    scriptPath: process.argv[1],
+                    cwd: process.cwd(),
+                    stateDir: process.env.NEBULA_SCHEDULER_STATE_DIR || path.join(os.homedir(), '.nebula', 'allocations'),
+                };
+                allocation_service_1.allocationService.init(scheduler, ctx);
+                console.log('[Scheduler] SLURM detected — compute allocations enabled');
+            }
+            else {
+                console.log('[Scheduler] No batch scheduler detected — compute allocations disabled');
+            }
+        }
+        catch (err) {
+            console.warn('[Scheduler] Init failed:', err instanceof Error ? err.message : String(err));
+        }
+    }
     if (REATTACH_KERNELS) {
         try {
             const result = await kernel_1.kernelService.reattachOrphanedSessions();
@@ -483,6 +522,41 @@ async function main() {
             console.warn(`[Kernel] Reattach failed: ${message}`);
         }
     }
+    // Final "you're up" banner — the one part of startup written for humans.
+    // Everything a first-time user needs: where to point the browser, where the
+    // files live, whether cluster compute is on, and how to reach a remote
+    // server from a laptop. Client-mode servers skip it (no user is watching).
+    if (!CLIENT_MODE) {
+        const host = os.hostname();
+        let rootDir = '~';
+        try {
+            rootDir = fs_service_1.fsService.getRootDirectory();
+        }
+        catch { /* keep default */ }
+        const lines = [
+            '',
+            '  ──────────────────────────────────────────────────────',
+            '   Nebula Notebook is running',
+            '',
+            `   Open:      http://localhost:${PORT}`,
+            `   Network:   http://${host}:${PORT}`,
+            `   Files:     ${rootDir}`,
+            `   Compute:   ${schedulerDetected
+                ? 'SLURM detected — allocate compute nodes from the kernel menu'
+                : 'no batch scheduler here — kernels run on this machine'}`,
+            ...(setupNeeded ? ['   Sign-in:   scan the QR code above with an authenticator app'] : []),
+            '',
+            '   On a remote machine? From your laptop:',
+            `     ssh -L ${PORT}:localhost:${PORT} ${host}    then open http://localhost:${PORT}`,
+            '   Cluster guide: https://github.com/jzthree/nebula-notebook/blob/main/docs/CLUSTER_SETUP.md',
+            '  ──────────────────────────────────────────────────────',
+            '',
+        ];
+        console.log(lines.join('\n'));
+    }
+    // Daily notify-only update check (NEBULA_NO_UPDATE_CHECK=1 to disable)
+    if (!CLIENT_MODE)
+        (0, update_check_1.startUpdateChecker)();
     // Graceful shutdown
     let shuttingDown = false;
     const shutdown = async () => {
@@ -510,10 +584,11 @@ async function main() {
         catch (err) {
             console.error('[Server] Error during kernel cleanup:', err);
         }
-        // Cleanup cluster registration
+        // Cleanup cluster registration + scheduler polling
         try {
             await client_registration_1.clientRegistration.shutdown();
             server_registry_1.serverRegistry.shutdown();
+            allocation_service_1.allocationService.shutdown();
         }
         catch (err) {
             console.error('[Server] Error during cluster cleanup:', err);
@@ -544,9 +619,54 @@ async function main() {
     console.log(`[Server] Notebook WebSocket: ${wsProtocol}://localhost:${PORT}/api/notebook/{path}/ws`);
     console.log(`[Server] Terminal WebSocket: ${wsProtocol}://localhost:${PORT}/ws?id={terminal_id}`);
     console.log(`[Server] Root directory: ${fs_service_1.fsService.getRootDirectory()} (change with --workdir)`);
-    // Initialize client registration (explicit client mode only)
+    // Initialize client registration (explicit client mode only). With PORT=0
+    // (scheduler-launched jobs pick an ephemeral port), register the *actual* bound
+    // port so the main server proxies kernels to the right place.
     if (CLIENT_MODE) {
-        client_registration_1.clientRegistration.initFromEnv(Number(PORT));
+        const addr = fastify.server.address();
+        const boundPort = addr && typeof addr === 'object' && addr ? addr.port : Number(PORT);
+        const clientServerId = `${os.hostname()}:${boundPort}`;
+        server_registry_1.serverRegistry.setLocalServerId(clientServerId);
+        kernel_1.kernelService.setServerIdentity(clientServerId, serverInstanceId);
+        client_registration_1.clientRegistration.initFromEnv(boundPort);
+        // Opt-in idle auto-release: exit this process after N idle minutes so the
+        // batch job completes and the allocation ends naturally (no scancel needed).
+        const idleExitMinutes = Math.floor(Number(process.env.NEBULA_IDLE_EXIT_MINUTES) || 0);
+        if (idleExitMinutes > 0) {
+            console.log(`[IdleExit] Enabled — allocation auto-ends after ${idleExitMinutes} idle minutes`);
+            (0, idle_exit_1.startIdleExitMonitor)({
+                timeoutMinutes: idleExitMinutes,
+                getKernelSnapshot: () => kernel_1.kernelService.getIdleSnapshot(),
+                getLastPtyActivityMs: () => {
+                    const terminals = pty_manager_1.ptyManager.list();
+                    if (terminals.length === 0)
+                        return null;
+                    return Math.max(...terminals.map((t) => t.lastActivity));
+                },
+                onWarn: (minutesLeft) => {
+                    console.warn(`[IdleExit] Idle — will end allocation in ${minutesLeft}m; run anything to keep it`);
+                },
+                onIdleExit: async () => {
+                    console.log(`[IdleExit] Idle for ${idleExitMinutes} minutes — releasing allocation (exiting)`);
+                    // Shut kernels down cleanly WITHOUT preservation so nothing tries to
+                    // resurrect them, then drop the cluster registration and exit 0 —
+                    // the batch job completes and the allocation ends.
+                    (0, server_1.cleanupTerminals)();
+                    try {
+                        await kernel_1.kernelService.shutdown({ preserveKernels: false });
+                    }
+                    catch (err) {
+                        console.error('[IdleExit] Error during kernel cleanup:', err);
+                    }
+                    try {
+                        await client_registration_1.clientRegistration.shutdown();
+                    }
+                    catch { /* best effort — we are exiting anyway */ }
+                    console.log('[IdleExit] Allocation released — exiting');
+                    process.exit(0);
+                },
+            });
+        }
     }
 }
 // Run

package/node-server/dist/kernel/kernel-service.d.ts

@@ -7,6 +7,19 @@
 import { KernelOutput, ExecutionResult, ExecutionQueueInfo, StartKernelOptions, SessionInfo, KernelServiceConfig } from './types';
 import { SessionStore } from './session-store';
 import { KernelSpec } from './kernelspec';
+/** Kernel-originated comm event surfaced to onComm listeners. */
+export interface CommEvent {
+    msgType: 'comm_open' | 'comm_msg' | 'comm_close';
+    commId: string;
+    targetName?: string;
+    data: Record<string, unknown>;
+    /** Binary buffer frames, base64-encoded. Present only when non-empty. */
+    buffers?: string[];
+}
+/** Resolved by BoundedAsyncQueue.next() when the queue has been closed. */
+export declare const IOPUB_QUEUE_CLOSED: unique symbol;
+/** Resolved by BoundedAsyncQueue.next(timeoutMs) when the wait timed out. */
+export declare const IOPUB_QUEUE_TIMEOUT: unique symbol;
 export declare class KernelService {
     private sessions;
     private fileToSession;
@@ -28,7 +41,23 @@ export declare class KernelService {
     private cellOutputBuffers;
     private cellOutputTracking;
     private executingCellIds;
+    private iopubReaders;
+    private iopubParentSubscribers;
+    private iopubCatchAllSubscribers;
+    private commStates;
+    private shellReaders;
+    private shellReplyWaiters;
     constructor(config?: KernelServiceConfig, sessionStore?: SessionStore);
+    private deadListeners;
+    onSessionDead(cb: (sessionId: string) => void): void;
+    private notifySessionDead;
+    private commListeners;
+    onComm(cb: (sessionId: string, comm: CommEvent) => void): void;
+    private notifyComm;
+    private livenessTimer;
+    private startLivenessSweep;
+    /** One liveness pass (exposed for tests; normally driven by the timer). */
+    sweepLiveness(): void;
     setServerIdentity(serverId: string, serverInstanceId?: string): void;
     /**
      * Check if a PID is still alive.
@@ -109,6 +138,57 @@ export declare class KernelService {
      * @param pid Optional kernel PID — used to distinguish "busy" from "dead" on timeout
      */
     private waitForReady;
+    private startIopubReader;
+    private stopIopubReader;
+    private closeIopubSubscribers;
+    private dispatchIopubMessage;
+    /**
+     * Subscribe to iopub messages parented by a specific msg_id. Must be called
+     * BEFORE sending the request so no reply can slip past the demux. Callers
+     * must unsubscribe in a finally block.
+     */
+    private subscribeIopubParent;
+    private unsubscribeIopubParent;
+    /** Subscribe to ALL iopub messages for a session (any parent). */
+    private subscribeIopubCatchAll;
+    private unsubscribeIopubCatchAll;
+    private startShellReader;
+    private stopShellReader;
+    private closeShellReplyWaiters;
+    /**
+     * Register a one-shot waiter for the shell reply parented by msgId. Must be
+     * called BEFORE sending the request so the reply cannot slip past the
+     * dispatch. Resolves 'closed' immediately if no reader loop is alive, or
+     * later when the reader stops (kernel stop/restart/cleanup).
+     */
+    private registerShellReplyWaiter;
+    private removeShellReplyWaiter;
+    /**
+     * Await a previously registered shell reply with a timeout. The waiter is
+     * always deregistered on the way out (timeout, reply, or error), so a late
+     * reply is dropped by the reader instead of leaking a waiter.
+     */
+    private waitForShellReply;
+    private handleKernelCommMessage;
+    private rememberOpenComm;
+    /**
+     * Open comms known for a session (for late-joining clients).
+     * Returns comm_id -> { targetName, openData } where openData is the last
+     * state-carrying comm_open payload observed for that comm.
+     */
+    getOpenComms(sessionId: string): Record<string, {
+        targetName: string;
+        openData: Record<string, unknown>;
+    }>;
+    /**
+     * Send a comm message (comm_open / comm_msg / comm_close) to the kernel on
+     * the shell channel. Comm messages produce NO shell reply, so the queued
+     * slot releases as soon as the send completes — we never block waiting for
+     * a reply that will not come.
+     *
+     * @param buffers Optional binary buffer frames, base64-encoded.
+     */
+    sendCommMessage(sessionId: string, msgType: 'comm_open' | 'comm_msg' | 'comm_close', content: Record<string, unknown>, buffers?: string[]): Promise<void>;
     /**
      * Monitor a busy reattached kernel on iopub. When its current execution
      * finishes (status: idle on iopub), verify shell connectivity and update
@@ -128,10 +208,16 @@ export declare class KernelService {
      * Get or create kernel for a file (one notebook = one kernel).
      * Returns whether a new session was created.
      */
+    /** In-flight create/attach per normalized file path (single-flight).
+     *  Without this, two near-simultaneous requests (UI re-render + agent op,
+     *  double-click) both miss the fileToSession check and spawn TWO kernel
+     *  processes — the second overwrites the mapping and the first leaks. */
+    private inflightKernelCreates;
     getOrCreateKernel(filePath: string, kernelName?: string): Promise<{
         sessionId: string;
         created: boolean;
     }>;
+    private getOrCreateKernelInternal;
     /**
      * Get existing kernel session ID for a notebook file (if any).
      * Returns null if no live session is associated with the file.
@@ -156,7 +242,11 @@ export declare class KernelService {
     executeCode(sessionId: string, code: string, onOutput: (output: KernelOutput, cellId?: string | null) => Promise<void>, onQueueInfo?: (info: ExecutionQueueInfo) => void, cellId?: string | null): Promise<ExecutionResult>;
     private enqueueExecution;
     /**
-     * Queue shell socket requests to prevent concurrent receive operations
+     * Serialize shell socket SENDS. Receives are owned by the unified shell
+     * reader, so tasks queued here must be send-only and release the slot as
+     * soon as the send completes (register any reply waiter BEFORE enqueueing,
+     * await the reply AFTER the slot is released). Holding the slot across a
+     * reply wait would let one slow request delay every later send.
      */
     private enqueueShellRequest;
     private reserveExecutionSlot;
@@ -174,7 +264,10 @@ export declare class KernelService {
         cursor_end: number;
     }>;
     /**
-     * Internal completion implementation (runs within shell queue)
+     * Internal completion implementation. The send is serialized through the
+     * shell queue; the reply is awaited via the unified shell reader, so a
+     * timeout here simply drops the waiter and can never block or swallow a
+     * later request's reply.
      */
     private completeInternal;
     /**
@@ -247,6 +340,15 @@ export declare class KernelService {
      */
     getSessionStatusFast(sessionId: string): SessionInfo | null;
     getSessionStatus(sessionId: string): Promise<SessionInfo | null>;
+    /**
+     * Activity snapshot for the idle auto-release monitor (client mode):
+     * whether any kernel is busy/starting, and the most recent kernel activity
+     * across sessions in ms since epoch (sessions track it in seconds).
+     */
+    getIdleSnapshot(): {
+        anyBusy: boolean;
+        lastActivityMs: number | null;
+    };
     /**
      * Get all sessions
      */
@@ -261,6 +363,15 @@ export declare class KernelService {
         status: string;
         lastHeartbeat: number;
     }[];
+    /**
+     * Auto-delete dead session rows whose kernel process is CONFIRMED gone
+     * (no PID, PID not running, or PID reused by another process). These are
+     * pure bookkeeping — nothing to kill, nothing to lose — so they need no
+     * user confirmation. Rows whose PID is still alive are kept for the
+     * explicit "Clean Up" flow (killing a process should stay a user action,
+     * and legacy rows without a start-time fingerprint can't be verified).
+     */
+    autoCleanupDeadSessions(): Promise<number>;
     /**
      * Cleanup dead sessions by deleting them from the database
      */