nebula-notebook 0.1.1 → 0.2.0

package/node-server/dist/scheduler/slurm-scheduler.js

@@ -0,0 +1,393 @@
+"use strict";
+/**
+ * SLURM implementation of the Scheduler interface.
+ *
+ * Everything shells out to the standard SLURM client CLIs (sbatch, squeue,
+ * scancel, sinfo, sacctmgr, sacct). The Nebula main server runs on the login
+ * node where these are available; detection is capability-based.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SlurmScheduler = void 0;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const util_2 = require("./util");
+const execFileP = (0, util_1.promisify)(child_process_1.execFile);
+async function run(cmd, args, timeoutMs = 15_000) {
+    const { stdout, stderr } = await execFileP(cmd, args, {
+        timeout: timeoutMs,
+        maxBuffer: 16 * 1024 * 1024,
+    });
+    return { stdout: stdout.toString(), stderr: stderr.toString() };
+}
+function toInt(v) {
+    const n = parseInt((v ?? '').trim(), 10);
+    return Number.isFinite(n) ? n : 0;
+}
+/** Pull `Key=value` (value up to next space) out of a `scontrol -o` line. */
+function scontrolField(line, key) {
+    const m = line.match(new RegExp(`(?:^|\\s)${key}=(\\S+)`));
+    return m ? m[1] : undefined;
+}
+/** Map a SLURM state code or name to our normalized JobState. */
+function mapState(raw) {
+    const s = (raw || '').trim().toUpperCase();
+    if (s === 'PD' || s === 'PENDING' || s === 'CF' || s === 'CONFIGURING')
+        return 'pending';
+    if (s === 'R' || s === 'RUNNING')
+        return 'running';
+    if (s === 'CG' || s === 'COMPLETING')
+        return 'completing';
+    if (s === 'CD' || s === 'COMPLETED')
+        return 'completed';
+    if (s === 'CA' || s === 'CANCELLED' || s.startsWith('CANCELLED'))
+        return 'cancelled';
+    if (['F', 'FAILED', 'TO', 'TIMEOUT', 'NF', 'NODE_FAIL', 'OOM', 'OUT_OF_MEMORY', 'BF', 'BOOT_FAIL', 'DL', 'DEADLINE'].includes(s)) {
+        return 'failed';
+    }
+    return 'unknown';
+}
+async function expandNodes(nodelist) {
+    const nl = (nodelist || '').trim();
+    if (!nl || nl === '(null)' || nl === 'None' || nl === 'n/a')
+        return [];
+    try {
+        const { stdout } = await run('scontrol', ['show', 'hostnames', nl], 5_000);
+        return stdout.split('\n').map((s) => s.trim()).filter(Boolean);
+    }
+    catch {
+        return [nl];
+    }
+}
+class SlurmScheduler {
+    name = 'slurm';
+    /** Cache of per-partition required-QoS (site job-submit filters change rarely). */
+    qosCache = new Map();
+    // Short-TTL caches + in-flight de-duplication so the dashboard's 15s poll, the
+    // allocation modal, and manual refresh don't each re-run the (potentially slow)
+    // sinfo/scontrol/squeue/sacctmgr queries against the scheduler.
+    static LOAD_TTL_MS = 10_000;
+    static ASSOC_TTL_MS = 60_000;
+    loadCache = null;
+    loadInflight = null;
+    assocCache = new Map();
+    assocInflight = new Map();
+    async detect() {
+        try {
+            await run('sbatch', ['--version'], 5_000);
+            await run('squeue', ['--version'], 5_000);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async associations(user) {
+        const cached = this.assocCache.get(user);
+        if (cached && Date.now() - cached.at < SlurmScheduler.ASSOC_TTL_MS)
+            return cached.data;
+        const inflight = this.assocInflight.get(user);
+        if (inflight)
+            return inflight;
+        const p = this.associationsFresh(user)
+            .then((data) => { this.assocCache.set(user, { data, at: Date.now() }); return data; })
+            .finally(() => { this.assocInflight.delete(user); });
+        this.assocInflight.set(user, p);
+        return p;
+    }
+    async associationsFresh(user) {
+        let account;
+        const partitions = new Set();
+        const qoses = new Set();
+        let defaultQos;
+        try {
+            const { stdout } = await run('sacctmgr', [
+                '-nP', 'show', 'assoc', `user=${user}`,
+                'format=Account,Partition,QOS,DefaultQOS',
+            ]);
+            for (const line of stdout.split('\n')) {
+                if (!line.trim())
+                    continue;
+                const [acct, part, qos, defQos] = line.split('|');
+                if (acct && !account)
+                    account = acct.trim();
+                if (part && part.trim())
+                    partitions.add(part.trim());
+                if (qos)
+                    qos.split(',').forEach((q) => q.trim() && qoses.add(q.trim()));
+                if (defQos && defQos.trim() && !defaultQos)
+                    defaultQos = defQos.trim();
+            }
+        }
+        catch {
+            /* sacctmgr may be unavailable / accounting disabled */
+        }
+        // Account-level associations often leave Partition blank (== not restricted).
+        // Fall back to the full partition list so the user can still pick one;
+        // an actually-disallowed choice is caught at submit / estimate time.
+        if (partitions.size === 0) {
+            try {
+                const { stdout } = await run('sinfo', ['-h', '-o', '%R']);
+                stdout.split('\n').forEach((p) => {
+                    const t = p.trim();
+                    if (t)
+                        partitions.add(t);
+                });
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        return {
+            account,
+            partitions: [...partitions],
+            qoses: [...qoses],
+            defaultQos,
+        };
+    }
+    async load() {
+        if (this.loadCache && Date.now() - this.loadCache.at < SlurmScheduler.LOAD_TTL_MS) {
+            return this.loadCache.data;
+        }
+        if (this.loadInflight)
+            return this.loadInflight;
+        const p = this.loadFresh()
+            .then((data) => { this.loadCache = { data, at: Date.now() }; return data; })
+            .finally(() => { this.loadInflight = null; });
+        this.loadInflight = p;
+        return p;
+    }
+    async loadFresh() {
+        const partitions = new Map();
+        // Fire all four scheduler queries concurrently — the wall time is the slowest
+        // one, not the sum (scontrol/squeue dominate on big/busy clusters). Each is
+        // independent and optional; a failed query just leaves its slice of data empty.
+        const [sinfoRes, nodeRes, squeueRes, qosRes] = await Promise.allSettled([
+            run('sinfo', ['-h', '-o', '%R|%a|%l|%C|%D|%T']),
+            run('scontrol', ['show', 'node', '-o'], 20_000),
+            run('squeue', ['-h', '-r', '-o', '%P|%q|%t']),
+            run('sacctmgr', ['-nP', 'show', 'qos', 'format=Name,Priority,MaxWall,Preempt']),
+        ]);
+        // sinfo emits one line per (partition, node-state) group; aggregate per partition.
+        if (sinfoRes.status === 'fulfilled') {
+            for (const line of sinfoRes.value.stdout.split('\n')) {
+                if (!line.trim())
+                    continue;
+                const [name, avail, timeLimit, cpus, nodeCount, stateName] = line.split('|');
+                const [ca, ci, co, ct] = (cpus || '').split('/').map(toInt);
+                let p = partitions.get(name);
+                if (!p) {
+                    p = {
+                        name,
+                        up: (avail || '').trim().toLowerCase() === 'up',
+                        timeLimit: (timeLimit || '').trim(),
+                        cpus: { alloc: 0, idle: 0, other: 0, total: 0 },
+                        nodes: { idle: 0, mixed: 0, alloc: 0, down: 0, total: 0 },
+                        jobs: { pending: 0, running: 0 },
+                    };
+                    partitions.set(name, p);
+                }
+                p.cpus.alloc += ca;
+                p.cpus.idle += ci;
+                p.cpus.other += co;
+                p.cpus.total += ct;
+                const nc = toInt(nodeCount);
+                p.nodes.total += nc;
+                const st = (stateName || '').trim().toLowerCase();
+                if (st.startsWith('idle'))
+                    p.nodes.idle += nc;
+                else if (st.startsWith('mix') || st.startsWith('alloc'))
+                    p.nodes.mixed += nc;
+                else if (st.startsWith('down') || st.startsWith('drain') || st.startsWith('fail'))
+                    p.nodes.down += nc;
+            }
+        }
+        // GPU capacity per partition, from per-node TRES: configured (CfgTRES) vs
+        // allocated (AllocTRES) `gres/gpu`, so we can report *idle* (available) GPUs
+        // rather than a per-node count. Generic — no site-specific node/gres names.
+        if (nodeRes.status === 'fulfilled') {
+            const agg = new Map();
+            for (const line of nodeRes.value.stdout.split('\n')) {
+                if (!line.trim())
+                    continue;
+                const cfg = scontrolField(line, 'CfgTRES') || '';
+                const cfgGpu = toInt((cfg.match(/gres\/gpu=(\d+)/) || [])[1]);
+                if (cfgGpu === 0)
+                    continue; // node has no GPUs
+                const parts = scontrolField(line, 'Partitions');
+                if (!parts)
+                    continue;
+                const allocGpu = toInt((scontrolField(line, 'AllocTRES')?.match(/gres\/gpu=(\d+)/) || [])[1]);
+                const type = (scontrolField(line, 'Gres')?.match(/gpu:([^:(]+)/) || [])[1] || 'gpu';
+                for (const part of parts.split(',')) {
+                    const e = agg.get(part) || { type, total: 0, used: 0 };
+                    e.total += cfgGpu;
+                    e.used += allocGpu;
+                    if (!e.type || e.type === 'gpu')
+                        e.type = type;
+                    agg.set(part, e);
+                }
+            }
+            for (const [part, g] of agg) {
+                const p = partitions.get(part);
+                if (p && g.total > 0)
+                    p.gpus = { type: g.type, total: g.total, idle: Math.max(0, g.total - g.used) };
+            }
+        }
+        // Queue depth from squeue, aggregated per partition AND per QoS.
+        const qosUsage = new Map();
+        if (squeueRes.status === 'fulfilled') {
+            for (const line of squeueRes.value.stdout.split('\n')) {
+                if (!line.trim())
+                    continue;
+                const [part, qos, state] = line.split('|');
+                const s = (state || '').trim().toUpperCase();
+                const p = partitions.get((part || '').trim());
+                if (p) {
+                    if (s === 'PD')
+                        p.jobs.pending += 1;
+                    else if (s === 'R')
+                        p.jobs.running += 1;
+                }
+                const qn = (qos || '').trim();
+                if (qn) {
+                    const u = qosUsage.get(qn) || { running: 0, pending: 0 };
+                    if (s === 'PD')
+                        u.pending += 1;
+                    else if (s === 'R')
+                        u.running += 1;
+                    qosUsage.set(qn, u);
+                }
+            }
+        }
+        // QoS definitions + preemption graph. In SLURM a QoS's `Preempt` column lists
+        // the QoS's it can preempt; a QoS is therefore *preemptible* (can be
+        // interrupted) exactly when some other QoS lists it as a preempt target.
+        // This is derived entirely from the scheduler — no site-specific QoS names.
+        const qoses = [];
+        if (qosRes.status === 'fulfilled') {
+            const rows = [];
+            for (const line of qosRes.value.stdout.split('\n')) {
+                if (!line.trim())
+                    continue;
+                const [name, priority, maxWall, preempt] = line.split('|');
+                rows.push({
+                    name: (name || '').trim(),
+                    priority: toInt(priority),
+                    maxWall: maxWall && maxWall.trim() ? maxWall.trim() : undefined,
+                    preempts: (preempt || '').split(',').map((s) => s.trim()).filter(Boolean),
+                });
+            }
+            const preemptedBy = new Set();
+            for (const r of rows)
+                for (const target of r.preempts)
+                    preemptedBy.add(target);
+            for (const r of rows) {
+                qoses.push({
+                    name: r.name,
+                    priority: r.priority,
+                    maxWall: r.maxWall,
+                    preemptible: preemptedBy.has(r.name),
+                    preempts: r.preempts,
+                    jobs: qosUsage.get(r.name) || { running: 0, pending: 0 },
+                });
+            }
+        }
+        return { partitions: [...partitions.values()], qoses, fetchedAt: Date.now() };
+    }
+    async allowedQos(partition) {
+        const cached = this.qosCache.get(partition);
+        if (cached && Date.now() - cached.at < 300_000)
+            return cached.allowed;
+        let allowed = null;
+        try {
+            // A no-QoS dry run: succeeds when the partition accepts any QoS. A site
+            // job-submit filter that requires an explicit QoS rejects it and names the
+            // acceptable set in the message ("... Allowed: a, b").
+            await run('sbatch', [
+                '--test-only',
+                `--partition=${partition}`,
+                '--cpus-per-task=1', '--mem=1G', '--time=00:10:00', '--wrap=true',
+            ], 15_000);
+            allowed = null;
+        }
+        catch (e) {
+            const text = String(e?.stderr || e?.message || '');
+            const m = text.match(/requires explicit --qos\.?\s*Allowed:\s*([^\n]+)/i);
+            allowed = m ? m[1].split(',').map((s) => s.trim()).filter(Boolean) : null;
+        }
+        this.qosCache.set(partition, { allowed, at: Date.now() });
+        return allowed;
+    }
+    async estimateStart(spec) {
+        const args = [
+            '--test-only',
+            `--partition=${spec.partition}`,
+            `--cpus-per-task=${spec.cpus}`,
+            `--mem=${spec.memGb}G`,
+            `--time=${(0, util_2.formatWalltime)(spec.walltimeMinutes)}`,
+        ];
+        if (spec.qos)
+            args.push(`--qos=${spec.qos}`);
+        if (spec.account)
+            args.push(`--account=${spec.account}`);
+        if (spec.gpus)
+            args.push(`--gres=gpu:${spec.gpuType ? `${spec.gpuType}:` : ''}${spec.gpus}`);
+        args.push('--wrap=true');
+        // `sbatch --test-only` writes "Job N to start at <time> ... on nodes <n>" to stderr.
+        try {
+            const { stdout, stderr } = await run('sbatch', args, 15_000);
+            const text = `${stderr}\n${stdout}`;
+            const m = text.match(/to start at (\S+)(?:.*?on nodes? (\S+))?/i);
+            if (m)
+                return { startsAt: m[1], nodes: m[2] ? [m[2]] : undefined };
+            return { reason: text.trim() || 'no estimate available' };
+        }
+        catch (e) {
+            const reason = (e?.stderr || e?.message || 'test-only failed').toString().trim();
+            return { reason };
+        }
+    }
+    async submit(scriptPath) {
+        const { stdout } = await run('sbatch', ['--parsable', scriptPath]);
+        const jobId = stdout.trim().split(';')[0].trim();
+        if (!/^\d+$/.test(jobId)) {
+            throw new Error(`Unexpected sbatch output: ${stdout.trim()}`);
+        }
+        return { jobId };
+    }
+    async query(jobId) {
+        // Active jobs: squeue.
+        try {
+            const { stdout } = await run('squeue', ['-h', '-j', jobId, '-o', '%T|%N|%r']);
+            const line = stdout.split('\n').find((l) => l.trim());
+            if (line) {
+                const [state, nodelist, reason] = line.split('|');
+                return {
+                    state: mapState(state),
+                    nodes: await expandNodes(nodelist),
+                    reason: reason && reason.trim() && reason.trim() !== 'None' ? reason.trim() : undefined,
+                };
+            }
+        }
+        catch {
+            /* fall through to sacct */
+        }
+        // Finished jobs: sacct.
+        try {
+            const { stdout } = await run('sacct', ['-nXP', '-j', jobId, '-o', 'State,NodeList']);
+            const line = stdout.split('\n').find((l) => l.trim());
+            if (line) {
+                const [state, nodelist] = line.split('|');
+                return { state: mapState(state), nodes: await expandNodes(nodelist) };
+            }
+        }
+        catch {
+            /* ignore */
+        }
+        return { state: 'unknown', nodes: [] };
+    }
+    async cancel(jobId) {
+        await run('scancel', [jobId]);
+    }
+}
+exports.SlurmScheduler = SlurmScheduler;

package/node-server/dist/scheduler/types.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Scheduler abstraction — a thin interface over an HPC batch scheduler.
+ *
+ * SLURM is the first implementation; PBS/LSF can implement the same interface
+ * later without touching the allocation service or routes.
+ */
+export type JobState = 'pending' | 'running' | 'completing' | 'completed' | 'failed' | 'cancelled' | 'unknown';
+/** The resource request for one compute allocation. */
+export interface JobSpec {
+    partition: string;
+    qos?: string;
+    account?: string;
+    cpus: number;
+    memGb: number;
+    gpus?: number;
+    /** Specific GPU model to request (e.g. from the scheduler's gres names). Optional. */
+    gpuType?: string;
+    walltimeMinutes: number;
+    jobName: string;
+    /**
+     * Opt-in idle auto-release: the client server on the compute node exits its
+     * own process after this many minutes without kernel/terminal activity, so
+     * the batch job completes and the allocation ends naturally. Omitted = never.
+     */
+    idleTimeoutMinutes?: number;
+}
+export interface JobStatus {
+    state: JobState;
+    nodes: string[];
+    reason?: string;
+}
+/** Result of a dry-run start-time estimate (SLURM `sbatch --test-only`). */
+export interface StartEstimate {
+    startsAt?: string;
+    nodes?: string[];
+    reason?: string;
+}
+/** What a given user is allowed to submit to. */
+export interface Associations {
+    account?: string;
+    partitions: string[];
+    qoses: string[];
+    defaultQos?: string;
+}
+export interface PartitionLoad {
+    name: string;
+    up: boolean;
+    timeLimit: string;
+    cpus: {
+        alloc: number;
+        idle: number;
+        other: number;
+        total: number;
+    };
+    /** GPU capacity for the partition: total configured vs currently idle (available). */
+    gpus?: {
+        type: string;
+        total: number;
+        idle: number;
+    };
+    nodes: {
+        idle: number;
+        mixed: number;
+        alloc: number;
+        down: number;
+        total: number;
+    };
+    jobs: {
+        pending: number;
+        running: number;
+    };
+}
+export interface QosLoad {
+    name: string;
+    priority: number;
+    maxWall?: string;
+    /** True if some other QoS is configured to preempt this one (jobs may be interrupted). */
+    preemptible: boolean;
+    /** QoS names this QoS can preempt (empty for most). */
+    preempts: string[];
+    /** Live usage under this QoS across the cluster. */
+    jobs: {
+        running: number;
+        pending: number;
+    };
+}
+/** A point-in-time snapshot of cluster busyness for the launcher's load monitor. */
+export interface QueueLoad {
+    partitions: PartitionLoad[];
+    qoses: QosLoad[];
+    fetchedAt: number;
+}
+export interface Scheduler {
+    readonly name: string;
+    /** Is this scheduler available on this host (are its CLIs present)? */
+    detect(): Promise<boolean>;
+    /** Partitions/QoS the user may submit to, and their default QoS. */
+    associations(user: string): Promise<Associations>;
+    /** Per-partition / per-QoS busyness snapshot. */
+    load(): Promise<QueueLoad>;
+    /**
+     * QoS names a partition will actually accept, or null when it accepts any
+     * (no explicit-QoS requirement). Lets the UI avoid offering a QoS the
+     * scheduler would reject. Discovered from the scheduler, not configured.
+     */
+    allowedQos(partition: string): Promise<string[] | null>;
+    /** Dry-run estimated start time for a spec, without submitting. */
+    estimateStart(spec: JobSpec): Promise<StartEstimate>;
+    /** Submit a rendered job script; returns the scheduler job id. */
+    submit(scriptPath: string): Promise<{
+        jobId: string;
+    }>;
+    /** Current state of a submitted job. */
+    query(jobId: string): Promise<JobStatus>;
+    /** Cancel a submitted job. */
+    cancel(jobId: string): Promise<void>;
+}

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

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Scheduler abstraction — a thin interface over an HPC batch scheduler.
+ *
+ * SLURM is the first implementation; PBS/LSF can implement the same interface
+ * later without touching the allocation service or routes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/node-server/dist/scheduler/util.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Small shared helpers for the scheduler module.
+ */
+/** Format minutes as a SLURM walltime string (`D-HH:MM:SS` or `HH:MM:SS`). */
+export declare function formatWalltime(minutes: number): string;
+/** POSIX single-quote a string so it is safe to embed in a shell script. */
+export declare function shellQuote(s: string): string;

package/node-server/dist/scheduler/util.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * Small shared helpers for the scheduler module.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatWalltime = formatWalltime;
+exports.shellQuote = shellQuote;
+/** Format minutes as a SLURM walltime string (`D-HH:MM:SS` or `HH:MM:SS`). */
+function formatWalltime(minutes) {
+    const total = Math.max(1, Math.floor(minutes));
+    const d = Math.floor(total / 1440);
+    const h = Math.floor((total % 1440) / 60);
+    const m = total % 60;
+    const hhmmss = `${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}:00`;
+    return d > 0 ? `${d}-${hhmmss}` : hhmmss;
+}
+/** POSIX single-quote a string so it is safe to embed in a shell script. */
+function shellQuote(s) {
+    return `'${String(s).replace(/'/g, `'\\''`)}'`;
+}

package/node-server/dist/terminal/pty-manager.js

@@ -37,6 +37,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ptyManager = exports.PtyManager = void 0;
+const path = __importStar(require("path"));
 const pty = __importStar(require("@homebridge/node-pty-prebuilt-multiarch"));
 const uuid_1 = require("uuid");
 const types_1 = require("./types");
@@ -76,6 +77,11 @@ class PtyManager {
         const cwd = options?.cwd || process.cwd();
         const cols = options?.cols || 80;
         const rows = options?.rows || 24;
+        // Make the `nebula` agent CLI resolvable in every Nebula terminal, and
+        // pre-point it at this server. The CLI is a thin layer over the same
+        // client the MCP uses (packages/mcp) — agents in the built-in terminal
+        // can drive notebooks without any MCP registration.
+        const nebulaCliBinDir = path.resolve(__dirname, '..', '..', '..', 'packages', 'mcp', 'bin');
         // Spawn PTY process
         const ptyProcess = pty.spawn(shell, [], {
             name: 'xterm-256color',
@@ -86,6 +92,8 @@ class PtyManager {
                 ...process.env,
                 TERM: 'xterm-256color',
                 COLORTERM: 'truecolor',
+                NEBULA_URL: process.env.NEBULA_URL ?? `http://localhost:${process.env.PORT || 3000}`,
+                PATH: `${nebulaCliBinDir}:${process.env.PATH ?? ''}`,
             },
         });
         const session = {

package/node-server/dist/terminal/server.js

@@ -40,6 +40,8 @@ exports.setupTerminalRoutes = setupTerminalRoutes;
 exports.setupTerminalWebSocket = setupTerminalWebSocket;
 exports.cleanupTerminals = cleanupTerminals;
 const ws_1 = require("ws");
+const net = __importStar(require("net"));
+const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const pty_manager_1 = require("./pty-manager");
 const fs_service_1 = require("../fs/fs-service");
@@ -59,9 +61,48 @@ const wsConnections = new Map();
  */
 async function setupTerminalRoutes(fastify) {
     // Terminal health check (includes terminal count and repo root for the
-    // path-qualified MCP setup hint shown in the agent terminal UI)
+    // path-qualified MCP setup hint shown in the agent terminal UI, plus
+    // hostname/port so the UI can compose an exact SSH tunnel command)
     fastify.get('/api/terminals/health', async (_request, reply) => {
-        return reply.send({ status: 'ok', terminals: pty_manager_1.ptyManager.list().length, repo_root: NEBULA_REPO_ROOT });
+        return reply.send({
+            status: 'ok',
+            terminals: pty_manager_1.ptyManager.list().length,
+            repo_root: NEBULA_REPO_ROOT,
+            hostname: os.hostname(),
+            port: Number(process.env.PORT) || 3000,
+        });
+    });
+    // Probe a loopback port on THIS host — used by remote-agent mode to detect
+    // whether the user's reverse SSH channel (ssh -R <port>:localhost:22) is up.
+    // Loopback-only by construction; the port is user-chosen and random.
+    fastify.get('/api/terminals/reverse-check', async (request, reply) => {
+        const port = Number(request.query.port);
+        if (!Number.isInteger(port) || port < 1024 || port > 65535) {
+            return reply.status(400).send({ error: 'port must be an integer in 1024-65535' });
+        }
+        // Two-signal probe at the cost of one connection: `up` = the listener
+        // accepted (fast path, unchanged); `ssh` = an SSH banner arrived within
+        // 700ms of connecting (an sshd greets immediately with "SSH-2.0-...").
+        // ssh=false means the port is forwarded but nothing SSH answers — the
+        // classic Remote-Login-off case; ssh=null means banner unknown (slow
+        // network) and MUST NOT be treated as a failure.
+        const result = await new Promise((resolve) => {
+            const sock = net.connect({ host: '127.0.0.1', port, timeout: 1200 });
+            let bannerTimer = null;
+            const finish = (up, ssh) => {
+                if (bannerTimer)
+                    clearTimeout(bannerTimer);
+                sock.destroy();
+                resolve({ up, ssh });
+            };
+            sock.once('connect', () => {
+                bannerTimer = setTimeout(() => finish(true, null), 700);
+                sock.once('data', (buf) => finish(true, buf.toString('latin1').startsWith('SSH-')));
+            });
+            sock.once('timeout', () => finish(false, null));
+            sock.once('error', () => finish(false, null));
+        });
+        return reply.send({ up: result.up, ssh: result.ssh });
     });
     // List all terminals
     fastify.get('/api/terminals', async (_request, reply) => {

package/node-server/dist/update-check.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Update check — notify-only, never auto-installs.
+ *
+ * Once at startup (and daily after), asks the npm registry for the latest
+ * published nebula-notebook version and compares it to the running one.
+ * Result is surfaced in /api/health (`update`) for the UI pill and logged
+ * once to the server console. Opt out with NEBULA_NO_UPDATE_CHECK=1.
+ * Network failures are silent: an update check must never affect operation.
+ */
+export interface UpdateInfo {
+    current: string;
+    latest: string | null;
+    update_available: boolean;
+    checked_at: number | null;
+}
+/** Numeric semver compare on MAJOR.MINOR.PATCH; ignores prerelease tags. */
+export declare function isNewerVersion(latest: string, current: string): boolean;
+export declare function startUpdateChecker(): void;
+export declare function stopUpdateChecker(): void;
+export declare function getUpdateInfo(): UpdateInfo;