@otto-code/brain 0.8.0 → 0.8.2

package/dist/runtime/managed.js

@@ -1,12 +1,54 @@
 /**
  * The self-contained runtime source: otto-brain downloads a pinned llama.cpp
  * build into `$OTTO_HOME/otto-brain/runtimes/` and runs it directly, so the tool
- * needs no other software installed. Downloaded runtimes keep their DLLs in the
- * same directory as the exe (so `vendorDir` is null - buildEnv already puts the
- * runtime dir on PATH, which is what the DLL-stub trap requires).
+ * needs no other software installed. Downloaded runtimes keep their shared
+ * libraries in the same directory as the binary (so `vendorDir` is null - the
+ * loader path built by `args.buildEnv` already covers that directory, which is
+ * what the DLL-stub trap requires).
  *
- * Extraction uses only OS built-ins - PowerShell's Expand-Archive for .zip and
- * the bundled `tar` for tarballs - to keep the "nothing else to install" promise.
+ * Extraction uses only OS built-ins - PowerShell's Expand-Archive for .zip on
+ * Windows, the bundled `tar` for tarballs everywhere else - to keep the
+ * "nothing else to install" promise.
+ *
+ * ## The upstream asset matrix (verified against release b10265)
+ *
+ * Every fact below was read off the release, not inferred from the naming
+ * scheme, because the scheme has changed at least once: tag b4600 shipped
+ * `llama-b4600-bin-win-cuda-cu12.4-x64.zip` while b10265 ships
+ * `llama-b10265-bin-win-cuda-12.4-x64.zip` (no `cu`). A pin bump must re-verify
+ * the names against that tag's asset list; they are not stable across tags.
+ *
+ *  - Windows assets are `.zip`; macOS and Linux assets are `.tar.gz`.
+ *  - **Linux has no CUDA *release asset*, and we deliberately do not source one
+ *    elsewhere.** The Linux GPU assets are Vulkan, ROCm and SYCL only, so the
+ *    Linux GPU default is Vulkan - the one accelerator covering NVIDIA, AMD and
+ *    Intel from a single asset. There is a real Linux CUDA build upstream, in
+ *    the `ghcr.io/ggml-org/llama.cpp:server-cuda-b<n>` container images (484 of
+ *    them, and 376 build numbers carry both an image and a release, so a pinned
+ *    version-aligned import is genuinely possible). It was extracted, run and
+ *    benchmarked on 2026-08-04 and then rejected on the numbers:
+ *
+ *      CUDA beats Vulkan by 1.00x-1.04x on an RTX 5090 at every prefill depth
+ *      from 512 to 8192 and at token generation, inside the run-to-run error at
+ *      three of five points, because NVIDIA's Vulkan driver exposes
+ *      NV_coopmat2 and llama.cpp's Vulkan backend uses those tensor cores.
+ *
+ *    Paying for that would mean a 40x download (1.3 GB against 32 MB) and a 14x
+ *    on-disk footprint, assembled from three origins, because `libggml-cuda.so`
+ *    also needs `libcublas`, `libcudart` and `libnccl.so.2` - and NCCL ships in
+ *    neither NVIDIA redistributable. Do not reopen this without a measurement on
+ *    hardware that does *not* report NV_coopmat2, which is the one case where
+ *    the gap could still be real. Full evidence:
+ *    findings/linux-gpu-acceleration/2026-08-04-cuda-vs-vulkan-and-cuda-asset-origins.md
+ *  - **No Linux asset ships `libgomp.so.1`**, which `llama-server` hard-links,
+ *    so a host without `libgomp1` installs a runtime that then exits 127 on
+ *    spawn. Windows bundles its OpenMP runtime (`libomp140.x86_64.dll`); Linux
+ *    bundles nothing. `buildEnv` cannot paper over it - the library is not in
+ *    the runtime dir that `LD_LIBRARY_PATH` already points at.
+ *  - Windows CUDA needs a *second* archive (`cudart-llama-bin-win-cuda-*.zip`)
+ *    extracted over the first, and that asset's name carries no build tag.
+ *  - macOS arm64 is Metal-accelerated in the stock `macos-arm64` asset; there is
+ *    no separate Metal asset to select. macOS x64 is CPU-only in practice.
  */
 import { spawn } from "node:child_process";
 import fs from "node:fs";
