@otto-code/brain 0.8.10 → 0.8.13

package/dist/service/serve.js

@@ -13,7 +13,7 @@ import { execFile, spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import http from "node:http";
 import https from "node:https";
-import { getCalibration, forModel, loadPersistedConfig, loadProfilesStore, put, putCalibration, saveBrainConfig, saveProfilesStore, } from "../config/index.js";
+import { getCalibrationForBudget, forModel, loadPersistedConfig, loadProfilesStore, put, putCalibration, saveBrainConfig, saveProfilesStore, } from "../config/index.js";
 import { resolveBrainPaths } from "../config/paths.js";
 import { query as queryGpu } from "../gpu.js";
 import { managedModelsDir, pickAutoModel, pickModel, scanModels } from "../models/index.js";
@@ -26,16 +26,19 @@ import * as archive from "../ops/archive.js";
 import { calibrate } from "../ops/calibrate.js";
 import { sweep } from "../ops/sweep.js";
 import * as bench from "../bench/index.js";
-import { createCpuSampler, sample as sampleSystem } from "../sysmon.js";
+import { createCpuSampler, sample as sampleSystem, slots as sampleSlots } from "../sysmon.js";
 import { createHostApi } from "./host-api.js";
 import { errorMessage } from "./http-util.js";
-import { createRouter, Telemetry } from "./router.js";
-import { BrainStatusPublisher } from "./status-events.js";
+import { createRouter, createSlotEraser, Telemetry } from "./router.js";
+import { Scheduler } from "./scheduler.js";
+import { ModelProcessPool } from "./process-pool.js";
+import { BrainLogPublisher, BrainStatusPublisher } from "./status-events.js";
 import { Supervisor } from "./supervisor.js";
 import * as tailscale from "./tailscale.js";
 import { CertManager, resolveTlsOptions } from "./tls.js";
 import { removePidFile, writePidFile } from "./pid-lock.js";
 import { createBrainRunLog } from "./run-log.js";
+import { formatBrainLog } from "./log-format.js";
 /** The effective config with secrets masked, for the `/__host/config` read. */
 function redactConfig(config) {
     return {
@@ -62,16 +65,77 @@ function collectEvals() {
     }
 }
 const REMOTE_JOB_RETENTION_MS = 5 * 60000;
+/** Model pulls only write the model store, so independent entries can transfer together. */
+export function canRunAlongsideModelPull(kind) {
+    return kind === "pull" || kind === "runtime-remove";
+}
+export function componentOnlyArgs(args, components) {
+    const separator = args.lastIndexOf("--");
+    const beforeTarget = separator === -1 ? args : args.slice(0, separator);
+    const target = separator === -1 ? [] : args.slice(separator);
+    const base = [];
+    for (let index = 0; index < beforeTarget.length; index += 1) {
+        const arg = beforeTarget[index];
+        if (arg === "--primary-only")
+            continue;
+        if (arg === "--component") {
+            index += 1;
+            continue;
+        }
+        base.push(arg);
+    }
+    return [
+        ...base,
+        "--components-only",
+        ...components.flatMap((component) => ["--component", component]),
+        ...target,
+    ];
+}
 class ServiceJobRunner {
-    constructor(onPullCompleted, runResidentJob) {
+    constructor(onPullCompleted, runResidentJob, scheduler, resolveTarget, log) {
         this.onPullCompleted = onPullCompleted;
         this.runResidentJob = runResidentJob;
+        this.scheduler = scheduler;
+        this.resolveTarget = resolveTarget;
+        this.log = log;
         this.jobs = new Map();
     }
-    start(kind, target, args) {
+    area(kind) {
+        return kind === "pull" || kind === "runtime-install" || kind === "runtime-remove"
+            ? "library"
+            : "model";
+    }
+    start(kind, target, args, pull) {
+        if (kind === "pull" && pull) {
+            const existing = [...this.jobs.values()].find((job) => job.kind === "pull" && job.status === "running" && job.pull?.entryKey === pull.entryKey);
+            if (existing?.pull) {
+                const components = pull.components.filter((component) => !existing.pull.components.has(component));
+                if (components.length > 0) {
+                    for (const component of components)
+                        existing.pull.components.add(component);
+                    existing.pull.queue.push({ args: componentOnlyArgs(args, components), components });
+                    existing.message = `Queued ${components.join(", ")}…`;
+                    this.log("library", `job ${existing.id} queued bundle components: ${components.join(", ")}`);
+                }
+                return this.publicJob(existing);
+            }
+        }
+        const isResidentOperation = kind === "calibrate" || kind === "sweep" || kind === "bench";
         const running = [...this.jobs.values()].find((job) => job.status === "running");
-        if (running)
-            throw new Error(`Another operation is already running (${running.label}).`);
+        const activeNonDownload = [...this.jobs.values()].find((job) => job.status === "running" && job.kind !== "pull");
+        // Resident operations join Scheduler instead of rejecting one another. It
+        // owns their turn order with API requests and performs every model swap.
+        const conflict = isResidentOperation
+            ? undefined
+            : canRunAlongsideModelPull(kind)
+                ? activeNonDownload
+                : running;
+        if (conflict)
+            throw new Error(`Another operation is already running (${conflict.label}).`);
+        const residentTarget = isResidentOperation ? this.resolveTarget(target) : null;
+        if (isResidentOperation && !residentTarget) {
+            throw new Error("No installed model is available for this operation.");
+        }
         const job = {
             id: `brainjob_${randomUUID()}`,
             kind,
@@ -89,21 +153,43 @@ class ServiceJobRunner {
             finishedAt: null,
             child: null,
             controller: null,
+            ...(kind === "pull" && pull
+                ? {
+                    pull: {
+                        entryKey: pull.entryKey,
+                        components: new Set(pull.components),
+                        queue: [],
+                    },
+                }
+                : {}),
         };
         this.jobs.set(job.id, job);
+        this.log(this.area(job.kind), `job ${job.id} started: ${job.label}`);
         if (kind === "calibrate" || kind === "sweep" || kind === "bench") {
+            const model = residentTarget;
             const controller = new AbortController();
             job.controller = controller;
-            void this.runResidentJob(kind, target, {
-                message: (value) => {
-                    if (job.status === "running")
-                        job.message = value.slice(-1000);
-                },
-                percent: (value) => {
-                    if (job.status === "running")
-                        job.percent = value;
+            job.queuePosition = this.scheduler.stats().queued + 1;
+            job.message = `Queued for ${model.displayName}`;
+            void this.scheduler
+                .submit(model, (supervisor) => controller.signal.aborted
+                ? Promise.reject(new Error("Operation canceled."))
+                : this.runResidentJob(supervisor, kind, model.id, {
+                    message: (value) => {
+                        if (job.status === "running")
+                            job.message = value.slice(-1000);
+                    },
+                    percent: (value) => {
+                        if (job.status === "running")
+                            job.percent = value;
+                    },
+                }, controller.signal), {
+                kind: kind === "bench" ? "benchmark" : kind,
+                onStart: () => {
+                    job.queuePosition = null;
+                    job.message = `${job.label} started`;
                 },
-            }, controller.signal)
+            })
                 .then(() => this.finish(job, "succeeded", null))
                 .catch((error) => this.finish(job, controller.signal.aborted ? "canceled" : "failed", errorMessage(error)));
             return this.publicJob(job);
@@ -113,20 +199,36 @@ class ServiceJobRunner {
         const entry = process.argv[1];
         if (!entry)
             throw new Error("The brain service has no CLI entry point.");
+        this.startChild(job, args, entry);
+        return this.publicJob(job);
+    }
+    startChild(job, args, entry) {
         const child = spawn(process.execPath, [entry, ...args], {
             cwd: process.cwd(),
             env: process.env,
-            stdio: ["ignore", "ignore", "pipe"],
+            stdio: ["ignore", "pipe", "pipe"],
             windowsHide: true,
         });
         job.child = child;
+        this.log(this.area(job.kind), `job ${job.id} spawned pid ${child.pid ?? "unknown"}: ${args.join(" ")}`);
+        child.stdout?.setEncoding("utf8");
         child.stderr?.setEncoding("utf8");
-        child.stderr?.on("data", (chunk) => this.ingestOutput(job, chunk));
+        child.stdout?.on("data", (chunk) => this.ingestOutput(job, "stdout", chunk));
+        child.stderr?.on("data", (chunk) => this.ingestOutput(job, "stderr", chunk));
         child.once("error", (error) => this.finish(job, "failed", error.message));
         child.once("close", (code) => {
             if (job.status !== "running")
                 return;
-            if (code === 0 && kind === "pull") {
+            job.child = null;
+            if (code === 0 && job.kind === "pull" && job.pull) {
+                const next = job.pull.queue.shift();
+                if (next) {
+                    job.message = `Queued ${next.components.join(", ")}…`;
+                    this.startChild(job, next.args, entry);
+                    return;
+                }
+            }
+            if (code === 0 && job.kind === "pull") {
                 try {
                     // Downloads happen in a child process, but inventory is served from
                     // this process's in-memory scan. Reconcile before reporting success
@@ -140,9 +242,8 @@ class ServiceJobRunner {
             }
             this.finish(job, code === 0 ? "succeeded" : "failed", code === 0 ? null : (job.message ?? `Exited with code ${code}.`));
         });
-        return this.publicJob(job);
     }
-    async query(args) {
+    async query(args, area = "library") {
         const entry = process.argv[1];
         if (!entry)
             throw new Error("The brain service has no CLI entry point.");
@@ -157,10 +258,21 @@ class ServiceJobRunner {
             let err = "";
             child.stdout?.setEncoding("utf8");
             child.stderr?.setEncoding("utf8");
-            child.stdout?.on("data", (chunk) => (out += chunk));
-            child.stderr?.on("data", (chunk) => (err += chunk));
-            child.once("error", reject);
+            this.log(area, `query started: ${args.join(" ")}`);
+            child.stdout?.on("data", (chunk) => {
+                out += chunk;
+                this.logOutput(area, "query stdout", chunk);
+            });
+            child.stderr?.on("data", (chunk) => {
+                err += chunk;
+                this.logOutput(area, "query stderr", chunk);
+            });
+            child.once("error", (error) => {
+                this.log(area, `query failed to start: ${error.message}`);
+                reject(error);
+            });
             child.once("close", (code) => {
+                this.log(area, `query exited with code ${code}`);
                 if (code !== 0)
                     return reject(new Error(err.trim() || `Exited with code ${code}.`));
                 try {
@@ -198,10 +310,11 @@ class ServiceJobRunner {
         else {
             child.kill("SIGTERM");
         }
+        this.log(this.area(job.kind), `canceling job ${job.id}`);
         this.finish(job, "canceled", "Canceled.");
         return this.list();
     }
-    ingestOutput(job, chunk) {
+    ingestOutput(job, source, chunk) {
         for (const line of chunk
             .split(/[\r\n]+/u)
             .map((value) => value.trim())
@@ -209,6 +322,7 @@ class ServiceJobRunner {
             const progress = /(\d{1,3})\s*%/u.exec(line);
             if (progress)
                 job.percent = Math.max(0, Math.min(100, Number(progress[1])));
+            this.log(this.area(job.kind), `job ${job.id} ${source}: ${line}`);
             // The final JSON result is not a useful status label. Keep progress and
             // actionable text instead, so a failed bundle pull tells the user why.
             if (line !== "[" && !/^[\]{}",]+$/u.test(line))
@@ -225,8 +339,17 @@ class ServiceJobRunner {
         job.finishedAt = new Date().toISOString();
         if (status === "succeeded")
             job.percent = 100;
+        this.log(this.area(job.kind), `job ${job.id} ${status}${error ? `: ${error}` : ""}`);
     }
-    publicJob({ child: _child, controller: _controller, ...job }) {
+    logOutput(area, source, chunk) {
+        for (const line of chunk
+            .split(/[\r\n]+/u)
+            .map((entry) => entry.trim())
+            .filter(Boolean)) {
+            this.log(area, `${source}: ${line}`);
+        }
+    }
+    publicJob({ child: _child, controller: _controller, pull: _pull, ...job }) {
         return job;
     }
 }
@@ -272,9 +395,16 @@ function withAuth(inner, token) {
 }
 export async function startService({ config, modelNeedle, env = process.env, onLog = () => { }, }) {
     const runLog = createBrainRunLog(env);
-    const log = (line) => {
-        runLog.write(line);
-        onLog(line);
+    const logEvents = new BrainLogPublisher();
+    const log = (area, message) => {
+        const line = formatBrainLog(area, message);
+        for (const entry of runLog.write(line)) {
+            logEvents.publish(entry);
+            // The daemon also captures this foreground child's stderr before the
+            // management listener exists. Give it the exact durable entry, rather
+            // than a second un-timestamped rendering of the same event.
+            onLog(entry);
+        }
     };
     // The management API must be useful before any setup exists: the Brain page
     // is where the owner downloads both a runtime and their first model. Keep the
@@ -331,7 +461,7 @@ export async function startService({ config, modelNeedle, env = process.env, onL
             // service down. An explicit CLI selection remains an actionable error.
             if (modelNeedle)
                 throw error;
-            log(`note: ${error instanceof Error ? error.message : "configured model is unavailable"}`);
+            log("server", `note: ${error instanceof Error ? error.message : "configured model is unavailable"}`);
         }
     }
     let profile = model ? forModel(store, model, config.defaults) : null;
@@ -340,66 +470,69 @@ export async function startService({ config, modelNeedle, env = process.env, onL
         const fit = vram.fitToBudget({
             model,
             profile,
-            calibration: getCalibration(store, model, profile),
+            calibration: getCalibrationForBudget(store, model, profile),
             totalVramBytes: gpu.totalBytes,
         });
         if (!fit.adjusted && !fit.budget.fits) {
             // Starting the host is what exposes the Library and model profile UI.
             // An automatic startup candidate that cannot load must therefore leave
             // the host alive and unloaded, not make the only recovery surface vanish.
-            log(`note: not loading ${model.displayName}: ${fit.reason ?? "does not fit in available VRAM"}`);
+            log("model", `note: not loading ${model.displayName}: ${fit.reason ?? "does not fit in available VRAM"}`);
             model = null;
             profile = null;
         }
         else {
             if (fit.adjusted && fit.reason)
-                log(`note: ${fit.reason}`);
+                log("model", `note: ${fit.reason}`);
             profile = fit.profile;
         }
     }
     const telemetry = new Telemetry();
-    const supervisor = new Supervisor({ runtime, paths, getProfilesStore: () => store });
-    supervisor.on("log", (line) => {
-        runLog.write(line);
-        if (/error|failed|warn/i.test(line))
-            onLog(line);
+    const supervisor = new Supervisor({
+        runtime,
+        paths,
+        getProfilesStore: () => store,
+        logVerbosity: config.runtime.logVerbosity,
     });
-    supervisor.on("crashed", (error) => runLog.write(`FATAL ${error}`));
-    // Serialize model switches: the router queues request-driven switches, but the
-    // config path (POST /__host/config) calls loadModel directly. Chaining here
-    // guarantees two switches (e.g. a config write racing a request-driven switch)
-    // can never overlap two supervisor.start() calls, whichever caller triggers them.
-    let modelSwitchChain = Promise.resolve();
-    const loadModelUnsafe = async (target) => {
+    supervisor.on("log", (line) => log("server", line));
+    supervisor.on("crashed", (error) => log("model", `FATAL ${error}`));
+    const loadModelInto = async (resident, target, reservedElsewhereBytes) => {
         // A runtime can be installed from the Library tab after this service starts.
         // Resolve it at load time so the user does not have to restart the brain.
-        supervisor.runtime = resolveRuntime(config, env);
-        if (!supervisor.runtime) {
+        resident.runtime = resolveRuntime(config, env);
+        if (!resident.runtime) {
             throw new Error("no llama.cpp runtime available; install one from the Library tab");
         }
         const gpuInfo = await queryGpu();
         let fitProfile = forModel(store, target, config.defaults);
+        let reservationBytes = 0;
         if (gpuInfo) {
             const fit = vram.fitToBudget({
                 model: target,
                 profile: fitProfile,
-                calibration: getCalibration(store, target, fitProfile),
-                totalVramBytes: gpuInfo.totalBytes,
+                calibration: getCalibrationForBudget(store, target, fitProfile),
+                // Every resident process keeps its complete budget reserved. Fit this
+                // process against the capacity left after those independent allocations.
+                totalVramBytes: Math.max(0, gpuInfo.totalBytes - reservedElsewhereBytes),
             });
             if (!fit.adjusted && !fit.budget.fits)
                 throw new Error(fit.reason ?? "does not fit");
             fitProfile = fit.profile;
+            reservationBytes = fit.budget.totalBytes;
         }
-        await supervisor.start(target, fitProfile);
+        await resident.start(target, fitProfile);
         delete store.pendingReloadModelIds[target.id];
         store.lastModelId = target.id;
         saveProfilesStore(store, paths);
+        return reservationBytes;
     };
-    const loadModel = (target) => {
-        const run = modelSwitchChain.then(() => loadModelUnsafe(target));
-        // Keep the chain alive even if this switch fails, so a later switch still runs.
-        modelSwitchChain = run.catch(() => undefined);
-        return run;
+    let processPool = null;
+    const loadModel = async (target) => {
+        if (processPool) {
+            await processPool.preload(target);
+            return;
+        }
+        await loadModelInto(supervisor, target, 0);
     };
     // Apply an editable config patch from POST /__host/config: mutate the live
     // config (so the lock/default getters and future starts see it), persist it to
@@ -425,15 +558,42 @@ export async function startService({ config, modelNeedle, env = process.env, onL
                 throw new Error("lockModel must be a boolean");
             config.lockModel = p.lockModel;
         }
+        if ("maxLoadedModels" in p) {
+            const next = p.maxLoadedModels;
+            if (!Number.isInteger(next) || next < 1 || next > 16) {
+                throw new Error("maxLoadedModels must be an integer from 1 to 16");
+            }
+            config.maxLoadedModels = next;
+        }
+        if ("lockedModels" in p) {
+            const next = p.lockedModels;
+            if (!Array.isArray(next) || !next.every((value) => typeof value === "string")) {
+                throw new Error("lockedModels must be an array of model ids");
+            }
+            config.lockedModels = [...new Set(next)].slice(0, config.maxLoadedModels);
+        }
+        if (config.lockedModels.length > config.maxLoadedModels) {
+            config.lockedModels = config.lockedModels.slice(0, config.maxLoadedModels);
+        }
         const persisted = loadPersistedConfig(paths);
         persisted.defaultModel = config.defaultModel;
         persisted.lockModel = config.lockModel;
+        persisted.maxLoadedModels = config.maxLoadedModels;
+        persisted.lockedModels = config.lockedModels;
         saveBrainConfig(persisted, paths);
+        await processPool?.configure(config.maxLoadedModels);
         if (switchTo) {
             const target = catalog.find((m) => m.displayName === switchTo || m.id === switchTo);
             if (target)
                 await loadModel(target);
         }
+        if (config.lockModel) {
+            for (const id of config.lockedModels) {
+                const target = catalog.find((candidate) => candidate.id === id || candidate.displayName === id);
+                if (target)
+                    await loadModel(target);
+            }
+        }
         return redactConfig(config);
     };
     // One CPU sampler for the lifetime of the service: it reports a busy fraction
@@ -444,7 +604,7 @@ export async function startService({ config, modelNeedle, env = process.env, onL
     // /__host/events. One instance, so `capabilities.events` and the stream can
     // never disagree about whether this brain publishes.
     const statusEvents = new BrainStatusPublisher();
-    const runResidentJob = async (kind, target, update, signal) => {
+    const runResidentJob = async (supervisor, kind, target, update, signal) => {
         const ensureActive = () => {
             if (signal.aborted)
                 throw new Error("Operation canceled.");
@@ -455,13 +615,6 @@ export async function startService({ config, modelNeedle, env = process.env, onL
             : null;
         if (!targetModel)
             throw new Error("No installed model is available for this operation.");
-        const restoreModel = supervisor.model;
-        const restoreProfile = supervisor.profile;
-        const restore = async () => {
-            if (restoreModel && restoreProfile && !signal.aborted) {
-                await supervisor.start(restoreModel, restoreProfile, { preserveLogs: true });
-            }
-        };
         if (kind === "calibrate") {
             const runtime = supervisor.runtime ?? resolveRuntime(config, env);
             if (!runtime)
@@ -469,34 +622,29 @@ export async function startService({ config, modelNeedle, env = process.env, onL
             const profile = forModel(store, targetModel, config.defaults);
             update.message(`Calibrating ${targetModel.displayName}`);
             supervisor.recordLog(`operation calibrate: ${targetModel.displayName}`);
-            try {
-                const measurement = await calibrate({
-                    runtime,
-                    model: targetModel,
-                    profile,
-                    supervisor,
-                    onProgress: (event) => {
-                        ensureActive();
-                        const message = event.phase === "loading"
-                            ? `Calibrating ${event.contextSize.toLocaleString()} context`
-                            : event.phase === "measured"
-                                ? `Measured ${event.contextSize.toLocaleString()} context`
-                                : (event.reason ??
-                                    event.error ??
-                                    `Skipped ${event.contextSize.toLocaleString()} context`);
-                        update.message(message);
-                        supervisor.recordLog(`operation calibrate: ${message}`);
-                    },
-                });
-                ensureActive();
-                putCalibration(store, targetModel, profile, measurement);
-                saveProfilesStore(store, paths);
-                update.percent(100);
-                supervisor.recordLog(`operation calibrate: saved measurement for ${targetModel.displayName}`);
-            }
-            finally {
-                await restore();
-            }
+            const measurement = await calibrate({
+                runtime,
+                model: targetModel,
+                profile,
+                supervisor,
+                onProgress: (event) => {
+                    ensureActive();
+                    const message = event.phase === "loading"
+                        ? `Calibrating ${event.contextSize.toLocaleString()} context`
+                        : event.phase === "measured"
+                            ? `Measured ${event.contextSize.toLocaleString()} context`
+                            : (event.reason ??
+                                event.error ??
+                                `Skipped ${event.contextSize.toLocaleString()} context`);
+                    update.message(message);
+                    supervisor.recordLog(`operation calibrate: ${message}`);
+                },
+            });
+            ensureActive();
+            putCalibration(store, targetModel, profile, measurement);
+            saveProfilesStore(store, paths);
+            update.percent(100);
+            supervisor.recordLog(`operation calibrate: saved measurement for ${targetModel.displayName}`);
             return;
         }
         if (kind === "sweep") {
@@ -506,47 +654,42 @@ export async function startService({ config, modelNeedle, env = process.env, onL
             const profile = forModel(store, targetModel, config.defaults);
             update.message(`Sweeping ${targetModel.displayName}`);
             supervisor.recordLog(`operation sweep: ${targetModel.displayName}`);
-            try {
-                const report = await sweep({
-                    runtime,
-                    model: targetModel,
-                    profile,
-                    supervisor,
-                    onProgress: (event) => {
-                        ensureActive();
-                        const message = event.phase === "loading"
-                            ? `Budget ${event.budget}: loading`
-                            : event.phase === "generating"
-                                ? `Budget ${event.budget}: generating`
-                                : event.phase === "done"
-                                    ? `Budget ${event.budget}: complete`
-                                    : `Budget ${event.budget}: ${event.error ?? "failed"}`;
-                        update.message(message);
-                        supervisor.recordLog(`operation sweep: ${message}`);
-                    },
-                });
-                ensureActive();
-                if (report.recommended !== null) {
-                    profile.reasoningBudget = report.recommended;
-                    put(store, targetModel, profile);
-                    saveProfilesStore(store, paths);
-                    supervisor.recordLog(`operation sweep: saved budget ${report.recommended}`);
-                }
-                update.percent(100);
-            }
-            finally {
-                await restore();
+            const report = await sweep({
+                runtime,
+                model: targetModel,
+                profile,
+                supervisor,
+                onProgress: (event) => {
+                    ensureActive();
+                    const message = event.phase === "loading"
+                        ? `Budget ${event.budget}: loading`
+                        : event.phase === "generating"
+                            ? `Budget ${event.budget}: generating`
+                            : event.phase === "done"
+                                ? `Budget ${event.budget}: complete`
+                                : `Budget ${event.budget}: ${event.error ?? "failed"}`;
+                    update.message(message);
+                    supervisor.recordLog(`operation sweep: ${message}`);
+                },
+            });
+            ensureActive();
+            if (report.recommended !== null) {
+                profile.reasoningBudget = report.recommended;
+                put(store, targetModel, profile);
+                saveProfilesStore(store, paths);
+                supervisor.recordLog(`operation sweep: saved budget ${report.recommended}`);
             }
+            update.percent(100);
             return;
         }
         update.message(`Benchmarking ${targetModel.displayName}`);
         supervisor.recordLog(`operation benchmark: ${targetModel.displayName}`);
-        await loadModel(targetModel);
+        // Scheduler loaded this exact model before admitting the exclusive turn.
         ensureActive();
         supervisor.recordLog(`operation benchmark: resident model ready`);
         const profile = supervisor.profile ?? forModel(store, targetModel, config.defaults);
         const gpuInfo = await queryGpu();
-        const calibration = getCalibration(store, targetModel, profile);
+        const calibration = getCalibrationForBudget(store, targetModel, profile);
         const fit = gpuInfo
             ? vram.fitToBudget({
                 model: targetModel,
@@ -590,7 +733,58 @@ export async function startService({ config, modelNeedle, env = process.env, onL
         update.percent(100);
         supervisor.recordLog(`operation benchmark: saved result for ${targetModel.displayName}`);
     };
-    const jobs = new ServiceJobRunner(rescanCatalog, runResidentJob);
+    const attachSupervisorLogs = (resident) => {
+        if (resident === supervisor)
+            return;
+        resident.on("log", (line) => log("server", line));
+        resident.on("crashed", (error) => log("model", `FATAL ${error}`));
+        resident.on("state", () => statusEvents.notify());
+    };
+    const createPooledSupervisor = (index) => {
+        const resident = new Supervisor({
+            runtime: resolveRuntime(config, env),
+            internalPort: supervisor.internalPort + index,
+            paths,
+            getProfilesStore: () => store,
+            logVerbosity: config.runtime.logVerbosity,
+        });
+        attachSupervisorLogs(resident);
+        return resident;
+    };
+    const createResidentScheduler = (resident, loadResidentModel, onChange) => new Scheduler({
+        supervisor: resident,
+        loadModel: loadResidentModel,
+        logger: (message) => log("api", `WARN ${message}`),
+        onChange,
+        freeSlots: async () => {
+            if (resident.state !== "ready")
+                return null;
+            try {
+                const slots = await sampleSlots({ host: resident.host, port: resident.internalPort });
+                return slots ? { idle: slots.idle, ids: slots.idleSlots } : null;
+            }
+            catch {
+                return null;
+            }
+        },
+        eraseSlot: createSlotEraser(resident.host, resident.internalPort),
+    });
+    const scheduler = new ModelProcessPool({
+        initialSupervisor: supervisor,
+        maxModels: config.maxLoadedModels,
+        createSupervisor: createPooledSupervisor,
+        createScheduler: createResidentScheduler,
+        loadModel: loadModelInto,
+        logger: (message) => log("model", message),
+        onChange: () => statusEvents.notify(),
+    });
+    processPool = scheduler;
+    const jobs = new ServiceJobRunner(rescanCatalog, runResidentJob, scheduler, (target) => {
+        const modelId = target ?? scheduler.residentSupervisors()[0]?.model?.id ?? store.lastModelId ?? null;
+        return modelId
+            ? (catalog.find((candidate) => candidate.id === modelId || candidate.displayName === modelId) ?? null)
+            : null;
+    }, log);
     // Assigned once `stop` exists below. This indirection lets the management API
     // answer a remote restart request before closing its own socket.
     let requestRestart = () => { };
@@ -611,6 +805,8 @@ export async function startService({ config, modelNeedle, env = process.env, onL
             }
         },
         loadModel,
+        unloadModels: () => scheduler.unload(),
+        scheduler,
         // The same gate as POST /__host/config. Deleting someone's model files over
         // the network is strictly more dangerous than changing their default model,
         // so it does not get a weaker one.
@@ -618,13 +814,19 @@ export async function startService({ config, modelNeedle, env = process.env, onL
         getModelsDir: () => managedModelsDir(config, env),
         sampleResources: () => sampleSystem(cpuSampler, { host: supervisor.host, port: supervisor.internalPort }),
         statusEvents,
+        logEvents,
         jobs,
+        runLog,
         restart: () => requestRestart(),
+        log,
     });
     const handler = withAuth(createRouter({
         supervisor,
         telemetry,
-        logger: { warn: (m) => log(`WARN ${m}`) },
+        logger: {
+            info: (m) => log("api", m),
+            warn: (m) => log("api", `WARN ${m}`),
+        },
         getCatalog: () => catalog,
         loadModel,
         version: resolveVersion(),
@@ -632,6 +834,7 @@ export async function startService({ config, modelNeedle, env = process.env, onL
         getEvals: collectEvals,
         getLockModel: () => config.lockModel,
         getDefaultModel: () => config.defaultModel,
+        getLockedModels: () => config.lockedModels,
         applyConfigPatch,
         getAllowConfigWrite: allowWrite,
         hostApi,
@@ -639,6 +842,7 @@ export async function startService({ config, modelNeedle, env = process.env, onL
         // time in parallel: the shared rate tracker needs one ordered timeline.
         getResources: () => sampleSystem(cpuSampler),
         statusEvents,
+        scheduler,
     }), authToken);
     // TLS terminates in-process when configured; otherwise plain HTTP. The cert
     // manager issues/generates the first keypair before we listen, and hot-swaps
@@ -646,12 +850,18 @@ export async function startService({ config, modelNeedle, env = process.env, onL
     let certManager = null;
     let server;
     if (tlsOptions) {
-        certManager = new CertManager({ ...tlsOptions, logger: { info: onLog, warn: onLog } });
+        certManager = new CertManager({
+            ...tlsOptions,
+            logger: {
+                info: (message) => log("server", message),
+                warn: (message) => log("server", message),
+            },
+        });
         const secure = await certManager.load();
         const httpsServer = https.createServer({ key: secure.key, cert: secure.cert }, handler);
         certManager.on("renewed", (pair) => {
             httpsServer.setSecureContext({ key: pair.key, cert: pair.cert });
-            onLog("note: TLS certificate hot-swapped");
+            log("server", "note: TLS certificate hot-swapped");
         });
         server = httpsServer;
     }
@@ -660,22 +870,38 @@ export async function startService({ config, modelNeedle, env = process.env, onL
     }
     server.keepAliveTimeout = 75000;
     server.requestTimeout = 0;
-    await new Promise((resolve, reject) => {
-        server.once("error", reject);
-        server.listen(port, bindHost, resolve);
-    });
+    try {
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(port, bindHost, resolve);
+        });
+    }
+    catch (error) {
+        // A listener can fail before the host API exists, so this cannot travel
+        // through the host's own SSE endpoint. It still belongs to this service
+        // session: the foreground daemon child relays this timestamped entry until
+        // that endpoint becomes available.
+        log("server", `FATAL Brain service startup failed: ${errorMessage(error)}`);
+        throw error;
+    }
     certManager?.start();
-    if (model && profile && runtime) {
-        await supervisor.start(model, profile);
-        delete store.pendingReloadModelIds[model.id];
-        store.lastModelId = model.id;
-        saveProfilesStore(store, paths);
+    if (runtime && config.lockModel && config.lockedModels.length > 0) {
+        for (const lockedId of config.lockedModels.slice(0, config.maxLoadedModels)) {
+            const locked = catalog.find((candidate) => candidate.id === lockedId || candidate.displayName === lockedId);
+            if (locked)
+                await scheduler.preload(locked);
+        }
+    }
+    else if (model && profile && runtime) {
+        // Default model remains one auto-load. Additional process slots stay empty
+        // until a request names another model.
+        await scheduler.preload(model);
     }
     else if (!runtime) {
-        log("ready: no llama.cpp runtime installed; use the Library tab to download one");
+        log("server", "ready: no llama.cpp runtime installed; use the Library tab to download one");
     }
     else {
-        log("ready: no model installed; use the Library tab to download one");
+        log("server", "ready: no model installed; use the Library tab to download one");
     }
     writePidFile({
         pid: process.pid,
@@ -685,14 +911,22 @@ export async function startService({ config, modelNeedle, env = process.env, onL
         secure: Boolean(tlsOptions),
         displayHost,
     }, env);
-    log(`ready: ${supervisor.model?.displayName ?? "no model loaded"} on ${bindHost}:${port}; run log ${runLog.path}`);
+    log("server", `ready: ${scheduler
+        .residentSupervisors()
+        .map((resident) => resident.model?.displayName)
+        .filter(Boolean)
+        .join(", ") || "no model loaded"} on ${bindHost}:${port}; run log ${runLog.path}`);
     const stop = async () => {
         certManager?.stop();
-        log("Brain service stopping");
+        log("server", "Brain service stopping");
+        await scheduler.stop();
+        // Publish the terminal outcome before closing the SSE responses below.
+        // Once the listener is closed, the daemon can still report the child exit,
+        // but it cannot receive this service-owned, durable session-log entry.
+        log("server", "Brain service stopped");
         // Before server.close(), which waits on open connections: a subscribed
         // daemon holds an SSE response open indefinitely by design.
         statusEvents.close();
-        await supervisor.stop();
         server.closeIdleConnections?.();
         await new Promise((resolve) => server.close(() => resolve()));
         removePidFile(env);