labgate 0.5.30 → 0.5.32

package/dist/cli.js

@@ -37,6 +37,7 @@ const commander_1 = require("commander");
 const path_1 = require("path");
 const fs_1 = require("fs");
 const os_1 = require("os");
+const child_process_1 = require("child_process");
 const net_1 = require("net");
 const readline_1 = require("readline");
 const config_js_1 = require("./lib/config.js");
@@ -378,11 +379,13 @@ program
         process.exit(1);
     }
     const { startUI } = await import('./lib/ui.js');
+    const prewarmImageOnStartup = process.env.LABGATE_UI_PREWARM_ON_START === '1';
     const server = startUI({
         port: Number.isFinite(parsedPort) ? parsedPort : undefined,
         socketPath: hasSocket ? socketInput : undefined,
         listenAddress: hasListenAddress ? listenAddressInput : undefined,
         standalone: true,
+        prewarmImageOnStartup,
     });
     // In standalone mode, keep the process alive
     server.ref();
@@ -395,6 +398,86 @@ program
     const { listSessions } = await import('./lib/container.js');
     await listSessions();
 });
+// ── labgate continue [id-or-name] ─────────────────────────
+program
+    .command('continue')
+    .description('Attach to a running web terminal session (id, prefix, or custom name)')
+    .argument('[idOrName]', 'Web terminal session id, id prefix, or custom name')
+    .option('--latest', 'Attach to the most recent runnable local web terminal session')
+    .action(async (idOrName, opts) => {
+    const web = await import('./lib/web-terminal.js');
+    const { getTmuxBinary, hasTmuxSession, listWebTerminalRecords, resolveWebTerminalRecord } = web;
+    const query = (idOrName || '').trim();
+    const localNode = (0, os_1.hostname)();
+    const isInteractive = !!(process.stdin.isTTY && process.stdout.isTTY);
+    if (!query && !opts.latest && !isInteractive) {
+        console.error('No session id provided in non-interactive mode. Pass a session id/name or use `--latest`.');
+        process.exit(1);
+    }
+    let target = null;
+    if (query) {
+        const resolved = resolveWebTerminalRecord(query);
+        const localMatches = resolved.matches.filter((record) => record.node === localNode);
+        if (resolved.record && resolved.record.node === localNode) {
+            target = resolved.record;
+        }
+        else if (localMatches.length === 1) {
+            target = localMatches[0];
+        }
+        else if (localMatches.length > 1) {
+            console.error(`Ambiguous session selector "${query}". Matches:`);
+            for (const match of localMatches) {
+                const name = match.name ? ` (${match.name})` : '';
+                console.error(`  - ${match.id}${name}`);
+            }
+            process.exit(1);
+        }
+        else if (resolved.record && resolved.record.node !== localNode) {
+            console.error(`Session "${query}" was found on node "${resolved.record.node}". ` +
+                `Run \`labgate continue\` on that node.`);
+            process.exit(1);
+        }
+        else {
+            console.error(`Session "${query}" not found.`);
+            process.exit(1);
+        }
+    }
+    if (!target) {
+        const localRecords = listWebTerminalRecords().filter((record) => record.node === localNode);
+        for (const record of localRecords) {
+            if (await hasTmuxSession(record.tmuxSession)) {
+                target = record;
+                break;
+            }
+        }
+        if (!target) {
+            console.error('No runnable local web terminal session found. Start one in `labgate ui` first.');
+            process.exit(1);
+        }
+    }
+    else if (!await hasTmuxSession(target.tmuxSession)) {
+        console.error(`Session "${target.id}" is not running.`);
+        process.exit(1);
+    }
+    console.error('Attaching terminal. Tip: press Ctrl+b then d to detach and keep the session running for Web UI reconnect. ' +
+        'Ctrl+C sends SIGINT to the active process.');
+    const tmuxBin = await getTmuxBinary();
+    const attached = (0, child_process_1.spawnSync)(tmuxBin, ['attach-session', '-d', '-t', target.tmuxSession], {
+        stdio: 'inherit',
+    });
+    if (attached.error) {
+        console.error(`Failed to run tmux attach-session: ${attached.error.message}`);
+        process.exit(1);
+    }
+    if (attached.status !== null) {
+        process.exit(attached.status);
+    }
+    if (attached.signal) {
+        const signalNum = os_1.constants.signals[attached.signal];
+        process.exit(typeof signalNum === 'number' ? 128 + signalNum : 1);
+    }
+    process.exit(1);
+});
 // ── labgate stop <id> ─────────────────────────────────────
 program
     .command('stop')
