labgate 0.5.27 → 0.5.29

package/dist/lib/ui.js

@@ -41,6 +41,7 @@ const os_1 = require("os");
 const child_process_1 = require("child_process");
 const util_1 = require("util");
 const crypto_1 = require("crypto");
+const ws_1 = require("ws");
 const config_js_1 = require("./config.js");
 const container_js_1 = require("./container.js");
 const audit_js_1 = require("./audit.js");
@@ -49,10 +50,15 @@ const slurm_poller_js_1 = require("./slurm-poller.js");
 const results_store_js_1 = require("./results-store.js");
 const policy_js_1 = require("./policy.js");
 const license_js_1 = require("./license.js");
+const web_terminal_js_1 = require("./web-terminal.js");
 const log = __importStar(require("./log.js"));
 const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
 const HTML_PATH = (0, path_1.resolve)(__dirname, '..', 'lib', 'ui.html');
 const FONTS_DIR = (0, path_1.resolve)(__dirname, '..', '..', 'node_modules', 'geist', 'dist', 'fonts');
+const XTERM_CSS_PATH = (0, path_1.resolve)(__dirname, '..', '..', 'node_modules', '@xterm', 'xterm', 'css', 'xterm.css');
+const XTERM_JS_PATH = (0, path_1.resolve)(__dirname, '..', '..', 'node_modules', '@xterm', 'xterm', 'lib', 'xterm.js');
+const XTERM_FIT_JS_PATH = (0, path_1.resolve)(__dirname, '..', '..', 'node_modules', '@xterm', 'addon-fit', 'lib', 'addon-fit.js');
+const XTERM_WEB_LINKS_JS_PATH = (0, path_1.resolve)(__dirname, '..', '..', 'node_modules', '@xterm', 'addon-web-links', 'lib', 'addon-web-links.js');
 const WRITE_TOKEN_PLACEHOLDER = '__LABGATE_WRITE_TOKEN__';
 const UI_WRITE_TOKEN = (0, crypto_1.randomBytes)(24).toString('hex');
 const UI_AUTH_COOKIE = 'labgate_ui_token';
@@ -60,16 +66,76 @@ const UI_SHORT_LINK_PREFIX = '/s/';
 const DASHBOARD_LINK_FILE = '.labgate-dashboard-url';
 const LABGATE_INSTRUCTION_START = '<!-- LABGATE_SESSION_INSTRUCTION_START -->';
 const LABGATE_INSTRUCTION_END = '<!-- LABGATE_SESSION_INSTRUCTION_END -->';
