@otto-code/brain 0.7.6 → 0.8.1

package/dist/ops/report.js

@@ -26,7 +26,7 @@ function escapeHtml(text) {
     return String(text).replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
 }
 function formatGiB(bytes) {
-    return bytes ? `${(bytes / 1024 ** 3).toFixed(1)} GB` : "—";
+    return bytes ? `${(bytes / 1024 ** 3).toFixed(1)} GB` : "-";
 }
 /**
  * Per-model score card: each task labelled directly with its weight, then the
@@ -77,8 +77,8 @@ function groupedBars(records, columns, weightOf) {
                 (weight
                     ? `<text x="${labelWidth - 8}" y="${y + barHeight - 2}" text-anchor="end" class="twt">×${weight}</text>`
                     : "") +
-                bar(labelWidth, y, score * chartWidth, "scorebar", `${label}: ${(score * 100).toFixed(0)}%${weight ? ` (weight ${weight})` : ""} — ${escapeHtml(task ? task.summary : "not run")}`) +
-                `<text x="${labelWidth + chartWidth + 8}" y="${y + barHeight - 2}" class="val">${task ? `${(score * 100).toFixed(0)}%` : "—"}</text>`);
+                bar(labelWidth, y, score * chartWidth, "scorebar", `${label}: ${(score * 100).toFixed(0)}%${weight ? ` (weight ${weight})` : ""} - ${escapeHtml(task ? task.summary : "not run")}`) +
+                `<text x="${labelWidth + chartWidth + 8}" y="${y + barHeight - 2}" class="val">${task ? `${(score * 100).toFixed(0)}%` : "-"}</text>`);
         });
         // The weighted Overall, set off by a divider so it reads as the sum of the
         // task rows above it rather than one more task.
@@ -138,7 +138,7 @@ function depthChart(series, { valueOf, label, unit, formatValue }) {
             // 2px surface ring keeps overlapping markers separable.
             parts.push(`<circle cx="${sx(p.promptTokens || 0).toFixed(1)}" cy="${sy(v).toFixed(1)}" r="4.5" ` +
                 `fill="var(--series-${i + 1})" stroke="var(--surface-1)" stroke-width="2">` +
-                `<title>${escapeHtml(s.name)} — ${(p.promptTokens || 0).toLocaleString()} tokens: ` +
+                `<title>${escapeHtml(s.name)} - ${(p.promptTokens || 0).toLocaleString()} tokens: ` +
                 `${formatValue(v)} ${escapeHtml(unit)}</title></circle>`);
         }
     });
@@ -175,7 +175,7 @@ function runsChart(series) {
         for (const p of ordered) {
             parts.push(`<circle cx="${sx(p.runIndex).toFixed(1)}" cy="${sy(p.score).toFixed(1)}" r="4.5" ` +
                 `fill="var(--series-${i + 1})" stroke="var(--surface-1)" stroke-width="2">` +
-                `<title>${escapeHtml(s.name)} — run ${p.runIndex}: ${(p.score * 100).toFixed(0)}%</title></circle>`);
+                `<title>${escapeHtml(s.name)} - run ${p.runIndex}: ${(p.score * 100).toFixed(0)}%</title></circle>`);
         }
     });
     return (`<svg viewBox="0 0 ${width} ${height}" width="100%" role="img" ` +
@@ -261,12 +261,12 @@ function build(records, allRuns = records) {
         const cells = columns
             .map((c) => {
             const task = r.tasks.find((t) => t.id === c.id);
-            return `<td class="num">${task ? `${(task.score * 100).toFixed(0)}%` : "—"}</td>`;
+            return `<td class="num">${task ? `${(task.score * 100).toFixed(0)}%` : "-"}</td>`;
         })
             .join("");
-        return (`<tr><td>${escapeHtml(r.model.displayName)}</td><td>${escapeHtml(r.model.quant || "—")}</td>` +
+        return (`<tr><td>${escapeHtml(r.model.displayName)}</td><td>${escapeHtml(r.model.quant || "-")}</td>` +
             `<td class="num">${(r.profile?.contextSize || 0).toLocaleString()}</td>` +
-            `<td class="num">${r.profile?.reasoningBudget ?? "—"}</td>` +
+            `<td class="num">${r.profile?.reasoningBudget ?? "-"}</td>` +
             `${cells}<td class="num strong">${(r.overall * 100).toFixed(0)}%</td>` +
             `<td class="num">${formatGiB(r.vramBytes)}</td>` +
             `<td class="muted">${escapeHtml(r.ranAt.slice(0, 16).replace("T", " "))}</td></tr>`);
@@ -290,18 +290,18 @@ function build(records, allRuns = records) {
   </header>
 
   <section class="tiles">
-    ${statTile("Best model", best.model.displayName.slice(0, 26), `${(best.overall * 100).toFixed(0)}% — ${best.grade}`)}
+    ${statTile("Best model", best.model.displayName.slice(0, 26), `${(best.overall * 100).toFixed(0)}% - ${best.grade}`)}
     ${statTile("Runs recorded", records.length, `${columns.length} task categories`)}
-    ${statTile("Peak generation", fastest ? `${fastest.toFixed(0)} tok/s` : "—", "at shallowest depth measured")}
+    ${statTile("Peak generation", fastest ? `${fastest.toFixed(0)} tok/s` : "-", "at shallowest depth measured")}
     ${statTile("VRAM at load", formatGiB(best.vramBytes), best.loadSeconds ? `loaded in ${best.loadSeconds.toFixed(1)}s` : "")}
   </section>
 
   <section class="card">
     <h2>Scores by task</h2>
-    <p class="cap">Each row is one task, scored 0–100% from objectively verifiable outcomes — tool calls
+    <p class="cap">Each row is one task, scored 0–100% from objectively verifiable outcomes - tool calls
       checked against expected name and arguments, generated code compiled and its tests executed. The
       <b>×N</b> after a task is its weight. <b>Overall</b> is the weighted mean of the task scores,
-      <span class="mono">Σ(score × weight) ÷ Σ(weight)</span> — so a heavier task moves the headline
+      <span class="mono">Σ(score × weight) ÷ Σ(weight)</span> - so a heavier task moves the headline
       number more, and it is not the plain average of the bars above it.</p>
     ${groupedBars(ranked, columns, weightOf)}
   </section>
@@ -325,7 +325,7 @@ function build(records, allRuns = records) {
   <section class="card">
     <h2>Throughput against prompt depth</h2>
     <p class="cap">Generation speed at the same depths. A collapse here usually means the KV cache
-      spilled out of VRAM — the failure this tool's budget check exists to prevent.</p>
+      spilled out of VRAM - the failure this tool's budget check exists to prevent.</p>
     ${legend(depthSeries.map((s) => s.name.slice(0, 30)))}
     ${depthChart(depthSeries, {
             valueOf: (p) => p.generatePerSecond,
@@ -340,7 +340,7 @@ function build(records, allRuns = records) {
   <section class="card">
     <h2>Does each task actually tell us anything?</h2>
     <p class="cap">A task every model passes cannot rank them, however hard it looks. This is the
-      score spread across all runs — low spread means the task is saturated and its contribution to
+      score spread across all runs - low spread means the task is saturated and its contribution to
       the overall figure is inflating everyone equally. The weight is how hard that task pulls on the
       overall score, so a saturated <em>heavy</em> task matters most.</p>
     <div class="scroll">
@@ -352,9 +352,9 @@ function build(records, allRuns = records) {
         const tone = s.verdict === "saturated" ? "bad" : s.verdict === "weak" ? "warn" : "good";
         return (`<tr><td>${escapeHtml(s.category)}</td>` +
             `<td class="num">×${weightOf.get(s.id) ?? "?"}</td>` +
-            `<td class="num">${s.min === undefined ? "—" : `${(s.min * 100).toFixed(0)}%`}</td>` +
-            `<td class="num">${s.max === undefined ? "—" : `${(s.max * 100).toFixed(0)}%`}</td>` +
-            `<td class="num strong">${s.spread === null ? "—" : `${(s.spread * 100).toFixed(0)} pts`}</td>` +
+            `<td class="num">${s.min === undefined ? "-" : `${(s.min * 100).toFixed(0)}%`}</td>` +
+            `<td class="num">${s.max === undefined ? "-" : `${(s.max * 100).toFixed(0)}%`}</td>` +
+            `<td class="num strong">${s.spread === null ? "-" : `${(s.spread * 100).toFixed(0)} pts`}</td>` +
             `<td class="v-${tone}">${escapeHtml(s.verdict)}</td></tr>`);
     })
         .join("")}</tbody>
@@ -362,7 +362,7 @@ function build(records, allRuns = records) {
     </div>
     ${saturated.length
         ? `<ul class="notes"><li><strong>${saturated.map((s) => escapeHtml(s.category)).join(", ")}</strong>
-      ${saturated.length === 1 ? "is" : "are"} saturated — every model scores the same, so
+      ${saturated.length === 1 ? "is" : "are"} saturated - every model scores the same, so
       ${saturated.length === 1 ? "it needs" : "they need"} to get harder before
       ${saturated.length === 1 ? "it" : "they"} can contribute to a ranking.</li></ul>`
         : ""}
@@ -372,7 +372,7 @@ function build(records, allRuns = records) {
     <h2>Is the benchmark consistent?</h2>
     <p class="cap">The same model + settings, measured more than once. A method you can trust holds a
       flat line across runs; a jagged one means the score is noisy and small gaps between models are
-      not real. Runs are numbered, not dated — only how many times we have measured matters.</p>
+      not real. Runs are numbered, not dated - only how many times we have measured matters.</p>
     ${consistencySeries.length
         ? `
       ${legend(consistencySeries.map((s) => s.name.slice(0, 30)))}
@@ -380,7 +380,7 @@ function build(records, allRuns = records) {
       <p class="axl">run number</p>`
         : `
       <p class="empty">No config has been run more than once yet. Re-run a model a few times to see
-      its spread — the table below shows mean ± spread as repeats accumulate.</p>`}
+      its spread - the table below shows mean ± spread as repeats accumulate.</p>`}
     <div class="scroll">
       <table>
         <thead><tr><th>Model</th><th class="num">Runs</th><th class="num">Mean</th>
@@ -392,9 +392,9 @@ function build(records, allRuns = records) {
         const tone = v.count < 2 ? "muted" : spreadPts > 8 ? "v-warn" : "v-good";
         return (`<tr><td>${escapeHtml(v.model.displayName)}</td>` +
             `<td class="num">${v.count}</td>` +
-            `<td class="num strong">${o.mean === undefined ? "—" : `${(o.mean * 100).toFixed(0)}%`}</td>` +
-            `<td class="num ${tone}">${v.count < 2 ? "—" : `${spreadPts.toFixed(1)} pts`}</td>` +
-            `<td class="num">${v.count < 2 ? "—" : `${((o.min ?? 0) * 100).toFixed(0)}–${((o.max ?? 0) * 100).toFixed(0)}%`}</td></tr>`);
+            `<td class="num strong">${o.mean === undefined ? "-" : `${(o.mean * 100).toFixed(0)}%`}</td>` +
+            `<td class="num ${tone}">${v.count < 2 ? "-" : `${spreadPts.toFixed(1)} pts`}</td>` +
+            `<td class="num">${v.count < 2 ? "-" : `${((o.min ?? 0) * 100).toFixed(0)}–${((o.max ?? 0) * 100).toFixed(0)}%`}</td></tr>`);
     })
         .join("")}</tbody>
       </table>
@@ -406,7 +406,7 @@ function build(records, allRuns = records) {
   <section class="card">
     <h2>System health during runs</h2>
     <p class="cap">The machine state each score was measured under. A throttled or power-capped run is
-      slower and lower for reasons that have nothing to do with the model — read those scores with
+      slower and lower for reasons that have nothing to do with the model - read those scores with
       suspicion, or re-run them once the GPU has cooled.</p>
     <div class="scroll">
       <table>
@@ -418,10 +418,10 @@ function build(records, allRuns = records) {
             const throttled = h.thermalThrottle || h.powerThrottle;
             const label = h.thermalThrottle ? "thermal" : h.powerThrottle ? "power" : "no";
             return (`<tr><td>${escapeHtml(r.model.displayName)}</td>` +
-                `<td class="num">${h.tempC ? `${h.tempC.max}°C` : "—"}</td>` +
-                `<td class="num">${h.powerW ? `${h.powerW.avg.toFixed(0)} W` : "—"}</td>` +
-                `<td class="num">${h.gpuUtilPct ? `${h.gpuUtilPct.avg.toFixed(0)}%` : "—"}</td>` +
-                `<td class="num">${h.vramUsedMiB ? `${(h.vramUsedMiB.max / 1024).toFixed(1)} GB` : "—"}</td>` +
+                `<td class="num">${h.tempC ? `${h.tempC.max}°C` : "-"}</td>` +
+                `<td class="num">${h.powerW ? `${h.powerW.avg.toFixed(0)} W` : "-"}</td>` +
+                `<td class="num">${h.gpuUtilPct ? `${h.gpuUtilPct.avg.toFixed(0)}%` : "-"}</td>` +
+                `<td class="num">${h.vramUsedMiB ? `${(h.vramUsedMiB.max / 1024).toFixed(1)} GB` : "-"}</td>` +
                 `<td class="${throttled ? "v-bad" : "v-good"}">${throttled ? `⚠ ${label}` : "no"}</td></tr>`);
         })
             .join("")}</tbody>

package/dist/ops/results.d.ts

@@ -1,5 +1,6 @@
 import type { GpuInfo, Model, ModelFeatures } from "../types.js";
-import type { Profile } from "../config/schema.js";
+import type { Calibration, Profile } from "../config/schema.js";
+import type { FitResult } from "../vram.js";
 declare const RESULTS_DIR: string;
 /** Aggregate of a numeric health series (nvidia-smi samples during a run). */
 export interface AggStat {
@@ -49,7 +50,14 @@ export interface BenchReport {
     archiveId?: string | null;
     system?: SystemHealth | null;
 }
-/** The model identity persisted with a run. */
+/**
+ * The model identity persisted with a run.
+ *
+ * The geometry fields are here because a context size is only sensible against
+ * them: 32k on a model whose GGUF header says 8k native is a setup error, not a
+ * capability, and layer/KV-head counts are what make a KV cost per token
+ * explicable rather than just large.
+ */
 export interface RecordModel {
     id: string | null;
     displayName: string;
@@ -58,15 +66,92 @@ export interface RecordModel {
     sizeBytes: number | null;
     publisher: string | null;
     features: ModelFeatures | null;
+    /** Native context from the GGUF header - the ceiling `contextSize` sits under. */
+    contextLength: number | null;
+    blockCount: number | null;
+    headCountKv: number | null;
 }
-/** The subset of a profile persisted with a run. */
+/**
+ * The profile persisted with a run: every field that reaches llama-server.
+ *
+ * Schema 1 kept six of these. The omitted ones are exactly the ones that explain
+ * a bad score - `gpuLayers` short of the model's layer count silently runs part
+ * of it on the CPU, `parallelSlots` splits the context between slots so the
+ * effective window is a fraction of `contextSize`, and `extraArgs` can override
+ * anything above.
+ */
 export interface RecordProfile {
     contextSize: number;
     cacheTypeK: string;
     cacheTypeV: string;
     reasoningBudget: number;
+    reasoningBudgetMessage: string | null;
     vision: boolean;
     flashAttention: boolean;
+    gpuLayers: number | null;
+    parallelSlots: number | null;
+    batchSize: number | null;
+    ubatchSize: number | null;
+    extraArgs: string[];
+}
+/**
+ * How the run was actually set up, as opposed to how it was configured.
+ *
+ * The gap between the two is where bad scores come from. `fitToBudget` will cut
+ * a profile's context down to whatever fits the GPU and run anyway, which is the
+ * right call at load time and a silent lie afterwards: the record would say the
+ * model scored 41% at 128k context when it was really measured at 16k. Same for
+ * the KV budget - a context chosen off the theoretical formula (which
+ * overestimates by up to 4x) is a different measurement from one chosen off a
+ * calibration, even when the numbers land in the same place.
+ */
+export interface RecordSetup {
+    /**
+     * The exact llama-server argv this run was served with. Every other field
+     * here is a convenience; this one is the ground truth, and it is what makes a
+     * run reproducible by hand.
+     */
+    args: string[] | null;
+    /** True when the VRAM fit had to change the profile for the run to happen. */
+    adjusted: boolean;
+    /** The context the profile asked for, before any fit adjustment. */
+    requestedContextSize: number | null;
+    /** Why the fit changed the profile, in the fitter's own words. */
+    adjustReason: string | null;
+    /** Where the KV bytes/token came from. `theoretical` means nobody measured. */
+    kvSource: "measured" | "theoretical" | "unknown" | null;
+    /**
+     * True when the calibration came from a relative with the same attention
+     * geometry rather than from this file. Never present it as measured.
+     */
+    kvInherited: boolean;
+    kvBytesPerToken: number | null;
+    /** The formula's answer, kept beside the measured one to expose the gap. */
+    theoreticalKvBytesPerToken: number | null;
+    /** What the budget predicted the run would take, against `vramBytes` observed. */
+    predictedVramBytes: number | null;
+    reserveBytes: number | null;
+    headroomBytes: number | null;
+}
+/**
+ * Which suite graded the run.
+ *
+ * Two runs scored on different task sets are not comparable, and neither are a
+ * run that was allowed to execute generated code and one that was only allowed
+ * to syntax-check it. `configKey` deliberately does not include any of this (see
+ * `configKey()` below), so it is recorded here instead of silently merging
+ * unlike runs into one group.
+ */
+export interface RecordSuite {
+    /** False when `--no-execute` limited grading to a syntax check. */
+    execute: boolean | null;
+    concurrency: number | null;
+    /** Prompt depths for the depth-scaling task, when overridden. */
+    depths: number[] | null;
+    /** Task ids the run was restricted to (`--only`), when restricted. */
+    only: string[] | null;
+    /** True when the static suite was replaced by tasks mined from a repo. */
+    mined: boolean;
 }
 /** The GPU identity persisted with a run. */
 export interface RecordGpu {
@@ -85,12 +170,24 @@ export interface RecordTask {
     detail: unknown;
     error: string | null;
 }
-/** One stored benchmark run — the shared shape used across results and report. */
+/**
+ * One stored benchmark run - the shared shape used across results and report.
+ *
+ * `schema` is 2 as of the setup-capture change: 2 carries the full profile plus
+ * `setup` and `suite`; 1 carried six profile fields and neither. Readers must
+ * treat everything added in 2 as absent on an older record rather than assuming
+ * it, because those runs are still perfectly good scores - they just cannot say
+ * what they were measured with.
+ */
 export interface RunRecord {
     schema: number;
     ranAt: string;
     model: RecordModel;
     profile: RecordProfile | null;
+    /** Schema 2+. Absent on runs saved before setup capture. */
+    setup: RecordSetup | null;
+    /** Schema 2+. Absent on runs saved before setup capture. */
+    suite: RecordSuite | null;
     configKey: string;
     archiveId: string | null;
     gpu: RecordGpu | null;
@@ -106,15 +203,29 @@ export interface RunRecord {
     file?: string;
     runIndex?: number;
 }
-/** Arguments to `save`. */
+/**
+ * Arguments to `save`.
+ *
+ * Everything past `report` is optional so a caller that cannot supply it still
+ * writes a usable record - but every caller that CAN should, because a run saved
+ * without its setup is a score nobody can explain later.
+ */
 export interface SaveOptions {
     model: Model | null;
+    /** The profile the run was actually served with (post-fit, not as configured). */
     profile: Profile | null;
     report: BenchReport;
     gpu?: GpuInfo | null;
     runtime?: string | null;
     archiveId?: string | null;
     system?: SystemHealth | null;
+    /** The argv the supervisor launched, straight from `Supervisor.args`. */
+    args?: string[] | null;
+    /** The VRAM fit that produced `profile`, including what it had to change. */
+    fit?: FitResult | null;
+    /** The calibration the fit was computed against, if there was one. */
+    calibration?: Calibration | null;
+    suite?: Partial<RecordSuite> | null;
     timestamp?: Date;
 }
 /** Result of `save`: the written file path plus the persisted record. */
@@ -172,9 +283,17 @@ export interface TaskColumn {
     category: string;
 }
 declare function slugify(text: string): string;
-/** Stable identity for "same model, same settings", so reruns can be grouped. */
+/**
+ * Stable identity for "same model, same settings", so reruns can be grouped.
+ *
+ * Deliberately unchanged when the record grew: this string is the grouping key
+ * every stored run was written with, and widening it would not re-key history -
+ * it would split each model's past runs from its future ones and quietly reset
+ * every variance figure on the page. New settings are recorded as data, not
+ * folded in here.
+ */
 declare function configKey(profile: Profile | null): string;
-declare function save({ model, profile, report, gpu, runtime, archiveId, system, timestamp, }: SaveOptions): SaveResult;
+declare function save({ model, profile, report, gpu, runtime, archiveId, system, args, fit, calibration, suite, timestamp, }: SaveOptions): SaveResult;
 /** Every stored run, newest first. */
 declare function loadAll(): RunRecord[];
 /**
@@ -185,13 +304,13 @@ declare function latestPerConfig(records?: RunRecord[]): RunRecord[];
 /**
  * Group every run by model+config (all runs kept, not just the latest), and
  * number them oldest→newest so a run can be plotted against run number. Wall
- * time is deliberately not the axis — only how many times we have measured it.
+ * time is deliberately not the axis - only how many times we have measured it.
  */
 declare function grouped(records?: RunRecord[]): Group[];
 /** count / mean / sample-std / min / max of a numeric series. */
 declare function stats(values: Array<number | undefined>): Stats | null;
 /**
- * Per-config spread of overall and per-task scores across repeated runs — the
+ * Per-config spread of overall and per-task scores across repeated runs - the
  * measure of whether the benchmark method is itself consistent.
  */
 declare function variance(records?: RunRecord[]): VarianceRow[];

package/dist/ops/results.js

@@ -8,6 +8,16 @@ import { fileURLToPath } from "node:url";
  * compared and charted later. Runs record the configuration they were measured
  * under, because a score is meaningless without the quant, context size and
  * reasoning budget that produced it.
+ *
+ * **A run records every value it was measured with, not a summary of them.** A
+ * bad score is far more often a bad setup than a bad model, and the difference
+ * is only visible from the settings: a context the VRAM fit had to cut, a
+ * reasoning budget the model spends entirely on thinking, a KV quant that
+ * wrecked recall, weights that fell off the GPU because `gpuLayers` did not
+ * cover them, a budget estimated from the formula rather than measured. None of
+ * that is recoverable after the fact, so it is all written down at save time -
+ * including the exact llama-server argv the run was served with, which is the
+ * only true statement of what ran.
  */
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(HERE, "..", "..");
@@ -19,7 +29,15 @@ function slugify(text) {
         .replace(/^-|-$/g, "")
         .slice(0, 80);
 }
-/** Stable identity for "same model, same settings", so reruns can be grouped. */
+/**
+ * Stable identity for "same model, same settings", so reruns can be grouped.
+ *
+ * Deliberately unchanged when the record grew: this string is the grouping key
+ * every stored run was written with, and widening it would not re-key history -
+ * it would split each model's past runs from its future ones and quietly reset
+ * every variance figure on the page. New settings are recorded as data, not
+ * folded in here.
+ */
 function configKey(profile) {
     if (!profile)
         return "unknown";
@@ -30,10 +48,42 @@ function configKey(profile) {
         profile.vision ? "vision" : "novision",
     ].join("_");
 }
-function save({ model, profile, report, gpu = null, runtime = null, archiveId = null, system = null, timestamp = new Date(), }) {
+/** Read a numeric GGUF metadata field, which is `null` when the header lacked it. */
+function metadataNumber(model, key) {
+    const value = model?.metadata?.[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+/**
+ * Fold the fit and the calibration into the record's setup block.
+ *
+ * `fit.profile` is the profile that actually ran, so the requested context has
+ * to be read from what the fit was HANDED, not from what it returned - by the
+ * time `save` sees a profile, the adjustment has already been applied and is
+ * invisible.
+ */
+function buildSetup({ args, fit, calibration, }) {
+    if (!args && !fit && !calibration) {
+        return null;
+    }
+    const budget = fit?.budget ?? null;
+    return {
+        args: args ?? null,
+        adjusted: fit?.adjusted ?? false,
+        requestedContextSize: fit?.requestedContextSize ?? null,
+        adjustReason: fit?.reason ?? null,
+        kvSource: budget?.source ?? null,
+        kvInherited: calibration?.inherited === true,
+        kvBytesPerToken: budget?.kvBytesPerToken ?? null,
+        theoreticalKvBytesPerToken: budget?.theoreticalKvBytesPerToken ?? null,
+        predictedVramBytes: budget?.totalBytes ?? null,
+        reserveBytes: budget?.reserveBytes ?? null,
+        headroomBytes: budget?.headroomBytes ?? null,
+    };
+}
+function save({ model, profile, report, gpu = null, runtime = null, archiveId = null, system = null, args = null, fit = null, calibration = null, suite = null, timestamp = new Date(), }) {
     fs.mkdirSync(RESULTS_DIR, { recursive: true });
     const record = {
-        schema: 1,
+        schema: 2,
         ranAt: timestamp.toISOString(),
         model: {
             id: model?.id ?? null,
@@ -43,15 +93,37 @@ function save({ model, profile, report, gpu = null, runtime = null, archiveId =
             sizeBytes: model?.sizeBytes ?? null,
             publisher: model?.publisher ?? null,
             features: model?.features ?? null,
+            contextLength: metadataNumber(model, "contextLength"),
+            blockCount: metadataNumber(model, "blockCount"),
+            headCountKv: metadataNumber(model, "headCountKv"),
         },
+        // The whole profile, not a summary of it. `ProfileSchema` is `.passthrough()`
+        // and its numeric fields carry defaults, so read them defensively: a profile
+        // written by an older brain can be missing anything below `vision`.
         profile: profile
             ? {
                 contextSize: profile.contextSize,
                 cacheTypeK: profile.cacheTypeK,
                 cacheTypeV: profile.cacheTypeV,
                 reasoningBudget: profile.reasoningBudget,
+                reasoningBudgetMessage: profile.reasoningBudgetMessage ?? null,
                 vision: profile.vision,
                 flashAttention: profile.flashAttention,
+                gpuLayers: profile.gpuLayers ?? null,
+                parallelSlots: profile.parallelSlots ?? null,
+                batchSize: profile.batchSize ?? null,
+                ubatchSize: profile.ubatchSize ?? null,
+                extraArgs: profile.extraArgs ?? [],
+            }
+            : null,
+        setup: buildSetup({ args, fit, calibration }),
+        suite: suite
+            ? {
+                execute: suite.execute ?? null,
+                concurrency: suite.concurrency ?? null,
+                depths: suite.depths ?? null,
+                only: suite.only ?? null,
+                mined: suite.mined ?? false,
             }
             : null,
         configKey: configKey(profile),
@@ -119,7 +191,7 @@ function latestPerConfig(records = loadAll()) {
 /**
  * Group every run by model+config (all runs kept, not just the latest), and
  * number them oldest→newest so a run can be plotted against run number. Wall
- * time is deliberately not the axis — only how many times we have measured it.
+ * time is deliberately not the axis - only how many times we have measured it.
  */
 function grouped(records = loadAll()) {
     const groups = new Map();
@@ -157,7 +229,7 @@ function stats(values) {
     };
 }
 /**
- * Per-config spread of overall and per-task scores across repeated runs — the
+ * Per-config spread of overall and per-task scores across repeated runs - the
  * measure of whether the benchmark method is itself consistent.
  */
 function variance(records = loadAll()) {

package/dist/output/render.js

@@ -1,5 +1,5 @@
 /**
- * Format renderers for the output layer. chalk lives here and nowhere else —
+ * Format renderers for the output layer. chalk lives here and nowhere else -
  * command handlers express color declaratively via ColumnDef.color, and only
  * these renderers turn a result into text. Table output is ANSI-aware so colored
  * cells still align.

package/dist/output/types.d.ts

@@ -1,6 +1,6 @@
 /**
  * The output contract, mirroring @otto-code/cli's output layer: command handlers
- * do not print — they return a typed result plus a schema, and a wrapper renders
+ * do not print - they return a typed result plus a schema, and a wrapper renders
  * it in the user-selected format (table / json / yaml / quiet). This is what lets
  * every `otto brain` command support `--format`, `--json`, and `--quiet` uniformly.
  */

package/dist/runtime/args.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Translates a profile into llama-server arguments and builds the PATH the child
+ * needs. Runtime-source agnostic: works the same for an LM Studio runtime or a
+ * managed one, since both resolve to a `Runtime` (exe + optional vendorDir).
+ */
 import type { Profile } from "../config/schema.js";
 import type { Runtime } from "../types.js";
 export interface ServeTarget {
@@ -5,14 +10,22 @@ export interface ServeTarget {
     host?: string;
 }
 /**
- * PATH value the child process needs so the stub can resolve its DLLs. Both the
- * runtime dir and its vendor dir go first, ahead of the inherited PATH.
+ * Loader environment the child process needs so it can resolve its shared
+ * libraries. Both the runtime dir and its vendor dir go first, ahead of the
+ * inherited values.
+ *
+ * PATH is the Windows half of this (the DLL-stub trap). The other two platforms
+ * do not read PATH for libraries at all: a llama.cpp tarball puts
+ * `libggml*.so`/`libllama.so` (or the `.dylib` equivalents) next to the binary,
+ * so Linux needs LD_LIBRARY_PATH and macOS needs DYLD_LIBRARY_PATH or the
+ * binary dies at load with an unresolved-library error before it prints a line.
+ * PATH is still set everywhere - harmless, and it keeps the shape uniform.
  */
-export declare function buildEnv(runtime: Runtime, baseEnv?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function buildEnv(runtime: Runtime, baseEnv?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): NodeJS.ProcessEnv;
 /**
  * Translate a profile into llama-server arguments.
  *
- * Only settings that demonstrably matter for stable local inference are emitted —
+ * Only settings that demonstrably matter for stable local inference are emitted -
  * no experimental sampler knobs.
  */
 export declare function buildArgs(profile: Profile, { port, host }: ServeTarget): string[];

package/dist/runtime/args.js

@@ -1,26 +1,32 @@
 /**
- * Translates a profile into llama-server arguments and builds the PATH the child
- * needs. Runtime-source agnostic: works the same for an LM Studio runtime or a
- * managed one, since both resolve to a `Runtime` (exe + optional vendorDir).
- */
-import path from "node:path";
-/**
- * PATH value the child process needs so the stub can resolve its DLLs. Both the
- * runtime dir and its vendor dir go first, ahead of the inherited PATH.
+ * Loader environment the child process needs so it can resolve its shared
+ * libraries. Both the runtime dir and its vendor dir go first, ahead of the
+ * inherited values.
+ *
+ * PATH is the Windows half of this (the DLL-stub trap). The other two platforms
+ * do not read PATH for libraries at all: a llama.cpp tarball puts
+ * `libggml*.so`/`libllama.so` (or the `.dylib` equivalents) next to the binary,
+ * so Linux needs LD_LIBRARY_PATH and macOS needs DYLD_LIBRARY_PATH or the
+ * binary dies at load with an unresolved-library error before it prints a line.
+ * PATH is still set everywhere - harmless, and it keeps the shape uniform.
  */
-export function buildEnv(runtime, baseEnv = process.env) {
+export function buildEnv(runtime, baseEnv = process.env, platform = process.platform) {
     const parts = [runtime.dir];
     if (runtime.vendorDir)
         parts.push(runtime.vendorDir);
-    return {
-        ...baseEnv,
-        PATH: `${parts.join(path.delimiter)}${path.delimiter}${baseEnv.PATH || ""}`,
-    };
+    const delimiter = platform === "win32" ? ";" : ":";
+    const prepend = (existing) => `${parts.join(delimiter)}${delimiter}${existing || ""}`;
+    const env = { ...baseEnv, PATH: prepend(baseEnv.PATH) };
+    if (platform === "darwin")
+        env.DYLD_LIBRARY_PATH = prepend(baseEnv.DYLD_LIBRARY_PATH);
+    else if (platform !== "win32")
+        env.LD_LIBRARY_PATH = prepend(baseEnv.LD_LIBRARY_PATH);
+    return env;
 }
 /**
  * Translate a profile into llama-server arguments.
  *
- * Only settings that demonstrably matter for stable local inference are emitted —
+ * Only settings that demonstrably matter for stable local inference are emitted -
  * no experimental sampler knobs.
  */
 export function buildArgs(profile, { port, host = "127.0.0.1" }) {

package/dist/runtime/index.d.ts

@@ -1,13 +1,19 @@
 import type { BrainConfig } from "../config/schema.js";
 import type { Runtime } from "../types.js";
-import { type InstallProgress } from "./managed.js";
+import { type InstallProgress, type RuntimeTarget } from "./managed.js";
 export { BACKENDS_DIR, LMSTUDIO_ROOT, listRuntimes as listLmStudioRuntimes } from "./lmstudio.js";
 export { buildArgs, buildEnv, formatCommand, type ServeTarget } from "./args.js";
-export { installManagedRuntime, listManagedRuntimes, defaultRuntimeSpec, DEFAULT_LLAMA_BUILD, type RuntimeSpec, type InstallProgress, } from "./managed.js";
+export { installManagedRuntime, listManagedRuntimes, listRuntimeDevices, verifyRuntimeExecutable, defaultRuntimeSpec, extractArchive, resolveRuntimeVariant, serverExeName, supportedVariants, DEFAULT_LLAMA_BUILD, type RuntimeSpec, type RuntimeTarget, type RuntimeVariant, type InstallProgress, } from "./managed.js";
 /** Every runtime available on this machine, managed first then LM Studio. */
 export declare function listAllRuntimes(env?: NodeJS.ProcessEnv): Runtime[];
+/**
+ * Whether this machine has an NVIDIA GPU, for picking a managed build. Returns
+ * false rather than throwing when nvidia-smi is absent, which is the normal
+ * case on macOS and on AMD/Intel machines.
+ */
+export declare function probeNvidiaGpu(): Promise<boolean>;
 /** The runtime to use given config, or null when none is available. */
 export declare function resolveRuntime(config: BrainConfig, env?: NodeJS.ProcessEnv): Runtime | null;
 /** Ensure a runtime exists, downloading the default managed build if none does. */
-export declare function ensureRuntime(config: BrainConfig, env?: NodeJS.ProcessEnv, onProgress?: (progress: InstallProgress) => void): Promise<Runtime>;
+export declare function ensureRuntime(config: BrainConfig, env?: NodeJS.ProcessEnv, onProgress?: (progress: InstallProgress) => void, target?: RuntimeTarget): Promise<Runtime>;
 //# sourceMappingURL=index.d.ts.map