nebula-notebook 0.1.1 → 0.2.0

package/node-server/dist/notebook/headless-handler.d.ts

@@ -52,6 +52,8 @@ export declare class HeadlessOperationHandler {
      * Persist dirty notebooks to disk.
      */
     flush(notebookPath?: string): Promise<void>;
+    /** In-flight persist per notebook path (single-flight). */
+    private persisting;
     private asyncPersist;
     private schedulePersist;
     /**

package/node-server/dist/notebook/headless-handler.js

@@ -45,6 +45,7 @@ const cell_hash_1 = require("./cell-hash");
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const uuid_1 = require("uuid");
+const registry_1 = require("../fs/notebook-formats/registry");
 const cell_metadata_1 = require("./cell-metadata");
 const undoRedoManager_1 = require("./undoRedoManager");
 const kernelspec_1 = require("../kernel/kernelspec");
@@ -80,7 +81,7 @@ class HeadlessOperationHandler {
      */
     getCachedNotebook(notebookPath) {
         if (!this.cache.has(notebookPath)) {
-            const result = this.fsService.getNotebookCells(notebookPath);
+            const result = this.fsService.getNotebookCellsSync(notebookPath);
             this.cache.set(notebookPath, {
                 cells: result.cells || [],
                 metadata: result.metadata || {},
@@ -109,23 +110,41 @@ class HeadlessOperationHandler {
     async flush(notebookPath) {
         const paths = notebookPath ? [notebookPath] : Array.from(this.cache.keys());
         for (const p of paths) {
-            const notebook = this.cache.get(p);
-            if (notebook?.dirty) {
+            // A scheduled persist may have already cleared the dirty flag but not
+            // finished writing — flush must wait for it, or callers read a stale
+            // file. The persist loop keeps writing while dirty, so awaiting the
+            // in-flight run covers later mutations too.
+            const inFlight = this.persisting.get(p);
+            if (inFlight) {
+                await inFlight;
+            }
+            if (this.cache.get(p)?.dirty) {
                 await this.asyncPersist(p);
             }
         }
     }
-    async asyncPersist(notebookPath) {
-        const notebook = this.cache.get(notebookPath);
-        if (!notebook)
-            return;
-        // Keep writing while dirty
-        while (notebook.dirty) {
-            const cells = JSON.parse(JSON.stringify(notebook.cells));
-            notebook.dirty = false;
-            const history = this.undoRedoManager.getHistory(notebookPath, cells);
-            await this.fsService.saveNotebookBundle(notebookPath, cells, undefined, history);
-        }
+    /** In-flight persist per notebook path (single-flight). */
+    persisting = new Map();
+    asyncPersist(notebookPath) {
+        const existing = this.persisting.get(notebookPath);
+        if (existing)
+            return existing;
+        const run = (async () => {
+            const notebook = this.cache.get(notebookPath);
+            if (!notebook)
+                return;
+            // Keep writing while dirty
+            while (notebook.dirty) {
+                const cells = JSON.parse(JSON.stringify(notebook.cells));
+                notebook.dirty = false;
+                const history = this.undoRedoManager.getHistory(notebookPath, cells);
+                await this.fsService.saveNotebookBundle(notebookPath, cells, undefined, history);
+            }
+        })().finally(() => {
+            this.persisting.delete(notebookPath);
+        });
+        this.persisting.set(notebookPath, run);
+        return run;
     }
     schedulePersist(notebookPath) {
         // Schedule async persist
@@ -143,6 +162,10 @@ class HeadlessOperationHandler {
         else {
             this.cache.clear();
         }
+        // Undo/redo state is derived from the persisted history file; when the
+        // notebook may have changed underneath us (UI save, external edit
+        // reconciliation), rebuild it from disk on next access.
+        this.undoRedoManager.clearState(notebookPath);
     }
     /**
      * Check if notebook has unsaved changes.
@@ -155,21 +178,22 @@ class HeadlessOperationHandler {
      */
     checkAgentPermission(notebookPath, _operationType) {
         const status = this.fsService.getAgentPermissionStatus(notebookPath);
-        if (status.agent_created) {
+        // can_agent_modify already encodes the tri-state rule (agent-created notebooks
+        // are permitted unless explicitly revoked; user notebooks need permission +
+        // history), so an explicit user revoke wins even for agent-created notebooks.
+        if (status.can_agent_modify) {
             return null;
         }
-        if (status.agent_permitted) {
-            if (!status.has_history) {
-                return {
-                    success: false,
-                    error: `Agent cannot modify "${notebookPath}": notebook is user-permitted but history is not enabled. Open the notebook in the UI first to enable history tracking, or the agent can create a new notebook.`,
-                };
-            }
-            return null;
+        // User-permitted but history not yet enabled (soft, fixable) vs. not permitted.
+        if (status.agent_permitted && !status.has_history && !status.agent_created) {
+            return {
+                success: false,
+                error: `Agent cannot modify "${notebookPath}": notebook is user-permitted but history is not enabled. Open the notebook in the UI first to enable history tracking, or the agent can create a new notebook.`,
+            };
         }
         return {
             success: false,
-            error: `Agent cannot modify "${notebookPath}": notebook is not agent-permitted. Either open the notebook in Nebula UI and grant agent permission, or the agent can create a new notebook which will be automatically permitted.`,
+            error: `Agent cannot modify "${notebookPath}": notebook is not agent-permitted (agent access may have been revoked). Either open the notebook in Nebula UI and grant agent permission, or the agent can create a new notebook which will be automatically permitted.`,
         };
     }
     /**
@@ -781,6 +805,28 @@ class HeadlessOperationHandler {
                 error: `Notebook already exists: ${notebookPath}. Use overwrite=true to replace.`,
             };
         }
+        // Text notebook formats (.py percent / .qmd): create through the format
+        // adapter — agent flags live in the file's own metadata like .ipynb.
+        const formatAdapter = (0, registry_1.getFormatAdapter)(normalizedPath);
+        if (formatAdapter) {
+            const dir = path.dirname(normalizedPath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            const metadata = {
+                kernelspec: { name: kernelName, display_name: kernelDisplayName },
+                nebula: { agent_created: true, agent_permitted: true },
+            };
+            if (formatAdapter.name === 'qmd')
+                metadata.__qmd_language = 'python';
+            fs.writeFileSync(normalizedPath, formatAdapter.serialize([], metadata), 'utf-8');
+            this.invalidate(notebookPath);
+            return {
+                success: true,
+                path: notebookPath,
+                mtime: fs.statSync(normalizedPath).mtimeMs / 1000,
+            };
+        }
         const notebook = {
             nbformat: 4,
             nbformat_minor: 5,

package/node-server/dist/notebook/operation-router.js

@@ -48,6 +48,7 @@ const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const ws_1 = require("ws");
 const cell_hash_1 = require("./cell-hash");
+const registry_1 = require("../fs/notebook-formats/registry");
 const AGENT_LOCK_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
 const UI_STALE_TIMEOUT_MS = 45 * 1000; // 45 seconds
 function normalizeNotebookPath(notebookPath) {
@@ -320,9 +321,13 @@ class OperationRouter {
         const opType = operation.type;
         const agentId = operation.agentId;
         // For createNotebook, route to ANY connected UI (not path-specific)
-        // This allows the UI to open the new notebook in a new tab
+        // This allows the UI to open the new notebook in a new tab.
+        // EXCEPT text notebook formats (.py/.qmd): the UI's create handler only
+        // builds Jupyter JSON, so those are always created headless through the
+        // format adapters.
         const isCreateNotebook = opType === 'createNotebook';
-        const anyUI = isCreateNotebook ? this.getAnyUIConnection() : null;
+        const isTextFormatCreate = isCreateNotebook && (0, registry_1.isTextNotebookPath)(operation.notebookPath || '');
+        const anyUI = isCreateNotebook && !isTextFormatCreate ? this.getAnyUIConnection() : null;
         const hasUI = isCreateNotebook ? (anyUI !== null) : (this.getResponsiveUIConnection(normalizedPath) !== null);
         const backend = hasUI ? 'ui' : 'headless';
         // Clean up expired locks

package/node-server/dist/notebook/undoRedoManager.d.ts

@@ -182,7 +182,10 @@ export declare class HeadlessUndoRedoManager {
     /**
      * Clear state for a notebook (e.g., when closing).
      */
-    clearState(notebookPath: string): void;
+    /** Drop in-memory state so the next access rebuilds from the persisted
+     *  history file (the file/history may have changed underneath us: UI save,
+     *  external-edit reconciliation). Omit the path to clear all. */
+    clearState(notebookPath?: string): void;
     /**
      * Get updates since a timestamp (for agent awareness).
      * Returns human-readable summaries of operations made between agent sessions.

package/node-server/dist/notebook/undoRedoManager.js

@@ -142,7 +142,7 @@ class HeadlessUndoRedoManager {
             // Try to load existing history
             let loadedHistory = [];
             try {
-                loadedHistory = this.fsService.loadHistory(notebookPath);
+                loadedHistory = this.fsService.loadHistorySync(notebookPath);
             }
             catch (err) {
                 console.warn(`[UndoRedoManager] Failed to load history for ${notebookPath}:`, err);
@@ -357,8 +357,16 @@ class HeadlessUndoRedoManager {
     /**
      * Clear state for a notebook (e.g., when closing).
      */
+    /** Drop in-memory state so the next access rebuilds from the persisted
+     *  history file (the file/history may have changed underneath us: UI save,
+     *  external-edit reconciliation). Omit the path to clear all. */
     clearState(notebookPath) {
-        this.states.delete(notebookPath);
+        if (notebookPath) {
+            this.states.delete(notebookPath);
+        }
+        else {
+            this.states.clear();
+        }
     }
     /**
      * Get updates since a timestamp (for agent awareness).

package/node-server/dist/output/display-data.js

@@ -8,6 +8,8 @@ exports.buildDisplayOutput = buildDisplayOutput;
 exports.convertMimeBundleToJupyter = convertMimeBundleToJupyter;
 const PREFERRED_MIME_TYPES = [
     'application/vnd.nebula.web+json',
+    // Widget views must win over plotly/html when both are present
+    'application/vnd.jupyter.widget-view+json',
     'application/vnd.plotly.v1+json',
     'text/html',
     'image/png',

package/node-server/dist/routes/cluster.js

@@ -27,11 +27,11 @@ async function clusterRoutes(fastify) {
      * Body can include { resources } for initial resource info
      */
     fastify.post('/servers/register', async (request, reply) => {
-        const { host, port, name, secret, resources } = request.body;
+        const { host, port, name, secret, resources, allocationToken } = request.body;
         if (!host || !port) {
             return reply.code(400).send({ error: 'host and port are required' });
         }
-        const result = server_registry_1.serverRegistry.register({ host, port, name, secret, resources });
+        const result = server_registry_1.serverRegistry.register({ host, port, name, secret, resources, allocationToken });
         if (!result.success) {
             return reply.code(403).send({ error: result.error });
         }

package/node-server/dist/routes/compute.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Compute allocation API — submit and manage scheduler-backed compute.
+ *
+ * All routes live under /api/compute and are auth-protected like the rest of the
+ * API. They are no-ops (return `enabled: false`) when no scheduler is detected.
+ */
+import { FastifyInstance } from 'fastify';
+export default function computeRoutes(fastify: FastifyInstance): Promise<void>;

package/node-server/dist/routes/compute.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * Compute allocation API — submit and manage scheduler-backed compute.
+ *
+ * All routes live under /api/compute and are auth-protected like the rest of the
+ * API. They are no-ops (return `enabled: false`) when no scheduler is detected.
+ */
+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.default = computeRoutes;
+const os = __importStar(require("os"));
+const allocation_service_1 = require("../scheduler/allocation-service");
+function currentUser() {
+    return process.env.USER || process.env.LOGNAME || os.userInfo().username;
+}
+/** Build a JobSpec from request input, applying MVP defaults. */
+function parseSpec(x) {
+    const partition = String(x?.partition || '').trim();
+    const qos = x?.qos ? String(x.qos).trim() : undefined;
+    const account = x?.account ? String(x.account).trim() : undefined;
+    const cpus = Math.max(1, Math.floor(Number(x?.cpus) || 1));
+    const memGb = Math.max(1, Math.floor(Number(x?.memGb) || 4));
+    const gpusRaw = Math.floor(Number(x?.gpus) || 0);
+    const gpus = gpusRaw > 0 ? gpusRaw : undefined;
+    const gpuType = gpus && x?.gpuType ? String(x.gpuType).trim() || undefined : undefined;
+    const walltimeMinutes = Math.max(1, Math.floor(Number(x?.walltimeMinutes) || 120));
+    // Opt-in idle auto-release (minutes). Absent/invalid/<=0 = disabled.
+    const idleRaw = Math.floor(Number(x?.idleTimeoutMinutes) || 0);
+    const idleTimeoutMinutes = idleRaw > 0 ? idleRaw : undefined;
+    const jobName = (x?.jobName ? String(x.jobName) : `nebula-${partition || 'compute'}`)
+        .replace(/[^A-Za-z0-9._-]/g, '-')
+        .slice(0, 60) || 'nebula';
+    return { partition, qos, account, cpus, memGb, gpus, gpuType, walltimeMinutes, jobName, idleTimeoutMinutes };
+}
+async function computeRoutes(fastify) {
+    /** Whether scheduler-backed compute is available on this server. */
+    fastify.get('/compute/status', async (_req, reply) => {
+        return reply.send({
+            enabled: allocation_service_1.allocationService.isEnabled(),
+            scheduler: allocation_service_1.allocationService.getScheduler()?.name ?? null,
+        });
+    });
+    /** Allowed partitions/QoS for the current user + a live load snapshot. */
+    fastify.get('/compute/partitions', async (_req, reply) => {
+        const sched = allocation_service_1.allocationService.getScheduler();
+        if (!sched)
+            return reply.send({ enabled: false, associations: null, load: null });
+        const [associations, load] = await Promise.all([
+            sched.associations(currentUser()).catch(() => null),
+            sched.load().catch(() => null),
+        ]);
+        return reply.send({ enabled: true, associations, load });
+    });
+    /** QoS names a partition will accept (null = any). Drives the modal's QoS filter. */
+    fastify.get('/compute/partition-qos', async (req, reply) => {
+        const sched = allocation_service_1.allocationService.getScheduler();
+        if (!sched)
+            return reply.send({ allowed: null });
+        const partition = String(req.query?.partition || '').trim();
+        if (!partition)
+            return reply.send({ allowed: null });
+        const allowed = await sched.allowedQos(partition).catch(() => null);
+        return reply.send({ allowed });
+    });
+    /** Dry-run estimated start time for a prospective allocation. */
+    fastify.get('/compute/estimate', async (req, reply) => {
+        const sched = allocation_service_1.allocationService.getScheduler();
+        if (!sched)
+            return reply.code(400).send({ error: 'scheduler not available' });
+        const spec = parseSpec(req.query);
+        if (!spec.partition)
+            return reply.code(400).send({ error: 'partition is required' });
+        const estimate = await sched.estimateStart(spec);
+        return reply.send(estimate);
+    });
+    /** List current allocations (pending / running / active / ended). */
+    fastify.get('/compute/allocations', async (_req, reply) => {
+        return reply.send({ allocations: allocation_service_1.allocationService.list() });
+    });
+    /** Submit a new compute allocation. */
+    fastify.post('/compute/allocations', async (req, reply) => {
+        if (!allocation_service_1.allocationService.isEnabled()) {
+            return reply.code(400).send({ error: 'scheduler not available' });
+        }
+        const spec = parseSpec(req.body);
+        if (!spec.partition)
+            return reply.code(400).send({ error: 'partition is required' });
+        try {
+            const alloc = await allocation_service_1.allocationService.create(spec);
+            return reply.send(alloc);
+        }
+        catch (e) {
+            return reply.code(500).send({ error: e?.message || 'submit failed' });
+        }
+    });
+    /** Cancel an allocation (scancel + evict its server). */
+    fastify.delete('/compute/allocations/:id', async (req, reply) => {
+        const { id } = req.params;
+        const ok = await allocation_service_1.allocationService.cancel(id);
+        if (!ok)
+            return reply.code(404).send({ error: 'allocation not found' });
+        return reply.send({ cancelled: true });
+    });
+}

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

@@ -121,7 +121,7 @@ async function fsRoutes(fastify) {
             if (!filePath) {
                 return reply.code(400).send({ detail: 'path query parameter is required' });
             }
-            const result = fs_service_1.fsService.getFileMtime(filePath);
+            const result = await fs_service_1.fsService.getFileMtime(filePath);
             return reply.send(result);
         }
         catch (err) {
@@ -143,7 +143,7 @@ async function fsRoutes(fastify) {
             if (!filePath) {
                 return reply.code(400).send({ detail: 'path query parameter is required' });
             }
-            const result = fs_service_1.fsService.readFile(filePath);
+            const result = await fs_service_1.fsService.readFile(filePath);
             return reply.send(result);
         }
         catch (err) {

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

@@ -49,6 +49,7 @@ const fs_service_1 = require("../fs/fs-service");
 const operation_router_1 = require("../notebook/operation-router");
 const kernel_proxy_1 = require("../cluster/kernel-proxy");
 const server_registry_1 = require("../cluster/server-registry");
+const allocation_service_1 = require("../scheduler/allocation-service");
 // Track all WebSocket connections per kernel session for broadcasting
 const sessionWebSockets = new Map();
 // Only send streaming outputs to sockets after they've performed an initial output sync.
@@ -58,6 +59,51 @@ const outputSubscribedSockets = new WeakSet();
 // Shared kernel service instance - exported for use by headless handler
 const kernelService = new kernel_service_1.KernelService();
 exports.kernelService = kernelService;
+// When a kernel dies (crash, OOM, reattached PID gone), push the status to
+// every client immediately — otherwise the UI shows 'busy' until the next
+// poll or failed execute.
+kernelService.onSessionDead((sessionId) => {
+    const sockets = sessionWebSockets.get(sessionId);
+    if (!sockets || sockets.size === 0)
+        return;
+    const msg = JSON.stringify({ type: 'status', status: 'dead' });
+    for (const socket of sockets) {
+        try {
+            if (socket.readyState === ws_1.WebSocket.OPEN)
+                socket.send(msg);
+        }
+        catch {
+            // Socket already closing — the reconnect loop will handle it
+        }
+    }
+});
+// Broadcast kernel-originated comm messages (ipywidgets state sync, etc.) to
+// every client attached to the session. This includes idle-time traffic from
+// widget observers — comm messages are demuxed regardless of parent request.
+kernelService.onComm((sessionId, comm) => {
+    const sockets = sessionWebSockets.get(sessionId);
+    if (!sockets || sockets.size === 0)
+        return;
+    const msg = JSON.stringify({
+        type: 'comm',
+        comm: {
+            msg_type: comm.msgType,
+            comm_id: comm.commId,
+            ...(comm.targetName !== undefined && { target_name: comm.targetName }),
+            data: comm.data,
+            ...(comm.buffers && { buffers: comm.buffers }),
+        },
+    });
+    for (const socket of sockets) {
+        try {
+            if (socket.readyState === ws_1.WebSocket.OPEN)
+                socket.send(msg);
+        }
+        catch {
+            // Socket already closing — the reconnect loop will handle it
+        }
+    }
+});
 // Initialize kernel service on module load
 kernelService.initialize().catch(err => {
     console.error('Failed to initialize kernel service:', err);
@@ -190,6 +236,41 @@ function setupKernelWebSocket(wss) {
                     const result = await kernelService.complete(sessionId, code, cursorPos);
                     ws.send(JSON.stringify({ type: 'complete_reply', result }));
                 }
+                else if (message.type === 'comm') {
+                    // Client -> kernel comm message (ipywidgets interaction):
+                    // { type: 'comm', comm: { msg_type, comm_id, target_name?, data, buffers? } }
+                    const comm = (message.comm && typeof message.comm === 'object') ? message.comm : {};
+                    const msgType = comm.msg_type;
+                    if (msgType !== 'comm_open' && msgType !== 'comm_msg' && msgType !== 'comm_close') {
+                        ws.send(JSON.stringify({ type: 'error', error: `Invalid comm msg_type: ${String(msgType)}` }));
+                        return;
+                    }
+                    if (typeof comm.comm_id !== 'string' || comm.comm_id.length === 0) {
+                        ws.send(JSON.stringify({ type: 'error', error: 'comm.comm_id is required' }));
+                        return;
+                    }
+                    const content = {
+                        comm_id: comm.comm_id,
+                        data: (comm.data && typeof comm.data === 'object') ? comm.data : {},
+                    };
+                    if (msgType === 'comm_open') {
+                        content.target_name = typeof comm.target_name === 'string' ? comm.target_name : '';
+                    }
+                    const buffers = Array.isArray(comm.buffers)
+                        ? comm.buffers.filter((b) => typeof b === 'string')
+                        : undefined;
+                    await kernelService.sendCommMessage(sessionId, msgType, content, buffers);
+                }
+                else if (message.type === 'comm_info') {
+                    // Late-joiner support: list open comms known for this session.
+                    // Reply only to the requesting socket.
+                    const openComms = kernelService.getOpenComms(sessionId);
+                    const comms = {};
+                    for (const [commId, info] of Object.entries(openComms)) {
+                        comms[commId] = { target_name: info.targetName };
+                    }
+                    ws.send(JSON.stringify({ type: 'comm_info_reply', comms }));
+                }
             }
             catch (err) {
                 const errMessage = err instanceof Error ? err.message : 'Unknown error';
@@ -340,6 +421,10 @@ async function kernelRoutes(fastify) {
                 return reply.code(500).send({ detail: message });
             }
         }
+        // Confirmed-dead rows (process gone) are auto-removed without user
+        // confirmation — only ambiguous leftovers (PID still alive) are reported
+        // for the explicit Clean Up flow.
+        await kernelService.autoCleanupDeadSessions().catch(() => { });
         const deadSessions = kernelService.getDeadSessions();
         const sessions = deadSessions.map(s => ({
             session_id: s.sessionId,
@@ -612,10 +697,35 @@ async function kernelRoutes(fastify) {
         if ((0, kernel_proxy_1.isProxiedSession)(sessionId)) {
             try {
                 const remoteStatus = await (0, kernel_proxy_1.getRemoteKernelStatus)(sessionId);
-                return reply.send(remoteStatus);
+                // Return the COMPOSITE session id (serverId::remoteId) — the remote
+                // server reports its own local id, and leaking that to clients makes
+                // them reference a session the main server doesn't recognize.
+                return reply.send({ ...remoteStatus, id: sessionId });
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : 'Unknown error';
+                // "Server is offline / not found" from the registry is a HEARTBEAT
+                // signal, not ground truth: a compute node saturated by a heavy
+                // execution can miss heartbeats for minutes while its SLURM job (and
+                // kernel) are perfectly alive — then recover. Treating that as
+                // terminal permanently killed live kernels (red kernel, reconnect
+                // loop stopped, only a page refresh recovered).
+                //
+                // The scheduler is the authority: return 410 Gone (terminal) only
+                // when the session's allocation is confirmed ended/failed/cancelled
+                // by squeue polling. Everything else is 503 (transient) so the
+                // client's reconnect loop keeps trying and revives the kernel when
+                // the node recovers.
+                if (/server (is offline|not found)/i.test(message)) {
+                    const { serverId } = (0, kernel_proxy_1.parseSessionId)(sessionId);
+                    const allocation = serverId
+                        ? allocation_service_1.allocationService.list().find(a => a.serverId === serverId)
+                        : undefined;
+                    if (allocation && ['ended', 'failed', 'cancelled'].includes(allocation.state)) {
+                        return reply.code(410).send({ detail: `Allocation ${allocation.state} — kernel stopped`, reason: 'server_gone' });
+                    }
+                    return reply.code(503).send({ detail: `${message} (may be transient — compute node busy or re-registering)`, reason: 'server_unreachable' });
+                }
                 return reply.code(500).send({ detail: message });
             }
         }

package/node-server/dist/routes/notebook.js

@@ -109,7 +109,7 @@ async function notebookRoutes(fastify) {
             if (!notebookPath) {
                 return reply.code(400).send({ detail: 'notebook_path query parameter is required' });
             }
-            const history = fs_service_1.fsService.loadHistory(notebookPath);
+            const history = await fs_service_1.fsService.loadHistory(notebookPath);
             return reply.send({ notebook_path: notebookPath, history });
         }
         catch (err) {
@@ -184,6 +184,7 @@ async function notebookRoutes(fastify) {
             return reply.send({
                 status: 'ok',
                 notebook_path,
+                mtime: result.mtime,
                 ...(result.status || fs_service_1.fsService.getAgentPermissionStatus(notebook_path)),
             });
         }
@@ -338,4 +339,31 @@ async function notebookRoutes(fastify) {
             return reply.code(500).send({ detail: message });
         }
     });
+    /**
+     * Persist live ipywidgets state into notebook metadata.widgets
+     * (application/vnd.jupyter.widget-state+json), making saved notebooks
+     * render static widgets in Jupyter/nbviewer.
+     */
+    fastify.post('/notebook/widget-state', async (request, reply) => {
+        try {
+            const { path: filePath, widget_state } = request.body;
+            if (!filePath) {
+                return reply.code(400).send({ detail: 'path is required' });
+            }
+            if (!widget_state || typeof widget_state !== 'object') {
+                return reply.code(400).send({ detail: 'widget_state must be an object' });
+            }
+            const updateResult = await fs_service_1.fsService.updateNotebookMetadata(filePath, {
+                widgets: { 'application/vnd.jupyter.widget-state+json': widget_state },
+            });
+            if (!updateResult.success) {
+                return reply.code(500).send({ detail: updateResult.error || 'Failed to update notebook metadata' });
+            }
+            return reply.send({ status: 'ok', notebook_path: filePath, mtime: updateResult.mtime });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            return reply.code(500).send({ detail: message });
+        }
+    });
 }

package/node-server/dist/scheduler/allocation-service.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Allocation service — owns the lifecycle a compute allocation has *before* and
+ * *around* the cluster registry: submit a job, follow it through the queue, and
+ * correlate the client-server's registration (by one-time token) back to the
+ * allocation. Once correlated, the allocation is a normal registered server and
+ * kernels run on it through the existing cluster path.
+ *
+ * Phase-1 MVP: in-memory allocations, direct transport (no SSH tunnel — not
+ * needed where compute↔login is directly reachable).
+ */
+import type { Scheduler, JobSpec } from './types';
+import { type LaunchContext } from './job-template';
+export type AllocationState = 'pending' | 'running' | 'active' | 'ended' | 'failed' | 'cancelled';
+export interface Allocation {
+    id: string;
+    jobId?: string;
+    token: string;
+    spec: JobSpec;
+    state: AllocationState;
+    serverId?: string;
+    nodes?: string[];
+    reason?: string;
+    createdAt: number;
+    walltimeEndsAt?: number;
+}
+declare class AllocationService {
+    private scheduler;
+    private ctx;
+    private allocations;
+    private pollTimer;
+    private enabled;
+    init(scheduler: Scheduler, ctx: LaunchContext): void;
+    isEnabled(): boolean;
+    getScheduler(): Scheduler | null;
+    list(): Allocation[];
+    get(id: string): Allocation | undefined;
+    create(spec: JobSpec): Promise<Allocation>;
+    cancel(id: string): Promise<boolean>;
+    private poll;
+    shutdown(): void;
+}
+export declare const allocationService: AllocationService;
+export {};