+const IRIS_SAMPLE_DATASET_NAME = 'flowers-iris';
+const IRIS_SAMPLE_SOURCE_URL = 'https://raw.githubusercontent.com/mwaskom/seaborn-data/master/iris.csv';
+const IRIS_SAMPLE_README = '# Iris Flowers Dataset (Sample)\n' +
+    '\n' +
+    'Source: https://raw.githubusercontent.com/mwaskom/seaborn-data/master/iris.csv\n' +
+    '\n' +
+    'This dataset is a small sample for testing LabGate dataset registration.\n' +
+    'Rows: 150 iris flower measurements across three classes.\n';
+function resolveIrisSampleSourceUrl() {
+    const override = (process.env.LABGATE_IRIS_SAMPLE_SOURCE_URL || '').trim();
+    if (/^https?:\/\//i.test(override))
+        return override;
+    return IRIS_SAMPLE_SOURCE_URL;
+}
 // ── SLURM module state (initialised in startUI when slurm.enabled) ──
 let slurmDB = null;
 let slurmPoller = null;
 let resultsStore = null;
+const REQUIRED_SLURM_COMMANDS = ['sbatch', 'squeue', 'sacct', 'scancel'];
+const webTerminalBridges = new Map();
 function getResultsStore() {
     if (!resultsStore) {
         resultsStore = new results_store_js_1.ResultsStore((0, config_js_1.getResultsDbPath)());
     }
     return resultsStore;
 }
+function hasCommandInPath(command) {
+    const pathValue = (process.env.PATH || '').trim();
+    if (!pathValue)
+        return false;
+    const isWindows = (0, os_1.platform)() === 'win32';
+    const directories = pathValue.split(path_1.delimiter).filter(Boolean);
+    const hasExplicitExtension = /\.[^/\\]+$/.test(command);
+    const windowsExtensions = isWindows
+        ? (process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM')
+            .split(';')
+            .map((ext) => ext.trim().toLowerCase())
+            .filter(Boolean)
+        : [''];
+    for (const dir of directories) {
+        const candidates = isWindows
+            ? (hasExplicitExtension ? [command] : windowsExtensions.map((ext) => `${command}${ext}`))
+            : [command];
+        for (const candidate of candidates) {
+            const fullPath = (0, path_1.join)(dir, candidate);
+            if (!(0, fs_1.existsSync)(fullPath))
+                continue;
+            try {
+                const st = (0, fs_1.statSync)(fullPath);
+                if (!st.isFile())
+                    continue;
+                if (isWindows)
+                    return true;
+                (0, fs_1.accessSync)(fullPath, fs_1.constants.X_OK);
+                return true;
+            }
+            catch {
+                // Continue scanning PATH entries.
+            }
+        }
+    }
+    return false;
+}
+function getSlurmRuntimeStatus() {
+    const missingCommands = REQUIRED_SLURM_COMMANDS.filter((command) => !hasCommandInPath(command));
+    return {
+        available: missingCommands.length === 0,
+        missingCommands,
+    };
+}
 function readBody(req) {
     return new Promise((resolve, reject) => {
         const chunks = [];
@@ -82,6 +148,103 @@ function json(res, data, status = 200) {
     res.writeHead(status, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify(data));
 }
+function normalizeEmailCandidate(value) {
+    if (typeof value !== 'string')
+        return null;
+    const match = value.match(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/i);
+    if (!match)
+        return null;
+    return match[0].toLowerCase();
+}
+function deepFindEmail(value, depth = 0) {
+    if (depth > 6 || value === null || value === undefined)
+        return null;
+    const direct = normalizeEmailCandidate(value);
+    if (direct)
+        return direct;
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const found = deepFindEmail(item, depth + 1);
+            if (found)
+                return found;
+        }
+        return null;
+    }
+    if (typeof value !== 'object')
+        return null;
+    const record = value;
+    const keys = Object.keys(record);
+    for (const key of keys) {
+        if (!/email|mail/i.test(key))
+            continue;
+        const found = deepFindEmail(record[key], depth + 1);
+        if (found)
+            return found;
+    }
+    for (const key of keys) {
+        const found = deepFindEmail(record[key], depth + 1);
+        if (found)
+            return found;
+    }
+    return null;
+}
+function deepFindAccessToken(value, depth = 0) {
+    if (depth > 6 || value === null || value === undefined)
+        return '';
+    if (typeof value === 'string') {
+        const token = value.trim();
+        return token.length >= 20 ? token : '';
+    }
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const found = deepFindAccessToken(item, depth + 1);
+            if (found)
+                return found;
+        }
+        return '';
+    }
+    if (typeof value !== 'object')
+        return '';
+    const record = value;
+    const keys = Object.keys(record);
+    for (const key of keys) {
+        if (!/access.?token|token/i.test(key))
+            continue;
+        const found = deepFindAccessToken(record[key], depth + 1);
+        if (found)
+            return found;
+    }
+    return '';
+}
+function readClaudeCredentialSnapshot() {
+    const sandboxHome = (0, config_js_1.getSandboxHome)();
+    const credentialPaths = [
+        (0, path_1.join)(sandboxHome, '.claude', '.credentials.json'),
+        (0, path_1.join)(sandboxHome, '.claude', 'credentials.json'),
+    ];
+    for (const credPath of credentialPaths) {
+        if (!(0, fs_1.existsSync)(credPath))
+            continue;
+        try {
+            const parsed = JSON.parse((0, fs_1.readFileSync)(credPath, 'utf-8'));
+            const nestedOauth = parsed.claudeAiOauth ?? parsed.oauth ?? null;
+            const token = (typeof nestedOauth?.accessToken === 'string' && nestedOauth.accessToken.trim()) ||
+                (typeof parsed.accessToken === 'string' && parsed.accessToken.trim()) ||
+                deepFindAccessToken(parsed);
+            if (!token)
+                continue;
+            const email = deepFindEmail(nestedOauth?.email) ||
+                deepFindEmail(nestedOauth?.user) ||
+                deepFindEmail(nestedOauth?.profile) ||
+                deepFindEmail(parsed);
+            return { loggedIn: true, email: email || null };
+        }
+        catch {
+            // Ignore malformed credential files and keep searching.
+        }
+    }
+    return { loggedIn: false, email: null };
+}
 function getHeaderValue(req, name) {
     const value = req.headers[name.toLowerCase()];
     if (Array.isArray(value))
@@ -170,6 +333,39 @@ function clearDashboardLink(expectedUrl) {
         // Best effort cleanup.
     }
 }
+function supportsTerminalHyperlinks() {
+    if (!(process.stderr.isTTY ?? false))
+        return false;
+    if (process.env.LABGATE_UI_HYPERLINKS === '0')
+        return false;
+    if ((process.env.TERM || '').toLowerCase() === 'dumb')
+        return false;
+    return true;
+}
+function formatTerminalHyperlink(url) {
+    if (!supportsTerminalHyperlinks())
+        return url;
+    const safe = url.replace(/[\u001b\u0007]/g, '');
+    return `\u001b]8;;${safe}\u0007${url}\u001b]8;;\u0007`;
+}
+function shouldAutoOpenUiBrowser(standalone) {
+    if (!standalone)
+        return false;
+    if (process.env.LABGATE_UI_AUTO_OPEN === '0')
+        return false;
+    if (process.env.SSH_CONNECTION || process.env.SSH_TTY)
+        return false;
+    if (!(process.stdout.isTTY ?? false) && !(process.stderr.isTTY ?? false))
+        return false;
+    return (0, os_1.platform)() === 'darwin';
+}
+function autoOpenUiBrowser(url) {
+    (0, child_process_1.execFile)('open', [url], (err) => {
+        if (!err)
+            return;
+        log.warn('Could not auto-open browser. Use the Settings URL above.');
+    });
+}
 function serveFontFile(url, res) {
     // Only allow specific font files from the geist package
     const match = url.match(/^\/fonts\/([\w-]+\.woff2)$/);
@@ -195,6 +391,169 @@ function serveFontFile(url, res) {
     res.writeHead(404, { 'Content-Type': 'text/plain' });
     res.end('Font not found');
 }
+function serveVendorAsset(res, filePath, contentType) {
+    try {
+        if (!(0, fs_1.existsSync)(filePath)) {
+            res.writeHead(404, { 'Content-Type': 'text/plain' });
+            res.end('Not found');
+            return;
+        }
+        const data = (0, fs_1.readFileSync)(filePath);
+        res.writeHead(200, {
+            'Content-Type': contentType,
+            'Cache-Control': 'public, max-age=86400',
+        });
+        res.end(data);
+    }
+    catch {
+        res.writeHead(500, { 'Content-Type': 'text/plain' });
+        res.end('Could not load asset');
+    }
+}
+function normalizeWebTerminalAgent(raw) {
+    const agent = (raw || '').trim().toLowerCase();
+    if (agent === 'claude' || agent === 'codex')
+        return agent;
+    return null;
+}
+function serializeWebTerminalSession(record) {
+    return {
+        id: record.id,
+        agent: record.agent,
+        workdir: record.workdir,
+        node: record.node,
+        tmuxSession: record.tmuxSession,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+        status: record.status,
+        exitCode: record.exitCode,
+        error: record.error,
+    };
+}
+async function loadNodePtyModule() {
+    try {
+        const mod = await import('node-pty');
+        return mod?.spawn ? mod : (mod?.default?.spawn ? mod.default : null);
+    }
+    catch {
+        return null;
+    }
+}
+function appendWebTerminalBuffer(bridge, chunk) {
+    bridge.buffer += chunk;
+    // Keep recent output bounded to avoid unbounded memory growth.
+    if (bridge.buffer.length > 512_000) {
+        bridge.buffer = bridge.buffer.slice(bridge.buffer.length - 512_000);
+    }
+}
+function sendWebTerminalMessage(ws, payload) {
+    if (ws.readyState !== ws_1.WebSocket.OPEN)
+        return;
+    try {
+        ws.send(JSON.stringify(payload));
+    }
+    catch {
+        // Best effort.
+    }
+}
+function broadcastWebTerminalMessage(bridge, payload) {
+    for (const ws of bridge.clients) {
+        if (ws.readyState !== ws_1.WebSocket.OPEN) {
+            bridge.clients.delete(ws);
+            continue;
+        }
+        sendWebTerminalMessage(ws, payload);
+    }
+}
+async function ensureWebTerminalBridge(record) {
+    const existing = webTerminalBridges.get(record.id);
+    if (existing && existing.pty)
+        return existing;
+    const ptyModule = await loadNodePtyModule();
+    if (!ptyModule) {
+        return null;
+    }
+    let tmuxBin = 'tmux';
+    try {
+        tmuxBin = await (0, web_terminal_js_1.getTmuxBinary)();
+    }
+    catch (err) {
+        log.warn(`Could not resolve tmux binary for web terminal bridge ${record.id}: ${err?.message ?? String(err)}`);
+        return null;
+    }
+    const env = {};
+    for (const [k, v] of Object.entries(process.env)) {
+        if (v !== undefined)
+            env[k] = v;
+    }
+    let ptyProcess;
+    const spawnOpts = {
+        name: 'xterm-256color',
+        cols: 120,
+        rows: 32,
+        cwd: record.workdir,
+        env,
+    };
+    try {
+        ptyProcess = ptyModule.spawn(tmuxBin, ['attach-session', '-t', record.tmuxSession], spawnOpts);
+    }
+    catch (err) {
+        const shell = (process.env.SHELL || '/bin/bash').trim() || '/bin/bash';
+        const quote = (value) => `'${value.replace(/'/g, `'\\''`)}'`;
+        const launch = `${quote(tmuxBin)} attach-session -t ${quote(record.tmuxSession)}`;
+        try {
+            ptyProcess = ptyModule.spawn(shell, ['-lc', launch], spawnOpts);
+        }
+        catch (fallbackErr) {
+            log.warn(`Could not create web terminal bridge for ${record.id}. ` +
+                `direct=${err?.message ?? String(err)} fallback=${fallbackErr?.message ?? String(fallbackErr)}`);
+            return null;
+        }
+    }
+    const bridge = existing || {
+        id: record.id,
+        buffer: '',
+        clients: new Set(),
+        pty: ptyProcess,
+    };
+    bridge.pty = ptyProcess;
+    webTerminalBridges.set(record.id, bridge);
+    ptyProcess.onData((data) => {
+        appendWebTerminalBuffer(bridge, data);
+        broadcastWebTerminalMessage(bridge, { type: 'data', id: record.id, data });
+    });
+    ptyProcess.onExit(async () => {
+        bridge.pty = null;
+        const alive = await (0, web_terminal_js_1.hasTmuxSession)(record.tmuxSession);
+        if (!alive) {
+            const exitInfo = (0, web_terminal_js_1.readWebTerminalExitInfo)(record.id);
+            const finalCode = exitInfo?.exitCode ?? (record.exitCode ?? 0);
+            const finalStatus = finalCode === 0 ? 'exited' : 'failed';
+            const updated = (0, web_terminal_js_1.updateWebTerminalRecordStatus)(record.id, {
+                status: finalStatus,
+                exitCode: finalCode,
+                error: finalCode === 0 ? null : (record.error || `Exited with code ${finalCode}`),
+            });
+            broadcastWebTerminalMessage(bridge, {
+                type: 'status',
+                id: record.id,
+                status: updated?.status ?? finalStatus,
+                exitCode: updated?.exitCode ?? finalCode,
+            });
+        }
+    });
+    return bridge;
+}
+function stopWebTerminalBridge(bridge) {
+    if (!bridge.pty)
+        return;
+    try {
+        bridge.pty.kill('SIGTERM');
+    }
+    catch {
+        // Best effort.
+    }
+}
 function serveHTML(res) {
     try {
         const html = (0, fs_1.readFileSync)(HTML_PATH, 'utf-8').replaceAll(WRITE_TOKEN_PLACEHOLDER, UI_WRITE_TOKEN);
@@ -209,6 +568,12 @@ function serveHTML(res) {
 function handleGetConfig(_req, res) {
     const effective = (0, config_js_1.loadEffectiveConfig)();
     const response = { ...effective.config };
+    const slurmRuntime = getSlurmRuntimeStatus();
+    response._slurm = {
+        available: slurmRuntime.available,
+        missing_commands: slurmRuntime.missingCommands,
+        required_commands: [...REQUIRED_SLURM_COMMANDS],
+    };
     // Attach enterprise metadata so the frontend knows which fields to lock
     if (effective.enterprise) {
         response._enterprise = {
@@ -251,7 +616,8 @@ async function handlePostConfig(req, res) {
             if (effective.lockedFields.has('audit.log_dir') && incoming.audit?.log_dir !== orig.audit.log_dir) {
                 violations.push('audit.log_dir');
             }
-            if (effective.lockedFields.has('slurm.enabled') && incoming.slurm?.enabled !== orig.slurm.enabled) {
+            const incomingSlurmEnabled = incoming.slurm?.enabled ?? orig.slurm.enabled;
+            if (effective.lockedFields.has('slurm.enabled') && incomingSlurmEnabled !== orig.slurm.enabled) {
                 violations.push('slurm.enabled');
             }
             if (violations.length > 0) {
@@ -1382,6 +1748,16 @@ function handleGetSecurity(_req, res) {
         },
     });
 }
+function handleGetClaudeAuthStatus(_req, res) {
+    const auth = readClaudeCredentialSnapshot();
+    json(res, {
+        ok: true,
+        provider: 'claude',
+        loggedIn: auth.loggedIn,
+        email: auth.email,
+        checkedAt: new Date().toISOString(),
+    });
+}
 async function handleStopSession(req, res) {
     try {
         const body = await readBody(req);
@@ -1507,6 +1883,149 @@ async function handleRestartSession(req, res) {
         json(res, { ok: false, error: err.message ?? String(err) }, 500);
     }
 }
+async function handlePostWebTerminalStart(req, res) {
+    try {
+        const body = await readBody(req);
+        const parsed = JSON.parse(body || '{}');
+        const agent = normalizeWebTerminalAgent(parsed.agent || 'claude');
+        const rawWorkdir = String(parsed.workdir || '').trim();
+        if (!agent) {
+            json(res, { ok: false, error: 'agent must be "claude" or "codex"' }, 400);
+            return;
+        }
+        if (!rawWorkdir) {
+            json(res, { ok: false, error: 'workdir is required' }, 400);
+            return;
+        }
+        const resolvedWorkdir = (0, path_1.resolve)(rawWorkdir.replace(/^~/, (0, os_1.homedir)()));
+        if (!(0, fs_1.existsSync)(resolvedWorkdir)) {
+            json(res, { ok: false, error: `workdir does not exist: ${resolvedWorkdir}` }, 400);
+            return;
+        }
+        let st;
+        try {
+            st = (0, fs_1.statSync)(resolvedWorkdir);
+        }
+        catch {
+            json(res, { ok: false, error: `Could not access workdir: ${resolvedWorkdir}` }, 400);
+            return;
+        }
+        if (!st.isDirectory()) {
+            json(res, { ok: false, error: `workdir is not a directory: ${resolvedWorkdir}` }, 400);
+            return;
+        }
+        const tmuxAvailable = await (0, web_terminal_js_1.ensureTmuxAvailable)();
+        if (!tmuxAvailable.ok) {
+            json(res, { ok: false, error: tmuxAvailable.error }, 500);
+            return;
+        }
+        const cliEntrypoint = resolveCliEntrypoint();
+        const id = `wt-${Date.now().toString(36)}-${(0, crypto_1.randomBytes)(2).toString('hex')}`;
+        const record = (0, web_terminal_js_1.createWebTerminalRecord)({
+            id,
+            agent,
+            workdir: resolvedWorkdir,
+        });
+        (0, web_terminal_js_1.writeWebTerminalRecord)(record);
+        try {
+            await (0, web_terminal_js_1.startTmuxWebTerminalSession)(record, cliEntrypoint);
+            (0, web_terminal_js_1.updateWebTerminalRecordStatus)(id, { status: 'running', exitCode: null, error: null });
+        }
+        catch (err) {
+            const message = err?.message ?? String(err);
+            (0, web_terminal_js_1.updateWebTerminalRecordStatus)(id, { status: 'failed', exitCode: 1, error: message });
+            json(res, { ok: false, error: `Could not start tmux session: ${message}` }, 500);
+            return;
+        }
+        const bridge = await ensureWebTerminalBridge(record);
+        if (!bridge) {
+            try {
+                await (0, web_terminal_js_1.killTmuxSession)(record.tmuxSession);
+            }
+            catch { /* best effort */ }
+            (0, web_terminal_js_1.updateWebTerminalRecordStatus)(id, {
+                status: 'failed',
+                exitCode: 1,
+                error: 'node-pty bridge unavailable',
+            });
+            json(res, {
+                ok: false,
+                error: 'Started tmux session but could not create terminal bridge (node-pty unavailable).',
+            }, 500);
+            return;
+        }
+        json(res, {
+            ok: true,
+            session: serializeWebTerminalSession(record),
+        });
+    }
+    catch (err) {
+        json(res, { ok: false, error: err?.message ?? String(err) }, 500);
+    }
+}
+async function handleGetWebTerminalSessions(res) {
+    const records = (0, web_terminal_js_1.listWebTerminalRecords)();
+    const localNode = (0, os_1.hostname)();
+    for (const record of records) {
+        // Shared home directories may contain records from other nodes.
+        // Only mutate runtime status for sessions that belong to this node.
+        if (record.node !== localNode)
+            continue;
+        const alive = await (0, web_terminal_js_1.hasTmuxSession)(record.tmuxSession);
+        if (alive && record.status !== 'running') {
+            (0, web_terminal_js_1.updateWebTerminalRecordStatus)(record.id, { status: 'running', exitCode: null, error: null });
+        }
+        else if (!alive && record.status === 'running') {
+            const exitInfo = (0, web_terminal_js_1.readWebTerminalExitInfo)(record.id);
+            const finalCode = exitInfo?.exitCode ?? (record.exitCode ?? 0);
+            const finalStatus = finalCode === 0 ? 'exited' : 'failed';
+            (0, web_terminal_js_1.updateWebTerminalRecordStatus)(record.id, {
+                status: finalStatus,
+                exitCode: finalCode,
+                error: finalCode === 0 ? null : (record.error || `Exited with code ${finalCode}`),
+            });
+        }
+    }
+    const sessions = (0, web_terminal_js_1.listWebTerminalRecords)().map(serializeWebTerminalSession);
+    json(res, { ok: true, sessions });
+}
+async function handlePostWebTerminalStop(req, res) {
+    try {
+        const body = await readBody(req);
+        const parsed = JSON.parse(body || '{}');
+        const id = String(parsed.id || '').trim();
+        if (!(0, web_terminal_js_1.isValidWebTerminalId)(id)) {
+            json(res, { ok: false, error: 'Invalid terminal session id' }, 400);
+            return;
+        }
+        const record = (0, web_terminal_js_1.readWebTerminalRecord)(id);
+        if (!record) {
+            json(res, { ok: false, error: 'Terminal session not found' }, 404);
+            return;
+        }
+        if (record.node !== (0, os_1.hostname)()) {
+            json(res, { ok: false, error: `Terminal session is on a different node (${record.node})` }, 400);
+            return;
+        }
+        try {
+            await (0, web_terminal_js_1.killTmuxSession)(record.tmuxSession);
+        }
+        catch (err) {
+            const message = err?.message ?? String(err);
+            json(res, { ok: false, error: `Failed to stop tmux session: ${message}` }, 500);
+            return;
+        }
+        (0, web_terminal_js_1.updateWebTerminalRecordStatus)(id, { status: 'exited', exitCode: 0, error: null });
+        (0, web_terminal_js_1.clearWebTerminalExitInfo)(id);
+        const bridge = webTerminalBridges.get(id);
+        if (bridge)
+            stopWebTerminalBridge(bridge);
+        json(res, { ok: true });
+    }
+    catch (err) {
+        json(res, { ok: false, error: err?.message ?? String(err) }, 500);
+    }
+}
 /**
  * Validate a host path: exists, is a directory, and is readable.
  * Returns { valid: true/false, error?, path? } — advisory only, does not block.
@@ -1542,6 +2061,43 @@ async function handleValidatePath(req, res) {
         json(res, { valid: false, error: err.message ?? String(err) }, 400);
     }
 }
+// ── Directory browse helper ─────────────────────────────
+async function handleBrowseDir(req, res) {
+    try {
+        const body = await readBody(req);
+        const { path: rawPath } = JSON.parse(body);
+        const resolved = (rawPath && typeof rawPath === 'string' ? rawPath : '~').replace(/^~/, (0, os_1.homedir)());
+        if (!(0, fs_1.existsSync)(resolved) || !(0, fs_1.statSync)(resolved).isDirectory()) {
+            json(res, { ok: false, error: 'Not a directory', path: resolved });
+            return;
+        }
+        let entries;
+        try {
+            entries = (0, fs_1.readdirSync)(resolved);
+        }
+        catch {
+            json(res, { ok: false, error: 'Cannot read directory', path: resolved });
+            return;
+        }
+        const dirs = [];
+        for (const entry of entries) {
+            if (entry.startsWith('.'))
+                continue; // skip dotfiles
+            const full = (0, path_1.join)(resolved, entry);
+            try {
+                if ((0, fs_1.statSync)(full).isDirectory()) {
+                    dirs.push({ name: entry, path: full });
+                }
+            }
+            catch { /* skip inaccessible */ }
+        }
+        dirs.sort((a, b) => a.name.localeCompare(b.name));
+        json(res, { ok: true, path: resolved, dirs });
+    }
+    catch (err) {
+        json(res, { ok: false, error: err.message ?? String(err) }, 400);
+    }
+}
 // ── Dataset stats helpers ───────────────────────────────
 function formatBytesUI(bytes) {
     if (bytes === 0)
@@ -1665,6 +2221,129 @@ async function handlePostDatasetScan(req, res) {
         json(res, { ok: false, error: err.message ?? String(err) }, 500);
     }
 }
+async function handlePostDatasetExampleInstall(req, res) {
+    try {
+        const body = await readBody(req);
+        let parsed = {};
+        if (body.trim()) {
+            try {
+                parsed = JSON.parse(body);
+            }
+            catch {
+                json(res, { ok: false, error: 'Invalid JSON body' }, 400);
+                return;
+            }
+        }
+        const requestedNameRaw = typeof parsed.name === 'string' ? parsed.name.trim() : '';
+        const datasetName = requestedNameRaw || IRIS_SAMPLE_DATASET_NAME;
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(datasetName)) {
+            json(res, {
+                ok: false,
+                error: 'Invalid dataset name. Use alphanumerics, hyphens, dots, underscores.',
+            }, 400);
+            return;
+        }
+        const datasetMode = parsed.mode === 'rw' ? 'rw' : 'ro';
+        const sourceUrl = resolveIrisSampleSourceUrl();
+        const configPath = (0, config_js_1.getConfigPath)();
+        let obj = {};
+        if ((0, fs_1.existsSync)(configPath)) {
+            const rawText = (0, fs_1.readFileSync)(configPath, 'utf-8');
+            const stripped = rawText
+                .split('\n')
+                .filter((line) => !line.trimStart().startsWith('//'))
+                .join('\n');
+            try {
+                obj = JSON.parse(stripped);
+            }
+            catch {
+                obj = {};
+            }
+        }
+        const datasets = Array.isArray(obj.datasets) ? obj.datasets : [];
+        const byNameConflict = datasets.find((d) => {
+            const n = typeof d.name === 'string' ? d.name : '';
+            return n.toLowerCase() === datasetName.toLowerCase();
+        });
+        if (byNameConflict) {
+            json(res, { ok: false, error: `Dataset "${datasetName}" is already registered.` }, 409);
+            return;
+        }
+        const datasetDir = (0, path_1.join)(config_js_1.LABGATE_DIR, 'datasets', datasetName);
+        const byPathConflict = datasets.find((d) => {
+            if (typeof d.path !== 'string')
+                return false;
+            return (0, path_1.resolve)(d.path.replace(/^~/, (0, os_1.homedir)())) === (0, path_1.resolve)(datasetDir);
+        });
+        if (byPathConflict) {
+            json(res, { ok: false, error: `Dataset path is already registered: ${datasetDir}` }, 409);
+            return;
+        }
+        const ctrl = new AbortController();
+        const timeout = setTimeout(() => ctrl.abort(), 20_000);
+        let csvText = '';
+        try {
+            const download = await fetch(sourceUrl, { signal: ctrl.signal });
+            if (!download.ok) {
+                json(res, { ok: false, error: `Failed to download sample dataset (HTTP ${download.status}).` }, 502);
+                return;
+            }
+            csvText = await download.text();
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+        if (!csvText.trim()) {
+            json(res, { ok: false, error: 'Downloaded sample dataset is empty.' }, 502);
+            return;
+        }
+        if (csvText.length > 5_000_000) {
+            json(res, { ok: false, error: 'Downloaded sample dataset is unexpectedly large.' }, 502);
+            return;
+        }
+        (0, fs_1.mkdirSync)(datasetDir, { recursive: true, mode: config_js_1.PRIVATE_DIR_MODE });
+        const csvPath = (0, path_1.join)(datasetDir, 'iris.csv');
+        const readmePath = (0, path_1.join)(datasetDir, 'README.md');
+        (0, fs_1.writeFileSync)(csvPath, csvText, { encoding: 'utf-8', mode: config_js_1.PRIVATE_FILE_MODE });
+        (0, fs_1.writeFileSync)(readmePath, IRIS_SAMPLE_README, { encoding: 'utf-8', mode: config_js_1.PRIVATE_FILE_MODE });
+        const totalSize = (0, fs_1.statSync)(csvPath).size + (0, fs_1.statSync)(readmePath).size;
+        const lineCount = csvText
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0)
+            .length;
+        const rowCount = Math.max(0, lineCount - 1);
+        const entry = {
+            path: datasetDir,
+            name: datasetName,
+            mode: datasetMode,
+            description: `Iris flower measurements sample dataset (${rowCount} rows).`,
+            stats: {
+                file_count: 2,
+                total_size: totalSize,
+                total_size_formatted: formatBytesUI(totalSize),
+                scanned_at: new Date().toISOString(),
+            },
+        };
+        datasets.push(entry);
+        obj.datasets = datasets;
+        (0, fs_1.writeFileSync)(configPath, JSON.stringify(obj, null, 2) + '\n', { encoding: 'utf-8', mode: config_js_1.PRIVATE_FILE_MODE });
+        (0, config_js_1.ensurePrivateFile)(configPath);
+        json(res, {
+            ok: true,
+            dataset: entry,
+            downloaded_from: sourceUrl,
+            files: ['iris.csv', 'README.md'],
+        }, 201);
+    }
+    catch (err) {
+        if (err?.name === 'AbortError') {
+            json(res, { ok: false, error: 'Timed out downloading sample dataset.' }, 504);
+            return;
+        }
+        json(res, { ok: false, error: err?.message ?? String(err) }, 500);
+    }
+}
 function handleGetLogs(_req, res) {
     const config = (0, config_js_1.loadConfig)();
     if (!config.audit.enabled) {
@@ -2788,6 +3467,34 @@ function handleGetAdminLicense(_req, res) {
     const status = (0, license_js_1.validateLicense)();
     json(res, { ok: true, license: status });
 }
+function upgradeUnauthorized(socket) {
+    try {
+        socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n');
+    }
+    catch {
+        // Best effort.
+    }
+    try {
+        socket.destroy();
+    }
+    catch {
+        // Best effort.
+    }
+}
+function upgradeBadRequest(socket) {
+    try {
+        socket.write('HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n');
+    }
+    catch {
+        // Best effort.
+    }
+    try {
+        socket.destroy();
+    }
+    catch {
+        // Best effort.
+    }
+}
 /**
  * Start the settings UI server.
  * Returns the HTTP server so callers can close it when done.
@@ -2812,6 +3519,71 @@ function startUI(optsOrPort = {}, standaloneArg = true) {
     if (!useTcp) {
         (0, config_js_1.ensurePrivateDir)((0, path_1.dirname)(socketPath));
     }
+    const wsServer = new ws_1.WebSocketServer({ noServer: true });
+    wsServer.on('connection', async (ws, req) => {
+        const reqUrl = new URL(req.url || '/', 'http://localhost');
+        const id = reqUrl.searchParams.get('id') || '';
+        const record = (0, web_terminal_js_1.readWebTerminalRecord)(id);
+        if (!record) {
+            sendWebTerminalMessage(ws, { type: 'error', error: 'Terminal session not found' });
+            ws.close();
+            return;
+        }
+        const bridge = await ensureWebTerminalBridge(record);
+        if (!bridge) {
+            sendWebTerminalMessage(ws, { type: 'error', error: 'Could not open terminal bridge' });
+            ws.close();
+            return;
+        }
+        bridge.clients.add(ws);
+        sendWebTerminalMessage(ws, {
+            type: 'status',
+            id: record.id,
+            status: record.status,
+            exitCode: record.exitCode,
+            error: record.error,
+        });
+        if (bridge.buffer) {
+            sendWebTerminalMessage(ws, { type: 'data', id: record.id, data: bridge.buffer });
+        }
+        ws.on('message', (raw) => {
+            let parsed;
+            try {
+                parsed = JSON.parse(raw.toString('utf-8'));
+            }
+            catch {
+                return;
+            }
+            const current = webTerminalBridges.get(id);
+            if (!current || !current.pty)
+                return;
+            if (parsed?.type === 'input' && typeof parsed.data === 'string') {
+                try {
+                    current.pty.write(parsed.data);
+                }
+                catch { /* best effort */ }
+                return;
+            }
+            if (parsed?.type === 'resize') {
+                const cols = Number(parsed.cols);
+                const rows = Number(parsed.rows);
+                if (!Number.isFinite(cols) || !Number.isFinite(rows))
+                    return;
+                try {
+                    current.pty.resize(Math.max(40, Math.min(Math.floor(cols), 300)), Math.max(10, Math.min(Math.floor(rows), 120)));
+                }
+                catch {
+                    // Best effort.
+                }
+            }
+        });
+        ws.on('close', () => {
+            bridge.clients.delete(ws);
+            if (bridge.clients.size === 0) {
+                stopWebTerminalBridge(bridge);
+            }
+        });
+    });
     const server = (0, http_1.createServer)(async (req, res) => {
         const url = req.url ?? '/';
         const reqUrl = new URL(url, 'http://localhost');
@@ -2892,12 +3664,18 @@ function startUI(optsOrPort = {}, standaloneArg = true) {
             else if (pathname === '/api/validate-path' && method === 'POST') {
                 await handleValidatePath(req, res);
             }
+            else if (pathname === '/api/browse-dir' && method === 'POST') {
+                await handleBrowseDir(req, res);
+            }
             else if (pathname === '/api/dataset-stats' && method === 'GET') {
                 handleGetDatasetStats(req, res);
             }
             else if (pathname === '/api/dataset-scan' && method === 'POST') {
                 await handlePostDatasetScan(req, res);
             }
+            else if (pathname === '/api/dataset-example/install' && method === 'POST') {
+                await handlePostDatasetExampleInstall(req, res);
+            }
             else if (/^\/api\/sessions\/[^/]+\/instructions$/.test(pathname) && method === 'GET') {
                 handleGetSessionInstructions(pathname, reqUrl, res);
             }
@@ -2910,6 +3688,9 @@ function startUI(optsOrPort = {}, standaloneArg = true) {
             else if (pathname === '/api/security' && method === 'GET') {
                 handleGetSecurity(req, res);
             }
+            else if (pathname === '/api/claude/auth' && method === 'GET') {
+                handleGetClaudeAuthStatus(req, res);
+            }
             else if (pathname === '/api/results' && method === 'GET') {
                 handleGetResults(reqUrl, res);
             }
@@ -2925,6 +3706,15 @@ function startUI(optsOrPort = {}, standaloneArg = true) {
             else if (/^\/api\/results\/([^/]+)$/.test(pathname) && method === 'DELETE') {
                 await handleDeleteResult(pathname, res);
             }
+            else if (pathname === '/api/terminal/sessions' && method === 'GET') {
+                await handleGetWebTerminalSessions(res);
+            }
+            else if (pathname === '/api/terminal/start' && method === 'POST') {
+                await handlePostWebTerminalStart(req, res);
+            }
+            else if (pathname === '/api/terminal/stop' && method === 'POST') {
+                await handlePostWebTerminalStop(req, res);
+            }
             else if (pathname === '/api/mcp' && method === 'GET') {
                 handleGetMcp(req, res);
             }
@@ -2981,6 +3771,18 @@ function startUI(optsOrPort = {}, standaloneArg = true) {
             else if (pathname.startsWith('/fonts/') && method === 'GET') {
                 serveFontFile(pathname, res);
             }
+            else if (pathname === '/vendor/xterm/xterm.css' && method === 'GET') {
+                serveVendorAsset(res, XTERM_CSS_PATH, 'text/css; charset=utf-8');
+            }
+            else if (pathname === '/vendor/xterm/xterm.js' && method === 'GET') {
+                serveVendorAsset(res, XTERM_JS_PATH, 'application/javascript; charset=utf-8');
+            }
+            else if (pathname === '/vendor/xterm/addon-fit.js' && method === 'GET') {
+                serveVendorAsset(res, XTERM_FIT_JS_PATH, 'application/javascript; charset=utf-8');
+            }
+            else if (pathname === '/vendor/xterm/addon-web-links.js' && method === 'GET') {
+                serveVendorAsset(res, XTERM_WEB_LINKS_JS_PATH, 'application/javascript; charset=utf-8');
+            }
             else {
                 if (pathname.startsWith('/api/')) {
                     json(res, { ok: false, error: 'Not found' }, 404);
@@ -3001,6 +3803,42 @@ function startUI(optsOrPort = {}, standaloneArg = true) {
             }
         }
     });
+    server.on('upgrade', (req, socket, head) => {
+        const reqUrl = new URL(req.url || '/', 'http://localhost');
+        if (reqUrl.pathname !== '/api/terminal/ws') {
+            upgradeBadRequest(socket);
+            return;
+        }
+        if (useTcp) {
+            const auth = isAuthorizedRequest(req, reqUrl, uiAccessToken);
+            if (!auth.ok) {
+                upgradeUnauthorized(socket);
+                return;
+            }
+        }
+        const writeToken = (reqUrl.searchParams.get('writeToken') || '').trim();
+        if (!writeToken || writeToken !== UI_WRITE_TOKEN) {
+            upgradeUnauthorized(socket);
+            return;
+        }
+        const id = (reqUrl.searchParams.get('id') || '').trim();
+        if (!(0, web_terminal_js_1.isValidWebTerminalId)(id)) {
+            upgradeBadRequest(socket);
+            return;
+        }
+        const record = (0, web_terminal_js_1.readWebTerminalRecord)(id);
+        if (!record) {
+            upgradeBadRequest(socket);
+            return;
+        }
+        if (record.node !== (0, os_1.hostname)()) {
+            upgradeBadRequest(socket);
+            return;
+        }
+        wsServer.handleUpgrade(req, socket, head, (ws) => {
+            wsServer.emit('connection', ws, req);
+        });
+    });
     const bindTcp = (nextPort) => {
         listenPort = nextPort;
         server.listen(listenPort, '127.0.0.1');
@@ -3021,15 +3859,17 @@ function startUI(optsOrPort = {}, standaloneArg = true) {
         started = true;
         if (useTcp) {
             const actualPort = server.address()?.port ?? listenPort;
-            log.step(`Settings: http://localhost:${actualPort}/?token=${uiAccessToken}`);
             dashboardQuickLink = `http://localhost:${actualPort}${UI_SHORT_LINK_PREFIX}${uiShortCode}`;
-            log.step(`Settings quick link: ${dashboardQuickLink}`);
+            log.step(`Settings: ${formatTerminalHyperlink(dashboardQuickLink)}`);
             try {
                 writeDashboardLink(dashboardQuickLink);
             }
             catch {
                 // Best effort: statusline can still fall back to LABGATE_DASHBOARD_URL/default URL.
             }
+            if (shouldAutoOpenUiBrowser(standalone)) {
+                autoOpenUiBrowser(dashboardQuickLink);
+            }
         }
         else {
             try {
@@ -3066,6 +3906,17 @@ function startUI(optsOrPort = {}, standaloneArg = true) {
     server.on('close', () => {
         if (dashboardQuickLink)
             clearDashboardLink(dashboardQuickLink);
+        for (const bridge of webTerminalBridges.values()) {
+            stopWebTerminalBridge(bridge);
+            for (const ws of bridge.clients) {
+                try {
+                    ws.close();
+                }
+                catch { /* best effort */ }
+            }
+        }
+        webTerminalBridges.clear();
+        wsServer.close();
     });
     server.on('error', (err) => {
         if (!useTcp && err.code === 'EADDRINUSE') {