@otto-code/brain 0.8.0 → 0.8.1

package/dist/commands/runtime.d.ts

@@ -17,5 +17,6 @@ export declare function runRuntimeListCommand(_options: unknown, _command: Comma
 export declare function addRuntimeInstallOptions(cmd: Command): Command;
 export declare function runRuntimeInstallCommand(options: {
     build?: string;
+    variant?: string;
 }, _command: Command): Promise<AnyCommandResult<RuntimeRow>>;
 //# sourceMappingURL=runtime.d.ts.map

package/dist/commands/runtime.js

@@ -1,6 +1,7 @@
 import { loadBrainConfig } from "../config/index.js";
 import { resolveBrainPaths } from "../config/paths.js";
-import { defaultRuntimeSpec, installManagedRuntime, listAllRuntimes } from "../runtime/index.js";
+import { CommandError } from "../output/types.js";
+import { defaultRuntimeSpec, installManagedRuntime, listAllRuntimes, listRuntimeDevices, probeNvidiaGpu, supportedVariants, } from "../runtime/index.js";
 const runtimeSchema = {
     idField: "dir",
     columns: [
@@ -32,12 +33,26 @@ export async function runRuntimeListCommand(_options, _command) {
 export function addRuntimeInstallOptions(cmd) {
     return cmd
         .description("Download a self-contained llama.cpp runtime")
-        .option("--build <tag>", "llama.cpp release build tag");
+        .option("--build <tag>", "llama.cpp release build tag")
+        .option("--variant <name>", `accelerator to install (${supportedVariants().join("|")}); defaults to the best one this machine can use`);
 }
 export async function runRuntimeInstallCommand(options, _command) {
     loadBrainConfig();
     const { runtimesDir } = resolveBrainPaths();
-    const spec = defaultRuntimeSpec(options.build);
+    const available = supportedVariants();
+    if (options.variant && !available.includes(options.variant)) {
+        throw new CommandError({
+            code: "UNSUPPORTED_VARIANT",
+            message: `llama.cpp publishes no "${options.variant}" build for ${process.platform}/${process.arch}` +
+                ` - available: ${available.join(", ") || "(none)"}`,
+        });
+    }
+    // Only "auto" needs the GPU probe, and only to choose between CUDA and Vulkan
+    // on the platforms that have both.
+    const spec = defaultRuntimeSpec(options.build, {
+        variant: options.variant ?? "auto",
+        hasNvidiaGpu: options.variant ? undefined : await probeNvidiaGpu(),
+    });
     process.stderr.write(`  installing ${spec.label} (${spec.version})…\n`);
     const runtime = await installManagedRuntime(spec, runtimesDir, (p) => {
         if (p.phase === "downloading" && p.totalBytes) {
@@ -48,6 +63,20 @@ export async function runRuntimeInstallCommand(options, _command) {
             process.stderr.write("\n  extracting…\n");
     });
     process.stderr.write("\n");
+    // A GPU variant that finds no device still runs - on the CPU, at roughly a
+    // fortieth of the prefill throughput, and says nothing about it. Measured on
+    // WSL2, which carries no NVIDIA Vulkan ICD. Warn rather than fail: the runtime
+    // is genuinely installed and usable, just not accelerated.
+    // One line on purpose. The daemon's BrainOpsManager keeps the *last* stderr line
+    // as the job's message, so a multi-line warning would surface in the UI as a
+    // dangling fragment. As one line it survives intact on both the CLI and the GUI.
+    if (spec.variant !== "cpu") {
+        const devices = await listRuntimeDevices(runtime);
+        if (devices.length === 0) {
+            process.stderr.write(`  warning: this ${spec.variant} runtime reports no GPU device, so inference will run` +
+                ` on the CPU until a working ${spec.variant} driver for this GPU is installed.\n`);
+        }
+    }
     return {
         type: "single",
         data: {

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,10 +10,18 @@ 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.
  *

package/dist/runtime/args.js

@@ -1,21 +1,27 @@
 /**
- * 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.

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

package/dist/runtime/index.js

@@ -4,18 +4,32 @@
  * path) and `lmstudio` (discovered from an existing LM Studio install, a
  * zero-download fast path). Selection follows config: an explicit path override
  * wins; otherwise `auto` prefers a managed runtime and falls back to LM Studio.
+ *
+ * Both providers are cross-platform. Which accelerator a managed install picks
+ * is decided in `managed.resolveRuntimeVariant` from the platform, the arch and
+ * whether an NVIDIA GPU answered - `probeNvidiaGpu` below is the one place that
+ * asks, so the download layer stays free of process spawning.
  */
+import { query as queryGpu } from "../gpu.js";
 import { resolveBrainPaths } from "../config/paths.js";
 import { listRuntimes as listLmStudioRuntimes, resolveOverride } from "./lmstudio.js";
 import { defaultRuntimeSpec, installManagedRuntime, listManagedRuntimes, } from "./managed.js";
 export { BACKENDS_DIR, LMSTUDIO_ROOT, listRuntimes as listLmStudioRuntimes } from "./lmstudio.js";
 export { buildArgs, buildEnv, formatCommand } from "./args.js";
-export { installManagedRuntime, listManagedRuntimes, defaultRuntimeSpec, DEFAULT_LLAMA_BUILD, } from "./managed.js";
+export { installManagedRuntime, listManagedRuntimes, listRuntimeDevices, verifyRuntimeExecutable, defaultRuntimeSpec, extractArchive, resolveRuntimeVariant, serverExeName, supportedVariants, DEFAULT_LLAMA_BUILD, } from "./managed.js";
 /** Every runtime available on this machine, managed first then LM Studio. */
 export function listAllRuntimes(env = process.env) {
     const paths = resolveBrainPaths(env);
     return [...listManagedRuntimes(paths.runtimesDir), ...listLmStudioRuntimes()];
 }
+/**
+ * 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 async function probeNvidiaGpu() {
+    return (await queryGpu()) !== null;
+}
 /** The runtime to use given config, or null when none is available. */
 export function resolveRuntime(config, env = process.env) {
     const rc = config.runtime;
@@ -31,11 +45,15 @@ export function resolveRuntime(config, env = process.env) {
     return managed[0] ?? lmstudio[0] ?? null; // auto
 }
 /** Ensure a runtime exists, downloading the default managed build if none does. */
-export async function ensureRuntime(config, env = process.env, onProgress) {
+export async function ensureRuntime(config, env = process.env, onProgress, target = {}) {
     const existing = resolveRuntime(config, env);
     if (existing)
         return existing;
     const paths = resolveBrainPaths(env);
-    return installManagedRuntime(defaultRuntimeSpec(), paths.runtimesDir, onProgress);
+    const resolved = {
+        ...target,
+        hasNvidiaGpu: target.hasNvidiaGpu ?? (await probeNvidiaGpu()),
+    };
+    return installManagedRuntime(defaultRuntimeSpec(null, resolved), paths.runtimesDir, onProgress);
 }
 //# sourceMappingURL=index.js.map

package/dist/runtime/lmstudio.d.ts

@@ -4,7 +4,7 @@ export declare const BACKENDS_DIR: string;
 export declare function extractVersion(dirName: string): string;
 /** Compare dotted version strings numerically, descending. */
 export declare function compareVersionsDesc(a: string, b: string): number;
-export declare function listRuntimes(backendsDir?: string): Runtime[];
+export declare function listRuntimes(backendsDir?: string, platform?: NodeJS.Platform): Runtime[];
 /** Resolve an explicit runtime directory or exe override into a Runtime. */
-export declare function resolveOverride(override: string): Runtime;
+export declare function resolveOverride(override: string, platform?: NodeJS.Platform): Runtime;
 //# sourceMappingURL=lmstudio.d.ts.map

package/dist/runtime/lmstudio.js

@@ -1,33 +1,73 @@
 /**
- * Locates the llama-server binary shipped inside LM Studio.
+ * Locates the llama-server binary shipped inside LM Studio, on all three
+ * desktop platforms. LM Studio keeps its backends under `~/.lmstudio` on
+ * Windows, macOS and Linux alike, so only the directory naming and the binary
+ * name differ per platform.
  *
- * Important gotcha: that executable is a ~20KB stub. Launching it without the
- * matching `backends/vendor/...` directory on PATH fails with
+ * Important gotcha (Windows): that executable is a ~20KB stub. Launching it
+ * without the matching `backends/vendor/...` directory on PATH fails with
  * STATUS_DLL_NOT_FOUND (0xC0000135) and prints absolutely nothing, so we always
- * pair a runtime with its vendor directory. This is one of two runtime sources
- * (the other being the self-contained `managed` runtime); it stays as a
- * zero-download fast path when LM Studio is already installed.
+ * pair a runtime with its vendor directory, and a Windows runtime whose vendor
+ * dir is missing is skipped rather than offered. macOS and Linux builds are
+ * self-contained and fail loudly through the dynamic loader when they are not,
+ * which is why the name-shape fallback below is enabled only there.
+ *
+ * This is one of two runtime sources (the other being the self-contained
+ * `managed` runtime); it stays as a zero-download fast path when LM Studio is
+ * already installed.
  */
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { serverExeName } from "./managed.js";
 export const LMSTUDIO_ROOT = path.join(os.homedir(), ".lmstudio");
 export const BACKENDS_DIR = path.join(LMSTUDIO_ROOT, "extensions", "backends");
-// Most preferred first. Each entry maps a runtime prefix to its vendor dir.
-const RUNTIME_PREFERENCE = [
-    {
-        prefix: "llama.cpp-win-x86_64-nvidia-cuda12-",
-        vendor: "win-llama-cuda12-vendor-v2",
-        label: "CUDA 12",
-    },
-    {
-        prefix: "llama.cpp-win-x86_64-nvidia-cuda-",
-        vendor: "win-llama-cuda-vendor-v2",
-        label: "CUDA 11",
-    },
-    { prefix: "llama.cpp-win-x86_64-vulkan-", vendor: "win-llama-vulkan-vendor-v2", label: "Vulkan" },
-    { prefix: "llama.cpp-win-x86_64-avx2-", vendor: null, label: "CPU (AVX2)" },
-];
+/**
+ * Most preferred first, per platform. Each entry maps a runtime directory
+ * prefix to its vendor dir.
+ *
+ * Prefix (not substring) matching is deliberate: a CUDA directory is named
+ * `llama.cpp-win-x86_64-nvidia-cuda12-avx2-<version>`, so a substring rule for
+ * the AVX2 entry would match it a second time and offer the same runtime twice
+ * under the wrong label.
+ *
+ * The Windows rows are verified against a real install. The macOS and Linux
+ * rows follow LM Studio's documented naming but have not been read off a live
+ * install here - the shape fallback in `listRuntimes` is what makes discovery
+ * correct on those platforms regardless.
+ */
+const PREFERENCES = {
+    win32: [
+        {
+            prefix: "llama.cpp-win-x86_64-nvidia-cuda12-",
+            vendor: "win-llama-cuda12-vendor-v2",
+            label: "CUDA 12",
+        },
+        {
+            prefix: "llama.cpp-win-x86_64-nvidia-cuda-",
+            vendor: "win-llama-cuda-vendor-v2",
+            label: "CUDA 11",
+        },
+        {
+            prefix: "llama.cpp-win-x86_64-vulkan-",
+            vendor: "win-llama-vulkan-vendor-v2",
+            label: "Vulkan",
+        },
+        { prefix: "llama.cpp-win-x86_64-avx2-", vendor: null, label: "CPU (AVX2)" },
+    ],
+    darwin: [
+        { prefix: "llama.cpp-mac-arm64-apple-metal-", vendor: null, label: "Metal" },
+        { prefix: "llama.cpp-mac-arm64-", vendor: null, label: "CPU (arm64)" },
+        { prefix: "llama.cpp-mac-x86_64-", vendor: null, label: "CPU (x86_64)" },
+    ],
+    linux: [
+        { prefix: "llama.cpp-linux-x86_64-nvidia-cuda12-", vendor: null, label: "CUDA 12" },
+        { prefix: "llama.cpp-linux-x86_64-nvidia-cuda-", vendor: null, label: "CUDA 11" },
+        { prefix: "llama.cpp-linux-x86_64-vulkan-", vendor: null, label: "Vulkan" },
+        { prefix: "llama.cpp-linux-x86_64-avx2-", vendor: null, label: "CPU (AVX2)" },
+        { prefix: "llama.cpp-linux-aarch64-", vendor: null, label: "CPU (aarch64)" },
+    ],
+};
 // Directory names carry an instruction-set segment before the version
 // (…-cuda12-avx2-2.24.0), so take the trailing dotted number, not the remainder.
 const VERSION_SUFFIX = /(\d+(?:\.\d+)+)$/;
@@ -46,40 +86,87 @@ export function compareVersionsDesc(a, b) {
     }
     return 0;
 }
-export function listRuntimes(backendsDir = BACKENDS_DIR) {
+/** A readable label for a directory discovered outside the preference table. */
+function labelFromDirName(dirName) {
+    const lower = dirName.toLowerCase();
+    if (lower.includes("cuda12"))
+        return "CUDA 12";
+    if (lower.includes("cuda"))
+        return "CUDA";
+    if (lower.includes("metal"))
+        return "Metal";
+    if (lower.includes("vulkan"))
+        return "Vulkan";
+    if (lower.includes("rocm") || lower.includes("hip"))
+        return "ROCm";
+    if (lower.includes("avx2"))
+        return "CPU (AVX2)";
+    return "LM Studio runtime";
+}
+export function listRuntimes(backendsDir = BACKENDS_DIR, platform = process.platform) {
     if (!fs.existsSync(backendsDir))
         return [];
+    const exeName = serverExeName(platform);
     const entries = fs
         .readdirSync(backendsDir, { withFileTypes: true })
         .filter((e) => e.isDirectory())
         .map((e) => e.name);
     const found = [];
-    for (const pref of RUNTIME_PREFERENCE) {
+    const claimed = new Set();
+    for (const pref of PREFERENCES[platform] ?? []) {
         const matches = entries
-            .filter((name) => name.startsWith(pref.prefix))
+            .filter((name) => name.startsWith(pref.prefix) && !claimed.has(name))
             .map((name) => ({ name, version: extractVersion(name) }))
-            .filter(({ name }) => fs.existsSync(path.join(backendsDir, name, "llama-server.exe")))
+            .filter(({ name }) => fs.existsSync(path.join(backendsDir, name, exeName)))
             .sort((a, b) => compareVersionsDesc(a.version, b.version));
         for (const match of matches) {
             const vendorDir = pref.vendor ? path.join(backendsDir, "vendor", pref.vendor) : null;
             // A runtime whose vendor DLLs are missing cannot launch; skip it.
             if (vendorDir && !fs.existsSync(vendorDir))
                 continue;
+            claimed.add(match.name);
             found.push({
                 label: pref.label,
                 version: match.version,
                 dir: path.join(backendsDir, match.name),
-                exe: path.join(backendsDir, match.name, "llama-server.exe"),
+                exe: path.join(backendsDir, match.name, exeName),
                 vendorDir,
                 source: "lmstudio",
             });
         }
     }
+    // Shape fallback: anything that holds a llama-server binary is usable on the
+    // self-contained platforms, whatever LM Studio decided to call the directory.
+    // Not applied on Windows, where an unpaired stub launches and dies silently.
+    if (platform !== "win32") {
+        const extra = entries
+            .filter((name) => !claimed.has(name) && name !== "vendor")
+            .filter((name) => fs.existsSync(path.join(backendsDir, name, exeName)))
+            .map((name) => ({ name, version: extractVersion(name) }))
+            .sort((a, b) => compareVersionsDesc(a.version, b.version));
+        for (const match of extra) {
+            found.push({
+                label: labelFromDirName(match.name),
+                version: match.version,
+                dir: path.join(backendsDir, match.name),
+                exe: path.join(backendsDir, match.name, exeName),
+                vendorDir: null,
+                source: "lmstudio",
+            });
+        }
+    }
     return found;
 }
 /** Resolve an explicit runtime directory or exe override into a Runtime. */
-export function resolveOverride(override) {
-    const exe = override.endsWith(".exe") ? override : path.join(override, "llama-server.exe");
+export function resolveOverride(override, platform = process.platform) {
+    const exeName = serverExeName(platform);
+    // An override may name the binary directly or the directory holding it. On
+    // non-Windows the binary has no extension, so "is it a file?" is the only
+    // reliable test - a bare `.../llama-server` path looks exactly like a dir.
+    const looksLikeExe = path.basename(override).toLowerCase() === exeName.toLowerCase() ||
+        (platform === "win32" && override.toLowerCase().endsWith(".exe")) ||
+        (fs.existsSync(override) && fs.statSync(override).isFile());
+    const exe = looksLikeExe ? override : path.join(override, exeName);
     if (!fs.existsSync(exe))
         throw new Error(`llama-server not found at ${exe}`);
     const dir = path.dirname(exe);

package/dist/runtime/managed.d.ts

@@ -1,9 +1,23 @@
 import type { Runtime } from "../types.js";
+/** The accelerator a managed runtime is built against. */
+export type RuntimeVariant = "cuda" | "metal" | "vulkan" | "cpu";
 export interface RuntimeSpec {
     label: string;
     version: string;
     /** One or more archive URLs, extracted in order into the same target dir. */
     assets: string[];
+    /** Platform the assets are built for; drives exe name and extraction. */
+    platform: NodeJS.Platform;
+    variant: RuntimeVariant;
+}
+/** What to install for. Any field left out is read from the current process. */
+export interface RuntimeTarget {
+    platform?: NodeJS.Platform;
+    arch?: string;
+    /** Explicit accelerator, or "auto" to pick from platform + GPU presence. */
+    variant?: RuntimeVariant | "auto";
+    /** Whether an NVIDIA GPU was detected; only consulted by "auto". */
+    hasNvidiaGpu?: boolean;
 }
 export interface InstallProgress {
     phase: "downloading" | "extracting" | "done";
@@ -12,15 +26,65 @@ export interface InstallProgress {
     totalBytes?: number;
 }
 /**
- * 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 declare const DEFAULT_LLAMA_BUILD = "b10265";
+/** The binary name llama.cpp ships for a platform. */
+export declare function serverExeName(platform?: NodeJS.Platform): string;
+/**
+ * Pick the accelerator for a target. Deliberately conservative: it never
+ * chooses an accelerator whose asset does not exist for that platform/arch.
+ */
+export declare function resolveRuntimeVariant(target?: RuntimeTarget): RuntimeVariant;
+/**
+ * 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 declare function defaultRuntimeSpec(build?: string | null | undefined, target?: RuntimeTarget): RuntimeSpec;
+/** Variants with a published asset for a platform/arch, best first. */
+export declare function supportedVariants(platform?: NodeJS.Platform, arch?: string): RuntimeVariant[];
+/**
+ * A managed runtime is any dir under runtimesDir that contains llama-server,
+ * best accelerator first and newest build first within an accelerator.
+ */
+export declare function listManagedRuntimes(runtimesDir: string, platform?: NodeJS.Platform): Runtime[];
+/**
+ * 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 declare function missingLibraryFrom(stderr: string): string | null;
+export declare function describeLoaderFailure(stderr: string, runtimeDir: string, platform?: NodeJS.Platform): string | null;
+/**
+ * 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 declare function verifyRuntimeExecutable(runtime: Runtime, platform?: NodeJS.Platform, arch?: string): Promise<void>;
+/**
+ * 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 declare function parseDeviceList(stdout: string): string[];
+/**
+ * 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 declare const DEFAULT_LLAMA_BUILD = "b4600";
-/** Build the default Windows CUDA 12 spec for a given llama.cpp build tag. */
-export declare function defaultRuntimeSpec(build?: string): RuntimeSpec;
-/** A managed runtime is any dir under runtimesDir that contains llama-server.exe. */
-export declare function listManagedRuntimes(runtimesDir: string): Runtime[];
+export declare function listRuntimeDevices(runtime: Runtime, platform?: NodeJS.Platform): Promise<string[]>;
+export declare function extractArchive(archivePath: string, destDir: string, platform?: NodeJS.Platform): Promise<void>;
 /** Download + extract a runtime spec into runtimesDir and return the Runtime. */
 export declare function installManagedRuntime(spec: RuntimeSpec, runtimesDir: string, onProgress?: (progress: InstallProgress) => void): Promise<Runtime>;
 //# sourceMappingURL=managed.d.ts.map

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@otto-code/brain",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Otto Brain - self-contained host for local GGUF models, with measured VRAM budgeting and reasoning-budget control",
   "license": "AGPL-3.0-or-later",
   "bin": {