@@ -14,24 +56,125 @@ import { createWriteStream } from "node:fs";
 import path from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
+import { buildEnv } from "./args.js";
 /**
- * The default runtime build. The llama.cpp release tag and CUDA asset names must
- * be pinned per platform; verify the URLs against the current release before
- * shipping. Overridable via config (`runtime.path`) or an explicit spec.
+ * The default runtime build. Bumping this requires re-reading the tag's asset
+ * names (see the module header) - the naming scheme is not stable across tags.
  */
-export const DEFAULT_LLAMA_BUILD = "b4600";
+export const DEFAULT_LLAMA_BUILD = "b10265";
 const LLAMA_RELEASE_BASE = "https://github.com/ggml-org/llama.cpp/releases/download";
-/** Build the default Windows CUDA 12 spec for a given llama.cpp build tag. */
-export function defaultRuntimeSpec(build = DEFAULT_LLAMA_BUILD) {
+/** The CUDA toolkit version whose Windows assets we pin. */
+const WINDOWS_CUDA = "12.4";
+/** The binary name llama.cpp ships for a platform. */
+export function serverExeName(platform = process.platform) {
+    return platform === "win32" ? "llama-server.exe" : "llama-server";
+}
+/**
+ * Pick the accelerator for a target. Deliberately conservative: it never
+ * chooses an accelerator whose asset does not exist for that platform/arch.
+ */
+export function resolveRuntimeVariant(target = {}) {
+    const platform = target.platform ?? process.platform;
+    const arch = target.arch ?? process.arch;
+    const requested = target.variant ?? "auto";
+    if (requested !== "auto")
+        return requested;
+    if (platform === "darwin")
+        return arch === "arm64" ? "metal" : "cpu";
+    // Windows is the only platform with an upstream CUDA build. Everywhere else a
+    // GPU means Vulkan.
+    if (platform === "win32") {
+        if (arch === "arm64")
+            return "cpu";
+        return target.hasNvidiaGpu ? "cuda" : "vulkan";
+    }
+    if (platform === "linux")
+        return target.hasNvidiaGpu === false ? "cpu" : "vulkan";
+    return "cpu";
+}
+const VARIANT_LABELS = {
+    cuda: `CUDA ${WINDOWS_CUDA}`,
+    metal: "Metal",
+    vulkan: "Vulkan",
+    cpu: "CPU",
+};
+/**
+ * The archive names for a platform/arch/variant, or null when upstream ships no
+ * such asset. Returning null (rather than guessing a URL) is what keeps a bad
+ * combination from failing later as an opaque 404 mid-download.
+ */
+function assetNames(build, platform, arch, variant) {
+    const bin = (suffix, ext) => `llama-${build}-bin-${suffix}.${ext}`;
+    if (platform === "win32") {
+        if (arch === "arm64")
+            return variant === "cpu" ? [bin("win-cpu-arm64", "zip")] : null;
+        if (arch !== "x64")
+            return null;
+        if (variant === "cuda") {
+            return [
+                bin(`win-cuda-${WINDOWS_CUDA}-x64`, "zip"),
+                // The CUDA runtime DLLs ride in a companion archive whose name carries
+                // no build tag; it is published under each release tag all the same.
+                `cudart-llama-bin-win-cuda-${WINDOWS_CUDA}-x64.zip`,
+            ];
+        }
+        if (variant === "vulkan")
+            return [bin("win-vulkan-x64", "zip")];
+        if (variant === "cpu")
+            return [bin("win-cpu-x64", "zip")];
+        return null;
+    }
+    if (platform === "darwin") {
+        if (arch === "arm64") {
+            // One asset serves both: the stock macos-arm64 build is Metal-enabled.
+            return variant === "metal" || variant === "cpu" ? [bin("macos-arm64", "tar.gz")] : null;
+        }
+        if (arch === "x64")
+            return variant === "cpu" ? [bin("macos-x64", "tar.gz")] : null;
+        return null;
+    }
+    if (platform === "linux") {
+        const slice = arch === "arm64" ? "arm64" : arch === "x64" ? "x64" : null;
+        if (!slice)
+            return null;
+        if (variant === "vulkan")
+            return [bin(`ubuntu-vulkan-${slice}`, "tar.gz")];
+        if (variant === "cpu")
+            return [bin(`ubuntu-${slice}`, "tar.gz")];
+        // No Linux CUDA/Metal *release* asset. A CUDA container image exists and was
+        // measured at parity with Vulkan; see the header before reopening this.
+        return null;
+    }
+    return null;
+}
+/**
+ * Build the runtime spec for a target. Throws when upstream publishes nothing
+ * for the combination, naming what it tried so the message is actionable.
+ */
+export function defaultRuntimeSpec(build = DEFAULT_LLAMA_BUILD, target = {}) {
+    const tag = build || DEFAULT_LLAMA_BUILD;
+    const platform = target.platform ?? process.platform;
+    const arch = target.arch ?? process.arch;
+    const variant = resolveRuntimeVariant({ ...target, platform, arch });
+    const names = assetNames(tag, platform, arch, variant);
+    if (!names) {
+        throw new Error(`llama.cpp publishes no ${variant} build for ${platform}/${arch} - ` +
+            `pass --variant with one of ${supportedVariants(platform, arch).join(", ") || "(none)"}, ` +
+            `or point runtime.path at a runtime you built yourself`);
+    }
     return {
-        label: "CUDA 12 (managed)",
-        version: build,
-        assets: [
-            `${LLAMA_RELEASE_BASE}/${build}/llama-${build}-bin-win-cuda-12.4-x64.zip`,
-            `${LLAMA_RELEASE_BASE}/${build}/cudart-llama-bin-win-cuda-12.4-x64.zip`,
-        ],
+        label: `${VARIANT_LABELS[variant]} (managed)`,
+        version: tag,
+        assets: names.map((name) => `${LLAMA_RELEASE_BASE}/${tag}/${name}`),
+        platform,
+        variant,
     };
 }
+/** Variants with a published asset for a platform/arch, best first. */
+export function supportedVariants(platform = process.platform, arch = process.arch) {
+    const order = ["cuda", "metal", "vulkan", "cpu"];
+    return order.filter((v) => assetNames(DEFAULT_LLAMA_BUILD, platform, arch, v) !== null);
+}
 function slug(spec) {
     return `${spec.label}-${spec.version}`
         .toLowerCase()
@@ -54,16 +197,37 @@ function findFile(dir, name) {
     }
     return null;
 }
-/** A managed runtime is any dir under runtimesDir that contains llama-server.exe. */
-export function listManagedRuntimes(runtimesDir) {
+/**
+ * Rank a managed runtime directory by the accelerator its slug encodes, best
+ * first. Once more than one variant can be installed side by side, readdir
+ * order is not a defensible preference: a machine that installed CPU for a
+ * one-off test would otherwise have it silently outrank its CUDA runtime.
+ */
+function managedVariantRank(dirName) {
+    const order = ["cuda", "metal", "vulkan", "cpu"];
+    const lower = dirName.toLowerCase();
+    const index = order.findIndex((variant) => lower.startsWith(`${variant}-`));
+    return index === -1 ? order.length : index;
+}
+/** Numeric part of a `bNNNNN` llama.cpp build tag, for ordering. */
+function buildNumber(version) {
+    const match = /(\d+)/.exec(version);
+    return match ? Number(match[1]) : 0;
+}
+/**
+ * A managed runtime is any dir under runtimesDir that contains llama-server,
+ * best accelerator first and newest build first within an accelerator.
+ */
+export function listManagedRuntimes(runtimesDir, platform = process.platform) {
     if (!fs.existsSync(runtimesDir))
         return [];
+    const exeName = serverExeName(platform);
     const found = [];
     for (const entry of fs.readdirSync(runtimesDir, { withFileTypes: true })) {
         if (!entry.isDirectory())
             continue;
         const root = path.join(runtimesDir, entry.name);
-        const exe = findFile(root, "llama-server.exe");
+        const exe = findFile(root, exeName);
         if (!exe)
             continue;
         found.push({
@@ -75,7 +239,8 @@ export function listManagedRuntimes(runtimesDir) {
             source: "managed",
         });
     }
-    return found;
+    return found.sort((a, b) => managedVariantRank(a.label) - managedVariantRank(b.label) ||
+        buildNumber(b.version) - buildNumber(a.version));
 }
 async function downloadFile(url, dest, onProgress) {
     const response = await fetch(url);
@@ -100,22 +265,212 @@ function run(command, args) {
         child.on("close", (code) => code === 0 ? resolve() : reject(new Error(`${command} exited ${code}: ${stderr.trim()}`)));
     });
 }
-async function extractArchive(archivePath, destDir) {
+/** Spawn and collect the outcome instead of throwing, so callers can classify it. */
+function runCapture(command, args, env) {
+    return new Promise((resolve) => {
+        const child = spawn(command, args, { windowsHide: true, env });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (d) => (stdout += d.toString()));
+        child.stderr.on("data", (d) => (stderr += d.toString()));
+        child.on("error", (err) => resolve({ code: null, stdout, stderr: `${stderr}${err}` }));
+        child.on("close", (code) => resolve({ code, stdout, stderr }));
+    });
+}
+/**
+ * Distro packages providing a library llama.cpp links but ships on no asset.
+ * Keyed by soname because that is the string the dynamic loader prints.
+ */
+const SYSTEM_LIBRARY_PACKAGES = {
+    "libgomp.so.1": "libgomp1 (Debian/Ubuntu), libgomp (Fedora/RHEL) or gcc-libs (Arch)",
+};
+/**
+ * Where to fetch the one library upstream leaves unmet on Linux.
+ *
+ * Debian's pool rather than Ubuntu's for two measured reasons: bookworm's
+ * `libgomp1` carries a `GLIBC_2.34` floor, which is *exactly* llama-server's own
+ * floor, so bundling it cannot narrow the set of systems the runtime already ran
+ * on; and its payload is `data.tar.xz`, which `tar` reads with the near-universal
+ * `xz`, where Ubuntu 24.04+ moved to zstd, which a minimal image does not have.
+ */
+const LIBGOMP_PACKAGE = {
+    x64: "https://deb.debian.org/debian/pool/main/g/gcc-12/libgomp1_12.2.0-14+deb12u1_amd64.deb",
+    arm64: "https://deb.debian.org/debian/pool/main/g/gcc-12/libgomp1_12.2.0-14+deb12u1_arm64.deb",
+};
+/**
+ * Read one member out of a Unix `ar` archive, which is the container format of a
+ * `.deb`. Parsed here rather than shelled out to `ar`, which is binutils and not
+ * present on a minimal image - the exact kind of host that needs this repair.
+ *
+ * Layout: an 8-byte magic, then per member a fixed 60-byte ASCII header whose
+ * name is bytes 0-15 and size bytes 48-57, followed by the payload padded to an
+ * even offset.
+ */
+function readArMember(archive, member) {
+    if (archive.subarray(0, 8).toString("ascii") !== "!<arch>\n")
+        return null;
+    let offset = 8;
+    while (offset + 60 <= archive.length) {
+        const header = archive.subarray(offset, offset + 60);
+        const name = header.subarray(0, 16).toString("ascii").trim().replace(/\/$/, "");
+        const size = Number.parseInt(header.subarray(48, 58).toString("ascii").trim(), 10);
+        if (!Number.isInteger(size) || size < 0)
+            return null;
+        const start = offset + 60;
+        if (name === member)
+            return archive.subarray(start, start + size);
+        offset = start + size + (size % 2);
+    }
+    return null;
+}
+/**
+ * Try to satisfy a missing system library by placing it beside the binary, where
+ * `buildEnv`'s loader path already looks.
+ *
+ * Only ever runs *after* the runtime has already failed to start, so it cannot
+ * regress a host that works: a system with its own `libgomp` never reaches here.
+ * Returns false on any failure, which leaves the caller reporting the actionable
+ * error it would have reported anyway. Best effort, never fatal in itself.
+ */
+async function repairMissingLibrary(soname, destDir, arch) {
+    if (soname !== "libgomp.so.1")
+        return false;
+    const url = LIBGOMP_PACKAGE[arch === "x64" ? "x64" : arch === "arm64" ? "arm64" : ""];
+    if (!url)
+        return false;
+    const scratch = path.join(destDir, ".libgomp-repair");
+    try {
+        fs.mkdirSync(scratch, { recursive: true });
+        const debPath = path.join(scratch, "lib.deb");
+        await downloadFile(url, debPath);
+        const payload = readArMember(fs.readFileSync(debPath), "data.tar.xz");
+        if (!payload)
+            return false;
+        const tarPath = path.join(scratch, "data.tar.xz");
+        fs.writeFileSync(tarPath, payload);
+        await extractArchive(tarPath, scratch, "linux");
+        // The package ships `libgomp.so.1` as a symlink to the real `libgomp.so.1.0.0`;
+        // copy the target under the soname so no symlink support is needed.
+        const real = findFile(scratch, "libgomp.so.1.0.0");
+        if (!real)
+            return false;
+        fs.copyFileSync(real, path.join(destDir, soname));
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        fs.rmSync(scratch, { recursive: true, force: true });
+    }
+}
+/**
+ * The actionable message for a dynamic-loader failure, or null when the output
+ * is not one. Pure, so the classification is testable without spawning.
+ *
+ * Returning null for an unrecognised failure is deliberate: a future llama.cpp
+ * that exits non-zero from `--version` must not turn a perfectly usable install
+ * into a hard failure. Only a positively identified missing library throws.
+ */
+export function missingLibraryFrom(stderr) {
+    const missing = 
+    // glibc's loader, and macOS dyld.
+    /error while loading shared libraries:\s*([^\s:]+)/.exec(stderr) ??
+        /Library not loaded:\s*(\S+)/.exec(stderr);
+    return missing ? missing[1] : null;
+}
+export function describeLoaderFailure(stderr, runtimeDir, platform = process.platform) {
+    const lib = missingLibraryFrom(stderr);
+    if (!lib)
+        return null;
+    const hint = SYSTEM_LIBRARY_PACKAGES[lib.replace(/^.*[/\\]/, "")];
+    return (`the runtime installed but cannot start: ${lib} is missing from this system. ` +
+        `llama.cpp links it and ships it on no ${platform} asset, so it has to come from the OS` +
+        (hint ? ` - install ${hint}` : "") +
+        `. The runtime is at ${runtimeDir}; re-run once the library is present.`);
+}
+/**
+ * Run the freshly installed binary once, so a missing *system* library surfaces
+ * at install time naming the library, instead of hours later as an opaque
+ * supervisor crash.
+ *
+ * This is not hypothetical: no upstream Linux asset ships `libgomp.so.1`, which
+ * `llama-server` hard-links, so on a host without `libgomp1` the download and
+ * extract both succeed and the binary then dies with exit 127. `buildEnv` cannot
+ * fix that - the library is not in the runtime dir LD_LIBRARY_PATH points at.
+ */
+export async function verifyRuntimeExecutable(runtime, platform = process.platform, arch = process.arch) {
+    const env = buildEnv(runtime, process.env, platform);
+    const first = await runCapture(runtime.exe, ["--version"], env);
+    if (first.code === 0)
+        return;
+    const problem = describeLoaderFailure(first.stderr, runtime.dir, platform);
+    if (!problem)
+        return;
+    // Repair before giving up. `libgomp.so.1` is missing from every upstream Linux
+    // asset, so on a minimal image this is the *expected* first outcome, not an
+    // exceptional one, and telling the user to go install a package is a worse
+    // answer than placing the library where the loader already looks.
+    const soname = missingLibraryFrom(first.stderr);
+    if (platform === "linux" && soname && (await repairMissingLibrary(soname, runtime.dir, arch))) {
+        const retry = await runCapture(runtime.exe, ["--version"], env);
+        if (retry.code === 0)
+            return;
+        throw new Error(describeLoaderFailure(retry.stderr, runtime.dir, platform) ?? problem);
+    }
+    throw new Error(problem);
+}
+/**
+ * Device lines out of `--list-devices` stdout, which is a header followed by one
+ * indented line per device, or the literal `(none)`. Pure half of
+ * `listRuntimeDevices`.
+ */
+export function parseDeviceList(stdout) {
+    return stdout
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line && !/^available devices:/i.test(line) && line !== "(none)");
+}
+/**
+ * Devices the runtime's backends actually found, one line each. Empty means the
+ * accelerator resolved to nothing and inference would silently fall back to CPU,
+ * which is a real configuration: on WSL2 there is no NVIDIA Vulkan ICD, so a
+ * Vulkan runtime on an NVIDIA machine reports no device and runs ~41x slower at
+ * prefill without saying so. Never throws; a probe failure reads as "unknown".
+ */
+export async function listRuntimeDevices(runtime, platform = process.platform) {
+    const env = buildEnv(runtime, process.env, platform);
+    const { code, stdout } = await runCapture(runtime.exe, ["--list-devices"], env);
+    if (code !== 0)
+        return [];
+    return parseDeviceList(stdout);
+}
+export async function extractArchive(archivePath, destDir, platform = process.platform) {
     fs.mkdirSync(destDir, { recursive: true });
     if (/\.zip$/i.test(archivePath)) {
-        // PowerShell ships with Windows; -Force overwrites an interrupted extract.
-        // Paths are rooted at $OTTO_HOME (under the user profile), so a username with
-        // an apostrophe would break - or inject into - a raw single-quoted string.
-        // Escape single quotes for PowerShell (a literal ' is written as '').
-        const psQuote = (value) => `'${value.replace(/'/g, "''")}'`;
-        await run("powershell", [
-            "-NoProfile",
-            "-Command",
-            `Expand-Archive -LiteralPath ${psQuote(archivePath)} -DestinationPath ${psQuote(destDir)} -Force`,
-        ]);
+        if (platform === "win32") {
+            // PowerShell ships with Windows; -Force overwrites an interrupted extract.
+            // Paths are rooted at $OTTO_HOME (under the user profile), so a username with
+            // an apostrophe would break - or inject into - a raw single-quoted string.
+            // Escape single quotes for PowerShell (a literal ' is written as '').
+            const psQuote = (value) => `'${value.replace(/'/g, "''")}'`;
+            await run("powershell", [
+                "-NoProfile",
+                "-Command",
+                `Expand-Archive -LiteralPath ${psQuote(archivePath)} -DestinationPath ${psQuote(destDir)} -Force`,
+            ]);
+            return;
+        }
+        // macOS and Linux both ship a tar that reads zip (bsdtar on macOS, and on
+        // Linux the current assets are tarballs anyway - this branch only matters
+        // for a hand-passed zip). `unzip` is not assumed: it is not installed by
+        // default on every distro.
+        await run("tar", ["-xf", archivePath, "-C", destDir]);
         return;
     }
-    if (/\.(tar\.gz|tgz|tar)$/i.test(archivePath)) {
+    // `.tar.xz` is here for the .deb payload the Linux libgomp repair unpacks; tar
+    // picks the decompressor itself, so this stays within the OS built-ins rule.
+    if (/\.(tar\.gz|tgz|tar\.xz|tar)$/i.test(archivePath)) {
         await run("tar", ["-xf", archivePath, "-C", destDir]);
         return;
     }
@@ -123,20 +478,26 @@ async function extractArchive(archivePath, destDir) {
 }
 /** Download + extract a runtime spec into runtimesDir and return the Runtime. */
 export async function installManagedRuntime(spec, runtimesDir, onProgress) {
+    const platform = spec.platform ?? process.platform;
     const targetDir = path.join(runtimesDir, slug(spec));
     fs.mkdirSync(targetDir, { recursive: true });
     for (const url of spec.assets) {
         const archivePath = path.join(targetDir, path.basename(new URL(url).pathname));
         await downloadFile(url, archivePath, onProgress);
         onProgress?.({ phase: "extracting", asset: url });
-        await extractArchive(archivePath, targetDir);
+        await extractArchive(archivePath, targetDir, platform);
         fs.rmSync(archivePath, { force: true });
     }
-    const exe = findFile(targetDir, "llama-server.exe");
+    const exeName = serverExeName(platform);
+    const exe = findFile(targetDir, exeName);
     if (!exe)
-        throw new Error(`installed runtime has no llama-server.exe under ${targetDir}`);
-    onProgress?.({ phase: "done" });
-    return {
+        throw new Error(`installed runtime has no ${exeName} under ${targetDir}`);
+    if (platform !== "win32") {
+        // Archive mode bits survive `tar -x`, but not every extractor preserves
+        // them; without +x the supervisor's spawn fails with a bare EACCES.
+        fs.chmodSync(exe, 0o755);
+    }
+    const runtime = {
         label: spec.label,
         version: spec.version,
         dir: path.dirname(exe),
@@ -144,5 +505,10 @@ export async function installManagedRuntime(spec, runtimesDir, onProgress) {
         vendorDir: null,
         source: "managed",
     };
+    // Before reporting success. An install that cannot exec is not an install, and
+    // the loader error names the cause far better than the later spawn failure does.
+    await verifyRuntimeExecutable(runtime, platform);
+    onProgress?.({ phase: "done" });
+    return runtime;
 }
 //# sourceMappingURL=managed.js.map

package/dist/service/host-api.d.ts

@@ -48,6 +48,10 @@ export interface HostCapabilities {
     resources: boolean;
     /** GET /__host/models */
     inventory: boolean;
+    /** POST /__host/model/rename */
+    rename: boolean;
+    /** POST /__host/model/rename/reset */
+    reset: boolean;
     /** Whether writes are currently permitted (allowRemoteConfig). */
     writable: boolean;
 }

package/dist/service/host-api.js

@@ -1,9 +1,11 @@
 import { calibrationInfo, profileFieldDescriptors, profileWarnings, sanitizeProfilePatch, } from "../config/profile-edit.js";
 import { forModel, getCalibration, put } from "../config/profiles.js";
 import { deleteModelFiles, diskUsage, planDelete, totalModelBytes } from "../models/manage.js";
+import { deleteDisplayName, updateDisplayName } from "../models/rename-map.js";
 import * as vram from "../vram.js";
 import { errorMessage, readJsonBody, sendError, sendJson } from "./http-util.js";
 const MAX_PATCH_BYTES = 256 * 1024;
+const MAX_DISPLAY_NAME = 200;
 const DEFAULT_LOG_LINES = 200;
 function stateOf(supervisor, model) {
     if (!supervisor.model || supervisor.model.id !== model.id)
@@ -101,6 +103,8 @@ export function createHostApi(deps) {
         load: true,
         resources: true,
         inventory: true,
+        rename: true,
+        reset: true,
         writable: deps.getAllowWrite(),
     });
     /** Refuse a write unless the owner opted into remote configuration. */
@@ -180,6 +184,53 @@ export function createHostApi(deps) {
             })();
         });
     };
+    const handleRename = (req, res, model) => {
+        readJsonBody(req, MAX_DISPLAY_NAME + 64, (result) => {
+            if (!result.ok) {
+                sendError(res, 400, result.error);
+                return;
+            }
+            const body = result.body;
+            const displayName = body.displayName;
+            if (typeof displayName !== "string" || displayName.trim().length === 0) {
+                sendError(res, 400, "displayName must be a non-empty string");
+                return;
+            }
+            if (displayName.length > MAX_DISPLAY_NAME) {
+                sendError(res, 400, `displayName must be at most ${MAX_DISPLAY_NAME} characters`);
+                return;
+            }
+            if (/[^\x20-\x7E]/.test(displayName)) {
+                sendError(res, 400, "displayName must not contain control characters or non-ASCII");
+                return;
+            }
+            // /v1/models keys its `id` on displayName (router.ts) and both the
+            // completion path and defaultModel/switchTo resolve a model by
+            // `displayName === name || id === name` - a collision here would make
+            // one of the two models unreachable by name with no error anywhere.
+            const conflict = deps
+                .getCatalog()
+                .find((m) => m.id !== model.id && (m.displayName === displayName || m.id === displayName));
+            if (conflict) {
+                sendError(res, 409, `another model is already named "${displayName}"`);
+                return;
+            }
+            updateDisplayName(model.id, displayName);
+            sendJson(res, { displayName });
+        });
+    };
+    const handleReset = (req, res, model) => {
+        readJsonBody(req, 4096, (result) => {
+            if (!result.ok) {
+                sendError(res, 400, result.error);
+                return;
+            }
+            deleteDisplayName(model.id);
+            const catalog = deps.rescan();
+            const updated = resolveModel(catalog, model.id);
+            sendJson(res, { displayName: updated ? updated.displayName : model.displayName });
+        });
+    };
     const handleBudget = (res, model, params) => {
         void (async () => {
             try {
@@ -326,6 +377,8 @@ export function createHostApi(deps) {
             "/__host/model/budget",
             "/__host/model/load",
             "/__host/model/fields",
+            "/__host/model/rename",
+            "/__host/model/rename/reset",
         ]);
         if (!modelRoutes.has(route))
             return false;
@@ -359,6 +412,18 @@ export function createHostApi(deps) {
             handleLoad(res, model);
             return true;
         }
+        if (route === "/__host/model/rename" && method === "POST") {
+            if (!guardWrite(res))
+                return true;
+            handleRename(req, res, model);
+            return true;
+        }
+        if (route === "/__host/model/rename/reset" && method === "POST") {
+            if (!guardWrite(res))
+                return true;
+            handleReset(req, res, model);
+            return true;
+        }
         if (route === "/__host/model" && method === "DELETE") {
             if (!guardWrite(res))
                 return true;

package/dist/service/router.js

@@ -298,6 +298,25 @@ function proxyBuffered({ agent, supervisor, telemetry, logger, req, res, body, r
             }
             res.writeHead(upstreamRes.statusCode ?? 502, outHeaders);
             const isStream = String(upstreamRes.headers["content-type"] || "").includes("event-stream");
+            const upstreamResponseFailed = (error) => {
+                if (settled)
+                    return;
+                const message = `llama-server response ended unexpectedly: ${error.message}`;
+                telemetry.record({
+                    at: new Date().toISOString(),
+                    path: req.url,
+                    verdict: "failed",
+                    error: message,
+                });
+                logger?.warn?.(message);
+                // Headers may already be on the wire for an SSE response. Destroying
+                // it is the only honest result, but `done()` still releases the queue.
+                if (!res.writableEnded && !res.destroyed)
+                    res.destroy(error);
+                done();
+            };
+            upstreamRes.once("aborted", () => upstreamResponseFailed(new Error("upstream response aborted")));
+            upstreamRes.once("error", upstreamResponseFailed);
             if (isStream) {
                 let sawContent = false;
                 let sawReasoning = false;

package/dist/service/run-log.d.ts

@@ -0,0 +1,8 @@
+export interface BrainRunLog {
+    path: string;
+    write(line: string): void;
+}
+/** Start a fresh Brain log and prune only expired Brain run logs. */
+export declare function createBrainRunLog(env?: NodeJS.ProcessEnv): BrainRunLog;
+export declare function pruneBrainRunLogs(logsDir: string, now?: number): void;
+//# sourceMappingURL=run-log.d.ts.map