nebula-notebook 0.1.1 → 0.2.1

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/fs/types.d.ts

@@ -85,7 +85,16 @@ export interface NotebookCellsResponse {
 export interface SaveNotebookResult {
     success: boolean;
     mtime: number;
+    /** Client sent outputs-unchanged sentinels the server couldn't resolve — it must retry with a full payload. */
+    needsFull?: boolean;
 }
+/**
+ * Sentinel the client puts in place of a code cell's outputs when they are
+ * unchanged since its last successful save. The server re-uses the outputs
+ * already in the file (matched by nebula_id), so autosaves don't re-upload
+ * megabytes of unchanged base64 images over slow uplinks.
+ */
+export declare const OUTPUTS_UNCHANGED_SENTINEL = "__nebula-outputs-unchanged-v1__";
 export interface JupyterCellMetadata {
     nebula_id?: string;
     scrolled?: boolean;

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

@@ -3,3 +3,11 @@
  * Filesystem Service Types
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.OUTPUTS_UNCHANGED_SENTINEL = void 0;
+/**
+ * Sentinel the client puts in place of a code cell's outputs when they are
+ * unchanged since its last successful save. The server re-uses the outputs
+ * already in the file (matched by nebula_id), so autosaves don't re-upload
+ * megabytes of unchanged base64 images over slow uplinks.
+ */
+exports.OUTPUTS_UNCHANGED_SENTINEL = '__nebula-outputs-unchanged-v1__';

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

@@ -59,6 +59,7 @@ const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const crypto = __importStar(require("crypto"));
 const crypto_1 = require("crypto");
+const zlib = __importStar(require("zlib"));
 // Import routes
 const kernel_1 = __importStar(require("./routes/kernel"));
 const fs_1 = __importDefault(require("./routes/fs"));
@@ -67,17 +68,28 @@ 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"));
+const autocomplete_1 = __importDefault(require("./routes/autocomplete"));
 // 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");
+const environment_1 = require("./environment");
 // 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 ||
@@ -231,6 +243,22 @@ async function createApp() {
         });
         console.log('[Server] HTTP/1.1 mode (no TLS)');
     }
+    // Gzipped JSON uploads (Content-Type: application/gzip). The client
+    // compresses large bodies (notebook autosaves) so slow-upload tunnels
+    // aren't saturated for seconds per save; bodyLimit applies to the
+    // COMPRESSED size, which is the wire cost we care about.
+    fastify.addContentTypeParser('application/gzip', { parseAs: 'buffer' }, (_req, body, done) => {
+        zlib.gunzip(body, (err, buf) => {
+            if (err)
+                return done(err);
+            try {
+                done(null, JSON.parse(buf.toString('utf-8')));
+            }
+            catch (e) {
+                done(e);
+            }
+        });
+    });
     // Request timing hook
     fastify.addHook('onResponse', (request, reply, done) => {
         const duration = reply.elapsedTime;
@@ -239,9 +267,46 @@ async function createApp() {
         }
         done();
     });
-    // Register CORS
+    // Event-loop stall detector: a 100ms heartbeat that logs when it fires late.
+    // Any [perf] line here means the WHOLE server (terminal WS forwarding
+    // included) was frozen that long by synchronous work — the prime suspect
+    // whenever "everything hangs for a moment". Correlate timestamps with
+    // [Slow Request] lines to find the culprit route.
+    {
+        let last = process.hrtime.bigint();
+        const timer = setInterval(() => {
+            const now = process.hrtime.bigint();
+            const stallMs = Number(now - last) / 1e6 - 100;
+            last = now;
+            if (stallMs > 150) {
+                console.warn(`[perf] event-loop stall ~${Math.round(stallMs)}ms at ${new Date().toISOString()}`);
+            }
+        }, 100);
+        timer.unref(); // never keep the process alive for this
+    }
+    // Register CORS. Allowlist instead of '*': cross-origin BROWSER pages lose
+    // API access (drive-by protection), while nothing we ship is affected —
+    // the terminal/agent/MCP are non-browser clients (no Origin header, CORS
+    // doesn't apply), the served UI is same-origin, ssh port-forwards land on
+    // localhost, and vite dev is a localhost origin. Extra origins for exotic
+    // serving setups: NEBULA_ALLOWED_ORIGINS=https://a.com,https://b.com
+    const extraOrigins = (process.env.NEBULA_ALLOWED_ORIGINS || '')
+        .split(',').map((s) => s.trim()).filter(Boolean);
     await fastify.register(cors_1.default, {
-        origin: '*',
+        origin: (origin, cb) => {
+            if (!origin)
+                return cb(null, true); // non-browser client or same-origin
+            if (extraOrigins.includes(origin))
+                return cb(null, true);
+            try {
+                const { hostname } = new URL(origin);
+                if (hostname === 'localhost' || hostname === '::1' || hostname === '127.0.0.1' || hostname.startsWith('127.')) {
+                    return cb(null, true);
+                }
+            }
+            catch { /* malformed Origin — treat as disallowed */ }
+            cb(null, false); // no CORS headers -> browser blocks the cross-origin page
+        },
         credentials: true,
         methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
         allowedHeaders: ['Content-Type', 'Authorization', 'X-API-Key', 'X-API-Provider'],
@@ -271,11 +336,14 @@ 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,
             cwd: rootDir,
+            update,
+            environment: (0, environment_1.getEnvironment)(),
         });
     });
     fastify.get('/api/ready', async (_request, reply) => {
@@ -307,10 +375,12 @@ async function createApp() {
     });
     // API routes (protected)
     await fastify.register(kernel_1.default, { prefix: '/api' });
+    await fastify.register(autocomplete_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);
@@ -446,8 +516,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)();
@@ -468,6 +539,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();
@@ -480,6 +580,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/jzhoulab/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 () => {
@@ -507,10 +642,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);
@@ -541,12 +677,66 @@ 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);
+        void client_registration_1.clientRegistration.initFromEnv(boundPort); // async: resolves the controller-routable IP first
+        // 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
+// A single stray rejection must not take down every kernel, terminal, and
+// SLURM allocation this process is holding. Log loudly and keep serving —
+// for a state-holding server, dying is strictly worse than degrading.
+process.on('unhandledRejection', (reason) => {
+    console.error('[fatal-ish] Unhandled promise rejection (continuing):', reason);
+});
+process.on('uncaughtException', (err) => {
+    console.error('[fatal-ish] Uncaught exception (continuing):', err);
+});
 main().catch((err) => {
     console.error('[Server] Fatal error:', err);
     process.exit(1);