labgate 0.5.31 → 0.5.33

package/dist/lib/ui.js

@@ -50,9 +50,13 @@ const audit_js_1 = require("./audit.js");
 const slurm_db_js_1 = require("./slurm-db.js");
 const slurm_poller_js_1 = require("./slurm-poller.js");
 const results_store_js_1 = require("./results-store.js");
+const display_store_js_1 = require("./display-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 explorer_js_1 = require("./explorer.js");
+const explorer_eval_js_1 = require("./explorer-eval.js");
+const explorer_store_js_1 = require("./explorer-store.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');
@@ -72,6 +76,9 @@ const IRIS_SAMPLE_DATASET_NAME = 'flowers-iris';
 const IRIS_SAMPLE_SOURCE_URL = 'https://raw.githubusercontent.com/mwaskom/seaborn-data/master/iris.csv';
 const PODMAN_SETUP_TIMEOUT_MS = 30 * 60 * 1000;
 const PODMAN_SETUP_MAX_BUFFER = 16 * 1024 * 1024;
+const EXPLORER_TSP_TEMPLATE_DIR = (0, path_1.resolve)(__dirname, '..', '..', 'templates', 'tsp-lab');
+const EXPLORER_TSP_TEMPLATE_SOURCE_REPO = (0, path_1.join)((0, config_js_1.getExplorerRootDir)(), 'templates', 'tsp-lab-source');
+const EXPLORER_ARTIFACT_READ_MAX_BYTES = 2 * 1024 * 1024;
 const IRIS_SAMPLE_README = '# Iris Flowers Dataset (Sample)\n' +
     '\n' +
     'Source: https://raw.githubusercontent.com/mwaskom/seaborn-data/master/iris.csv\n' +
@@ -88,6 +95,7 @@ function resolveIrisSampleSourceUrl() {
 let slurmDB = null;
 let slurmPoller = null;
 let resultsStore = null;
+let displayStore = null;
 const REQUIRED_SLURM_COMMANDS = ['sbatch', 'squeue', 'sacct', 'scancel'];
 const webTerminalBridges = new Map();
 const WEB_TERMINAL_INIT_RETENTION_MS = 60 * 60 * 1000;
@@ -116,6 +124,12 @@ function getResultsStore() {
     }
     return resultsStore;
 }
+function getDisplayStore() {
+    if (!displayStore) {
+        displayStore = new display_store_js_1.DisplayStore((0, config_js_1.getDisplayDbPath)());
+    }
+    return displayStore;
+}
 function hasCommandInPath(command) {
     const pathValue = (process.env.PATH || '').trim();
     if (!pathValue)
@@ -1017,6 +1031,13 @@ function readRecordString(record, key) {
     const value = record[key];
     return typeof value === 'string' ? value : '';
 }
+function normalizeToolUseId(value) {
+    if (typeof value === 'string')
+        return value.trim();
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    return '';
+}
 function collectClaudeTextFromContent(content) {
     if (!Array.isArray(content))
         return '';
@@ -1069,6 +1090,15 @@ function buildClaudeHeadlessApptainerArgs(config, workdir, prompt, resumeSession
     const sandboxHome = (0, config_js_1.getSandboxHome)();
     const sifPath = (0, path_1.join)((0, config_js_1.getImagesDir)(), (0, container_js_1.imageToSifName)(config.image));
     const resume = resumeSessionId.trim();
+    // Ensure display.json exists before bind-mounting it
+    const displayDbPath = (0, config_js_1.getDisplayDbPath)();
+    if (!(0, fs_1.existsSync)(displayDbPath)) {
+        (0, config_js_1.ensurePrivateDir)((0, path_1.dirname)(displayDbPath));
+        (0, fs_1.writeFileSync)(displayDbPath, JSON.stringify({ version: 1, events: [] }, null, 2) + '\n', {
+            encoding: 'utf-8',
+            mode: config_js_1.PRIVATE_FILE_MODE,
+        });
+    }
     return [
         'exec',
         '--containall',
@@ -1088,6 +1118,7 @@ function buildClaudeHeadlessApptainerArgs(config, workdir, prompt, resumeSession
             return ['--bind', bindSpec];
         }),
         ...((0, fs_1.existsSync)((0, config_js_1.getConfigPath)()) ? ['--bind', `${(0, config_js_1.getConfigPath)()}:/labgate-config/config.json`] : []),
+        '--bind', `${(0, config_js_1.getDisplayDbPath)()}:/labgate-config/display.json`,
         '--env', 'HOME=/home/sandbox',
         '--env', 'ANTHROPIC_API_KEY=',
         sifPath,
@@ -1164,27 +1195,32 @@ function closeWebTerminalBridgeClients(bridge, code = 4001, reason = 'labgate-br
 }
 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) {
+        if (existing && existing.pty) {
+            log.warn(`Could not resolve tmux binary for web terminal bridge ${record.id}: ${err?.message ?? String(err)}`);
+            return existing;
+        }
         log.warn(`Could not resolve tmux binary for web terminal bridge ${record.id}: ${err?.message ?? String(err)}`);
         return null;
     }
     try {
-        // Keep wheel scrolling intuitive for both new and existing sessions.
-        await execFileAsync(tmuxBin, ['set-option', '-t', record.tmuxSession, 'mouse', 'on'], { timeout: 10_000 });
+        // Keep web terminal copy/selection behavior reliable by letting xterm own
+        // mouse selection instead of tmux copy-mode selection.
+        await execFileAsync(tmuxBin, ['set-option', '-t', record.tmuxSession, 'mouse', 'off'], { timeout: 10_000 });
     }
     catch {
         // Best effort only; attach should still proceed.
     }
+    if (existing && existing.pty)
+        return existing;
+    const ptyModule = await loadNodePtyModule();
+    if (!ptyModule) {
+        return null;
+    }
     const env = {};
     for (const [k, v] of Object.entries(process.env)) {
         if (v !== undefined)
@@ -1345,7 +1381,6 @@ async function startClaudeHeadlessWsRun(ws, record, prompt, resumeSessionId) {
         return () => { };
     }
     const args = buildClaudeHeadlessApptainerArgs(config, record.workdir, trimmedPrompt, resumeSessionId);
-    send({ type: 'status', stage: 'run', message: 'Running Claude in headless mode...' });
     const child = (0, child_process_1.spawn)('apptainer', args, {
         cwd: record.workdir,
         env: process.env,
@@ -1356,6 +1391,7 @@ async function startClaudeHeadlessWsRun(ws, record, prompt, resumeSessionId) {
     let latestClaudeSessionId = resumeSessionId.trim();
     let emittedAssistantText = '';
     let doneSent = false;
+    let syntheticToolUseSeq = 0;
     const sendDone = (exitCode) => {
         if (doneSent)
             return;
@@ -1406,6 +1442,53 @@ async function startClaudeHeadlessWsRun(ws, record, prompt, resumeSessionId) {
                     send({ type: 'delta', text: delta });
                 }
             }
+            // Forward tool_use events from assistant messages
+            const eventType = readRecordString(event, 'type').trim().toLowerCase();
+            if (eventType === 'assistant') {
+                const msgContent = event.message?.content;
+                if (Array.isArray(msgContent)) {
+                    for (const block of msgContent) {
+                        if (block && typeof block === 'object' && !Array.isArray(block) && block.type === 'tool_use') {
+                            const toolBlock = block;
+                            const toolName = String(toolBlock.name || 'tool');
+                            const detail = extractToolDetailFromToolUseBlock(toolBlock);
+                            const toolUseId = normalizeToolUseId(toolBlock.id) || `tool-${Date.now().toString(36)}-${(++syntheticToolUseSeq).toString(36)}`;
+                            // Intercept display_widget calls and forward rich content payload
+                            if (toolName === 'display_widget') {
+                                const input = toolBlock.input;
+                                if (input && typeof input.widget === 'string') {
+                                    send({
+                                        type: 'rich_content',
+                                        widget: String(input.widget),
+                                        title: input.title ? String(input.title) : undefined,
+                                        data: (input.data && typeof input.data === 'object') ? input.data : {},
+                                        id: toolUseId,
+                                    });
+                                }
+                            }
+                            // Always also send the normal tool_use card
+                            send({ type: 'tool_use', tool_use_id: toolUseId, name: toolName, detail });
+                        }
+                    }
+                }
+            }
+            // Forward tool_result events (indicates tool execution completed)
+            if (eventType === 'user') {
+                const msgContent = event.message?.content;
+                if (Array.isArray(msgContent)) {
+                    for (const block of msgContent) {
+                        if (block && typeof block === 'object' && !Array.isArray(block) && block.type === 'tool_result') {
+                            const resultBlock = block;
+                            const toolUseId = normalizeToolUseId(resultBlock.tool_use_id);
+                            send({
+                                type: 'tool_result',
+                                tool_use_id: toolUseId || undefined,
+                                is_error: !!resultBlock.is_error,
+                            });
+                        }
+                    }
+                }
+            }
             if (isClaudeAuthenticationFailure(event, snapshot, stderrBuffer)) {
                 send({
                     type: 'auth_required',
@@ -2248,6 +2331,39 @@ function findProjectJsonlFiles(agent) {
 /**
  * Extract a human-readable detail string from a JSONL entry's tool_use blocks.
  */
+function extractToolDetailFromToolUseBlock(block) {
+    const name = String(block.name || '');
+    const inputRaw = block.input;
+    const input = inputRaw && typeof inputRaw === 'object' && !Array.isArray(inputRaw)
+        ? inputRaw
+        : {};
+    if (name === 'Bash' || name === 'bash') {
+        const cmd = String(input.command || '').slice(0, 60);
+        return cmd ? `Ran \`${cmd}\`` : 'Running Bash';
+    }
+    if (name === 'Edit' || name === 'edit') {
+        const file = String(input.file_path || '').split('/').pop() || '';
+        return file ? `Edited ${file}` : 'Editing a file';
+    }
+    if (name === 'Read' || name === 'read') {
+        const file = String(input.file_path || '').split('/').pop() || '';
+        return file ? `Read ${file}` : 'Reading a file';
+    }
+    if (name === 'Write' || name === 'write') {
+        const file = String(input.file_path || '').split('/').pop() || '';
+        return file ? `Wrote ${file}` : 'Writing a file';
+    }
+    if (name === 'Grep' || name === 'grep') {
+        return `Searching for "${String(input.pattern || '').slice(0, 40)}"`;
+    }
+    if (name === 'Glob' || name === 'glob') {
+        return `Finding files: ${String(input.pattern || '').slice(0, 40)}`;
+    }
+    if (name === 'Task' || name === 'task') {
+        return 'Spawned subagent';
+    }
+    return `Using ${name}`;
+}
 function extractToolDetail(entry) {
     if (!entry.message?.content)
         return '';
@@ -2255,35 +2371,8 @@ function extractToolDetail(entry) {
     if (!Array.isArray(content))
         return '';
     for (const block of content) {
-        if (block.type === 'tool_use') {
-            const name = block.name || '';
-            const input = block.input || {};
-            if (name === 'Bash' || name === 'bash') {
-                const cmd = (input.command || '').slice(0, 60);
-                return cmd ? `Ran \`${cmd}\`` : `Running Bash`;
-            }
-            if (name === 'Edit' || name === 'edit') {
-                const file = (input.file_path || '').split('/').pop() || '';
-                return file ? `Edited ${file}` : 'Editing a file';
-            }
-            if (name === 'Read' || name === 'read') {
-                const file = (input.file_path || '').split('/').pop() || '';
-                return file ? `Read ${file}` : 'Reading a file';
-            }
-            if (name === 'Write' || name === 'write') {
-                const file = (input.file_path || '').split('/').pop() || '';
-                return file ? `Wrote ${file}` : 'Writing a file';
-            }
-            if (name === 'Grep' || name === 'grep') {
-                return `Searching for "${(input.pattern || '').slice(0, 40)}"`;
-            }
-            if (name === 'Glob' || name === 'glob') {
-                return `Finding files: ${(input.pattern || '').slice(0, 40)}`;
-            }
-            if (name === 'Task' || name === 'task') {
-                return `Spawned subagent`;
-            }
-            return `Using ${name}`;
+        if (block && typeof block === 'object' && !Array.isArray(block) && block.type === 'tool_use') {
+            return extractToolDetailFromToolUseBlock(block);
         }
     }
     return '';
@@ -3588,6 +3677,8 @@ function mapContainerPathToHost(path, sandboxHome) {
         return (0, config_js_1.getSlurmDbPath)();
     if (path === '/labgate-config/results.json')
         return (0, config_js_1.getResultsDbPath)();
+    if (path === '/labgate-config/display.json')
+        return (0, config_js_1.getDisplayDbPath)();
     return path;
 }
 function readMcpConfigData() {
@@ -4424,6 +4515,88 @@ function startResultsWatcher() {
         resultsWatcher = null;
     }
 }
+// ── Display (widgets) file watcher ──
+const DISPLAY_WATCH_DEBOUNCE_MS = 120;
+let lastDisplaySignature = getDisplayFileSignature();
+let displayWatcher = null;
+let displayWatchDebounce = null;
+function getDisplayFileSignature() {
+    const displayPath = (0, config_js_1.getDisplayDbPath)();
+    try {
+        if (!(0, fs_1.existsSync)(displayPath))
+            return 'missing';
+        const st = (0, fs_1.statSync)(displayPath);
+        return `${st.size}:${Math.floor(st.mtimeMs)}`;
+    }
+    catch {
+        return 'error';
+    }
+}
+function maybeBroadcastWidgetsChanged() {
+    const signature = getDisplayFileSignature();
+    if (signature === lastDisplaySignature)
+        return;
+    if (sseClients.size === 0)
+        return;
+    lastDisplaySignature = signature;
+    broadcastSSE('widgets_changed', {
+        changed_at: new Date().toISOString(),
+        signature,
+    });
+}
+function scheduleDisplayChangeCheck(delayMs = DISPLAY_WATCH_DEBOUNCE_MS) {
+    if (displayWatchDebounce) {
+        clearTimeout(displayWatchDebounce);
+    }
+    displayWatchDebounce = setTimeout(() => {
+        displayWatchDebounce = null;
+        maybeBroadcastWidgetsChanged();
+    }, delayMs);
+    displayWatchDebounce.unref?.();
+}
+function stopDisplayWatcher() {
+    if (displayWatchDebounce) {
+        clearTimeout(displayWatchDebounce);
+        displayWatchDebounce = null;
+    }
+    if (displayWatcher) {
+        try {
+            displayWatcher.close();
+        }
+        catch {
+            // Best effort.
+        }
+        displayWatcher = null;
+    }
+}
+function startDisplayWatcher() {
+    if (displayWatcher)
+        return;
+    lastDisplaySignature = getDisplayFileSignature();
+    const displayPath = (0, config_js_1.getDisplayDbPath)();
+    const watchDir = (0, path_1.dirname)(displayPath);
+    const watchFile = (0, path_1.basename)(displayPath);
+    try {
+        (0, config_js_1.ensurePrivateDir)(watchDir);
+    }
+    catch {
+        // Best effort.
+    }
+    try {
+        displayWatcher = (0, fs_1.watch)(watchDir, (_eventType, filename) => {
+            const changed = filename ? String(filename) : '';
+            if (changed && changed !== watchFile)
+                return;
+            scheduleDisplayChangeCheck();
+        });
+        displayWatcher.on('error', () => {
+            stopDisplayWatcher();
+        });
+    }
+    catch {
+        displayWatcher = null;
+    }
+}
 function handleSSE(_req, res) {
     res.writeHead(200, {
         'Content-Type': 'text/event-stream',
@@ -4452,6 +4625,7 @@ function startSSEBroadcast() {
     if (sseInterval)
         return;
     startResultsWatcher();
+    startDisplayWatcher();
     sseInterval = setInterval(async () => {
         if (sseClients.size === 0)
             return;
@@ -4727,6 +4901,648 @@ function handleGetAdminLicense(_req, res) {
     const status = (0, license_js_1.validateLicense)();
     json(res, { ok: true, license: status });
 }
+// ── Display file endpoint ────────────────────────────────
+// Serves files from the container filesystem to the browser for display widgets.
+// Maps container paths to host paths using the same mount logic as the session.
+function resolveDisplayFilePath(containerPath) {
+    const config = (0, config_js_1.loadConfig)();
+    const sandboxHome = (0, config_js_1.getSandboxHome)();
+    // /home/sandbox/... → sandbox home
+    if (containerPath.startsWith('/home/sandbox/')) {
+        return (0, path_1.join)(sandboxHome, containerPath.slice('/home/sandbox/'.length));
+    }
+    // /datasets/<name>/... → dataset host path
+    const datasetMatch = containerPath.match(/^\/datasets\/([^/]+)\/(.+)$/);
+    if (datasetMatch) {
+        const [, dsName, rest] = datasetMatch;
+        const ds = (config.datasets || []).find((d) => d.name === dsName);
+        if (ds) {
+            const resolved = ds.path.replace(/^~/, (0, os_1.homedir)());
+            return (0, path_1.join)(resolved, rest);
+        }
+    }
+    // /work/... → workdir from active sessions
+    if (containerPath.startsWith('/work/')) {
+        const rest = containerPath.slice('/work/'.length);
+        // Check active session workdirs
+        try {
+            const sessionDir = (0, config_js_1.getSessionsDir)();
+            if ((0, fs_1.existsSync)(sessionDir)) {
+                const files = (0, fs_1.readdirSync)(sessionDir).filter((f) => f.endsWith('.json'));
+                for (const f of files) {
+                    try {
+                        const data = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(sessionDir, f), 'utf-8'));
+                        if (data.workdir) {
+                            const candidate = (0, path_1.join)(data.workdir, rest);
+                            if ((0, fs_1.existsSync)(candidate))
+                                return candidate;
+                        }
+                    }
+                    catch { /* skip */ }
+                }
+            }
+        }
+        catch { /* skip */ }
+    }
+    // /mnt/<basename>/... → extra_paths
+    const mntMatch = containerPath.match(/^\/mnt\/([^/]+)\/(.+)$/);
+    if (mntMatch) {
+        const [, mountBase, rest] = mntMatch;
+        const ep = config.filesystem.extra_paths.find((p) => {
+            const resolved = p.path.replace(/^~/, (0, os_1.homedir)());
+            return (0, path_1.basename)(resolved) === mountBase;
+        });
+        if (ep) {
+            const resolved = ep.path.replace(/^~/, (0, os_1.homedir)());
+            return (0, path_1.join)(resolved, rest);
+        }
+    }
+    return null;
+}
+function getContentTypeForFile(filePath) {
+    const ext = filePath.split('.').pop()?.toLowerCase() || '';
+    const mimeMap = {
+        png: 'image/png',
+        jpg: 'image/jpeg',
+        jpeg: 'image/jpeg',
+        gif: 'image/gif',
+        svg: 'image/svg+xml',
+        webp: 'image/webp',
+        pdf: 'application/pdf',
+        csv: 'text/csv',
+        tsv: 'text/tab-separated-values',
+        txt: 'text/plain',
+        json: 'application/json',
+        pdb: 'chemical/x-pdb',
+        cif: 'chemical/x-cif',
+        mmcif: 'chemical/x-mmcif',
+        fasta: 'text/plain',
+        fa: 'text/plain',
+        fastq: 'text/plain',
+        fq: 'text/plain',
+        html: 'text/html',
+        xml: 'application/xml',
+    };
+    return mimeMap[ext] || 'application/octet-stream';
+}
+function handleDisplayFile(reqUrl, res) {
+    const containerPath = reqUrl.searchParams.get('path');
+    if (!containerPath) {
+        json(res, { ok: false, error: 'Missing path parameter' }, 400);
+        return;
+    }
+    // Prevent directory traversal
+    if (containerPath.includes('..') || containerPath.includes('\0')) {
+        json(res, { ok: false, error: 'Invalid path' }, 400);
+        return;
+    }
+    const hostPath = resolveDisplayFilePath(containerPath);
+    if (!hostPath) {
+        json(res, { ok: false, error: 'Path not within any allowed mount' }, 404);
+        return;
+    }
+    // Verify the resolved path doesn't escape via symlinks
+    let realPath;
+    try {
+        realPath = (0, fs_1.realpathSync)(hostPath);
+    }
+    catch {
+        json(res, { ok: false, error: 'File not found' }, 404);
+        return;
+    }
+    try {
+        const stat = (0, fs_1.statSync)(realPath);
+        if (!stat.isFile()) {
+            json(res, { ok: false, error: 'Not a file' }, 400);
+            return;
+        }
+        // Limit to 50MB
+        if (stat.size > 50 * 1024 * 1024) {
+            json(res, { ok: false, error: 'File too large (max 50MB)' }, 413);
+            return;
+        }
+        const contentType = getContentTypeForFile(realPath);
+        const data = (0, fs_1.readFileSync)(realPath);
+        res.writeHead(200, {
+            'Content-Type': contentType,
+            'Content-Length': data.length,
+            'Cache-Control': 'no-cache',
+        });
+        res.end(data);
+    }
+    catch {
+        json(res, { ok: false, error: 'Failed to read file' }, 500);
+    }
+}
+function handleGetWidgets(res) {
+    try {
+        const store = getDisplayStore();
+        const widgets = store.listEvents();
+        json(res, { ok: true, widgets });
+    }
+    catch (err) {
+        json(res, { ok: false, error: err.message || 'Failed to list widgets' }, 500);
+    }
+}
+function handleClearWidgets(res) {
+    try {
+        const store = getDisplayStore();
+        store.clearEvents();
+        json(res, { ok: true });
+    }
+    catch (err) {
+        json(res, { ok: false, error: err.message || 'Failed to clear widgets' }, 500);
+    }
+}
+function parseExplorerExperimentId(reqUrl) {
+    return String(reqUrl.searchParams.get('experiment_id') || '').trim();
+}
+function parseExplorerRunId(reqUrl) {
+    return String(reqUrl.searchParams.get('run_id') || '').trim();
+}
+function parseExplorerListInt(raw, fallback, min, max) {
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed))
+        return fallback;
+    return Math.max(min, Math.min(max, Math.floor(parsed)));
+}
+async function ensureExplorerQuickstartSourceRepo() {
+    if (!(0, fs_1.existsSync)(EXPLORER_TSP_TEMPLATE_DIR)) {
+        throw new Error(`Bundled template not found: ${EXPLORER_TSP_TEMPLATE_DIR}`);
+    }
+    const gitDir = (0, path_1.join)(EXPLORER_TSP_TEMPLATE_SOURCE_REPO, '.git');
+    if ((0, fs_1.existsSync)(gitDir))
+        return EXPLORER_TSP_TEMPLATE_SOURCE_REPO;
+    (0, config_js_1.ensurePrivateDir)((0, path_1.dirname)(EXPLORER_TSP_TEMPLATE_SOURCE_REPO));
+    (0, fs_1.mkdirSync)(EXPLORER_TSP_TEMPLATE_SOURCE_REPO, { recursive: true, mode: config_js_1.PRIVATE_DIR_MODE });
+    (0, fs_1.cpSync)(EXPLORER_TSP_TEMPLATE_DIR, EXPLORER_TSP_TEMPLATE_SOURCE_REPO, { recursive: true, force: true });
+    await execFileAsync('git', ['init', '.'], { cwd: EXPLORER_TSP_TEMPLATE_SOURCE_REPO });
+    await execFileAsync('git', ['add', '.'], { cwd: EXPLORER_TSP_TEMPLATE_SOURCE_REPO });
+    try {
+        await execFileAsync('git', ['-c', 'user.name=labgate-ui', '-c', 'user.email=labgate@local', 'commit', '-m', 'template baseline'], { cwd: EXPLORER_TSP_TEMPLATE_SOURCE_REPO });
+    }
+    catch (err) {
+        const detail = commandErrorDetail(err);
+        if (!/nothing to commit/i.test(detail)) {
+            throw err;
+        }
+    }
+    return EXPLORER_TSP_TEMPLATE_SOURCE_REPO;
+}
+async function parseExplorerQuickstartInput(body) {
+    const nameInput = String(body.name || '').trim();
+    const experimentName = nameInput || `TSP Demo ${new Date().toISOString().slice(0, 19).replace('T', ' ')}`;
+    const modeRaw = String(body.agent_mode || 'stub').trim().toLowerCase();
+    const agentMode = modeRaw === 'claude' ? 'claude_headless' : (modeRaw || 'stub');
+    if (agentMode !== 'stub' && agentMode !== 'claude_headless') {
+        throw new Error('agent_mode must be stub or claude_headless');
+    }
+    const claudeResumeSessionId = String(body.claude_resume_session_id || '').trim();
+    const claudeTimeoutRaw = body.claude_timeout_sec;
+    const claudeTimeout = Number(claudeTimeoutRaw);
+    if (claudeTimeoutRaw !== undefined &&
+        (!Number.isFinite(claudeTimeout) || claudeTimeout < 60 || claudeTimeout > 14_400)) {
+        throw new Error('claude_timeout_sec must be between 60 and 14400');
+    }
+    const sourceRepoInput = String(body.source_repo_path || '').trim();
+    const sourceRepoPath = sourceRepoInput
+        ? (0, path_1.resolve)(sourceRepoInput)
+        : await ensureExplorerQuickstartSourceRepo();
+    if (!(0, fs_1.existsSync)(sourceRepoPath)) {
+        throw new Error(`source_repo_path not found: ${sourceRepoPath}`);
+    }
+    const evalCommand = String(body.eval_command || 'python3 eval.py').trim() || 'python3 eval.py';
+    const timeoutRaw = body.eval_timeout_sec;
+    const evalTimeoutSec = timeoutRaw === undefined ? 30 : Number(timeoutRaw);
+    if (!Number.isFinite(evalTimeoutSec) || evalTimeoutSec < 5 || evalTimeoutSec > 86_400) {
+        throw new Error('eval_timeout_sec must be between 5 and 86400');
+    }
+    const policy = {
+        epsilon: 0.15,
+        top_n: 5,
+        agent_mode: agentMode,
+    };
+    if (agentMode === 'stub') {
+        policy.stub_patch_file = 'stub-patches/enable_two_opt.patch';
+    }
+    else {
+        if (claudeResumeSessionId)
+            policy.claude_resume_session_id = claudeResumeSessionId;
+        if (claudeTimeoutRaw !== undefined)
+            policy.claude_timeout_sec = Math.floor(claudeTimeout);
+    }
+    return {
+        experimentName,
+        sourceRepoPath,
+        evalCommand,
+        evalTimeoutSec: Math.floor(evalTimeoutSec),
+        policy,
+    };
+}
+function handleGetExplorerExperiments(reqUrl, res) {
+    const limit = parseExplorerListInt(reqUrl.searchParams.get('limit'), 20, 1, 500);
+    const offset = parseExplorerListInt(reqUrl.searchParams.get('offset'), 0, 0, 100_000);
+    const store = new explorer_store_js_1.ExplorerStore();
+    try {
+        const experiments = store.listExperiments(limit, offset);
+        json(res, {
+            ok: true,
+            experiments,
+            returned: experiments.length,
+            limit,
+            offset,
+        });
+    }
+    catch (err) {
+        json(res, { ok: false, error: err?.message || String(err) }, 500);
+    }
+    finally {
+        store.close();
+    }
+}
+function handleGetExplorerOverview(reqUrl, res) {
+    const experimentId = parseExplorerExperimentId(reqUrl);
+    if (!experimentId) {
+        json(res, { ok: false, error: 'Missing experiment_id' }, 400);
+        return;
+    }
+    try {
+        const overview = (0, explorer_js_1.getExperimentOverview)(experimentId);
+        if (!overview) {
+            json(res, { ok: false, error: 'Experiment not found' }, 404);
+            return;
+        }
+        json(res, { ok: true, overview });
+    }
+    catch (err) {
+        json(res, { ok: false, error: err?.message || String(err) }, 500);
+    }
+}
+function handleGetExplorerTree(reqUrl, res) {
+    const experimentId = parseExplorerExperimentId(reqUrl);
+    if (!experimentId) {
+        json(res, { ok: false, error: 'Missing experiment_id' }, 400);
+        return;
+    }
+    const mode = String(reqUrl.searchParams.get('mode') || 'best_path').trim() === 'full' ? 'full' : 'best_path';
+    try {
+        const tree = (0, explorer_js_1.getExperimentTree)(experimentId, mode);
+        json(res, { ok: true, tree });
+    }
+    catch (err) {
+        json(res, { ok: false, error: err?.message || String(err) }, 500);
+    }
+}
+function handleGetExplorerRuns(reqUrl, res) {
+    const experimentId = parseExplorerExperimentId(reqUrl);
+    if (!experimentId) {
+        json(res, { ok: false, error: 'Missing experiment_id' }, 400);
+        return;
+    }
+    const limit = parseExplorerListInt(reqUrl.searchParams.get('limit'), 20, 1, 500);
+    const offset = parseExplorerListInt(reqUrl.searchParams.get('offset'), 0, 0, 100_000);
+    const store = new explorer_store_js_1.ExplorerStore();
+    try {
+        const runs = store.listRuns(experimentId, { limit, offset });
+        const total = store.getRunCount(experimentId);
+        json(res, { ok: true, runs, total, returned: runs.length, limit, offset });
+    }
+    catch (err) {
+        json(res, { ok: false, error: err?.message || String(err) }, 500);
+    }
+    finally {
+        store.close();
+    }
+}
+function handleGetExplorerRun(reqUrl, res) {
+    const runId = parseExplorerRunId(reqUrl);
+    if (!runId) {
+        json(res, { ok: false, error: 'Missing run_id' }, 400);
+        return;
+    }
+    try {
+        const details = (0, explorer_js_1.getRunDetails)(runId);
+        if (!details) {
+            json(res, { ok: false, error: 'Run not found' }, 404);
+            return;
+        }
+        json(res, { ok: true, details });
+    }
+    catch (err) {
+        json(res, { ok: false, error: err?.message || String(err) }, 500);
+    }
+}
+function handleGetExplorerCompare(reqUrl, res) {
+    const experimentId = parseExplorerExperimentId(reqUrl);
+    const runId = parseExplorerRunId(reqUrl);
+    if (!experimentId || !runId) {
+        json(res, { ok: false, error: 'Missing experiment_id or run_id' }, 400);
+        return;
+    }
+    const compareTo = String(reqUrl.searchParams.get('to') || 'best').trim() || 'best';
+    const includePatch = reqUrl.searchParams.get('include_patch') === '1';
+    try {
+        const comparison = (0, explorer_js_1.compareRun)({
+            experiment_id: experimentId,
+            run_id: runId,
+            compare_to: compareTo,
+            include_patch: includePatch,
+        });
+        json(res, { ok: true, comparison });
+    }
+    catch (err) {
+        json(res, { ok: false, error: err?.message || String(err) }, 500);
+    }
+}
+function handleGetExplorerArtifact(reqUrl, res) {
+    const runId = parseExplorerRunId(reqUrl);
+    if (!runId) {
+        json(res, { ok: false, error: 'Missing run_id' }, 400);
+        return;
+    }
+    const kind = String(reqUrl.searchParams.get('kind') || 'summary').trim().toLowerCase();
+    if (!['summary', 'diff', 'stdout', 'stderr', 'eval', 'agent', 'claude_stdout', 'claude_stderr'].includes(kind)) {
+        json(res, { ok: false, error: 'Invalid kind (expected summary|diff|stdout|stderr|eval|agent|claude_stdout|claude_stderr)' }, 400);
+        return;
+    }
+    const details = (0, explorer_js_1.getRunDetails)(runId);
+    if (!details) {
+        json(res, { ok: false, error: 'Run not found' }, 404);
+        return;
+    }
+    const artifacts = details.artifacts;
+    const pathByKind = {
+        summary: artifacts.summary_path,
+        diff: artifacts.diff_path,
+        stdout: artifacts.stdout_path,
+        stderr: artifacts.stderr_path,
+        eval: artifacts.eval_json_path,
+        agent: artifacts.agent_log_path,
+        claude_stdout: artifacts.claude_stdout_path,
+        claude_stderr: artifacts.claude_stderr_path,
+    };
+    const availableByKind = {
+        summary: artifacts.available.summary,
+        diff: artifacts.available.diff,
+        stdout: artifacts.available.stdout,
+        stderr: artifacts.available.stderr,
+        eval: artifacts.available.eval_json,
+        agent: artifacts.available.agent_log,
+        claude_stdout: artifacts.available.claude_stdout,
+        claude_stderr: artifacts.available.claude_stderr,
+    };
+    const filePath = pathByKind[kind];
+    if (!filePath || !availableByKind[kind] || !(0, fs_1.existsSync)(filePath)) {
+        json(res, {
+            ok: false,
+            error: 'Artifact missing (possibly pruned)',
+            artifacts_pruned: artifacts.artifacts_pruned,
+            worktree_pruned: artifacts.worktree_pruned,
+        }, 404);
+        return;
+    }
+    try {
+        const st = (0, fs_1.statSync)(filePath);
+        if (!st.isFile()) {
+            json(res, { ok: false, error: 'Artifact is not a file' }, 400);
+            return;
+        }
+        const readBytes = Math.min(st.size, EXPLORER_ARTIFACT_READ_MAX_BYTES);
+        const offset = Math.max(0, st.size - readBytes);
+        const fd = (0, fs_1.openSync)(filePath, 'r');
+        const buf = Buffer.alloc(readBytes);
+        try {
+            (0, fs_1.readSync)(fd, buf, 0, readBytes, offset);
+        }
+        finally {
+            (0, fs_1.closeSync)(fd);
+        }
+        let text = buf.toString('utf-8');
+        if (offset > 0) {
+            const firstNewline = text.indexOf('\n');
+            if (firstNewline >= 0)
+                text = text.slice(firstNewline + 1);
+        }
+        if (kind === 'eval') {
+            let parsedEval = null;
+            try {
+                parsedEval = JSON.parse(text);
+            }
+            catch {
+                parsedEval = null;
+            }
+            json(res, {
+                ok: true,
+                kind,
+                path: filePath,
+                size: st.size,
+                truncated: st.size > readBytes,
+                eval: parsedEval,
+                raw: text,
+            });
+            return;
+        }
+        json(res, {
+            ok: true,
+            kind,
+            path: filePath,
+            size: st.size,
+            truncated: st.size > readBytes,
+            text,
+        });
+    }
+    catch (err) {
+        json(res, { ok: false, error: err?.message || String(err) }, 500);
+    }
+}
+async function handlePostExplorerQuickstart(req, res) {
+    try {
+        let body = {};
+        try {
+            body = JSON.parse(await readBody(req) || '{}');
+        }
+        catch {
+            body = {};
+        }
+        const input = await parseExplorerQuickstartInput(body);
+        const experiment = (0, explorer_js_1.createExplorerExperiment)({
+            name: input.experimentName,
+            source_repo_path: input.sourceRepoPath,
+            eval_command: input.evalCommand,
+            eval_timeout_sec: input.evalTimeoutSec,
+            policy: input.policy,
+            retention: {
+                keep_worktrees: false,
+                artifacts: 'minimal',
+                keep_last_n: 50,
+                keep_best: true,
+                keep_failed_last_n: 20,
+                max_delete_runs: 200,
+            },
+        });
+        const baselineArtifactDir = (0, config_js_1.getExplorerArtifactDir)(experiment.id, 'baseline');
+        const baseline = (0, explorer_eval_js_1.runEvaluation)({
+            worktree_path: experiment.repo_path,
+            eval_command: experiment.eval_command,
+            timeout_sec: experiment.eval_timeout_sec,
+            artifact_dir: baselineArtifactDir,
+        });
+        const store = new explorer_store_js_1.ExplorerStore();
+        try {
+            store.createEvent(experiment.id, 'note', {
+                message: 'baseline evaluation',
+                status: baseline.status,
+                score: baseline.score ?? null,
+                artifact_dir: baselineArtifactDir,
+                error: baseline.error || null,
+            });
+        }
+        finally {
+            store.close();
+        }
+        const overview = (0, explorer_js_1.getExperimentOverview)(experiment.id);
+        json(res, {
+            ok: true,
+            experiment,
+            baseline: {
+                status: baseline.status,
+                score: baseline.score ?? null,
+                error: baseline.error || null,
+                artifact_dir: baselineArtifactDir,
+            },
+            overview,
+        });
+    }
+    catch (err) {
+        const message = err?.message || String(err);
+        const status = /must be|not found/i.test(message) ? 400 : 500;
+        json(res, { ok: false, error: message }, status);
+    }
+}
+async function handlePostExplorerRegister(req, res) {
+    try {
+        let body = {};
+        try {
+            body = JSON.parse(await readBody(req) || '{}');
+        }
+        catch {
+            body = {};
+        }
+        const input = await parseExplorerQuickstartInput(body);
+        const experiment = (0, explorer_js_1.createExplorerExperiment)({
+            name: input.experimentName,
+            source_repo_path: input.sourceRepoPath,
+            eval_command: input.evalCommand,
+            eval_timeout_sec: input.evalTimeoutSec,
+            policy: input.policy,
+            retention: {
+                keep_worktrees: false,
+                artifacts: 'minimal',
+                keep_last_n: 50,
+                keep_best: true,
+                keep_failed_last_n: 20,
+                max_delete_runs: 200,
+            },
+        });
+        const overview = (0, explorer_js_1.getExperimentOverview)(experiment.id);
+        json(res, {
+            ok: true,
+            experiment,
+            overview,
+            flow: {
+                tool: 'experiment_register',
+                initialized: false,
+            },
+        });
+    }
+    catch (err) {
+        const message = err?.message || String(err);
+        const status = /must be|not found/i.test(message) ? 400 : 500;
+        json(res, { ok: false, error: message }, status);
+    }
+}
+async function handlePostExplorerInit(req, res) {
+    try {
+        let body = {};
+        try {
+            body = JSON.parse(await readBody(req) || '{}');
+        }
+        catch {
+            body = {};
+        }
+        const experimentId = String(body.experiment_id || '').trim();
+        if (!experimentId) {
+            json(res, { ok: false, error: 'Missing experiment_id' }, 400);
+            return;
+        }
+        const store = new explorer_store_js_1.ExplorerStore();
+        try {
+            const experiment = store.getExperiment(experimentId);
+            if (!experiment) {
+                json(res, { ok: false, error: 'Experiment not found' }, 404);
+                return;
+            }
+            const baselineArtifactDir = (0, config_js_1.getExplorerArtifactDir)(experiment.id, 'baseline');
+            const baseline = (0, explorer_eval_js_1.runEvaluation)({
+                worktree_path: experiment.repo_path,
+                eval_command: experiment.eval_command,
+                timeout_sec: experiment.eval_timeout_sec,
+                artifact_dir: baselineArtifactDir,
+            });
+            store.createEvent(experiment.id, 'note', {
+                message: 'experiment initialized with baseline evaluation',
+                status: baseline.status,
+                score: baseline.score ?? null,
+                artifact_dir: baselineArtifactDir,
+                error: baseline.error || null,
+            });
+            const overview = (0, explorer_js_1.getExperimentOverview)(experiment.id, store);
+            json(res, {
+                ok: true,
+                experiment,
+                baseline: {
+                    status: baseline.status,
+                    score: baseline.score ?? null,
+                    error: baseline.error || null,
+                    artifact_dir: baselineArtifactDir,
+                },
+                overview,
+                flow: {
+                    tool: 'experiment_init',
+                    initialized: true,
+                },
+            });
+        }
+        finally {
+            store.close();
+        }
+    }
+    catch (err) {
+        json(res, { ok: false, error: err?.message || String(err) }, 500);
+    }
+}
+async function handlePostExplorerTick(req, res) {
+    try {
+        let body = {};
+        try {
+            body = JSON.parse(await readBody(req) || '{}');
+        }
+        catch {
+            body = {};
+        }
+        const experimentId = String(body.experiment_id || '').trim();
+        if (!experimentId) {
+            json(res, { ok: false, error: 'Missing experiment_id' }, 400);
+            return;
+        }
+        const result = (0, explorer_js_1.runAutopilotTick)(experimentId);
+        const runDetails = result.run_id ? (0, explorer_js_1.getRunDetails)(result.run_id) : null;
+        json(res, { ok: true, result, run_details: runDetails });
+    }
+    catch (err) {
+        json(res, { ok: false, error: err?.message || String(err) }, 500);
+    }
+}
 function upgradeUnauthorized(socket) {
     try {
         socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n');
@@ -5123,6 +5939,54 @@ function startUI(optsOrPort = {}, standaloneArg = true) {
             else if (pathname === '/api/admin/license' && method === 'GET') {
                 handleGetAdminLicense(req, res);
             }
+            else if (pathname === '/api/explorer/experiments' && method === 'GET') {
+                handleGetExplorerExperiments(reqUrl, res);
+            }
+            else if (pathname === '/api/explorer/overview' && method === 'GET') {
+                handleGetExplorerOverview(reqUrl, res);
+            }
+            else if (pathname === '/api/explorer/tree' && method === 'GET') {
+                handleGetExplorerTree(reqUrl, res);
+            }
+            else if (pathname === '/api/explorer/runs' && method === 'GET') {
+                handleGetExplorerRuns(reqUrl, res);
+            }
+            else if (pathname === '/api/explorer/run' && method === 'GET') {
+                handleGetExplorerRun(reqUrl, res);
+            }
+            else if (pathname === '/api/explorer/compare' && method === 'GET') {
+                handleGetExplorerCompare(reqUrl, res);
+            }
+            else if (pathname === '/api/explorer/artifact' && method === 'GET') {
+                handleGetExplorerArtifact(reqUrl, res);
+            }
+            else if (pathname === '/api/explorer/register' && method === 'POST') {
+                await handlePostExplorerRegister(req, res);
+            }
+            else if (pathname === '/api/explorer/init' && method === 'POST') {
+                await handlePostExplorerInit(req, res);
+            }
+            else if (pathname === '/api/explorer/quickstart' && method === 'POST') {
+                await handlePostExplorerQuickstart(req, res);
+            }
+            else if (pathname === '/api/explorer/tick' && method === 'POST') {
+                await handlePostExplorerTick(req, res);
+            }
+            else if (pathname === '/api/explorer/step' && method === 'POST') {
+                await handlePostExplorerTick(req, res);
+            }
+            else if (pathname === '/api/explorer/go' && method === 'POST') {
+                await handlePostExplorerTick(req, res);
+            }
+            else if (pathname === '/api/display/file' && method === 'GET') {
+                handleDisplayFile(reqUrl, res);
+            }
+            else if (pathname === '/api/widgets' && method === 'GET') {
+                handleGetWidgets(res);
+            }
+            else if (pathname === '/api/widgets/clear' && method === 'POST') {
+                handleClearWidgets(res);
+            }
             else if (pathname.startsWith('/fonts/') && method === 'GET') {
                 serveFontFile(pathname, res);
             }
@@ -5278,7 +6142,8 @@ function startUI(optsOrPort = {}, standaloneArg = true) {
             }
             if (useTcp) {
                 const actualPort = server.address()?.port ?? listenPort;
-                dashboardQuickLink = `http://localhost:${actualPort}${UI_SHORT_LINK_PREFIX}${uiShortCode}`;
+                // Use an explicit IPv4 loopback host to avoid `localhost` IPv6 collisions on macOS.
+                dashboardQuickLink = `http://127.0.0.1:${actualPort}${UI_SHORT_LINK_PREFIX}${uiShortCode}`;
                 log.step(`Settings: ${formatTerminalHyperlink(dashboardQuickLink)}`);
                 try {
                     writeDashboardLink(dashboardQuickLink);
@@ -5387,6 +6252,7 @@ function startUI(optsOrPort = {}, standaloneArg = true) {
         }
         sseClients.clear();
         stopResultsWatcher();
+        stopDisplayWatcher();
         // Cleanup SLURM resources
         if (slurmPoller) {
             slurmPoller.stop();
@@ -5400,6 +6266,7 @@ function startUI(optsOrPort = {}, standaloneArg = true) {
             slurmDB = null;
         }
         resultsStore = null;
+        displayStore = null;
     });
     return server;
 }