lastlight-evals 0.1.1 → 0.2.0

package/dist/run.js

@@ -18,21 +18,39 @@
  * `evals/mechanism.test.ts` in the normal `npm test` suite.
  */
 import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { spawn } from "node:child_process";
 import * as p from "@clack/prompts";
 import chalk from "chalk";
 import { loadDotEnv, hasProviderKey, evalModels, compareModels, modelLabels, resolveModel, setModelsPath } from "./env.js";
-import { runInstance, applyEvalEnv } from "./run-instance.js";
-import { summarize, writeArtifacts, aggregateTrials } from "./report.js";
-import { writeHtml } from "./html-report.js";
+import { runInstance, applyEvalEnv, slug } from "./run-instance.js";
+import { loadMergedConfig } from "./config.js";
+import { summarize, writeArtifacts, writeScorecard, aggregateTrials, } from "./report.js";
 import { bootstrapAssets } from "./bootstrap.js";
 import { discoverTiers, loadInstances, workflowFor } from "./discovery.js";
-import { builtinDatasetsRoot, resultsRoot } from "./paths.js";
+import { builtinDatasetsRoot, tierResultsDir, makeRunId, gitShortSha, resultsRoot, dashboardDistRoot } from "./paths.js";
+import { startServer } from "./serve.js";
 import { runInit } from "./init.js";
