labgate 0.5.29 → 0.5.31

package/dist/lib/ui.js

@@ -43,7 +43,9 @@ const util_1 = require("util");
 const crypto_1 = require("crypto");
 const ws_1 = require("ws");
 const config_js_1 = require("./config.js");
+const init_js_1 = require("./init.js");
 const container_js_1 = require("./container.js");
+const runtime_js_1 = require("./runtime.js");
 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");
@@ -68,6 +70,8 @@ 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 PODMAN_SETUP_TIMEOUT_MS = 30 * 60 * 1000;
+const PODMAN_SETUP_MAX_BUFFER = 16 * 1024 * 1024;
 const IRIS_SAMPLE_README = '# Iris Flowers Dataset (Sample)\n' +
     '\n' +
     'Source: https://raw.githubusercontent.com/mwaskom/seaborn-data/master/iris.csv\n' +
@@ -86,6 +90,26 @@ let slurmPoller = null;
 let resultsStore = null;
 const REQUIRED_SLURM_COMMANDS = ['sbatch', 'squeue', 'sacct', 'scancel'];
 const webTerminalBridges = new Map();
+const WEB_TERMINAL_INIT_RETENTION_MS = 60 * 60 * 1000;
+const WEB_TERMINAL_IMAGE_PULL_TIMEOUT_MS = 60 * 60 * 1000;
+const WEB_TERMINAL_IMAGE_PULL_MAX_BUFFER = 64 * 1024 * 1024;
+const WEB_TERMINAL_AGENT_PREP_TIMEOUT_MS = 30 * 60 * 1000;
+const WEB_TERMINAL_AGENT_PREP_MAX_BUFFER = 32 * 1024 * 1024;
+const WEB_TERMINAL_STARTUP_READY_TIMEOUT_MS = 90 * 1000;
+const WEB_TERMINAL_STARTUP_READY_POLL_MS = 120;
+const WEB_TERMINAL_STARTUP_READY_BUFFER_LIMIT = 64 * 1024;
+const WEB_TERMINAL_STARTUP_ALIVE_CHECK_MS = 750;
+const WEB_TERMINAL_BUFFER_MAX_BYTES = 512_000;
+const WEB_TERMINAL_HISTORY_MAX_BYTES = 8 * 1024 * 1024;
+const WEB_TERMINAL_HISTORY_CHUNK_BYTES = 8 * 1024;
+const WEB_TERMINAL_HISTORY_PAGE_DEFAULT = 120;
+const WEB_TERMINAL_HISTORY_PAGE_MAX = 600;
+const WEB_TERMINAL_STARTUP_HEADER_RE = /(?:^|\n)\s*LabGate\s*(?:\n|$)/i;
+const WEB_TERMINAL_STARTUP_BLOCKED_RE = /(?:^|\n)\s*Blocked\s+\d+\s+patterns\b/i;
+const CLAUDE_HEADLESS_STDERR_LIMIT = 12_000;
+const webTerminalInitJobs = new Map();
+const webTerminalImagePullLocks = new Map();
+const webTerminalAgentPrepLocks = new Map();
 function getResultsStore() {
     if (!resultsStore) {
         resultsStore = new results_store_js_1.ResultsStore((0, config_js_1.getResultsDbPath)());
@@ -136,6 +160,475 @@ function getSlurmRuntimeStatus() {
         missingCommands,
     };
 }
+function commandErrorDetail(err) {
+    return [
+        err?.stderr,
+        err?.stdout,
+        err?.message,
+        err?.cause?.stderr,
+        err?.cause?.stdout,
+        err?.cause?.message,
+    ]
+        .filter((part) => typeof part === 'string' && part.trim().length > 0)
+        .map((part) => String(part).trim())
+        .join('\n');
+}
+function isPodmanNotReadyError(error) {
+    return /podman is installed but not ready/i.test(error || '');
+}
+async function prepareRuntimeForWebTerminal(preferred) {
+    const initial = (0, runtime_js_1.checkRuntime)(preferred);
+    if (initial.ok) {
+        return { ok: true, initialized: false };
+    }
+    const canAutoSetupPodman = ((0, os_1.platform)() === 'darwin' &&
+        preferred !== 'apptainer' &&
+        hasCommandInPath('podman') &&
+        isPodmanNotReadyError(initial.error));
+    if (!canAutoSetupPodman) {
+        return {
+            ok: false,
+            initialized: false,
+            error: initial.error || 'Container runtime unavailable.',
+        };
+    }
+    log.step('Podman runtime not ready. Attempting automatic machine setup for UI launch...');
+    try {
+        try {
+            await execFileAsync('podman', ['machine', 'init'], {
+                timeout: PODMAN_SETUP_TIMEOUT_MS,
+                maxBuffer: PODMAN_SETUP_MAX_BUFFER,
+            });
+        }
+        catch (err) {
+            const detail = commandErrorDetail(err);
+            if (!/already exists/i.test(detail)) {
+                throw err;
+            }
+        }
+        await execFileAsync('podman', ['machine', 'start'], {
+            timeout: PODMAN_SETUP_TIMEOUT_MS,
+            maxBuffer: PODMAN_SETUP_MAX_BUFFER,
+        });
+    }
+    catch (err) {
+        const detail = commandErrorDetail(err);
+        return {
+            ok: false,
+            initialized: true,
+            error: [
+                'Podman setup failed during UI session launch.',
+                detail || 'Unknown Podman error.',
+                '',
+                'Try in a terminal:',
+                '  podman machine init',
+                '  podman machine start',
+            ].join('\n'),
+        };
+    }
+    const after = (0, runtime_js_1.checkRuntime)(preferred);
+    if (!after.ok) {
+        return {
+            ok: false,
+            initialized: true,
+            error: after.error || 'Container runtime unavailable after setup.',
+        };
+    }
+    return { ok: true, initialized: true };
+}
+function createWebTerminalInitId() {
+    return `wti-${Date.now().toString(36)}-${(0, crypto_1.randomBytes)(2).toString('hex')}`;
+}
+function createWebTerminalInitJob(agent, workdir) {
+    const now = new Date().toISOString();
+    return {
+        id: createWebTerminalInitId(),
+        agent,
+        workdir,
+        status: 'running',
+        stage: 'queued',
+        message: 'Queued session initialization.',
+        startedAt: now,
+        updatedAt: now,
+        session: null,
+        error: null,
+        code: null,
+        phase: null,
+        initialized: false,
+    };
+}
+function pruneWebTerminalInitJobs() {
+    const now = Date.now();
+    for (const [id, job] of webTerminalInitJobs.entries()) {
+        if (job.status === 'running')
+            continue;
+        const ageMs = now - Date.parse(job.updatedAt || job.startedAt || '');
+        if (Number.isFinite(ageMs) && ageMs > WEB_TERMINAL_INIT_RETENTION_MS) {
+            webTerminalInitJobs.delete(id);
+        }
+    }
+}
+function updateWebTerminalInitJob(id, patch) {
+    const existing = webTerminalInitJobs.get(id);
+    if (!existing)
+        return null;
+    const updated = {
+        ...existing,
+        ...patch,
+        updatedAt: new Date().toISOString(),
+    };
+    webTerminalInitJobs.set(id, updated);
+    return updated;
+}
+function serializeWebTerminalInitJob(job) {
+    return {
+        id: job.id,
+        agent: job.agent,
+        workdir: job.workdir,
+        status: job.status,
+        stage: job.stage,
+        message: job.message,
+        startedAt: job.startedAt,
+        updatedAt: job.updatedAt,
+        session: job.session,
+        error: job.error,
+        code: job.code,
+        phase: job.phase,
+        initialized: job.initialized,
+    };
+}
+async function withWebTerminalImagePullLock(lockKey, work) {
+    const existing = webTerminalImagePullLocks.get(lockKey);
+    if (existing) {
+        await existing;
+        return;
+    }
+    let current = null;
+    current = (async () => {
+        try {
+            await work();
+        }
+        finally {
+            if (current && webTerminalImagePullLocks.get(lockKey) === current) {
+                webTerminalImagePullLocks.delete(lockKey);
+            }
+        }
+    })();
+    webTerminalImagePullLocks.set(lockKey, current);
+    await current;
+}
+async function ensureWebTerminalImageReady(runtime, image, onProgress) {
+    onProgress?.('image_check', `Checking image availability for ${image}...`);
+    if (runtime === 'podman') {
+        const imageExists = async () => {
+            try {
+                await execFileAsync('podman', ['image', 'exists', image], {
+                    timeout: 10_000,
+                    maxBuffer: WEB_TERMINAL_IMAGE_PULL_MAX_BUFFER,
+                });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        };
+        if (await imageExists())
+            return;
+        await withWebTerminalImagePullLock(`podman:${image}`, async () => {
+            if (await imageExists())
+                return;
+            onProgress?.('image_pull', `Pulling container image ${image}...`);
+            await execFileAsync('podman', ['pull', image], {
+                timeout: WEB_TERMINAL_IMAGE_PULL_TIMEOUT_MS,
+                maxBuffer: WEB_TERMINAL_IMAGE_PULL_MAX_BUFFER,
+            });
+        });
+        return;
+    }
+    const imagesDir = (0, config_js_1.getImagesDir)();
+    const sifPath = (0, path_1.join)(imagesDir, (0, container_js_1.imageToSifName)(image));
+    if ((0, fs_1.existsSync)(sifPath))
+        return;
+    await withWebTerminalImagePullLock(`apptainer:${image}`, async () => {
+        if ((0, fs_1.existsSync)(sifPath))
+            return;
+        (0, fs_1.mkdirSync)(imagesDir, { recursive: true });
+        onProgress?.('image_pull', `Pulling container image ${image}...`);
+        await execFileAsync('apptainer', ['pull', sifPath, `docker://${image}`], {
+            timeout: WEB_TERMINAL_IMAGE_PULL_TIMEOUT_MS,
+            maxBuffer: WEB_TERMINAL_IMAGE_PULL_MAX_BUFFER,
+        });
+    });
+}
+function getWebTerminalAgentBootstrapSpec(agent) {
+    if (agent === 'codex') {
+        return { bin: 'codex', pkg: '@openai/codex' };
+    }
+    return { bin: 'claude', pkg: '@anthropic-ai/claude-code' };
+}
+async function withWebTerminalAgentPrepareLock(lockKey, work) {
+    const existing = webTerminalAgentPrepLocks.get(lockKey);
+    if (existing) {
+        await existing;
+        return;
+    }
+    let current = null;
+    current = (async () => {
+        try {
+            await work();
+        }
+        finally {
+            if (current && webTerminalAgentPrepLocks.get(lockKey) === current) {
+                webTerminalAgentPrepLocks.delete(lockKey);
+            }
+        }
+    })();
+    webTerminalAgentPrepLocks.set(lockKey, current);
+    await current;
+}
+function getPodmanPrewarmNetworkArgs(networkMode) {
+    const mode = String(networkMode || '').trim().toLowerCase();
+    if (mode === 'none')
+        return ['--network', 'none'];
+    if (mode === 'host')
+        return ['--network', 'host'];
+    return [];
+}
+async function runWebTerminalAgentBootstrapScript(runtime, image, sandboxHome, resolvedWorkdir, networkMode, script) {
+    if (runtime === 'podman') {
+        const result = await execFileAsync('podman', [
+            'run',
+            '--rm',
+            '--workdir', '/work',
+            '--volume', `${sandboxHome}:/home/sandbox`,
+            '--volume', `${resolvedWorkdir}:/work`,
+            '--env', 'HOME=/home/sandbox',
+            ...getPodmanPrewarmNetworkArgs(networkMode),
+            image,
+            'bash',
+            '-lc',
+            script,
+        ], {
+            timeout: WEB_TERMINAL_AGENT_PREP_TIMEOUT_MS,
+            maxBuffer: WEB_TERMINAL_AGENT_PREP_MAX_BUFFER,
+        });
+        return {
+            stdout: String(result?.stdout || ''),
+            stderr: String(result?.stderr || ''),
+        };
+    }
+    const sifPath = (0, path_1.join)((0, config_js_1.getImagesDir)(), (0, container_js_1.imageToSifName)(image));
+    const result = await execFileAsync('apptainer', [
+        'exec',
+        '--containall',
+        '--cleanenv',
+        '--home', `${sandboxHome}:/home/sandbox`,
+        '--bind', `${resolvedWorkdir}:/work`,
+        '--pwd', '/work',
+        sifPath,
+        'bash',
+        '-lc',
+        script,
+    ], {
+        timeout: WEB_TERMINAL_AGENT_PREP_TIMEOUT_MS,
+        maxBuffer: WEB_TERMINAL_AGENT_PREP_MAX_BUFFER,
+    });
+    return {
+        stdout: String(result?.stdout || ''),
+        stderr: String(result?.stderr || ''),
+    };
+}
+async function ensureWebTerminalAgentReady(runtime, image, agent, resolvedWorkdir, networkMode, onProgress) {
+    const spec = getWebTerminalAgentBootstrapSpec(agent);
+    const sandboxHome = (0, config_js_1.getSandboxHome)();
+    const installedBin = (0, path_1.join)(sandboxHome, '.npm-global', 'bin', spec.bin);
+    if ((0, fs_1.existsSync)(installedBin)) {
+        return;
+    }
+    await withWebTerminalAgentPrepareLock(spec.bin, async () => {
+        if ((0, fs_1.existsSync)(installedBin))
+            return;
+        onProgress?.('agent_prepare', `Preparing ${agent} CLI in sandbox home...`);
+        const script = [
+            'set -euo pipefail',
+            'export HOME=/home/sandbox',
+            'mkdir -p "$HOME/.npm-global"',
+            'npm config set prefix "$HOME/.npm-global" 2>/dev/null || true',
+            'export PATH="$HOME/.npm-global/bin:$PATH"',
+            `if ! command -v ${spec.bin} >/dev/null 2>&1; then npm i -g ${spec.pkg}; fi`,
+        ].join('\n');
+        await runWebTerminalAgentBootstrapScript(runtime, image, sandboxHome, resolvedWorkdir, networkMode, script);
+    });
+}
+function extractAgentVersionFromOutput(output) {
+    const marker = String(output || '')
+        .split('\n')
+        .map((line) => line.trim())
+        .find((line) => line.startsWith('LABGATE_AGENT_VERSION:'));
+    if (!marker)
+        return null;
+    const raw = marker.slice('LABGATE_AGENT_VERSION:'.length).trim();
+    if (!raw)
+        return null;
+    return raw.replace(/^v/, '');
+}
+async function updateWebTerminalAgentCli(runtime, image, agent, resolvedWorkdir, networkMode) {
+    const spec = getWebTerminalAgentBootstrapSpec(agent);
+    const sandboxHome = (0, config_js_1.getSandboxHome)();
+    let version = null;
+    await withWebTerminalAgentPrepareLock(spec.bin, async () => {
+        const script = [
+            'set -euo pipefail',
+            'export HOME=/home/sandbox',
+            'mkdir -p "$HOME/.npm-global"',
+            'npm config set prefix "$HOME/.npm-global" 2>/dev/null || true',
+            'export PATH="$HOME/.npm-global/bin:$PATH"',
+            `npm i -g "${spec.pkg}"`,
+            `_labgate_ver="$(${spec.bin} --version 2>/dev/null || true)"`,
+            '_labgate_ver="$(printf "%s" "$_labgate_ver" | head -n 1 | tr -d \'\\r\')"',
+            'echo "LABGATE_AGENT_VERSION:${_labgate_ver}"',
+        ].join('\n');
+        const result = await runWebTerminalAgentBootstrapScript(runtime, image, sandboxHome, resolvedWorkdir, networkMode, script);
+        version = extractAgentVersionFromOutput([result.stdout, result.stderr].filter(Boolean).join('\n'));
+    });
+    return { version };
+}
+function toRuntimeUnavailableResult(runtimeReady) {
+    return {
+        ok: false,
+        status: runtimeReady.initialized ? 502 : 503,
+        body: {
+            ok: false,
+            code: 'runtime_unavailable',
+            phase: 'runtime_setup',
+            initialized: runtimeReady.initialized,
+            error: runtimeReady.error || 'Container runtime unavailable.',
+        },
+    };
+}
+async function startWebTerminalSession(agent, resolvedWorkdir, opts = {}) {
+    const onProgress = opts.onProgress;
+    const config = (0, config_js_1.loadConfig)();
+    onProgress?.('runtime_setup', 'Checking container runtime...');
+    const runtimeReady = await prepareRuntimeForWebTerminal(config.runtime);
+    if (!runtimeReady.ok) {
+        return toRuntimeUnavailableResult(runtimeReady);
+    }
+    const runtimeCheck = (0, runtime_js_1.checkRuntime)(config.runtime);
+    if (!runtimeCheck.ok || !runtimeCheck.runtime) {
+        return {
+            ok: false,
+            status: runtimeReady.initialized ? 502 : 503,
+            body: {
+                ok: false,
+                code: 'runtime_unavailable',
+                phase: 'runtime_setup',
+                initialized: runtimeReady.initialized,
+                error: runtimeCheck.error || 'Container runtime unavailable.',
+            },
+        };
+    }
+    // Preflight tmux before any slow image/agent preparation to avoid unnecessary side effects.
+    const tmuxAvailable = await (0, web_terminal_js_1.ensureTmuxAvailable)();
+    if (!tmuxAvailable.ok) {
+        return {
+            ok: false,
+            status: 500,
+            body: { ok: false, error: tmuxAvailable.error },
+        };
+    }
+    if (opts.prewarmImage) {
+        try {
+            await ensureWebTerminalImageReady(runtimeCheck.runtime, config.image, onProgress);
+        }
+        catch (err) {
+            const detail = commandErrorDetail(err);
+            return {
+                ok: false,
+                status: 502,
+                body: {
+                    ok: false,
+                    code: 'image_prepare_failed',
+                    phase: 'image_prepare',
+                    runtime: runtimeCheck.runtime,
+                    image: config.image,
+                    error: detail || `Failed to pull image ${config.image}.`,
+                },
+            };
+        }
+    }
+    if (opts.prewarmAgent) {
+        try {
+            await ensureWebTerminalAgentReady(runtimeCheck.runtime, config.image, agent, resolvedWorkdir, config.network.mode, onProgress);
+        }
+        catch (err) {
+            const detail = commandErrorDetail(err);
+            return {
+                ok: false,
+                status: 502,
+                body: {
+                    ok: false,
+                    code: 'agent_prepare_failed',
+                    phase: 'agent_prepare',
+                    runtime: runtimeCheck.runtime,
+                    agent,
+                    image: config.image,
+                    error: detail || `Failed to prepare ${agent} in sandbox home.`,
+                },
+            };
+        }
+    }
+    onProgress?.('tmux_check', 'Checking terminal multiplexer availability...');
+    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,
+        runtime: runtimeCheck.runtime,
+        workdir: resolvedWorkdir,
+    });
+    (0, web_terminal_js_1.writeWebTerminalRecord)(record);
+    onProgress?.('session_start', `Starting ${agent} terminal session...`);
+    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 });
+        return {
+            ok: false,
+            status: 500,
+            body: { ok: false, error: `Could not start tmux session: ${message}` },
+        };
+    }
+    onProgress?.('session_start', 'Attaching terminal bridge...');
+    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',
+        });
+        return {
+            ok: false,
+            status: 500,
+            body: {
+                ok: false,
+                error: 'Started tmux session but could not create terminal bridge (node-pty unavailable).',
+            },
+        };
+    }
+    await waitForWebTerminalStartupSummary(record, bridge, onProgress);
+    return {
+        ok: true,
+        session: serializeWebTerminalSession(record),
+    };
+}
 function readBody(req) {
     return new Promise((resolve, reject) => {
         const chunks = [];
@@ -419,7 +912,9 @@ function normalizeWebTerminalAgent(raw) {
 function serializeWebTerminalSession(record) {
     return {
         id: record.id,
+        name: record.name || '',
         agent: record.agent,
+        runtime: record.runtime || '',
         workdir: record.workdir,
         node: record.node,
         tmuxSession: record.tmuxSession,
@@ -440,11 +935,62 @@ async function loadNodePtyModule() {
     }
 }
 function appendWebTerminalBuffer(bridge, chunk) {
+    if (!chunk)
+        return [];
     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);
+    if (bridge.buffer.length > WEB_TERMINAL_BUFFER_MAX_BYTES) {
+        bridge.buffer = bridge.buffer.slice(bridge.buffer.length - WEB_TERMINAL_BUFFER_MAX_BYTES);
+    }
+    const appended = [];
+    for (let i = 0; i < chunk.length; i += WEB_TERMINAL_HISTORY_CHUNK_BYTES) {
+        const piece = chunk.slice(i, i + WEB_TERMINAL_HISTORY_CHUNK_BYTES);
+        if (!piece)
+            continue;
+        const seq = bridge.nextSeq++;
+        const nextChunk = { seq, data: piece };
+        bridge.history.push(nextChunk);
+        appended.push(nextChunk);
+        bridge.historyBytes += piece.length;
+    }
+    while (bridge.historyBytes > WEB_TERMINAL_HISTORY_MAX_BYTES && bridge.history.length > 0) {
+        const removed = bridge.history.shift();
+        if (!removed)
+            break;
+        bridge.historyBytes = Math.max(0, bridge.historyBytes - removed.data.length);
     }
+    return appended;
+}
+function getWebTerminalHistoryPage(bridge, options) {
+    const history = bridge.history;
+    if (!history.length) {
+        return {
+            chunks: [],
+            hasMore: false,
+            nextBefore: null,
+            oldestSeq: null,
+            latestSeq: null,
+        };
+    }
+    const beforeSeq = options?.beforeSeq ?? null;
+    const rawLimit = options?.limit ?? WEB_TERMINAL_HISTORY_PAGE_DEFAULT;
+    const limit = Math.max(1, Math.min(WEB_TERMINAL_HISTORY_PAGE_MAX, Math.floor(rawLimit)));
+    let endIndex = history.length;
+    if (beforeSeq !== null && Number.isFinite(beforeSeq)) {
+        const idx = history.findIndex((chunk) => chunk.seq >= beforeSeq);
+        endIndex = idx >= 0 ? idx : history.length;
+    }
+    endIndex = Math.max(0, Math.min(endIndex, history.length));
+    const startIndex = Math.max(0, endIndex - limit);
+    const chunks = history.slice(startIndex, endIndex);
+    const hasMore = startIndex > 0;
+    return {
+        chunks,
+        hasMore,
+        nextBefore: hasMore && chunks.length > 0 ? chunks[0].seq : null,
+        oldestSeq: history[0]?.seq ?? null,
+        latestSeq: history[history.length - 1]?.seq ?? null,
+    };
 }
 function sendWebTerminalMessage(ws, payload) {
     if (ws.readyState !== ws_1.WebSocket.OPEN)
@@ -456,6 +1002,140 @@ function sendWebTerminalMessage(ws, payload) {
         // Best effort.
     }
 }
+function parseJsonObjectLine(line) {
+    try {
+        const parsed = JSON.parse(line);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function readRecordString(record, key) {
+    const value = record[key];
+    return typeof value === 'string' ? value : '';
+}
+function collectClaudeTextFromContent(content) {
+    if (!Array.isArray(content))
+        return '';
+    let text = '';
+    for (const part of content) {
+        if (!part || typeof part !== 'object' || Array.isArray(part))
+            continue;
+        const node = part;
+        if (node.type === 'text' && typeof node.text === 'string') {
+            text += node.text;
+        }
+    }
+    return text;
+}
+function extractClaudeStreamSessionId(event) {
+    const direct = readRecordString(event, 'session_id').trim();
+    if (direct)
+        return direct;
+    const message = event.message;
+    if (!message || typeof message !== 'object' || Array.isArray(message))
+        return '';
+    const nested = readRecordString(message, 'session_id').trim();
+    return nested || '';
+}
+function extractClaudeAssistantSnapshot(event) {
+    const type = readRecordString(event, 'type').trim().toLowerCase();
+    if (type === 'assistant') {
+        const message = event.message;
+        if (message && typeof message === 'object' && !Array.isArray(message)) {
+            const content = message.content;
+            const contentText = collectClaudeTextFromContent(content);
+            if (contentText)
+                return contentText;
+        }
+    }
+    if (type === 'result') {
+        const resultText = readRecordString(event, 'result');
+        if (resultText)
+            return resultText;
+    }
+    return '';
+}
+function isClaudeAuthenticationFailure(event, assistantSnapshot, stderrText) {
+    const packed = JSON.stringify(event).toLowerCase();
+    const message = `${assistantSnapshot}\n${stderrText}`.toLowerCase();
+    const authRe = /oauth token has expired|authentication_error|failed to authenticate|api error:\s*401/i;
+    return authRe.test(packed) || authRe.test(message);
+}
+function buildClaudeHeadlessApptainerArgs(config, workdir, prompt, resumeSessionId) {
+    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();
+    return [
+        'exec',
+        '--containall',
+        '--cleanenv',
+        '--home', `${sandboxHome}:/home/sandbox`,
+        '--bind', `${workdir}:/work`,
+        '--pwd', '/work',
+        ...config.filesystem.extra_paths.flatMap(({ path: p, mode }) => {
+            const resolved = p.replace(/^~/, (0, os_1.homedir)());
+            const target = `/mnt/${(0, path_1.basename)(resolved)}`;
+            const bindSpec = mode === 'ro' ? `${resolved}:${target}:ro` : `${resolved}:${target}`;
+            return ['--bind', bindSpec];
+        }),
+        ...(config.datasets || []).flatMap(({ path: p, name, mode }) => {
+            const resolved = p.replace(/^~/, (0, os_1.homedir)());
+            const bindSpec = mode === 'ro' ? `${resolved}:/datasets/${name}:ro` : `${resolved}:/datasets/${name}`;
+            return ['--bind', bindSpec];
+        }),
+        ...((0, fs_1.existsSync)((0, config_js_1.getConfigPath)()) ? ['--bind', `${(0, config_js_1.getConfigPath)()}:/labgate-config/config.json`] : []),
+        '--env', 'HOME=/home/sandbox',
+        '--env', 'ANTHROPIC_API_KEY=',
+        sifPath,
+        '/home/sandbox/.npm-global/bin/claude',
+        '-p',
+        '--verbose',
+        '--output-format',
+        'stream-json',
+        '--include-partial-messages',
+        ...(resume ? ['--resume', resume] : []),
+        prompt,
+    ];
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function stripAnsiForStartupReadiness(text) {
+    return String(text || '')
+        .replace(/\u001b\][^\u0007]*(?:\u0007|\u001b\\)/g, '')
+        .replace(/\u001b\[[0-9;?]*[ -/]*[@-~]/g, '')
+        .replace(/\r/g, '\n');
+}
+function hasWebTerminalStartupSummary(buffer) {
+    const plain = stripAnsiForStartupReadiness(buffer);
+    return WEB_TERMINAL_STARTUP_HEADER_RE.test(plain) && WEB_TERMINAL_STARTUP_BLOCKED_RE.test(plain);
+}
+async function waitForWebTerminalStartupSummary(record, bridge, onProgress) {
+    const deadline = Date.now() + WEB_TERMINAL_STARTUP_READY_TIMEOUT_MS;
+    let lastAliveCheck = 0;
+    onProgress?.('session_start', `Finalizing ${record.agent} startup...`);
+    while (Date.now() < deadline) {
+        const recent = bridge.buffer.length > WEB_TERMINAL_STARTUP_READY_BUFFER_LIMIT
+            ? bridge.buffer.slice(-WEB_TERMINAL_STARTUP_READY_BUFFER_LIMIT)
+            : bridge.buffer;
+        if (hasWebTerminalStartupSummary(recent))
+            return;
+        if (!bridge.pty)
+            return;
+        const now = Date.now();
+        if (now - lastAliveCheck >= WEB_TERMINAL_STARTUP_ALIVE_CHECK_MS) {
+            lastAliveCheck = now;
+            const alive = await (0, web_terminal_js_1.hasTmuxSession)(record.tmuxSession);
+            if (!alive)
+                return;
+        }
+        await sleep(WEB_TERMINAL_STARTUP_READY_POLL_MS);
+    }
+}
 function broadcastWebTerminalMessage(bridge, payload) {
     for (const ws of bridge.clients) {
         if (ws.readyState !== ws_1.WebSocket.OPEN) {
@@ -465,6 +1145,23 @@ function broadcastWebTerminalMessage(bridge, payload) {
         sendWebTerminalMessage(ws, payload);
     }
 }
+function closeWebTerminalBridgeClients(bridge, code = 4001, reason = 'labgate-bridge-detached') {
+    const clients = Array.from(bridge.clients);
+    bridge.clients.clear();
+    for (const ws of clients) {
+        try {
+            ws.close(code, reason);
+        }
+        catch {
+            try {
+                ws.close();
+            }
+            catch {
+                // Best effort.
+            }
+        }
+    }
+}
 async function ensureWebTerminalBridge(record) {
     const existing = webTerminalBridges.get(record.id);
     if (existing && existing.pty)
@@ -481,6 +1178,13 @@ async function ensureWebTerminalBridge(record) {
         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 });
+    }
+    catch {
+        // Best effort only; attach should still proceed.
+    }
     const env = {};
     for (const [k, v] of Object.entries(process.env)) {
         if (v !== undefined)
@@ -513,40 +1217,65 @@ async function ensureWebTerminalBridge(record) {
     const bridge = existing || {
         id: record.id,
         buffer: '',
+        history: [],
+        historyBytes: 0,
+        nextSeq: 1,
+        stopRequested: false,
         clients: new Set(),
         pty: ptyProcess,
     };
+    bridge.stopRequested = false;
     bridge.pty = ptyProcess;
     webTerminalBridges.set(record.id, bridge);
     ptyProcess.onData((data) => {
-        appendWebTerminalBuffer(bridge, data);
-        broadcastWebTerminalMessage(bridge, { type: 'data', id: record.id, data });
+        const appended = appendWebTerminalBuffer(bridge, data);
+        for (const chunk of appended) {
+            broadcastWebTerminalMessage(bridge, {
+                type: 'data',
+                id: record.id,
+                data: chunk.data,
+                seqStart: chunk.seq,
+                seqEnd: chunk.seq,
+            });
+        }
     });
     ptyProcess.onExit(async () => {
+        const stopRequested = bridge.stopRequested;
+        bridge.stopRequested = false;
         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,
-            });
+        if (alive) {
+            if (stopRequested)
+                return;
+            // Another tmux client (for example `labgate continue`) may have force-detached this bridge.
+            // Clear stale alternate-screen data and require clients to reconnect for a clean reattach.
+            bridge.buffer = '';
+            bridge.history = [];
+            bridge.historyBytes = 0;
+            closeWebTerminalBridgeClients(bridge);
+            return;
         }
+        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;
+    bridge.stopRequested = true;
     try {
         bridge.pty.kill('SIGTERM');
     }
@@ -554,6 +1283,192 @@ function stopWebTerminalBridge(bridge) {
         // Best effort.
     }
 }
+async function startClaudeHeadlessWsRun(ws, record, prompt, resumeSessionId) {
+    const send = (payload) => {
+        sendWebTerminalMessage(ws, payload);
+    };
+    const trimmedPrompt = prompt.trim();
+    if (!trimmedPrompt) {
+        send({ type: 'error', error: 'prompt is required' });
+        return () => { };
+    }
+    send({ type: 'status', stage: 'runtime_setup', message: 'Checking container runtime...' });
+    const config = (0, config_js_1.loadConfig)();
+    const runtimeReady = await prepareRuntimeForWebTerminal(config.runtime);
+    if (!runtimeReady.ok) {
+        send({
+            type: 'error',
+            code: 'runtime_unavailable',
+            error: runtimeReady.error || 'Container runtime unavailable.',
+        });
+        return () => { };
+    }
+    const runtimeCheck = (0, runtime_js_1.checkRuntime)(config.runtime);
+    if (!runtimeCheck.ok || !runtimeCheck.runtime) {
+        send({
+            type: 'error',
+            code: 'runtime_unavailable',
+            error: runtimeCheck.error || 'Container runtime unavailable.',
+        });
+        return () => { };
+    }
+    if (runtimeCheck.runtime !== 'apptainer') {
+        send({
+            type: 'error',
+            code: 'runtime_unsupported',
+            error: `Headless Claude chat currently supports Apptainer only (detected: ${runtimeCheck.runtime}).`,
+        });
+        return () => { };
+    }
+    try {
+        await ensureWebTerminalImageReady(runtimeCheck.runtime, config.image, (stage, message) => {
+            send({ type: 'status', stage, message });
+        });
+    }
+    catch (err) {
+        send({
+            type: 'error',
+            code: 'image_prepare_failed',
+            error: commandErrorDetail(err) || `Failed to prepare image ${config.image}.`,
+        });
+        return () => { };
+    }
+    try {
+        await ensureWebTerminalAgentReady(runtimeCheck.runtime, config.image, 'claude', record.workdir, config.network.mode, (stage, message) => send({ type: 'status', stage, message }));
+    }
+    catch (err) {
+        send({
+            type: 'error',
+            code: 'agent_prepare_failed',
+            error: commandErrorDetail(err) || 'Failed to prepare Claude CLI in sandbox home.',
+        });
+        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,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdoutBuffer = '';
+    let stderrBuffer = '';
+    let latestClaudeSessionId = resumeSessionId.trim();
+    let emittedAssistantText = '';
+    let doneSent = false;
+    const sendDone = (exitCode) => {
+        if (doneSent)
+            return;
+        doneSent = true;
+        send({
+            type: 'done',
+            exitCode,
+            sessionId: latestClaudeSessionId || null,
+            isError: exitCode !== 0,
+        });
+        try {
+            ws.close();
+        }
+        catch {
+            // Best effort.
+        }
+    };
+    child.stdout.on('data', (chunk) => {
+        stdoutBuffer += chunk.toString('utf-8');
+        while (true) {
+            const idx = stdoutBuffer.indexOf('\n');
+            if (idx < 0)
+                break;
+            const line = stdoutBuffer.slice(0, idx).trim();
+            stdoutBuffer = stdoutBuffer.slice(idx + 1);
+            if (!line)
+                continue;
+            const event = parseJsonObjectLine(line);
+            if (!event)
+                continue;
+            const sessionId = extractClaudeStreamSessionId(event);
+            if (sessionId && sessionId !== latestClaudeSessionId) {
+                latestClaudeSessionId = sessionId;
+                send({ type: 'session', sessionId });
+            }
+            const snapshot = extractClaudeAssistantSnapshot(event);
+            if (snapshot) {
+                let delta = '';
+                if (snapshot.startsWith(emittedAssistantText)) {
+                    delta = snapshot.slice(emittedAssistantText.length);
+                    emittedAssistantText = snapshot;
+                }
+                else if (!emittedAssistantText.startsWith(snapshot)) {
+                    delta = snapshot;
+                    emittedAssistantText = snapshot;
+                }
+                if (delta) {
+                    send({ type: 'delta', text: delta });
+                }
+            }
+            if (isClaudeAuthenticationFailure(event, snapshot, stderrBuffer)) {
+                send({
+                    type: 'auth_required',
+                    error: 'Claude authentication is required. Run /login in raw terminal mode to refresh session.',
+                });
+            }
+        }
+    });
+    child.stderr.on('data', (chunk) => {
+        const text = chunk.toString('utf-8');
+        stderrBuffer = (stderrBuffer + text).slice(-CLAUDE_HEADLESS_STDERR_LIMIT);
+    });
+    child.on('error', (err) => {
+        send({
+            type: 'error',
+            code: 'spawn_failed',
+            error: err.message || String(err),
+        });
+        sendDone(1);
+    });
+    child.on('close', (code) => {
+        const remaining = stdoutBuffer.trim();
+        if (remaining) {
+            const event = parseJsonObjectLine(remaining);
+            if (event) {
+                const sessionId = extractClaudeStreamSessionId(event);
+                if (sessionId && sessionId !== latestClaudeSessionId) {
+                    latestClaudeSessionId = sessionId;
+                    send({ type: 'session', sessionId });
+                }
+                const snapshot = extractClaudeAssistantSnapshot(event);
+                if (snapshot) {
+                    if (snapshot.startsWith(emittedAssistantText)) {
+                        const delta = snapshot.slice(emittedAssistantText.length);
+                        emittedAssistantText = snapshot;
+                        if (delta)
+                            send({ type: 'delta', text: delta });
+                    }
+                    else if (!emittedAssistantText.startsWith(snapshot)) {
+                        emittedAssistantText = snapshot;
+                        send({ type: 'delta', text: snapshot });
+                    }
+                }
+            }
+        }
+        const exitCode = typeof code === 'number' ? code : 1;
+        if (exitCode !== 0) {
+            const detail = stderrBuffer.trim();
+            if (detail) {
+                send({ type: 'error', code: 'claude_failed', error: detail });
+            }
+        }
+        sendDone(exitCode);
+    });
+    return () => {
+        try {
+            child.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);
@@ -1852,38 +2767,140 @@ async function handleRestartSession(req, res) {
             return;
         }
         try {
-            process.kill(data.pid, 'SIGTERM');
+            process.kill(data.pid, 'SIGTERM');
+        }
+        catch {
+            // Process is already gone. Continue with cleanup + relaunch.
+        }
+        await waitForSessionFileRemoval(sessionFile);
+        if ((0, fs_1.existsSync)(sessionFile)) {
+            let stillRunning = false;
+            try {
+                process.kill(data.pid, 0);
+                stillRunning = true;
+            }
+            catch {
+                // Process is gone.
+            }
+            if (stillRunning) {
+                json(res, { ok: false, error: 'Session did not stop in time. Please stop it first and retry.' }, 409);
+                return;
+            }
+            try {
+                (0, fs_1.unlinkSync)(sessionFile);
+            }
+            catch { /* best effort */ }
+        }
+        relaunchSessionDetached(agent, workdir);
+        json(res, { ok: true, restarted: { id, agent, workdir } });
+    }
+    catch (err) {
+        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 {
-            // Process is already gone. Continue with cleanup + relaunch.
+            json(res, { ok: false, error: `Could not access workdir: ${resolvedWorkdir}` }, 400);
+            return;
         }
-        await waitForSessionFileRemoval(sessionFile);
-        if ((0, fs_1.existsSync)(sessionFile)) {
-            let stillRunning = false;
-            try {
-                process.kill(data.pid, 0);
-                stillRunning = true;
-            }
-            catch {
-                // Process is gone.
-            }
-            if (stillRunning) {
-                json(res, { ok: false, error: 'Session did not stop in time. Please stop it first and retry.' }, 409);
-                return;
-            }
-            try {
-                (0, fs_1.unlinkSync)(sessionFile);
-            }
-            catch { /* best effort */ }
+        if (!st.isDirectory()) {
+            json(res, { ok: false, error: `workdir is not a directory: ${resolvedWorkdir}` }, 400);
+            return;
         }
-        relaunchSessionDetached(agent, workdir);
-        json(res, { ok: true, restarted: { id, agent, workdir } });
+        const result = await startWebTerminalSession(agent, resolvedWorkdir);
+        if (!result.ok) {
+            json(res, result.body, result.status);
+            return;
+        }
+        json(res, { ok: true, session: result.session });
     }
     catch (err) {
-        json(res, { ok: false, error: err.message ?? String(err) }, 500);
+        json(res, { ok: false, error: err?.message ?? String(err) }, 500);
     }
 }
-async function handlePostWebTerminalStart(req, res) {
+async function runWebTerminalInitJob(id) {
+    const job = webTerminalInitJobs.get(id);
+    if (!job)
+        return;
+    const progress = (stage, message) => {
+        updateWebTerminalInitJob(id, {
+            status: 'running',
+            stage,
+            message,
+        });
+    };
+    try {
+        const result = await startWebTerminalSession(job.agent, job.workdir, {
+            prewarmImage: true,
+            prewarmAgent: true,
+            onProgress: progress,
+        });
+        if (result.ok) {
+            updateWebTerminalInitJob(id, {
+                status: 'ready',
+                stage: 'ready',
+                message: 'Session ready.',
+                session: result.session,
+                error: null,
+                code: null,
+                phase: null,
+            });
+            pruneWebTerminalInitJobs();
+            return;
+        }
+        const body = result.body || {};
+        const errText = String(body.error || 'Session initialization failed.');
+        updateWebTerminalInitJob(id, {
+            status: 'failed',
+            stage: 'failed',
+            message: errText.split('\n')[0] || 'Session initialization failed.',
+            session: null,
+            error: errText,
+            code: typeof body.code === 'string' ? body.code : null,
+            phase: typeof body.phase === 'string' ? body.phase : null,
+            initialized: body.initialized === true,
+        });
+    }
+    catch (err) {
+        const detail = commandErrorDetail(err) || (err?.message ?? String(err));
+        updateWebTerminalInitJob(id, {
+            status: 'failed',
+            stage: 'failed',
+            message: 'Session initialization failed.',
+            session: null,
+            error: detail,
+            code: 'init_failed',
+            phase: 'init',
+            initialized: false,
+        });
+    }
+    finally {
+        pruneWebTerminalInitJobs();
+    }
+}
+async function handlePostWebTerminalInit(req, res) {
     try {
         const body = await readBody(req);
         const parsed = JSON.parse(body || '{}');
@@ -1914,55 +2931,107 @@ async function handlePostWebTerminalStart(req, res) {
             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);
+        pruneWebTerminalInitJobs();
+        const job = createWebTerminalInitJob(agent, resolvedWorkdir);
+        webTerminalInitJobs.set(job.id, job);
+        void runWebTerminalInitJob(job.id);
+        json(res, { ok: true, init: serializeWebTerminalInitJob(job) }, 202);
+    }
+    catch (err) {
+        json(res, { ok: false, error: err?.message ?? String(err) }, 500);
+    }
+}
+async function handlePostWebTerminalAgentUpdate(req, res) {
+    try {
+        const body = await readBody(req);
+        const parsed = JSON.parse(body || '{}');
+        const agent = normalizeWebTerminalAgent(parsed.agent || '');
+        if (!agent) {
+            json(res, { ok: false, error: 'agent must be "claude" or "codex"' }, 400);
+            return;
+        }
+        const config = (0, config_js_1.loadConfig)();
+        const runtimeReady = await prepareRuntimeForWebTerminal(config.runtime);
+        if (!runtimeReady.ok) {
+            json(res, {
+                ok: false,
+                code: 'runtime_unavailable',
+                phase: 'runtime_setup',
+                initialized: runtimeReady.initialized,
+                error: runtimeReady.error || 'Container runtime unavailable.',
+            }, runtimeReady.initialized ? 502 : 503);
+            return;
+        }
+        const runtimeCheck = (0, runtime_js_1.checkRuntime)(config.runtime);
+        if (!runtimeCheck.ok || !runtimeCheck.runtime) {
+            json(res, {
+                ok: false,
+                code: 'runtime_unavailable',
+                phase: 'runtime_setup',
+                initialized: runtimeReady.initialized,
+                error: runtimeCheck.error || 'Container runtime unavailable.',
+            }, runtimeReady.initialized ? 502 : 503);
             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 });
+            await ensureWebTerminalImageReady(runtimeCheck.runtime, config.image);
         }
         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);
+            const detail = commandErrorDetail(err);
+            json(res, {
+                ok: false,
+                code: 'image_prepare_failed',
+                phase: 'image_prepare',
+                runtime: runtimeCheck.runtime,
+                image: config.image,
+                error: detail || `Failed to pull image ${config.image}.`,
+            }, 502);
             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',
+        try {
+            const updated = await updateWebTerminalAgentCli(runtimeCheck.runtime, config.image, agent, (0, os_1.homedir)(), config.network.mode);
+            const spec = getWebTerminalAgentBootstrapSpec(agent);
+            json(res, {
+                ok: true,
+                agent,
+                pkg: spec.pkg,
+                runtime: runtimeCheck.runtime,
+                image: config.image,
+                version: updated.version,
+                restartNotice: `Restart active ${agent} sessions to use the updated CLI.`,
             });
+        }
+        catch (err) {
+            const detail = commandErrorDetail(err);
             json(res, {
                 ok: false,
-                error: 'Started tmux session but could not create terminal bridge (node-pty unavailable).',
-            }, 500);
-            return;
+                code: 'agent_update_failed',
+                phase: 'agent_prepare',
+                agent,
+                runtime: runtimeCheck.runtime,
+                image: config.image,
+                error: detail || `Failed to update ${agent} CLI.`,
+            }, 502);
         }
-        json(res, {
-            ok: true,
-            session: serializeWebTerminalSession(record),
-        });
     }
     catch (err) {
         json(res, { ok: false, error: err?.message ?? String(err) }, 500);
     }
 }
+async function handleGetWebTerminalInit(reqUrl, res) {
+    pruneWebTerminalInitJobs();
+    const id = String(reqUrl.searchParams.get('id') || '').trim();
+    if (!id) {
+        json(res, { ok: false, error: 'id is required' }, 400);
+        return;
+    }
+    const job = webTerminalInitJobs.get(id);
+    if (!job) {
+        json(res, { ok: false, error: 'Initialization job not found' }, 404);
+        return;
+    }
+    json(res, { ok: true, init: serializeWebTerminalInitJob(job) });
+}
 async function handleGetWebTerminalSessions(res) {
     const records = (0, web_terminal_js_1.listWebTerminalRecords)();
     const localNode = (0, os_1.hostname)();
@@ -1989,6 +3058,82 @@ async function handleGetWebTerminalSessions(res) {
     const sessions = (0, web_terminal_js_1.listWebTerminalRecords)().map(serializeWebTerminalSession);
     json(res, { ok: true, sessions });
 }
+async function handleGetWebTerminalHistory(reqUrl, res) {
+    const id = String(reqUrl.searchParams.get('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;
+    }
+    const beforeRaw = String(reqUrl.searchParams.get('before') || '').trim();
+    let beforeSeq = null;
+    if (beforeRaw) {
+        const parsedBefore = Number(beforeRaw);
+        if (!Number.isFinite(parsedBefore)) {
+            json(res, { ok: false, error: 'Invalid before sequence number' }, 400);
+            return;
+        }
+        beforeSeq = Math.max(0, Math.floor(parsedBefore));
+    }
+    const limitRaw = String(reqUrl.searchParams.get('limit') || '').trim();
+    let limit = WEB_TERMINAL_HISTORY_PAGE_DEFAULT;
+    if (limitRaw) {
+        const parsedLimit = Number(limitRaw);
+        if (!Number.isFinite(parsedLimit)) {
+            json(res, { ok: false, error: 'Invalid history limit' }, 400);
+            return;
+        }
+        limit = Math.max(1, Math.min(WEB_TERMINAL_HISTORY_PAGE_MAX, Math.floor(parsedLimit)));
+    }
+    const bridge = await ensureWebTerminalBridge(record);
+    if (!bridge) {
+        json(res, { ok: false, error: 'Could not open terminal bridge' }, 500);
+        return;
+    }
+    const page = getWebTerminalHistoryPage(bridge, { beforeSeq, limit });
+    json(res, {
+        ok: true,
+        id: record.id,
+        history: {
+            ...page,
+            limit,
+        },
+    });
+}
+async function handlePostWebTerminalRename(req, res) {
+    try {
+        const body = await readBody(req);
+        const parsed = JSON.parse(body || '{}');
+        const id = String(parsed.id || '').trim();
+        const name = typeof parsed.name === 'string' ? parsed.name.trim() : '';
+        if (!(0, web_terminal_js_1.isValidWebTerminalId)(id)) {
+            json(res, { ok: false, error: 'Invalid terminal session id' }, 400);
+            return;
+        }
+        if (name && !(0, web_terminal_js_1.isValidWebTerminalName)(name)) {
+            json(res, { ok: false, error: 'Invalid session name format' }, 400);
+            return;
+        }
+        const result = (0, web_terminal_js_1.renameWebTerminalRecord)(id, name);
+        if (!result.ok) {
+            const status = result.code === 'name_taken' ? 409 : result.code === 'not_found' ? 404 : 400;
+            json(res, { ok: false, error: result.error, code: result.code }, status);
+            return;
+        }
+        json(res, { ok: true, session: serializeWebTerminalSession(result.record) });
+    }
+    catch (err) {
+        json(res, { ok: false, error: err?.message ?? String(err) }, 500);
+    }
+}
 async function handlePostWebTerminalStop(req, res) {
     try {
         const body = await readBody(req);
@@ -2065,8 +3210,15 @@ async function handleValidatePath(req, res) {
 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)());
+        const parsed = JSON.parse(body);
+        const rawPath = typeof parsed.path === 'string' ? parsed.path : '~';
+        const includeFiles = !!parsed.includeFiles;
+        const includeHidden = !!parsed.includeHidden;
+        const rawLimit = Number(parsed.maxEntries);
+        const maxEntries = Number.isFinite(rawLimit)
+            ? Math.max(100, Math.min(5000, Math.floor(rawLimit)))
+            : 2000;
+        const resolved = 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;
@@ -2080,19 +3232,41 @@ async function handleBrowseDir(req, res) {
             return;
         }
         const dirs = [];
+        const files = [];
+        let truncated = false;
         for (const entry of entries) {
-            if (entry.startsWith('.'))
-                continue; // skip dotfiles
+            if (!includeHidden && entry.startsWith('.'))
+                continue; // skip dotfiles by default
             const full = (0, path_1.join)(resolved, entry);
             try {
-                if ((0, fs_1.statSync)(full).isDirectory()) {
+                const st = (0, fs_1.statSync)(full);
+                if (st.isDirectory()) {
                     dirs.push({ name: entry, path: full });
                 }
+                else if (includeFiles && st.isFile()) {
+                    files.push({ name: entry, path: full });
+                }
             }
             catch { /* skip inaccessible */ }
+            if ((dirs.length + files.length) >= maxEntries) {
+                truncated = true;
+                break;
+            }
         }
         dirs.sort((a, b) => a.name.localeCompare(b.name));
-        json(res, { ok: true, path: resolved, dirs });
+        files.sort((a, b) => a.name.localeCompare(b.name));
+        const entriesOut = [
+            ...dirs.map((d) => ({ name: d.name, path: d.path, type: 'dir' })),
+            ...files.map((f) => ({ name: f.name, path: f.path, type: 'file' })),
+        ];
+        json(res, {
+            ok: true,
+            path: resolved,
+            dirs,
+            files: includeFiles ? files : undefined,
+            entries: includeFiles ? entriesOut : undefined,
+            truncated,
+        });
     }
     catch (err) {
         json(res, { ok: false, error: err.message ?? String(err) }, 400);
@@ -2412,6 +3586,8 @@ function mapContainerPathToHost(path, sandboxHome) {
         return (0, config_js_1.getConfigPath)();
     if (path === '/labgate-config/slurm.db')
         return (0, config_js_1.getSlurmDbPath)();
+    if (path === '/labgate-config/results.json')
+        return (0, config_js_1.getResultsDbPath)();
     return path;
 }
 function readMcpConfigData() {
@@ -2584,7 +3760,7 @@ function collectMcpState() {
             env: resultsEntry?.env || null,
             mcpConfigPath,
             serverPath: resolveServerPathFromEntry(resultsEntry, sandboxHome),
-            dbPath: null,
+            dbPath: resolveDbPathFromEntry(resultsEntry, sandboxHome),
             tools: [
                 { name: 'list_results', title: 'List Results', description: 'List recorded results with filtering and pagination' },
                 { name: 'register_result', title: 'Register Result', description: 'Create a new structured result entry' },
@@ -3167,6 +4343,87 @@ function handleGetSlurmStats(res) {
 }
 // ── SSE: Server-Sent Events for real-time dashboard updates ──
 const sseClients = new Set();
+const RESULTS_WATCH_DEBOUNCE_MS = 120;
+let lastResultsSignature = getResultsFileSignature();
+let resultsWatcher = null;
+let resultsWatchDebounce = null;
+function getResultsFileSignature() {
+    const resultsPath = (0, config_js_1.getResultsDbPath)();
+    try {
+        if (!(0, fs_1.existsSync)(resultsPath))
+            return 'missing';
+        const st = (0, fs_1.statSync)(resultsPath);
+        return `${st.size}:${Math.floor(st.mtimeMs)}`;
+    }
+    catch {
+        return 'error';
+    }
+}
+function maybeBroadcastResultsChanged() {
+    const signature = getResultsFileSignature();
+    if (signature === lastResultsSignature)
+        return;
+    if (sseClients.size === 0)
+        return;
+    lastResultsSignature = signature;
+    broadcastSSE('results_changed', {
+        changed_at: new Date().toISOString(),
+        signature,
+    });
+}
+function scheduleResultsChangeCheck(delayMs = RESULTS_WATCH_DEBOUNCE_MS) {
+    if (resultsWatchDebounce) {
+        clearTimeout(resultsWatchDebounce);
+    }
+    resultsWatchDebounce = setTimeout(() => {
+        resultsWatchDebounce = null;
+        maybeBroadcastResultsChanged();
+    }, delayMs);
+    resultsWatchDebounce.unref?.();
+}
+function stopResultsWatcher() {
+    if (resultsWatchDebounce) {
+        clearTimeout(resultsWatchDebounce);
+        resultsWatchDebounce = null;
+    }
+    if (resultsWatcher) {
+        try {
+            resultsWatcher.close();
+        }
+        catch {
+            // Best effort.
+        }
+        resultsWatcher = null;
+    }
+}
+function startResultsWatcher() {
+    if (resultsWatcher)
+        return;
+    lastResultsSignature = getResultsFileSignature();
+    const resultsPath = (0, config_js_1.getResultsDbPath)();
+    const watchDir = (0, path_1.dirname)(resultsPath);
+    const watchFile = (0, path_1.basename)(resultsPath);
+    try {
+        (0, config_js_1.ensurePrivateDir)(watchDir);
+    }
+    catch {
+        // Best effort.
+    }
+    try {
+        resultsWatcher = (0, fs_1.watch)(watchDir, (_eventType, filename) => {
+            const changed = filename ? String(filename) : '';
+            if (changed && changed !== watchFile)
+                return;
+            scheduleResultsChangeCheck();
+        });
+        resultsWatcher.on('error', () => {
+            stopResultsWatcher();
+        });
+    }
+    catch {
+        resultsWatcher = null;
+    }
+}
 function handleSSE(_req, res) {
     res.writeHead(200, {
         'Content-Type': 'text/event-stream',
@@ -3194,6 +4451,7 @@ let sseInterval = null;
 function startSSEBroadcast() {
     if (sseInterval)
         return;
+    startResultsWatcher();
     sseInterval = setInterval(async () => {
         if (sseClients.size === 0)
             return;
@@ -3270,6 +4528,8 @@ function startSSEBroadcast() {
             }
             catch { /* slurm DB unavailable */ }
         }
+        // Results changes may come from external MCP processes; emit only on file mutation.
+        maybeBroadcastResultsChanged();
     }, 2000);
     sseInterval.unref?.();
 }
@@ -3504,10 +4764,12 @@ function startUI(optsOrPort = {}, standaloneArg = true) {
     const options = typeof optsOrPort === 'number'
         ? { port: optsOrPort, standalone: standaloneArg }
         : optsOrPort;
+    (0, init_js_1.ensureBundledIrisDatasetRegistration)();
     const standalone = options.standalone ?? true;
     const socketPath = options.socketPath || (0, config_js_1.getUiSocketPath)();
     const tcpPort = Number.isFinite(options.port) ? Math.floor(options.port) : null;
     const useTcp = tcpPort !== null;
+    const prewarmImageOnStartup = options.prewarmImageOnStartup === true;
     const requestedPort = tcpPort ?? 0;
     const maxPort = requestedPort + 3;
     const uiAccessToken = useTcp ? (0, crypto_1.randomBytes)(24).toString('hex') : '';
@@ -3520,9 +4782,16 @@ function startUI(optsOrPort = {}, standaloneArg = true) {
         (0, config_js_1.ensurePrivateDir)((0, path_1.dirname)(socketPath));
     }
     const wsServer = new ws_1.WebSocketServer({ noServer: true });
+    const claudeWsServer = 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 replayRaw = String(reqUrl.searchParams.get('replay') || '').trim().toLowerCase();
+        const replayDisabled = replayRaw === '0' || replayRaw === 'false' || replayRaw === 'off';
+        const afterSeqRaw = String(reqUrl.searchParams.get('afterSeq') || '').trim();
+        const parsedAfterSeq = afterSeqRaw ? Number(afterSeqRaw) : NaN;
+        const hasAfterSeq = afterSeqRaw.length > 0 && Number.isFinite(parsedAfterSeq);
+        const afterSeq = hasAfterSeq ? Math.floor(parsedAfterSeq) : null;
         const record = (0, web_terminal_js_1.readWebTerminalRecord)(id);
         if (!record) {
             sendWebTerminalMessage(ws, { type: 'error', error: 'Terminal session not found' });
@@ -3543,7 +4812,19 @@ function startUI(optsOrPort = {}, standaloneArg = true) {
             exitCode: record.exitCode,
             error: record.error,
         });
-        if (bridge.buffer) {
+        if (afterSeq !== null) {
+            const pending = bridge.history.filter((chunk) => chunk.seq > afterSeq);
+            for (const chunk of pending) {
+                sendWebTerminalMessage(ws, {
+                    type: 'data',
+                    id: record.id,
+                    data: chunk.data,
+                    seqStart: chunk.seq,
+                    seqEnd: chunk.seq,
+                });
+            }
+        }
+        else if (!replayDisabled && bridge.buffer) {
             sendWebTerminalMessage(ws, { type: 'data', id: record.id, data: bridge.buffer });
         }
         ws.on('message', (raw) => {
@@ -3584,6 +4865,65 @@ function startUI(optsOrPort = {}, standaloneArg = true) {
             }
         });
     });
+    claudeWsServer.on('connection', (ws, req) => {
+        const reqUrl = new URL(req.url || '/', 'http://localhost');
+        const id = (reqUrl.searchParams.get('id') || '').trim();
+        const record = (0, web_terminal_js_1.readWebTerminalRecord)(id);
+        if (!record || record.node !== (0, os_1.hostname)()) {
+            sendWebTerminalMessage(ws, { type: 'error', error: 'Terminal session not found on this node.' });
+            ws.close();
+            return;
+        }
+        if (record.agent !== 'claude') {
+            sendWebTerminalMessage(ws, { type: 'error', error: 'Headless chat is currently supported for Claude sessions only.' });
+            ws.close();
+            return;
+        }
+        let disposeRun = null;
+        let runInFlight = false;
+        ws.on('message', (raw) => {
+            if (runInFlight) {
+                sendWebTerminalMessage(ws, { type: 'error', error: 'Headless Claude run already in progress for this socket.' });
+                return;
+            }
+            let parsed = null;
+            try {
+                parsed = JSON.parse(raw.toString('utf-8'));
+            }
+            catch {
+                sendWebTerminalMessage(ws, { type: 'error', error: 'Invalid request payload.' });
+                return;
+            }
+            if (!parsed || parsed.type !== 'prompt') {
+                sendWebTerminalMessage(ws, { type: 'error', error: 'Unsupported request. Expected { type: "prompt", prompt }.' });
+                return;
+            }
+            const prompt = typeof parsed.prompt === 'string' ? parsed.prompt : '';
+            const resumeSessionId = typeof parsed.resumeSessionId === 'string' ? parsed.resumeSessionId : '';
+            runInFlight = true;
+            void startClaudeHeadlessWsRun(ws, record, prompt, resumeSessionId)
+                .then((cleanup) => {
+                disposeRun = cleanup;
+            })
+                .catch((err) => {
+                sendWebTerminalMessage(ws, {
+                    type: 'error',
+                    code: 'headless_failed',
+                    error: err?.message ?? String(err),
+                });
+                sendWebTerminalMessage(ws, { type: 'done', exitCode: 1, isError: true });
+            });
+        });
+        ws.on('close', () => {
+            if (disposeRun) {
+                try {
+                    disposeRun();
+                }
+                catch { /* best effort */ }
+            }
+            disposeRun = null;
+        });
+    });
     const server = (0, http_1.createServer)(async (req, res) => {
         const url = req.url ?? '/';
         const reqUrl = new URL(url, 'http://localhost');
@@ -3709,9 +5049,24 @@ function startUI(optsOrPort = {}, standaloneArg = true) {
             else if (pathname === '/api/terminal/sessions' && method === 'GET') {
                 await handleGetWebTerminalSessions(res);
             }
+            else if (pathname === '/api/terminal/history' && method === 'GET') {
+                await handleGetWebTerminalHistory(reqUrl, res);
+            }
+            else if (pathname === '/api/terminal/init' && method === 'GET') {
+                await handleGetWebTerminalInit(reqUrl, res);
+            }
+            else if (pathname === '/api/terminal/init' && method === 'POST') {
+                await handlePostWebTerminalInit(req, res);
+            }
             else if (pathname === '/api/terminal/start' && method === 'POST') {
                 await handlePostWebTerminalStart(req, res);
             }
+            else if (pathname === '/api/terminal/agent/update' && method === 'POST') {
+                await handlePostWebTerminalAgentUpdate(req, res);
+            }
+            else if (pathname === '/api/terminal/rename' && method === 'POST') {
+                await handlePostWebTerminalRename(req, res);
+            }
             else if (pathname === '/api/terminal/stop' && method === 'POST') {
                 await handlePostWebTerminalStop(req, res);
             }
@@ -3805,7 +5160,8 @@ 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') {
+        const pathname = reqUrl.pathname;
+        if (pathname !== '/api/terminal/ws' && pathname !== '/api/claude/ws') {
             upgradeBadRequest(socket);
             return;
         }
@@ -3835,13 +5191,24 @@ function startUI(optsOrPort = {}, standaloneArg = true) {
             upgradeBadRequest(socket);
             return;
         }
-        wsServer.handleUpgrade(req, socket, head, (ws) => {
-            wsServer.emit('connection', ws, req);
+        if (pathname === '/api/terminal/ws') {
+            wsServer.handleUpgrade(req, socket, head, (ws) => {
+                wsServer.emit('connection', ws, req);
+            });
+            return;
+        }
+        if (record.agent !== 'claude') {
+            upgradeBadRequest(socket);
+            return;
+        }
+        claudeWsServer.handleUpgrade(req, socket, head, (ws) => {
+            claudeWsServer.emit('connection', ws, req);
         });
     });
     const bindTcp = (nextPort) => {
         listenPort = nextPort;
-        server.listen(listenPort, '127.0.0.1');
+        const address = options.listenAddress || '127.0.0.1';
+        server.listen(listenPort, address);
     };
     const bindUnixSocket = () => {
         try {
@@ -3857,51 +5224,104 @@ function startUI(optsOrPort = {}, standaloneArg = true) {
         if (started)
             return;
         started = true;
-        if (useTcp) {
-            const actualPort = server.address()?.port ?? listenPort;
-            dashboardQuickLink = `http://localhost:${actualPort}${UI_SHORT_LINK_PREFIX}${uiShortCode}`;
-            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);
+        void (async () => {
+            if (prewarmImageOnStartup) {
+                try {
+                    const cfg = (0, config_js_1.loadConfig)();
+                    const runtimeReady = await prepareRuntimeForWebTerminal(cfg.runtime);
+                    if (!runtimeReady.ok) {
+                        const firstLine = String(runtimeReady.error || 'Container runtime unavailable.')
+                            .split('\n')[0]
+                            .trim();
+                        log.warn(`Skipping startup image preparation: ${firstLine}`);
+                    }
+                    else {
+                        const runtimeCheck = (0, runtime_js_1.checkRuntime)(cfg.runtime);
+                        if (!runtimeCheck.ok || !runtimeCheck.runtime) {
+                            const firstLine = String(runtimeCheck.error || 'Container runtime unavailable.')
+                                .split('\n')[0]
+                                .trim();
+                            log.warn(`Skipping startup image preparation: ${firstLine}`);
+                        }
+                        else {
+                            const runtime = runtimeCheck.runtime;
+                            const image = cfg.image;
+                            let imageExists = false;
+                            if (runtime === 'podman') {
+                                try {
+                                    await execFileAsync('podman', ['image', 'exists', image], {
+                                        timeout: 10_000,
+                                        maxBuffer: WEB_TERMINAL_IMAGE_PULL_MAX_BUFFER,
+                                    });
+                                    imageExists = true;
+                                }
+                                catch {
+                                    imageExists = false;
+                                }
+                            }
+                            else {
+                                imageExists = (0, fs_1.existsSync)((0, path_1.join)((0, config_js_1.getImagesDir)(), (0, container_js_1.imageToSifName)(image)));
+                            }
+                            if (!imageExists) {
+                                log.step(`No cached image found for ${image}. Preparing it before opening UI...`);
+                                await ensureWebTerminalImageReady(runtime, image);
+                                log.success(`Prepared image ${image}.`);
+                            }
+                        }
+                    }
+                }
+                catch (err) {
+                    const detail = commandErrorDetail(err);
+                    const firstLine = (detail || err?.message || String(err)).split('\n')[0].trim();
+                    log.warn(`Startup image preparation failed: ${firstLine}`);
+                }
             }
-        }
-        else {
-            try {
-                (0, fs_1.chmodSync)(socketPath, config_js_1.PRIVATE_FILE_MODE);
+            if (useTcp) {
+                const actualPort = server.address()?.port ?? listenPort;
+                dashboardQuickLink = `http://localhost:${actualPort}${UI_SHORT_LINK_PREFIX}${uiShortCode}`;
+                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);
+                }
             }
-            catch {
-                // Best effort on platforms that do not support chmod on sockets.
+            else {
+                try {
+                    (0, fs_1.chmodSync)(socketPath, config_js_1.PRIVATE_FILE_MODE);
+                }
+                catch {
+                    // Best effort on platforms that do not support chmod on sockets.
+                }
+                log.step(`Settings socket: ${socketPath}`);
+                log.step('Use `labgate ui` for browser access on localhost (default port: 7700).');
             }
-            log.step(`Settings socket: ${socketPath}`);
-            log.step('Use `labgate ui` for browser access on localhost (default port: 7700).');
-        }
-        if (standalone) {
-            log.step('Press Ctrl+C to stop');
-        }
-        // Initialise SLURM tracking if enabled
-        const slurmConfig = (0, config_js_1.loadConfig)();
-        if (slurmConfig.slurm.enabled && !slurmDB) {
-            try {
-                slurmDB = new slurm_db_js_1.SlurmJobDB((0, config_js_1.getSlurmDbPath)());
-                slurmPoller = new slurm_poller_js_1.SlurmPoller({
-                    db: slurmDB,
-                    pollIntervalMs: slurmConfig.slurm.poll_interval_seconds * 1000,
-                    sacctLookbackHours: slurmConfig.slurm.sacct_lookback_hours,
-                });
-                slurmPoller.start();
-                log.step('SLURM job tracking enabled');
+            if (standalone) {
+                log.step('Press Ctrl+C to stop');
             }
-            catch (err) {
-                log.warn(`SLURM tracking unavailable: ${err.message}`);
+            // Initialise SLURM tracking if enabled
+            const slurmConfig = (0, config_js_1.loadConfig)();
+            if (slurmConfig.slurm.enabled && !slurmDB) {
+                try {
+                    slurmDB = new slurm_db_js_1.SlurmJobDB((0, config_js_1.getSlurmDbPath)());
+                    slurmPoller = new slurm_poller_js_1.SlurmPoller({
+                        db: slurmDB,
+                        pollIntervalMs: slurmConfig.slurm.poll_interval_seconds * 1000,
+                        sacctLookbackHours: slurmConfig.slurm.sacct_lookback_hours,
+                    });
+                    slurmPoller.start();
+                    log.step('SLURM job tracking enabled');
+                }
+                catch (err) {
+                    log.warn(`SLURM tracking unavailable: ${err.message}`);
+                }
             }
-        }
-        startSSEBroadcast();
+            startSSEBroadcast();
+        })();
     });
     server.on('close', () => {
         if (dashboardQuickLink)
@@ -3917,6 +5337,7 @@ function startUI(optsOrPort = {}, standaloneArg = true) {
         }
         webTerminalBridges.clear();
         wsServer.close();
+        claudeWsServer.close();
     });
     server.on('error', (err) => {
         if (!useTcp && err.code === 'EADDRINUSE') {
@@ -3960,6 +5381,12 @@ function startUI(optsOrPort = {}, standaloneArg = true) {
                 // Best effort cleanup.
             }
         }
+        if (sseInterval) {
+            clearInterval(sseInterval);
+            sseInterval = null;
+        }
+        sseClients.clear();
+        stopResultsWatcher();
         // Cleanup SLURM resources
         if (slurmPoller) {
             slurmPoller.stop();