nebula-notebook 0.1.1 → 0.2.1

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

@@ -0,0 +1,406 @@
+"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 [];
+    // Plain single hostname (no ranges/lists) — the common case for 1-node
+    // allocations. Don't shell out to scontrol just to echo it back.
+    if (!/[\[\],]/.test(nl))
+        return [nl];
+    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.
+    // 20s: deliberately ABOVE the clients' 15s poll so steady-state polling
+    // alternates cache hit/miss instead of missing every time (10s never hit).
+    static LOAD_TTL_MS = 20_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') {
+            // Aggregate per (partition, GPU model) — heterogeneous queues mix cards.
+            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 byType = agg.get(part) ?? new Map();
+                    const e = byType.get(type) || { total: 0, used: 0 };
+                    e.total += cfgGpu;
+                    e.used += allocGpu;
+                    byType.set(type, e);
+                    agg.set(part, byType);
+                }
+            }
+            for (const [part, byType] of agg) {
+                const p = partitions.get(part);
+                if (!p)
+                    continue;
+                const list = [...byType.entries()]
+                    .filter(([, g]) => g.total > 0)
+                    .map(([type, g]) => ({ type, total: g.total, idle: Math.max(0, g.total - g.used) }))
+                    .sort((a, b) => b.total - a.total || a.type.localeCompare(b.type));
+                if (list.length)
+                    p.gpus = list;
+            }
+        }
+        // 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,118 @@
+/**
+ * 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, one entry per GPU model (heterogeneous
+     *  queues carry several): 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/agent-registry.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Agent registry — the server-side ledger of agent sessions (Claude Code /
+ * Codex CLIs running inside terminal ptys).
+ *
+ * Agents are project-scoped (keyed by the working directory they were
+ * launched in) and decoupled from notebooks: switching notebooks never kills
+ * or switches an agent; the user does, through the agent manager. Records
+ * persist to disk so agents survive as *resumable* entities even when their
+ * pty dies (browser gone, server restart, user hibernates them): the CLI's
+ * own on-disk trajectory (`claude --resume <id>` / `codex resume`) can
+ * reconstruct the conversation — the registry just remembers what exists,
+ * where, and how to revive it. The client owns launch/revive command
+ * construction (it knows about remote-agent mode); the server owns truth
+ * about what is live.
+ *
+ * States: 'live' (pty exists) → 'hibernated' (pty gone, trajectory on disk).
+ * All records load as 'hibernated' on boot — ptys never survive a restart.
+ */
+export interface AgentRecord {
+    /** Terminal (pty) id the agent runs in — stable, derived from workdir. */
+    terminalId: string;
+    kind: 'claude' | 'codex';
+    /** Directory the agent was launched in — the project scope. */
+    workdir: string;
+    /** Where the CLI process runs: this server, or the user's machine over the reverse channel. */
+    location: 'server' | 'remote';
+    /** Claude --session-id (resume pointer). Codex resumes via its own picker. */
+    sessionId?: string;
+    /** Notebook that launched it (informational only — agents are not bound to notebooks). */
+    launchedFrom?: string;
+    /**
+     * Pinned workspace-mirror dir slug (`p-<hash>-<name>` under ~/.nebula/agent).
+     * Stored at launch so record-driven resumes keep finding the conversation
+     * even if the slug derivation ever changes — paths in records don't drift.
+     */
+    mirrorSlug?: string;
+    state: 'live' | 'hibernated';
+    createdAt: number;
+    lastLaunchAt: number;
+}
+declare class AgentRegistry {
+    private records;
+    private exitUnsubs;
+    private loaded;
+    private ensureLoaded;
+    private persist;
+    /**
+     * Register (or re-register on revive) an agent launched in a terminal.
+     * MERGE semantics: fields the caller didn't supply NEVER overwrite stored
+     * truth — a resume relaunch that doesn't know the sessionId must not erase
+     * the registry's copy (that id is the conversation; losing it downgrades
+     * every later Continue to a picker).
+     */
+    register(rec: Omit<AgentRecord, 'state' | 'createdAt' | 'lastLaunchAt'>): AgentRecord;
+    private static TUI_INIT_RE;
+    private static TUI_TEARDOWN_RE;
+    private dataUnsubs;
+    private graceTimers;
+    private watchLiveness;
+    /** Feed pty output through the liveness machine (public for tests). */
+    observeOutput(terminalId: string, chunk: string): void;
+    /** List all agents, reconciling 'live' against actual pty existence. */
+    list(): AgentRecord[];
+    /**
+     * list() plus process-table facts for every record whose pty exists:
+     * - `busy`: the pty's shell has a live child — SOMETHING is running there.
+     *   Crucially reported on HIBERNATED records too: the TUI-stream liveness
+     *   machine can mis-score (an agent resumed by hand never re-registers), and
+     *   a client that trusts 'hibernated' then types a launch command straight
+     *   into the running TUI's input box (lab report: a live codex politely
+     *   declined to run the pasted ssh line). The process table is authoritative.
+     * - `idleShell` on live records: the inverse — 'live' but nothing running
+     *   (a hung-then-dead ssh hop leaves exactly this; a dead transport emits
+     *   no teardown, so only the process table can see it).
+     * Unknown checks claim nothing.
+     */
+    listEnriched(): Promise<(AgentRecord & {
+        idleShell?: boolean;
+        busy?: boolean;
+    })[]>;
+    /** Hibernate: close the pty; the record (and on-disk trajectory) remain. */
+    hibernate(terminalId: string): boolean;
+    /** Forget the agent entirely (pty closed; registry record removed). */
+    remove(terminalId: string): boolean;
+}
+export declare const agentRegistry: AgentRegistry;
+export {};