-/** Open a file in the OS default browser (best-effort, never throws). */
-function openInBrowser(file) {
-    const url = `file://${file}`;
+/**
+ * A clack spinner in a TTY; in non-TTY (CI / piped / agent) a quiet stub that
+ * drops the animation frames — which redraw dozens of times and shred piped logs
+ * — and emits only the final `stop()` line. The plan note already prints what's
+ * about to run, so dropping the in-progress frames loses nothing in automation.
+ */
+function makeSpinner() {
+    if (process.stdout.isTTY)
+        return p.spinner();
+    return {
+        start: () => { },
+        message: () => { },
+        stop: (msg) => {
+            if (msg)
+                p.log.message(msg);
+        },
+    };
+}
+/** Open a URL in the OS default browser (best-effort, never throws). */
+function openInBrowser(url) {
     const [cmd, args] = process.platform === "darwin"
         ? ["open", [url]]
         : process.platform === "win32"
@@ -81,6 +99,12 @@ function fmtMs(ms) {
 function familyLabel(envKey) {
     return envKey.replace(/_API_KEY$/i, "").toLowerCase() || "default";
 }
+/** Attach run metadata to a scorecard (mutate-and-return; `summarize` hands back
+ * a fresh object each call, so this is safe). */
+function withMeta(card, meta) {
+    card.meta = meta;
+    return card;
+}
 /**
  * Silence `console.*` for the whole batch (parallel mode). The per-run
  * `quiet()` swap saves/restores console and would corrupt under concurrent
@@ -98,6 +122,8 @@ function verdictLine(tierName, inst, r) {
     const head = `${chalk.cyan(tierName)}/${inst.instance_id}`;
     if (r.error)
         return `${head}  ${chalk.red("harness error")}`;
+    if (r.blocked)
+        return `${head}  ${chalk.yellow("blocked")} ${chalk.dim("(workflow gate)")}`;
     const count = (pass) => (pass !== undefined && r.trials ? chalk.dim(` ${pass}/${r.trials}`) : "");
     const parts = [];
     if (r.resolved !== undefined)
@@ -136,24 +162,104 @@ function strFlag(name) {
     }
     return process.env[`EVAL_${name.toUpperCase()}`];
 }
+/** Collect ALL occurrences of a repeatable string flag (`--name a --name b` or
+ * `--name=a`). Used by `--overlay`, which may repeat in `config` mode to compare
+ * one arm per overlay. */
+function strFlagAll(name) {
+    const out = [];
+    const argv = process.argv;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === `--${name}` && argv[i + 1] !== undefined) {
+            out.push(argv[i + 1]);
+            i++;
+            continue;
+        }
+        const m = argv[i].match(new RegExp(`^--${name}=(.+)$`));
+        if (m)
+            out.push(m[1]);
+    }
+    return out;
+}
 /** CLI flags that take a following value (so it isn't read as a tier name). */
-const VALUE_FLAGS = new Set(["--runs", "--model", "--models", "--overlay", "--datasets", "--models-file"]);
+const VALUE_FLAGS = new Set(["--runs", "--model", "--models", "--mode", "--overlay", "--datasets", "--models-file"]);
 async function runEval() {
     loadDotEnv();
     p.intro(chalk.bold(`Last Light ${chalk.yellow("·")} eval`));
+    // Run type — the comparison axis:
+    //   `models` — compare N models, each FORCED across every workflow step.
+    //   `config` — run an overlay's REAL per-step model config (what ships); the
+    //              arm is the config/overlay, compared across runs (or N overlays
+    //              side-by-side). `--mode` wins; an explicit `--model`/`--compare`
+    //              implies `models`; otherwise ask in a TTY (default `models`).
+    const modeFlag = strFlag("mode");
+    const modelArg = strFlag("model") ?? strFlag("models");
+    const compare = process.argv.includes("--compare");
+    let runType;
+    if (modeFlag === "config")
+        runType = "config";
+    else if (modeFlag === "models" || modelArg || compare)
+        runType = "models";
+    else if (process.stdin.isTTY) {
+        const picked = await p.select({
+            message: "What do you want to eval?",
+            options: [
+                { value: "models", label: "compare models", hint: "force each model across every workflow step" },
+                { value: "config", label: "eval config", hint: "an overlay's real per-step model config (what ships)" },
+            ],
+            initialValue: "models",
+        });
+        if (p.isCancel(picked)) {
+            p.cancel("aborted");
+            return 1;
+        }
+        runType = picked;
+    }
+    else
+        runType = "models";
     // Asset roots FIRST — before any getWorkflow/runWorkflow. `--overlay` (or
     // LASTLIGHT_OVERLAY_DIR) layers a deployment's own workflows/skills over the
     // built-ins, and also contributes its `evals/datasets/` (see discovery).
-    const overlayDir = strFlag("overlay") ?? process.env.LASTLIGHT_OVERLAY_DIR;
-    bootstrapAssets({ overlayDir });
+    // With neither set, auto-detect a local `./instance/` overlay checkout — the
+    // Separate layout `init --clone` produces — so a bare run "just works".
+    // `--overlay` may REPEAT in config mode (one arm per overlay).
+    const autoInstance = join(process.cwd(), "instance");
+    const autoOverlay = existsSync(join(autoInstance, "config.yaml")) ? autoInstance : undefined;
+    const overlayFlags = strFlagAll("overlay");
+    let overlays = overlayFlags.length
+        ? overlayFlags
+        : [process.env.LASTLIGHT_OVERLAY_DIR ?? autoOverlay].filter((d) => !!d);
+    // In a config-mode TTY with no overlay given, ask for one (blank ⇒ core defaults).
+    if (runType === "config" && !overlayFlags.length && process.stdin.isTTY) {
+        const ans = await p.text({
+            message: "Overlay dir whose config.yaml drives per-step models (blank = core defaults):",
+            placeholder: overlays[0] ?? autoInstance,
+            initialValue: overlays[0] ?? "",
+        });
+        if (p.isCancel(ans)) {
+            p.cancel("aborted");
+            return 1;
+        }
+        const dir = ans.trim();
+        overlays = dir ? [dir] : [];
+    }
+    // The primary overlay wires discovery + the initial asset bootstrap. Config
+    // arms re-bootstrap their own overlay before running (the asset root is a
+    // process global — see the serial loop below).
+    const overlayDir = overlays[0];
+    if (overlayDir && overlayDir === autoOverlay)
+        p.log.info(`overlay → ${chalk.cyan("./instance")} ${chalk.dim("(auto-detected)")}`);
+    const { builtInRoot } = bootstrapAssets({ overlayDir });
     // A user/overlay can ship its own model registry too: explicit --models-file
     // wins, else an overlay's `evals/models.json` if present, else the built-in.
     const overlayModels = overlayDir ? join(overlayDir, "evals", "models.json") : undefined;
     const modelsFile = strFlag("models-file") ?? (overlayModels && existsSync(overlayModels) ? overlayModels : undefined);
     if (modelsFile)
         setModelsPath(modelsFile);
-    // Discover tiers across built-in + user (--datasets) + overlay roots.
-    const userDatasetsDir = strFlag("datasets") ?? process.env.LASTLIGHT_EVALS_DATASETS;
+    // Discover tiers across built-in + user (--datasets) + overlay roots. With no
+    // explicit `--datasets`, default to the workspace's own `./evals/datasets`
+    // (what `init` seeds) so editing/adding tiers there is picked up automatically.
+    const autoDatasets = join(process.cwd(), "evals", "datasets");
+    const userDatasetsDir = strFlag("datasets") ?? process.env.LASTLIGHT_EVALS_DATASETS ?? (existsSync(autoDatasets) ? autoDatasets : undefined);
     const discovered = discoverTiers({
         builtinRoot: builtinDatasetsRoot(),
         userDatasetsDir,
@@ -165,7 +271,6 @@ async function runEval() {
         p.outro(chalk.red("aborted"));
         return 1;
     }
-    const compare = process.argv.includes("--compare");
     const noOpen = process.argv.includes("--no-open") || !!process.env.CI;
     const runs = intFlag("runs", 1);
     // Positional tier names — skip flags AND the values that follow value-flags.
@@ -221,35 +326,51 @@ async function runEval() {
         if (!discovered.has(t))
             p.log.warn(`Unknown tier "${t}". Known: ${known.join(", ")}`);
     }
-    // Model selection precedence:
-    //   1. --model / --models (or EVAL_MODEL[S]) — an explicit list, fuzzy-matched
-    //      against models.json; lets you test one model quickly.
-    //   2. --compare — the full cross-vendor set (key-gated).
-    //   3. default single model from models.json.
-    // Each entry carries its provider family (env-key) for parallel grouping.
-    const modelArg = strFlag("model") ?? strFlag("models");
-    const mode = modelArg ? "select" : compare ? "compare" : "single";
-    const entries = modelArg
-        ? modelArg
-            .split(",")
-            .map((s) => s.trim())
-            .filter(Boolean)
-            .map((tok) => {
-            const r = resolveModel(tok);
-            return { id: r.id, family: r.family };
-        })
-        : compare
-            ? compareModels().map((m) => ({ id: m.id, family: m.envKey ?? m.provider ?? "default" }))
-            : evalModels().map((id) => ({ id, family: "default" }));
-    if (!entries.length) {
+    // The model-selection sub-mode (only meaningful for `models` runs); shown in
+    // the plan note. `config` runs report their arm count instead.
+    const mode = runType === "config" ? "config" : modelArg ? "select" : compare ? "compare" : "single";
+    let arms;
+    if (runType === "config") {
+        // One arm per overlay (or a single core-defaults arm when none). `--model`
+        // overrides each merged config's `default` key for quick what-if runs.
+        const configOverlays = overlays.length ? overlays : [overlayDir];
+        arms = configOverlays.map((dir) => {
+            const merged = loadMergedConfig(builtInRoot, dir);
+            if (modelArg)
+                merged.models.default = resolveModel(modelArg).id;
+            const label = dir ? basename(dir) : "config";
+            return { label, family: label, modelConfig: merged.models, variantConfig: merged.variants, overlayDir: dir };
+        });
+    }
+    else {
+        // Model selection precedence:
+        //   1. --model / --models (or EVAL_MODEL[S]) — an explicit list, fuzzy-matched.
+        //   2. --compare — the full cross-vendor set (key-gated).
+        //   3. default single model from models.json.
+        const entries = modelArg
+            ? modelArg
+                .split(",")
+                .map((s) => s.trim())
+                .filter(Boolean)
+                .map((tok) => {
+                const r = resolveModel(tok);
+                return { id: r.id, family: r.family };
+            })
+            : compare
+                ? compareModels().map((m) => ({ id: m.id, family: m.envKey ?? m.provider ?? "default" }))
+                : evalModels().map((id) => ({ id, family: "default" }));
+        arms = entries.map((e) => ({ label: e.id, family: e.family }));
+    }
+    if (!arms.length) {
         p.log.error("No comparison models available — set provider keys (OPENAI_API_KEY / ANTHROPIC_API_KEY /\n" +
             "FIREWORKS_API_KEY …) for the entries in evals/models.json.");
         p.outro(chalk.red("aborted"));
         return 1;
     }
     const labels = modelLabels();
-    // Resolve the work-list up front so we can show deterministic progress.
-    const work = [];
+    // Instances per tier, resolved ONCE — the case set is identical across arms
+    // (arms vary only the model selection / assets, never the cases).
+    const tierInstances = new Map();
     for (const tierName of tiers) {
         const tier = discovered.get(tierName);
         const instances = loadInstances(tier);
@@ -257,7 +378,15 @@ async function runEval() {
             p.log.warn(`tier "${tierName}": no instances at ${tier.instancesPath} — skipping`);
             continue;
         }
-        for (const e of entries) {
+        tierInstances.set(tierName, instances);
+    }
+    // Resolve the work-list up front so we can show deterministic progress. Arms
+    // are the OUTER loop so a `config` run's per-arm overlay switches at most once
+    // (the serial loop re-bootstraps on arm change; see below).
+    const work = [];
+    for (const arm of arms) {
+        for (const [tierName, instances] of tierInstances) {
+            const tier = discovered.get(tierName);
             for (const inst of instances) {
                 // Per-instance workflow wins, else the tier's defaultWorkflow (throws if
                 // neither is set — surfaced as a harness error for that case).
@@ -265,8 +394,11 @@ async function runEval() {
                     tierName,
                     defaultWorkflow: workflowFor(tier, inst),
                     datasetDir: tier.root,
-                    model: e.id,
-                    family: e.family,
+                    model: arm.label,
+                    family: arm.family,
+                    modelConfig: arm.modelConfig,
+                    variantConfig: arm.variantConfig,
+                    overlayDir: arm.overlayDir,
                     inst,
                 });
             }
@@ -288,28 +420,78 @@ async function runEval() {
         else
             byFamily.set(w.family, [w]);
     }
-    const parallel = !process.argv.includes("--serial") && byFamily.size > 1;
-    const resultsDir = join(resultsRoot(), `${tiers.join("+")}${compare ? "-compare" : ""}`);
-    const htmlBase = {
-        models: entries.map((e) => labels[e.id] ?? e.id),
-        tiers,
-        labels,
+    // `config` runs stay SERIAL: arms may carry distinct overlays and the asset
+    // root is a process global, so the serial loop re-bootstraps per arm (below).
+    const parallel = runType === "models" && !process.argv.includes("--serial") && byFamily.size > 1;
+    // Each tier writes its OWN folder + scorecard (all sharing this run's id), so
+    // tiers stay separate in the dashboard instead of collapsing into one combined
+    // `<a+b>` entry. A single invocation appears as the same run under each tier it
+    // touched. The `-compare` suffix keeps cross-vendor runs on their own trend
+    // line, distinct from single-model runs of the same tier. The dashboard server
+    // indexes the whole tree; each tier dir is a `tierKey` segment the SPA routes on.
+    // `-compare` keeps cross-vendor runs on their own trend line; `-config` keeps
+    // config-eval runs on theirs — so the three run shapes never collapse together.
+    const gitSha = gitShortSha();
+    const tierKeyFor = (tier) => `${tier}${runType === "config" ? "-config" : compare ? "-compare" : ""}`;
+    // One shared runId, checked free in the first tier's dir (collisions in the
+    // same second across runs are what the suffix guards — rare, one dir suffices).
+    const runId = makeRunId(new Date(), gitSha, tierResultsDir(tierKeyFor(tiers[0])));
+    const resultsDirFor = (tier) => join(tierResultsDir(tierKeyFor(tier)), runId);
+    // Each case's session logs live under `sessions/<id>__<model>/trial-<N>/`
+    // (relative to the tier run dir) — the model is in the name since several
+    // models share a run dir; per-trial keeps every `--runs N` trial. `full.jsonl`
+    // is the consolidated live-followable transcript; `NN-<phase>.jsonl` are the
+    // per-phase splits written when the trial finishes.
+    const caseRelFor = (instanceId, model) => `sessions/${slug(instanceId)}__${slug(model)}`;
+    const trialRelFor = (instanceId, model, trial) => `${caseRelFor(instanceId, model)}/trial-${trial}`;
+    // Per-tier run metadata stamped into every scorecard write (the dashboard reads
+    // identity, labels, and live state straight off disk). `live`/`progress`/
+    // `pending`/`generatedAt` are layered on per write; `tiers` is the single tier.
+    const armLabels = arms.map((a) => labels[a.label] ?? a.label);
+    const baseMetaFor = (tier) => ({
+        runId,
+        runType,
+        tiers: [tier],
+        models: armLabels,
         runs,
-    };
+        gitSha,
+        labels,
+    });
+    // In `config` runs the axis is the config(s); show the merged per-step model
+    // map for a single-arm run so the plan is legible.
+    const axisLine = runType === "config"
+        ? `${chalk.bold("configs")} ${armLabels.join(", ")}`
+        : `${chalk.bold("models")}  ${armLabels.join(", ")}`;
+    const phaseMapLine = runType === "config" && arms.length === 1 && arms[0].modelConfig
+        ? `\n${chalk.bold("models")}  ${chalk.dim(Object.entries(arms[0].modelConfig)
+            .map(([k, v]) => `${k}→${v}`)
+            .join("  "))}`
+        : "";
     p.note(`${chalk.bold("mode")}    ${mode}${parallel ? chalk.dim(` (parallel · ${byFamily.size} families)`) : ""}\n` +
-        `${chalk.bold("models")}  ${entries.map((e) => labels[e.id] ?? e.id).join(", ")}\n` +
+        `${axisLine}${phaseMapLine}\n` +
         `${chalk.bold("tiers")}   ${tiers.join(", ")}\n` +
         `${chalk.bold("cases")}   ${work.length}${runs > 1
             ? chalk.dim(` × ${runs} trials = ${work.length * runs} runs · worst-case verdict, mean cost`)
             : ""}`, "plan");
     // `total` counts individual trials so live progress advances per model call.
     const total = work.length * runs;
-    // Open the report immediately (live placeholder) so it fills in as we go.
-    writeHtml(resultsDir, summarize([]), { ...htmlBase, generatedAt: new Date().toISOString(), live: true, progress: `0/${total}` });
-    const htmlFile = join(resultsDir, "index.html");
+    // Seed an empty live scorecard per tier so the dashboard has something to poll,
+    // then start the server and open the SPA deep-linked at this run. The server is
+    // skipped entirely when not opening (CI / --no-open) — we only write JSON.
+    for (const tier of tiers) {
+        writeScorecard(resultsDirFor(tier), withMeta(summarize([]), { ...baseMetaFor(tier), generatedAt: new Date().toISOString(), live: true, progress: `0/${total}` }));
+    }
+    let server;
     if (!noOpen) {
-        openInBrowser(htmlFile);
-        p.log.info(`Live report → ${chalk.cyan(htmlFile)} ${chalk.dim("(auto-refreshing)")}`);
+        try {
+            server = await startServer({ resultsRoot: resultsRoot(), dashboardRoot: dashboardDistRoot() });
+            const runUrl = `${server.url}/#/${encodeURIComponent(tierKeyFor(tiers[0]))}/${encodeURIComponent(runId)}`;
+            openInBrowser(runUrl);
+            p.log.info(`Live dashboard → ${chalk.cyan(runUrl)}`);
+        }
+        catch (err) {
+            p.log.warn(`Couldn't start the dashboard server (${err.message}) — writing JSON only.`);
+        }
     }
     const all = [];
     let harnessErrors = 0;
@@ -317,44 +499,76 @@ async function runEval() {
     // Track in-flight cases so the live report can show running / queued rows.
     const caseKey = (tier, model, id) => `${tier}|${model}|${id}`;
     const running = new Set();
-    // writeHtml/summarize/all.push run synchronously to completion inside one
-    // event-loop turn, so even with concurrent families they never interleave.
+    // Current trial number per running case, so the live "follow" link points at
+    // the right `trial-<N>/full.jsonl` (matters only for `--runs N>1`).
+    const trialOf = new Map();
+    // writeScorecard/summarize/all.push run synchronously to completion inside one
+    // event-loop turn, so even with concurrent families they never interleave; the
+    // temp-file+rename keeps a polling dashboard from reading a half-written file.
     const refresh = () => {
         const done = new Set(all.map((r) => caseKey(r.tier ?? "", r.model, r.instance_id)));
-        const pending = work
-            .map((w) => ({ w, k: caseKey(w.tierName, w.model, w.inst.instance_id) }))
-            .filter(({ k }) => !done.has(k))
-            .map(({ w, k }) => ({
-            tier: w.tierName,
-            model: w.model,
-            instance_id: w.inst.instance_id,
-            status: (running.has(k) ? "running" : "pending"),
-        }));
-        writeHtml(resultsDir, summarize(all), {
-            ...htmlBase,
-            generatedAt: new Date().toISOString(),
-            live: true,
-            progress: `${completed}/${total}`,
-            pending,
-        });
+        const now = new Date().toISOString();
+        for (const tier of tiers) {
+            const tierResults = all.filter((r) => (r.tier ?? "") === tier);
+            const pending = work
+                .filter((w) => w.tierName === tier)
+                .map((w) => ({ w, k: caseKey(w.tierName, w.model, w.inst.instance_id) }))
+                .filter(({ k }) => !done.has(k))
+                .map(({ w, k }) => ({
+                tier: w.tierName,
+                model: w.model,
+                instance_id: w.inst.instance_id,
+                status: running.has(k) ? "running" : "pending",
+                // Only a running case has a (live-updating) transcript to follow —
+                // point at the current trial's consolidated `full.jsonl`.
+                sessionLog: running.has(k)
+                    ? `${trialRelFor(w.inst.instance_id, w.model, trialOf.get(k) ?? 1)}/full.jsonl`
+                    : undefined,
+            }));
+            // Per-tier progress (cases), not the global trial count — each tier's
+            // scorecard stands alone, so "0/5" across both tiers was misleading.
+            const tierCases = work.filter((w) => w.tierName === tier).length;
+            writeScorecard(resultsDirFor(tier), withMeta(summarize(tierResults), {
+                ...baseMetaFor(tier),
+                generatedAt: now,
+                live: true,
+                progress: `${tierResults.length}/${tierCases}`,
+                pending,
+            }));
+        }
     };
     // Run one case `runs` times and fold the trials into a single result
     // (worst-case verdict, mean metrics). `onTrial` ticks per model call.
     const runItem = async (w, onTrial) => {
+        const k = caseKey(w.tierName, w.model, w.inst.instance_id);
         const trials = [];
-        for (let t = 0; t < runs; t++) {
+        for (let t = 1; t <= runs; t++) {
+            trialOf.set(k, t); // so the live "follow" link targets this trial
+            const trialRel = trialRelFor(w.inst.instance_id, w.model, t);
             const r = await runInstance(w.inst, {
                 model: w.model,
+                // `config` arms carry the merged per-step maps; `models` arms leave
+                // these undefined so the workflow forces `w.model` on every step.
+                modelConfig: w.modelConfig,
+                variantConfig: w.variantConfig,
                 datasetDir: w.datasetDir,
                 defaultWorkflow: w.defaultWorkflow,
                 manageEnv: false,
+                // Per-trial dir: `full.jsonl` (consolidated, live) + `NN-<phase>.jsonl`.
+                sessionTrialDir: join(resultsDirFor(w.tierName), trialRel),
+                sessionTrialRel: trialRel,
+                trial: t,
             });
             r.tier = w.tierName;
             trials.push(r);
             completed++;
             onTrial();
         }
-        return aggregateTrials(trials);
+        const agg = aggregateTrials(trials);
+        // Keep every trial's per-phase sessions on the aggregate (aggregateTrials
+        // only carries trial 0's fields through).
+        agg.sessions = trials.map((r) => r.sessionTrial).filter((s) => !!s);
+        return agg;
     };
     // Install the eval's static-token env ONCE for the whole batch so concurrent
     // runs share one stable baseline (manageEnv:false on every runInstance).
@@ -372,7 +586,7 @@ async function runEval() {
                 });
                 return `${chalk.dim(`${completed}/${total}`)}  ${segs.join(chalk.dim(" · "))}`;
             };
-            const s = p.spinner();
+            const s = makeSpinner();
             s.start(status());
             const restoreConsole = silenceConsole();
             const verdicts = [];
@@ -391,7 +605,7 @@ async function runEval() {
                         all.push(result);
                         if (result.error)
                             harnessErrors++;
-                        const mark = result.error ? chalk.red("✗") : chalk.green("✓");
+                        const mark = result.error ? chalk.red("✗") : result.blocked ? chalk.yellow("■") : chalk.green("✓");
                         verdicts.push(`${mark} ${chalk.dim(familyLabel(f))}  ${verdictLine(w.tierName, w.inst, result)}`);
                         refresh();
                     }
@@ -405,9 +619,16 @@ async function runEval() {
         }
         else {
             // Serial: one spinner per case (updates per trial) + a verdict line.
+            // `config` runs repoint the (process-global) asset root when the arm's
+            // overlay changes — work is arms-outer, so this fires at most once per arm.
+            let currentOverlay = overlayDir;
             for (let i = 0; i < work.length; i++) {
                 const w = work[i];
-                const s = p.spinner();
+                if (runType === "config" && w.overlayDir !== currentOverlay) {
+                    bootstrapAssets({ overlayDir: w.overlayDir });
+                    currentOverlay = w.overlayDir;
+                }
+                const s = makeSpinner();
                 const head = `${chalk.dim(`[${i + 1}/${work.length}]`)} ${chalk.cyan(w.tierName)}/${w.inst.instance_id}  ${chalk.dim(labels[w.model] ?? w.model)}`;
                 s.start(head);
                 const k = caseKey(w.tierName, w.model, w.inst.instance_id);
@@ -424,7 +645,7 @@ async function runEval() {
                 all.push(result);
                 if (result.error)
                     harnessErrors++;
-                const mark = result.error ? chalk.red("✗") : chalk.green("✓");
+                const mark = result.error ? chalk.red("✗") : result.blocked ? chalk.yellow("■") : chalk.green("✓");
                 s.stop(`${chalk.dim(`[${i + 1}/${work.length}]`)} ${mark} ${verdictLine(w.tierName, w.inst, result)}`);
                 if (result.error) {
                     p.log.error(chalk.dim(result.error));
@@ -439,28 +660,119 @@ async function runEval() {
     finally {
         restoreEvalEnv();
     }
-    // Final, static report + machine artifacts.
-    const card = summarize(all);
-    writeArtifacts(resultsDir, card);
-    const html = writeHtml(resultsDir, card, { ...htmlBase, generatedAt: new Date().toISOString() });
-    p.log.success(`Scorecard → ${chalk.cyan(html)}`);
-    p.log.success(`Artifacts → ${chalk.cyan(resultsDir)}/{scorecard.json,predictions.jsonl}`);
+    // Final, static scorecard + machine artifacts. The run-level metadata is
+    // persisted into scorecard.json so the dashboard can label, order, and (no
+    // longer) live-poll the run without re-deriving from the current config.
+    const generatedAt = new Date().toISOString();
+    for (const tier of tiers) {
+        const tierResults = all.filter((r) => (r.tier ?? "") === tier);
+        writeArtifacts(resultsDirFor(tier), withMeta(summarize(tierResults), { ...baseMetaFor(tier), generatedAt, live: false }));
+    }
+    p.log.success(`Artifacts → ${chalk.cyan(tiers.map((t) => resultsDirFor(t)).join("\n             "))}\n             /{scorecard.json,predictions.jsonl,sessions/}`);
     const ran = runs > 1 ? `${completed} runs (${all.length} cases × ${runs})` : `${all.length} runs`;
-    if (harnessErrors > 0) {
-        p.outro(chalk.yellow(`done — ${ran}, ${harnessErrors} harness error${harnessErrors === 1 ? "" : "s"} (see above)`));
+    // Keep the dashboard server alive so the just-finished run stays viewable.
+    // Only block in an interactive terminal — piped/non-TTY callers exit cleanly.
+    if (server && process.stdout.isTTY) {
+        const runUrl = `${server.url}/#/${encodeURIComponent(tierKeyFor(tiers[0]))}/${encodeURIComponent(runId)}`;
+        p.log.success(`Dashboard → ${chalk.cyan(runUrl)} ${chalk.dim("(serving · Ctrl-C to stop)")}`);
+        const tail = harnessErrors > 0 ? chalk.yellow(`done — ${ran}, ${harnessErrors} harness error${harnessErrors === 1 ? "" : "s"} (see above)`) : chalk.green(`done — ${ran}`);
+        p.outro(tail);
+        await waitForSigint();
+        await server.close();
     }
     else {
-        p.outro(chalk.green(`done — ${ran}, report at ${html}`));
+        if (server)
+            await server.close();
+        if (harnessErrors > 0) {
+            p.outro(chalk.yellow(`done — ${ran}, ${harnessErrors} harness error${harnessErrors === 1 ? "" : "s"} (see above)`));
+        }
+        else {
+            p.outro(chalk.green(`done — ${ran}`));
+        }
     }
     // Non-zero ONLY on harness failure — model quality is the measurement.
     return harnessErrors > 0 ? 1 : 0;
 }
-/** Top-level subcommand dispatcher: `run` (default) | `init`. */
+/** Resolve on the first SIGINT (Ctrl-C) so `run`/`serve` can keep a server up
+ * for browsing and shut it down cleanly when the user is done. */
+function waitForSigint() {
+    return new Promise((resolve) => {
+        const onSig = () => {
+            process.off("SIGINT", onSig);
+            resolve();
+        };
+        process.on("SIGINT", onSig);
+    });
+}
+/**
+ * `serve` — start the dashboard server over `eval-results/` and open it in the
+ * browser to browse every past run (no models run). The same server `run` uses
+ * for the live report; blocks until Ctrl-C. There is no HTML to regenerate any
+ * more — the SPA reads the JSON directly.
+ */
+async function runServe() {
+    loadDotEnv();
+    const noOpen = process.argv.includes("--no-open");
+    const port = intFlag("port", 0) || undefined;
+    let server;
+    try {
+        server = await startServer({ resultsRoot: resultsRoot(), dashboardRoot: dashboardDistRoot(), port });
+    }
+    catch (err) {
+        console.error(`Couldn't start the dashboard server: ${err.message}`);
+        return 1;
+    }
+    console.log(`Dashboard → ${server.url}  (serving ${resultsRoot()} · Ctrl-C to stop)`);
+    if (!noOpen)
+        openInBrowser(server.url);
+    await waitForSigint();
+    await server.close();
+    return 0;
+}
+const USAGE = `lastlight-evals — eval harness for Last Light workflows
+
+Usage:
+  lastlight-evals [run] [tiers...] [options]   Run evals (default command)
+  lastlight-evals init [dir] [options]         Scaffold an overlay+evals workspace
+  lastlight-evals serve [options]              Browse past runs in the dashboard (no models run)
+
+Run options:
+  --mode <models|config>  Comparison axis. models (default): force each --model
+                          across every step. config: run an overlay's real
+                          per-step model config (its config.yaml). No flags in a
+                          TTY ⇒ asks.
+  --overlay <dir>      Layer a deployment's workflows/skills + evals/ over built-ins.
+                       Repeatable in --mode config (one arm per overlay).
+  --model <m[,m2]>     models: model(s) to run (fuzzy-matched against models.json).
+                       config: override each config's default model.
+  --compare            Cross-vendor set (only models whose provider key is present)
+  --runs <n>           Repeat each case n× (worst-case verdict, mean metrics)
+  --serial             Force serial execution across provider families
+  --datasets <dir>     Extra datasets root to discover tiers from
+  --models-file <f>    Use an explicit models.json
+  --no-open            Don't open / auto-serve the dashboard (also implied by CI=1)
+
+Serve options:
+  --port <n>           Preferred port for the dashboard server (default 4319)
+  --no-open            Start the server but don't open a browser
+
+Run \`lastlight-evals init --help\` for init-specific flags.
+GitHub is mocked end-to-end — no real GitHub token is needed, only a provider key.`;
+/** Top-level subcommand dispatcher: `run` (default) | `init` | `serve`. */
 async function main() {
     const sub = process.argv[2];
+    // Top-level help — only when it's not standing in for a `run` tier name.
+    if (sub === "help" || sub === "--help" || sub === "-h") {
+        console.log(USAGE);
+        return 0;
+    }
     if (sub === "init") {
-        // `init [dir]` — scaffold a fresh overlay+evals repo.
-        return runInit(process.argv[3]);
+        // `init [dir] [flags]` — scaffold a fresh overlay+evals repo.
+        return runInit(process.argv.slice(3));
+    }
+    if (sub === "serve") {
+        // `serve` — browse past runs; the live dashboard server, standalone.
+        return runServe();
     }
     // `run` is the default; allow an explicit leading `run` token too.
     if (sub === "run")