nebula-notebook 0.2.0 → 0.2.2

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

@@ -44,6 +44,13 @@ export declare class FilesystemService {
     /**
      * Async variant of atomicWriteFileSync (write temp, fsync, rename, fsync dir).
      * Used on hot notebook-save paths so large writes never block the event loop.
+     *
+     * `durable: false` skips both fsyncs while keeping the tmp+rename atomicity.
+     * Use it for auxiliary files (history/session/journal/lastsave): on network
+     * filesystems (GPFS) each fsync can take seconds, and a save doing ~10 of
+     * them was observed at 20-27s. A crash can lose the last few seconds of an
+     * auxiliary file, but never corrupt it — the rename is still atomic. The
+     * notebook file itself stays fully durable.
      */
     private atomicWriteFile;
     private writeJsonAtomic;
@@ -59,6 +66,9 @@ export declare class FilesystemService {
      * Get file info for a path
      */
     private getFileInfo;
+    /** Async, non-blocking variant of getFileInfo (one `fsp.stat`). Used by
+     *  listDirectory so a folder's entries stat in parallel off the event loop. */
+    private getFileInfoAsync;
     /**
      * Convert FileInfo to FileInfoResponse for API
      */
@@ -74,7 +84,7 @@ export declare class FilesystemService {
     /**
      * List contents of a directory
      */
-    listDirectory(dirPath: string): DirectoryListing;
+    listDirectory(dirPath: string): Promise<DirectoryListing>;
     /**
      * Read a file's contents
      */
@@ -198,6 +208,12 @@ export declare class FilesystemService {
      * Get notebook-level metadata
      */
     getNotebookMetadata(notebookPath: string): Record<string, unknown>;
+    /**
+     * Async variant of getNotebookMetadata. Nebula-written notebooks put
+     * `metadata` first, so the head-bytes scan avoids reading and parsing the
+     * whole file; externally written notebooks fall back to a full async read.
+     */
+    getNotebookMetadataAsync(notebookPath: string): Promise<Record<string, unknown>>;
     /**
      * Update notebook-level metadata without modifying cells
      */
@@ -222,6 +238,14 @@ export declare class FilesystemService {
      * Derive agent permission status from persisted notebook metadata.
      */
     getAgentPermissionStatus(notebookPath: string): AgentPermissionSnapshot;
+    /**
+     * Async variant of getAgentPermissionStatus for hot request paths (it runs
+     * on every agent write operation). Reads metadata via the head-bytes fast
+     * path and checks history without parsing it, so the per-operation gate
+     * never blocks the event loop on a slow network filesystem.
+     */
+    getAgentPermissionStatusAsync(notebookPath: string): Promise<AgentPermissionSnapshot>;
+    private deriveAgentPermission;
     /**
      * Check if a notebook is permitted for agent modifications
      */
@@ -230,6 +254,12 @@ export declare class FilesystemService {
      * Check if a notebook has history tracking enabled
      */
     hasHistory(notebookPath: string): boolean;
+    /**
+     * Async variant of hasHistory that only parses small files: history journals
+     * grow to hundreds of KB, and this check runs on every agent operation — a
+     * file that large necessarily has entries, so its size alone answers.
+     */
+    hasHistoryAsync(notebookPath: string): Promise<boolean>;
     /**
      * Save operation history for a notebook
      */

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

@@ -45,6 +45,7 @@ const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const crypto = __importStar(require("crypto"));
 const util_1 = require("util");
+const types_1 = require("./types");
 const default_kernel_1 = require("../kernel/default-kernel");
 const registry_1 = require("./notebook-formats/registry");
 const percent_1 = require("./notebook-formats/percent");
@@ -351,8 +352,16 @@ class FilesystemService {
     /**
      * Async variant of atomicWriteFileSync (write temp, fsync, rename, fsync dir).
      * Used on hot notebook-save paths so large writes never block the event loop.
+     *
+     * `durable: false` skips both fsyncs while keeping the tmp+rename atomicity.
+     * Use it for auxiliary files (history/session/journal/lastsave): on network
+     * filesystems (GPFS) each fsync can take seconds, and a save doing ~10 of
+     * them was observed at 20-27s. A crash can lose the last few seconds of an
+     * auxiliary file, but never corrupt it — the rename is still atomic. The
+     * notebook file itself stays fully durable.
      */
-    async atomicWriteFile(targetPath, data) {
+    async atomicWriteFile(targetPath, data, opts = {}) {
+        const durable = opts.durable !== false;
         const dir = path.dirname(targetPath);
         await fs_1.promises.mkdir(dir, { recursive: true });
         const tmpName = `.${path.basename(targetPath)}.${process.pid}.${Date.now()}.${crypto.randomUUID()}.tmp`;
@@ -360,12 +369,15 @@ class FilesystemService {
         const handle = await fs_1.promises.open(tmpPath, 'w', 0o600);
         try {
             await handle.writeFile(data, 'utf-8');
-            await handle.sync();
+            if (durable)
+                await handle.sync();
         }
         finally {
             await handle.close();
         }
         await fs_1.promises.rename(tmpPath, targetPath);
+        if (!durable)
+            return;
         // Best-effort directory fsync
         try {
             const dirHandle = await fs_1.promises.open(dir, 'r');
@@ -380,8 +392,8 @@ class FilesystemService {
             // Ignore fsync errors on directory handles
         }
     }
-    async writeJsonAtomic(targetPath, payload) {
-        await this.atomicWriteFile(targetPath, JSON.stringify(payload, null, 2));
+    async writeJsonAtomic(targetPath, payload, opts = {}) {
+        await this.atomicWriteFile(targetPath, JSON.stringify(payload, null, 2), opts);
     }
     /**
      * Format file size for display
@@ -438,6 +450,21 @@ class FilesystemService {
             extension: isDir ? '' : path.extname(name),
         };
     }
+    /** Async, non-blocking variant of getFileInfo (one `fsp.stat`). Used by
+     *  listDirectory so a folder's entries stat in parallel off the event loop. */
+    async getFileInfoAsync(filePath) {
+        const stat = await fs_1.promises.stat(filePath);
+        const name = path.basename(filePath);
+        const isDir = stat.isDirectory();
+        return {
+            name,
+            path: filePath,
+            isDirectory: isDir,
+            size: isDir ? 0 : stat.size,
+            modified: stat.mtimeMs / 1000,
+            extension: isDir ? '' : path.extname(name),
+        };
+    }
     /**
      * Convert FileInfo to FileInfoResponse for API
      */
@@ -492,32 +519,35 @@ class FilesystemService {
     /**
      * List contents of a directory
      */
-    listDirectory(dirPath) {
+    async listDirectory(dirPath) {
         const normalizedPath = this.normalizePath(dirPath);
-        if (!fs.existsSync(normalizedPath)) {
+        let stat;
+        try {
+            stat = await fs_1.promises.stat(normalizedPath);
+        }
+        catch {
             throw new Error(`Path not found: ${normalizedPath}`);
         }
-        const stat = fs.statSync(normalizedPath);
         if (!stat.isDirectory()) {
             throw new Error(`Not a directory: ${normalizedPath}`);
         }
-        const items = [];
-        const entries = fs.readdirSync(normalizedPath);
-        for (const name of entries) {
-            // Skip hidden files
-            if (name.startsWith('.')) {
-                continue;
-            }
-            const fullPath = path.join(normalizedPath, name);
+        const entries = await fs_1.promises.readdir(normalizedPath);
+        // Stat every visible entry in PARALLEL rather than one blocking statSync at a
+        // time. On a network filesystem a serial loop stalls the single event
+        // loop for N × stat-latency, delaying every other in-flight request (kernel
+        // starts, terminal creation, saves) — the source of the "everything hangs
+        // while a folder lists" latency.
+        const settled = await Promise.all(entries
+            .filter((name) => !name.startsWith('.')) // skip hidden files
+            .map(async (name) => {
             try {
-                const info = this.getFileInfo(fullPath);
-                items.push(this.toFileInfoResponse(info));
+                return this.toFileInfoResponse(await this.getFileInfoAsync(path.join(normalizedPath, name)));
             }
             catch {
-                // Skip files we can't access
-                continue;
+                return null; // skip entries we can't access
             }
-        }
+        }));
+        const items = settled.filter((x) => x !== null);
         // Sort: directories first, then by name
         items.sort((a, b) => {
             if (a.isDirectory !== b.isDirectory) {
@@ -672,7 +702,7 @@ class FilesystemService {
             const canonical = adapter.parse(serializedText).cells;
             await this.writeJsonAtomic(this.getLastSavePath(notebookPath), {
                 cells: canonical.map((c) => ({ id: c.id, type: c.type, content: c.content })),
-            });
+            }, { durable: false });
         }
         catch (e) {
             console.warn('[FilesystemService] Failed to write lastsave record:', e);
@@ -1217,6 +1247,29 @@ class FilesystemService {
         }
         kernelName = kernelName || 'python3';
         const displayName = kernelName === 'python3' ? 'Python 3' : kernelName.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+        // Resolve outputs-unchanged sentinels from the file on disk: the client
+        // elides unchanged outputs (often MBs of base64 images) from autosaves so
+        // slow uplinks aren't saturated. If anything can't be resolved, ask the
+        // client to retry with a full payload rather than guessing.
+        const sentinelCells = cells.filter((c) => c.outputs === types_1.OUTPUTS_UNCHANGED_SENTINEL);
+        const priorOutputs = new Map();
+        if (sentinelCells.length > 0) {
+            try {
+                const existing = JSON.parse(await fs_1.promises.readFile(normalizedPath, 'utf-8'));
+                for (const jc of existing.cells || []) {
+                    const nid = jc.metadata?.nebula_id;
+                    if (nid)
+                        priorOutputs.set(String(nid), { outputs: jc.outputs || [], execution_count: jc.execution_count ?? null });
+                }
+            }
+            catch {
+                return { success: false, mtime: 0, needsFull: true };
+            }
+            for (const c of sentinelCells) {
+                if (!priorOutputs.has(c.id))
+                    return { success: false, mtime: 0, needsFull: true };
+            }
+        }
         const nbCells = cells.map((cell) => {
             const preservedMetadata = cell._metadata || {};
             const cellMetadata = {
@@ -1235,8 +1288,15 @@ class FilesystemService {
                 metadata: cellMetadata,
             };
             if (cell.type === 'code') {
-                nbCell.outputs = this.convertOutputsToJupyter(cell.outputs);
-                nbCell.execution_count = cell.executionCount;
+                if (cell.outputs === types_1.OUTPUTS_UNCHANGED_SENTINEL) {
+                    const prior = priorOutputs.get(cell.id);
+                    nbCell.outputs = prior.outputs;
+                    nbCell.execution_count = cell.executionCount ?? prior.execution_count;
+                }
+                else {
+                    nbCell.outputs = this.convertOutputsToJupyter(cell.outputs);
+                    nbCell.execution_count = cell.executionCount;
+                }
             }
             return nbCell;
         });
@@ -1307,12 +1367,14 @@ class FilesystemService {
             // Ensure .nebula directory exists for journal/history/session
             const { nebulaDir } = this.getNebulaPaths(notebookPath);
             await fs_1.promises.mkdir(nebulaDir, { recursive: true });
-            await this.writeJsonAtomic(journalPath, journal);
+            // Auxiliary files: atomic but non-durable (no fsync) — see atomicWriteFile.
+            // Only the notebook itself (inside saveNotebookCells) pays for fsync.
+            await this.writeJsonAtomic(journalPath, journal, { durable: false });
             if (historyPath) {
-                await this.writeJsonAtomic(historyPath, history || []);
+                await this.writeJsonAtomic(historyPath, history || [], { durable: false });
             }
             if (sessionPath) {
-                await this.writeJsonAtomic(sessionPath, session || {});
+                await this.writeJsonAtomic(sessionPath, session || {}, { durable: false });
             }
             const result = await this.saveNotebookCells(notebookPath, cells, kernelName, notebookMetadata);
             const committedJournal = {
@@ -1320,7 +1382,7 @@ class FilesystemService {
                 status: 'commit',
                 committedAt: Date.now(),
             };
-            await this.writeJsonAtomic(journalPath, committedJournal);
+            await this.writeJsonAtomic(journalPath, committedJournal, { durable: false });
             try {
                 await fs_1.promises.unlink(journalPath);
             }
@@ -1335,6 +1397,9 @@ class FilesystemService {
      * Outputs and execution counts are never serialized — by format design.
      */
     async saveTextNotebookCells(adapter, normalizedPath, cells, kernelName, notebookMetadata) {
+        // Text formats never serialize outputs; neutralize any outputs-unchanged
+        // sentinels so nothing downstream sees the marker string.
+        cells = cells.map((c) => c.outputs === types_1.OUTPUTS_UNCHANGED_SENTINEL ? { ...c, outputs: [] } : c);
         let existingMetadata = {};
         try {
             existingMetadata = adapter.parse(await fs_1.promises.readFile(normalizedPath, 'utf-8')).metadata;
@@ -1384,6 +1449,39 @@ class FilesystemService {
             return {};
         }
     }
+    /**
+     * Async variant of getNotebookMetadata. Nebula-written notebooks put
+     * `metadata` first, so the head-bytes scan avoids reading and parsing the
+     * whole file; externally written notebooks fall back to a full async read.
+     */
+    async getNotebookMetadataAsync(notebookPath) {
+        const normalizedPath = this.normalizePath(notebookPath);
+        const formatAdapter = (0, registry_1.getFormatAdapter)(normalizedPath);
+        try {
+            if (formatAdapter) {
+                return formatAdapter.parse(await fs_1.promises.readFile(normalizedPath, 'utf-8')).metadata;
+            }
+            const handle = await fs_1.promises.open(normalizedPath, 'r');
+            let head;
+            try {
+                const buf = Buffer.alloc(NOTEBOOK_METADATA_FAST_PATH_BYTES);
+                const { bytesRead } = await handle.read(buf, 0, NOTEBOOK_METADATA_FAST_PATH_BYTES, 0);
+                head = buf.toString('utf-8', 0, bytesRead);
+            }
+            finally {
+                await handle.close();
+            }
+            const extracted = extractTopLevelObjectField(head, 'metadata');
+            if (extracted) {
+                return extracted;
+            }
+            const notebook = JSON.parse(await fs_1.promises.readFile(normalizedPath, 'utf-8'));
+            return notebook.metadata || {};
+        }
+        catch {
+            return {};
+        }
+    }
     /**
      * Update notebook-level metadata without modifying cells
      */
@@ -1564,8 +1662,24 @@ class FilesystemService {
      */
     getAgentPermissionStatus(notebookPath) {
         const metadata = this.getNotebookMetadata(notebookPath);
-        const nebula = (metadata.nebula || {});
         const hasHistory = this.hasHistory(notebookPath);
+        return this.deriveAgentPermission(metadata, hasHistory);
+    }
+    /**
+     * Async variant of getAgentPermissionStatus for hot request paths (it runs
+     * on every agent write operation). Reads metadata via the head-bytes fast
+     * path and checks history without parsing it, so the per-operation gate
+     * never blocks the event loop on a slow network filesystem.
+     */
+    async getAgentPermissionStatusAsync(notebookPath) {
+        const [metadata, hasHistory] = await Promise.all([
+            this.getNotebookMetadataAsync(notebookPath),
+            this.hasHistoryAsync(notebookPath),
+        ]);
+        return this.deriveAgentPermission(metadata, hasHistory);
+    }
+    deriveAgentPermission(metadata, hasHistory) {
+        const nebula = (metadata.nebula || {});
         const agentCreated = Boolean(nebula.agent_created);
         const agentPermitted = Boolean(nebula.agent_permitted);
         // Tri-state: an explicit user revoke (agent_permitted === false) always wins,
@@ -1616,6 +1730,24 @@ class FilesystemService {
             return false;
         }
     }
+    /**
+     * Async variant of hasHistory that only parses small files: history journals
+     * grow to hundreds of KB, and this check runs on every agent operation — a
+     * file that large necessarily has entries, so its size alone answers.
+     */
+    async hasHistoryAsync(notebookPath) {
+        const historyPath = this.getHistoryPath(notebookPath);
+        try {
+            const stat = await fs_1.promises.stat(historyPath);
+            if (stat.size > 4096)
+                return true;
+            const history = JSON.parse(await fs_1.promises.readFile(historyPath, 'utf-8'));
+            return Array.isArray(history) && history.length > 0;
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * Save operation history for a notebook
      */

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/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"));
@@ -68,6 +69,7 @@ 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");
@@ -80,6 +82,7 @@ const mock_scheduler_1 = require("./scheduler/mock-scheduler");
 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
@@ -240,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;
@@ -248,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'],
@@ -287,6 +343,7 @@ async function createApp() {
             ready: kernel_1.kernelService.isReady,
             cwd: rootDir,
             update,
+            environment: (0, environment_1.getEnvironment)(),
         });
     });
     fastify.get('/api/ready', async (_request, reply) => {
@@ -318,6 +375,7 @@ 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' });
@@ -548,7 +606,7 @@ async function main() {
             '',
             '   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',
+            '   Cluster guide: https://github.com/jzhoulab/nebula-notebook/blob/main/docs/CLUSTER_SETUP.md',
             '  ──────────────────────────────────────────────────────',
             '',
         ];
@@ -628,7 +686,7 @@ async function main() {
         const clientServerId = `${os.hostname()}:${boundPort}`;
         server_registry_1.serverRegistry.setLocalServerId(clientServerId);
         kernel_1.kernelService.setServerIdentity(clientServerId, serverInstanceId);
-        client_registration_1.clientRegistration.initFromEnv(boundPort);
+        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);
@@ -670,6 +728,15 @@ async function main() {
     }
 }
 // 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);

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

@@ -20,6 +20,23 @@ export interface CommEvent {
 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;
+/**
+ * Polyfill IPython-style `!command` lines for kernels whose language lacks
+ * them, by rewriting each such line into the language's own shell-call idiom
+ * before the code reaches the kernel. Because the rewritten code still runs
+ * in the kernel process, cwd, environment (conda env, loaded modules), and
+ * machine (allocation node) are all the kernel's — the same guarantees
+ * IPython's native `!` gives Python users.
+ *
+ * Python kernels are deliberately untouched: IPython's `!` is richer than a
+ * plain shell call (output capture `x = !ls`, `{var}` interpolation,
+ * streaming output) and a rewrite would break it.
+ *
+ * Only whole lines that start with `!` are rewritten. Known limits (v1):
+ * a line inside a multi-line string that happens to start with `!` would be
+ * rewritten too, and R's intern=TRUE buffers output until the command exits.
+ */
+export declare function rewriteShellLines(code: string, language: string | undefined): string;
 export declare class KernelService {
     private sessions;
     private fileToSession;