@@ -702,6 +785,539 @@ datasetCmd
     console.log(`  Path:  ${hostPath}`);
     console.log(`  Scanned: ${stats.scanned_at}`);
 });
+// ── labgate explore ─────────────────────────────────────
+const exploreCmd = program
+    .command('explore')
+    .description('Solution Explorer commands');
+exploreCmd
+    .command('create')
+    .description('Create a new Solution Explorer experiment from an existing git repository')
+    .requiredOption('--name <name>', 'Experiment name')
+    .requiredOption('--repo <path>', 'Source repository path to clone for isolated exploration')
+    .requiredOption('--eval <command>', 'Evaluation command (must print JSON as last stdout line)')
+    .option('--base-ref <ref>', 'Base git ref (default: HEAD)', 'HEAD')
+    .option('--timeout <sec>', 'Evaluation timeout seconds', '120')
+    .option('--epsilon <value>', 'Exploration epsilon (0..1)', '0.15')
+    .option('--top-n <count>', 'Top-N pool for epsilon exploration', '5')
+    .option('--max-runs <count>', 'Optional max run budget')
+    .option('--agent-mode <mode>', 'Agent mode: stub|claude_headless', 'stub')
+    .option('--stub-patch <path>', 'Patch file path for stub agent mode')
+    .option('--claude-resume-session <id>', 'Optional Claude session id to resume in claude_headless mode')
+    .option('--claude-timeout <sec>', 'Optional Claude headless timeout seconds (60..14400)')
+    .option('--keep-worktrees', 'Retention policy: keep run worktrees instead of pruning')
+    .option('--artifacts-policy <mode>', 'Retention artifacts mode: all|minimal|none', 'minimal')
+    .option('--keep-last <count>', 'Retention keep_last_n', '50')
+    .option('--keep-failed-last <count>', 'Retention keep_failed_last_n', '20')
+    .option('--keep-best', 'Retention keep best run protected', true)
+    .option('--no-keep-best', 'Retention do not specially protect best run')
+    .option('--prune-after-days <days>', 'Retention prune_artifacts_after_days')
+    .option('--max-delete-runs <count>', 'Retention max_delete_runs', '200')
+    .option('--skip-baseline', 'Skip baseline evaluation check after experiment creation')
+    .action(async (opts) => {
+    try {
+        const timeout = parseInt(opts.timeout, 10);
+        if (!Number.isFinite(timeout) || timeout < 5 || timeout > 86400) {
+            console.error('Error: --timeout must be an integer between 5 and 86400.');
+            process.exit(1);
+        }
+        const epsilon = Number(opts.epsilon);
+        if (!Number.isFinite(epsilon) || epsilon < 0 || epsilon > 1) {
+            console.error('Error: --epsilon must be a number between 0 and 1.');
+            process.exit(1);
+        }
+        const topN = parseInt(opts.topN, 10);
+        if (!Number.isFinite(topN) || topN < 1 || topN > 100) {
+            console.error('Error: --top-n must be an integer between 1 and 100.');
+            process.exit(1);
+        }
+        let maxRuns;
+        if (opts.maxRuns !== undefined) {
+            const parsed = parseInt(opts.maxRuns, 10);
+            if (!Number.isFinite(parsed) || parsed < 1) {
+                console.error('Error: --max-runs must be an integer >= 1.');
+                process.exit(1);
+            }
+            maxRuns = parsed;
+        }
+        const agentModeRaw = String(opts.agentMode || 'stub').trim().toLowerCase();
+        const agentMode = agentModeRaw === 'claude' ? 'claude_headless' : agentModeRaw;
+        if (agentMode !== 'stub' && agentMode !== 'claude_headless') {
+            console.error('Error: --agent-mode must be one of: stub, claude_headless.');
+            process.exit(1);
+        }
+        let claudeTimeout;
+        if (opts.claudeTimeout !== undefined) {
+            const parsed = parseInt(opts.claudeTimeout, 10);
+            if (!Number.isFinite(parsed) || parsed < 60 || parsed > 4 * 60 * 60) {
+                console.error('Error: --claude-timeout must be an integer between 60 and 14400.');
+                process.exit(1);
+            }
+            claudeTimeout = parsed;
+        }
+        const artifactsPolicy = String(opts.artifactsPolicy || 'minimal').trim().toLowerCase();
+        if (!['all', 'minimal', 'none'].includes(artifactsPolicy)) {
+            console.error('Error: --artifacts-policy must be one of: all, minimal, none.');
+            process.exit(1);
+        }
+        const keepLast = parseInt(opts.keepLast, 10);
+        const keepFailedLast = parseInt(opts.keepFailedLast, 10);
+        const maxDeleteRuns = parseInt(opts.maxDeleteRuns, 10);
+        if (!Number.isFinite(keepLast) || keepLast < 0) {
+            console.error('Error: --keep-last must be an integer >= 0.');
+            process.exit(1);
+        }
+        if (!Number.isFinite(keepFailedLast) || keepFailedLast < 0) {
+            console.error('Error: --keep-failed-last must be an integer >= 0.');
+            process.exit(1);
+        }
+        if (!Number.isFinite(maxDeleteRuns) || maxDeleteRuns < 1) {
+            console.error('Error: --max-delete-runs must be an integer >= 1.');
+            process.exit(1);
+        }
+        let pruneAfterDays;
+        if (opts.pruneAfterDays !== undefined) {
+            const parsed = parseInt(opts.pruneAfterDays, 10);
+            if (!Number.isFinite(parsed) || parsed < 1) {
+                console.error('Error: --prune-after-days must be an integer >= 1.');
+                process.exit(1);
+            }
+            pruneAfterDays = parsed;
+        }
+        const policy = {
+            epsilon,
+            top_n: topN,
+            agent_mode: agentMode,
+        };
+        if (maxRuns !== undefined)
+            policy.max_runs = maxRuns;
+        if (opts.stubPatch)
+            policy.stub_patch_file = opts.stubPatch;
+        if (agentMode === 'claude_headless') {
+            const resumeId = String(opts.claudeResumeSession || '').trim();
+            if (resumeId)
+                policy.claude_resume_session_id = resumeId;
+            if (claudeTimeout !== undefined)
+                policy.claude_timeout_sec = claudeTimeout;
+        }
+        const retention = {
+            keep_worktrees: !!opts.keepWorktrees,
+            artifacts: artifactsPolicy,
+            keep_last_n: keepLast,
+            keep_best: opts.keepBest !== false,
+            keep_failed_last_n: keepFailedLast,
+            ...(pruneAfterDays !== undefined ? { prune_artifacts_after_days: pruneAfterDays } : {}),
+            max_delete_runs: maxDeleteRuns,
+        };
+        const { createExplorerExperiment } = await import('./lib/explorer.js');
+        const { runEvaluation } = await import('./lib/explorer-eval.js');
+        const { getExplorerArtifactDir } = await import('./lib/config.js');
+        const { ExplorerStore } = await import('./lib/explorer-store.js');
+        const experiment = createExplorerExperiment({
+            name: opts.name,
+            source_repo_path: opts.repo,
+            eval_command: opts.eval,
+            base_ref: opts.baseRef,
+            eval_timeout_sec: timeout,
+            policy,
+            retention,
+        });
+        console.log(`Experiment created: ${experiment.id}`);
+        console.log(`Name: ${experiment.name}`);
+        console.log(`Repo clone: ${experiment.repo_path}`);
+        console.log(`Base SHA: ${experiment.base_ref}`);
+        if (!opts.skipBaseline) {
+            const baselineArtifactDir = getExplorerArtifactDir(experiment.id, 'baseline');
+            const baseline = runEvaluation({
+                worktree_path: experiment.repo_path,
+                eval_command: experiment.eval_command,
+                timeout_sec: experiment.eval_timeout_sec,
+                artifact_dir: baselineArtifactDir,
+            });
+            const store = new 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();
+            }
+            if (baseline.status === 'eval_ok' && Number.isFinite(baseline.score)) {
+                console.log(`Baseline score: ${baseline.score.toFixed(6)}`);
+                console.log(`Baseline artifacts: ${baselineArtifactDir}`);
+            }
+            else {
+                console.error(`Baseline eval status: ${baseline.status}`);
+                if (baseline.error)
+                    console.error(`Baseline eval error: ${baseline.error}`);
+                console.error(`Baseline logs: ${baseline.stdout_path}, ${baseline.stderr_path}`);
+            }
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err?.message ?? String(err)}`);
+        process.exit(1);
+    }
+});
+exploreCmd
+    .command('list')
+    .description('List existing Solution Explorer experiments')
+    .option('-n, --limit <count>', 'Max experiments to list', '50')
+    .option('--offset <count>', 'Offset for pagination', '0')
+    .action(async (opts) => {
+    try {
+        const limit = parseInt(opts.limit, 10);
+        const offset = parseInt(opts.offset, 10);
+        const { ExplorerStore } = await import('./lib/explorer-store.js');
+        const store = new ExplorerStore();
+        try {
+            const rows = store.listExperiments(Number.isFinite(limit) ? limit : 50, Number.isFinite(offset) ? offset : 0);
+            if (rows.length === 0) {
+                console.log('No experiments found.');
+                return;
+            }
+            for (const row of rows) {
+                console.log(`${row.id}  ${row.status.padEnd(8)}  ${row.name}  base=${row.base_ref.slice(0, 12)}  created=${row.created_at}`);
+            }
+        }
+        finally {
+            store.close();
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err?.message ?? String(err)}`);
+        process.exit(1);
+    }
+});
+exploreCmd
+    .command('status')
+    .description('Show experiment status, best run, and recent runs')
+    .argument('<experimentId>', 'Experiment id')
+    .option('-n, --limit <count>', 'How many recent runs to show', '10')
+    .action(async (experimentId, opts) => {
+    try {
+        const limitParsed = parseInt(opts.limit, 10);
+        const limit = Number.isFinite(limitParsed) && limitParsed > 0 ? limitParsed : 10;
+        const { ExplorerStore } = await import('./lib/explorer-store.js');
+        const store = new ExplorerStore();
+        try {
+            const experiment = store.getExperiment(experimentId);
+            if (!experiment) {
+                console.error(`Experiment not found: ${experimentId}`);
+                process.exit(1);
+            }
+            const best = store.getBestRun(experimentId);
+            const count = store.getRunCount(experimentId);
+            const active = store.hasActiveRun(experimentId);
+            const recent = store.listRuns(experimentId, { limit, offset: 0 });
+            console.log(`Experiment: ${experiment.id}`);
+            console.log(`Name: ${experiment.name}`);
+            console.log(`Status: ${experiment.status}`);
+            console.log(`Runs: ${count}${active ? ' (active run in progress)' : ''}`);
+            console.log(`Base SHA: ${experiment.base_ref}`);
+            if (best && best.score !== null) {
+                console.log(`Best run: ${best.id} score=${best.score.toFixed(6)} status=${best.status}`);
+            }
+            else {
+                console.log('Best run: none yet');
+            }
+            console.log('');
+            console.log('Recent runs:');
+            if (recent.length === 0) {
+                console.log('  (none)');
+            }
+            else {
+                for (const run of recent) {
+                    const score = run.score == null ? '-' : run.score.toFixed(6);
+                    console.log(`  ${run.id}  ${run.status.padEnd(13)}  score=${score}  parent=${(run.parent_run_id || '-').slice(0, 16)}`);
+                }
+            }
+        }
+        finally {
+            store.close();
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err?.message ?? String(err)}`);
+        process.exit(1);
+    }
+});
+exploreCmd
+    .command('pause')
+    .description('Pause an experiment (manual run steps become no-ops)')
+    .argument('<experimentId>', 'Experiment id')
+    .action(async (experimentId) => {
+    const { setExperimentStatus } = await import('./lib/explorer.js');
+    const ok = setExperimentStatus(experimentId, 'paused');
+    if (!ok) {
+        console.error(`Experiment not found: ${experimentId}`);
+        process.exit(1);
+    }
+    console.log(`Paused: ${experimentId}`);
+});
+exploreCmd
+    .command('resume')
+    .description('Resume an experiment')
+    .argument('<experimentId>', 'Experiment id')
+    .action(async (experimentId) => {
+    const { setExperimentStatus } = await import('./lib/explorer.js');
+    const ok = setExperimentStatus(experimentId, 'active');
+    if (!ok) {
+        console.error(`Experiment not found: ${experimentId}`);
+        process.exit(1);
+    }
+    console.log(`Resumed: ${experimentId}`);
+});
+exploreCmd
+    .command('tick')
+    .description('Run one manual exploration step for an experiment')
+    .requiredOption('--experiment <id>', 'Experiment id')
+    .action(async (opts) => {
+    try {
+        const { runAutopilotTick } = await import('./lib/explorer.js');
+        const result = runAutopilotTick(opts.experiment);
+        console.log(JSON.stringify(result, null, 2));
+        if (!result.did_work) {
+            process.exit(result.is_error === true ? 1 : 0);
+        }
+        if (result.status && !['eval_ok'].includes(result.status)) {
+            process.exit(2);
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err?.message ?? String(err)}`);
+        process.exit(1);
+    }
+});
+exploreCmd
+    .command('tree')
+    .description('Print run tree view as JSON')
+    .requiredOption('--experiment <id>', 'Experiment id')
+    .option('--mode <mode>', 'Tree mode: best_path|full', 'best_path')
+    .action(async (opts) => {
+    try {
+        const mode = String(opts.mode || 'best_path').trim() === 'full' ? 'full' : 'best_path';
+        const { getExperimentTree } = await import('./lib/explorer.js');
+        const tree = getExperimentTree(opts.experiment, mode);
+        console.log(JSON.stringify(tree, null, 2));
+    }
+    catch (err) {
+        console.error(`Error: ${err?.message ?? String(err)}`);
+        process.exit(1);
+    }
+});
+exploreCmd
+    .command('leaderboard')
+    .description('Print top scoring runs for an experiment')
+    .requiredOption('--experiment <id>', 'Experiment id')
+    .option('-k, --top <count>', 'Top-K rows', '10')
+    .action(async (opts) => {
+    try {
+        const topParsed = parseInt(opts.top, 10);
+        const topK = Number.isFinite(topParsed) && topParsed > 0 ? topParsed : 10;
+        const { getExperimentLeaderboard } = await import('./lib/explorer.js');
+        const rows = getExperimentLeaderboard(opts.experiment, topK);
+        console.log(JSON.stringify(rows, null, 2));
+    }
+    catch (err) {
+        console.error(`Error: ${err?.message ?? String(err)}`);
+        process.exit(1);
+    }
+});
+exploreCmd
+    .command('gc')
+    .description('Prune old worktrees/artifacts according to retention policy')
+    .requiredOption('--experiment <id>', 'Experiment id')
+    .option('--yes', 'Apply GC changes (default is dry-run)')
+    .option('--prune-worktrees', 'Enable worktree pruning', true)
+    .option('--no-prune-worktrees', 'Disable worktree pruning')
+    .option('--prune-artifacts', 'Enable artifact pruning', true)
+    .option('--no-prune-artifacts', 'Disable artifact pruning')
+    .option('--artifacts <mode>', 'Override artifacts mode: all|minimal|none')
+    .option('--keep-last <count>', 'Override keep_last_n')
+    .option('--keep-failed-last <count>', 'Override keep_failed_last_n')
+    .option('--keep-worktrees', 'Override keep_worktrees=true')
+    .option('--keep-best', 'Override keep_best=true')
+    .option('--no-keep-best', 'Override keep_best=false')
+    .option('--after-days <days>', 'Override prune_artifacts_after_days')
+    .option('--max-delete-runs <count>', 'Override max_delete_runs')
+    .action(async (opts) => {
+    try {
+        const retention = {};
+        if (opts.artifacts !== undefined)
+            retention.artifacts = opts.artifacts;
+        if (opts.keepLast !== undefined)
+            retention.keep_last_n = parseInt(opts.keepLast, 10);
+        if (opts.keepFailedLast !== undefined)
+            retention.keep_failed_last_n = parseInt(opts.keepFailedLast, 10);
+        if (opts.keepWorktrees === true)
+            retention.keep_worktrees = true;
+        if (opts.keepBest !== undefined)
+            retention.keep_best = opts.keepBest !== false;
+        if (opts.afterDays !== undefined)
+            retention.prune_artifacts_after_days = parseInt(opts.afterDays, 10);
+        if (opts.maxDeleteRuns !== undefined)
+            retention.max_delete_runs = parseInt(opts.maxDeleteRuns, 10);
+        const { runExperimentGc } = await import('./lib/explorer.js');
+        const plan = runExperimentGc(opts.experiment, {
+            dry_run: opts.yes !== true,
+            prune_worktrees: opts.pruneWorktrees !== false,
+            prune_artifacts: opts.pruneArtifacts !== false,
+            retention: Object.keys(retention).length > 0 ? retention : undefined,
+        });
+        console.log(JSON.stringify(plan, null, 2));
+    }
+    catch (err) {
+        console.error(`Error: ${err?.message ?? String(err)}`);
+        process.exit(1);
+    }
+});
+const exploreRetentionCmd = exploreCmd
+    .command('retention')
+    .description('Get or update retention policy for an experiment');
+exploreRetentionCmd
+    .command('show')
+    .requiredOption('--experiment <id>', 'Experiment id')
+    .action(async (opts) => {
+    try {
+        const { getExperimentOverview } = await import('./lib/explorer.js');
+        const overview = getExperimentOverview(opts.experiment);
+        if (!overview) {
+            console.error(`Experiment not found: ${opts.experiment}`);
+            process.exit(1);
+        }
+        console.log(JSON.stringify(overview.retention_policy, null, 2));
+    }
+    catch (err) {
+        console.error(`Error: ${err?.message ?? String(err)}`);
+        process.exit(1);
+    }
+});
+exploreRetentionCmd
+    .command('set')
+    .requiredOption('--experiment <id>', 'Experiment id')
+    .option('--keep-worktrees', 'Set keep_worktrees=true')
+    .option('--no-keep-worktrees', 'Set keep_worktrees=false')
+    .option('--artifacts <mode>', 'Set artifacts mode: all|minimal|none')
+    .option('--keep-last <count>', 'Set keep_last_n')
+    .option('--keep-failed-last <count>', 'Set keep_failed_last_n')
+    .option('--keep-best', 'Set keep_best=true')
+    .option('--no-keep-best', 'Set keep_best=false')
+    .option('--after-days <days>', 'Set prune_artifacts_after_days')
+    .option('--max-delete-runs <count>', 'Set max_delete_runs')
+    .action(async (opts) => {
+    try {
+        const patch = {};
+        if (opts.keepWorktrees !== undefined)
+            patch.keep_worktrees = opts.keepWorktrees;
+        if (opts.artifacts !== undefined)
+            patch.artifacts = opts.artifacts;
+        if (opts.keepLast !== undefined)
+            patch.keep_last_n = parseInt(opts.keepLast, 10);
+        if (opts.keepFailedLast !== undefined)
+            patch.keep_failed_last_n = parseInt(opts.keepFailedLast, 10);
+        if (opts.keepBest !== undefined)
+            patch.keep_best = opts.keepBest;
+        if (opts.afterDays !== undefined)
+            patch.prune_artifacts_after_days = parseInt(opts.afterDays, 10);
+        if (opts.maxDeleteRuns !== undefined)
+            patch.max_delete_runs = parseInt(opts.maxDeleteRuns, 10);
+        if (Object.keys(patch).length === 0) {
+            console.error('Error: no retention fields provided.');
+            process.exit(1);
+        }
+        const { setExperimentRetentionPolicy, getExperimentOverview } = await import('./lib/explorer.js');
+        const ok = setExperimentRetentionPolicy(opts.experiment, patch);
+        if (!ok) {
+            console.error(`Experiment not found: ${opts.experiment}`);
+            process.exit(1);
+        }
+        const overview = getExperimentOverview(opts.experiment);
+        console.log(JSON.stringify(overview?.retention_policy || {}, null, 2));
+    }
+    catch (err) {
+        console.error(`Error: ${err?.message ?? String(err)}`);
+        process.exit(1);
+    }
+});
+exploreCmd
+    .command('compare')
+    .description('Compare one run against best/parent/another run')
+    .requiredOption('--experiment <id>', 'Experiment id')
+    .requiredOption('--run <runId>', 'Selected run id')
+    .option('--to <target>', 'Comparison target: best|parent|<runId>', 'best')
+    .option('--diff', 'Include full patch artifact in compare output')
+    .option('--stat', 'Show diff stats (included by default)', true)
+    .action(async (opts) => {
+    try {
+        const { compareRun } = await import('./lib/explorer.js');
+        const result = compareRun({
+            experiment_id: opts.experiment,
+            run_id: opts.run,
+            compare_to: opts.to,
+            include_patch: opts.diff === true,
+        });
+        console.log(JSON.stringify(result, null, 2));
+    }
+    catch (err) {
+        console.error(`Error: ${err?.message ?? String(err)}`);
+        process.exit(1);
+    }
+});
+exploreCmd
+    .command('overview')
+    .description('Print aggregated experiment overview JSON for UI/status panels')
+    .requiredOption('--experiment <id>', 'Experiment id')
+    .action(async (opts) => {
+    try {
+        const { getExperimentOverview } = await import('./lib/explorer.js');
+        const overview = getExperimentOverview(opts.experiment);
+        if (!overview) {
+            console.error(`Experiment not found: ${opts.experiment}`);
+            process.exit(1);
+        }
+        console.log(JSON.stringify(overview, null, 2));
+    }
+    catch (err) {
+        console.error(`Error: ${err?.message ?? String(err)}`);
+        process.exit(1);
+    }
+});
+exploreCmd
+    .command('run')
+    .description('Print run details and artifact paths')
+    .requiredOption('--id <runId>', 'Run id')
+    .action(async (opts) => {
+    try {
+        const { getRunDetails } = await import('./lib/explorer.js');
+        const details = getRunDetails(opts.id);
+        if (!details) {
+            console.error(`Run not found: ${opts.id}`);
+            process.exit(1);
+        }
+        console.log(JSON.stringify(details, null, 2));
+    }
+    catch (err) {
+        console.error(`Error: ${err?.message ?? String(err)}`);
+        process.exit(1);
+    }
+});
+exploreCmd
+    .command('mcp')
+    .description('Run the Solution Explorer MCP server over stdio')
+    .option('--db <path>', 'Override explorer DB path')
+    .action(async (opts) => {
+    if (opts.db) {
+        process.env.LABGATE_EXPLORER_DB = (0, path_1.resolve)(opts.db);
+    }
+    const { main } = await import('./lib/explorer-mcp.js');
+    const args = opts.db ? ['--db', (0, path_1.resolve)(opts.db)] : [];
+    await main(args);
+});
 // ── labgate license ──────────────────────────────────────
 const licenseCmd = program
     .command('license')