@bendyline/gezel-inference 1.0.1 → 1.0.3

package/dist/providers/llama-cpp/build-provider.js

@@ -1,27 +1,30 @@
 import { availableParallelism } from 'node:os';
 import { delimiter, dirname, join } from 'node:path';
-import { DEFAULT_LOCAL_ENGINE_IDLE_TIMEOUT_MS, createLogger, estimateLlamaCppResidentBytes, } from '@bendyline/gezel';
-import { recordLlamaQuarantine } from '@bendyline/gezel/native';
+import { DEFAULT_LOCAL_ENGINE_IDLE_TIMEOUT_MS, createLogger, estimateLlamaCppResidentBytes, llamaCppBackendExclusion, llamaCppBackendLabel, } from '@bendyline/gezel';
+import { LLAMA_QUARANTINE_STRIKES, clearLlamaStartupStrikes, recordLlamaStartupCrash, unrunnableBuildExit, } from '@bendyline/gezel/native';
 import { gezelPaths } from '@bendyline/gezel/paths';
 import { mmprojBudgetBytes, nativeVisionEnabledFor } from '../../chat/vision-capability.js';
 import { effectiveEngineRelease, isEnginePinned } from '../../engines/native-manifest.js';
 import { engineInstallPhase } from '../../engines/registry.js';
 import { localDeviceSettingsLabel, noModelYetMessage, notReadyError, } from '../active-install-message.js';
 import { resolveCatalogLlamaCppEngineConfig, resolveCatalogReasoningBudget, } from '../catalog-model-config.js';
-import { CapacityDeniedError, NOT_ENOUGH_MEMORY_MESSAGE, autoKvCacheMaxBytes, availableSystemRamBytes, formatContextCapacityDenial, minViableLocalContextTokens, planAdaptiveContextGrowth, pressureIdleGraceMs, resolveLlamaCppContextRequirement, } from '../native/capacity-broker.js';
+import { CapacityDeniedError, NOT_ENOUGH_MEMORY_MESSAGE, availableSystemRamBytes, formatContextCapacityDenial, minViableLocalContextTokens, planAdaptiveContextGrowth, pressureIdleGraceMs, resolveLlamaCppContextRequirement, } from '../native/capacity-broker.js';
 import { measureAvailableGpuBytes } from '../native/device-capacity.js';
 import { engineApiKey, withEngineApiKey } from '../native/engine-api-key.js';
 import { makeEngineKey } from '../native/engine-key.js';
 import { pickFreePort } from '../native/port.js';
 import { NativeEngineSupervisor } from '../native/supervisor.js';
 import { patientFetch } from '../patient-fetch.js';
+import { currentLlamaCppBackend, noteGpuStartup, noteHostOutOfMemory } from './backend-health.js';
+import { adoptLlamaFallback } from './backend-quarantine.js';
 import { lastArgValue, readLlamaCppBuildMetadata } from './build-metadata.js';
 import { matchNvidiaRuntimeDevice, maxGpuVramBytes, pickBestGpuDevice, probeLlamaDevices, probeNvidiaRuntimeDevices, } from './devices.js';
 import { buildLlamaCppEngineArgs } from './engine-flags.js';
 import { readGgufSummaryAsync } from './gguf-metadata-async.js';
 import { effectiveLazyTensorBytes } from './gguf-metadata.js';
+import { GpuStartupWatch } from './gpu-startup-watch.js';
 import { isGemmaModel, planLlamaCppKv, resolveLlamaCppKvCacheType, } from './kv-cache-type.js';
-import { degradeDenseFfnOffloadDecision, degradeMoeOffloadDecision, estimateExactPerSlotKvBytesF16, estimateKvReserveBytes, estimateWindowedKvLinearization, fitsSwaFullInFastMemory, planDenseFfnOffload, planMoeOffload, } from './offload-planner.js';
+import { degradeDenseFfnOffloadDecision, degradeMoeOffloadDecision, estimateExactPerSlotKvBytesF16, estimateKvReserveBytes, estimateWindowedKvLinearization, planDenseFfnOffload, planMoeOffload, shedSlotsForGpuResidency, } from './offload-planner.js';
 import { LlamaCppProvider } from './provider.js';
 import { reasoningLaunchOverridesFromEnv } from './reasoning-launch.js';
 import { resolveSpecDraft } from './spec-draft.js';
@@ -69,6 +72,15 @@ export async function buildLlamaCppProvider(opts) {
         ? undefined
         : (process.env.GEZEL_LLAMA_SERVER_URL ?? config.llamaCppBaseUrl);
     const binary = process.env.GEZEL_LLAMA_SERVER_BIN;
+    // Read together with the binary: after a quarantine the env points at the
+    // fallback build, and a crash of THIS build must be charged to its own
+    // backend, not to whatever the env names by then.
+    const binaryBackend = process.env.GEZEL_LLAMA_SERVER_BACKEND;
+    // What the latest startup crash did to this build's standing, for the error
+    // the failed start raises. `onExit` runs before `ensureRunning` rejects.
+    let lastStartupCrash = null;
+    // Fresh for each launch: whether this start of a GPU build got its GPU.
+    let gpuWatch = null;
     // Preservation is a two-sided contract: launch llama-server with the
     // explicit preserve/no-preserve flag AND replay captured
     // `reasoning_content` only in the preserve case. v0.4.0 changed the server
@@ -269,6 +281,18 @@ export async function buildLlamaCppProvider(opts) {
         }
         throw notReadyError(noModelYetMessage('Local model', activeLlamaInstall(opts.llamaCppModels)), 'model-not-ready');
     }
+    // Install refuses an excluded backend; this catches a model installed
+    // before the exclusion was authored, or copied in by hand.
+    if (modelCatalogInfo && opts.catalog) {
+        const engineBackend = binaryBackend ?? currentLlamaCppBackend();
+        const detail = await opts.catalog.get('chat-model', modelCatalogInfo.id).catch(() => null);
+        const excluded = llamaCppBackendExclusion(detail?.manifest.kind === 'chat-model' ? detail.manifest.llamaCpp : undefined, engineBackend);
+        if (excluded && engineBackend) {
+            const err = new Error(`Local model: ${modelCatalogInfo.name} cannot run on the ${llamaCppBackendLabel(engineBackend)} llama.cpp engine. ${excluded} Pick another local model in Settings → ${localDeviceSettingsLabel()}.`);
+            err.isActionable = true;
+            throw err;
+        }
+    }
     // Per Phase 0 measurements on a cold Mac: Metal library compile is
     // ~14s and model load adds model-size-dependent time. Default
     // startupTimeoutMs is 60s which squeaks through for a 7B on a warm
@@ -323,13 +347,6 @@ export async function buildLlamaCppProvider(opts) {
     // path still clamps to the native train context.
     const explicitCtx = envNumCtx ?? perModelCtxOverride ?? config.llamaCppNumCtx;
     const hostFloorTokens = minViableLocalContextTokens();
-    // A per-model override below the host floor is deliberate user intent —
-    // lower the admission floor to the override instead of silently raising
-    // the request back to 64K. Env / machine-wide values keep their
-    // historical floor semantics.
-    const minViableTokens = perModelCtxOverride !== undefined && explicitCtx === perModelCtxOverride
-        ? Math.min(hostFloorTokens, perModelCtxOverride)
-        : hostFloorTokens;
     const contextRequirement = resolveLlamaCppContextRequirement({
         modelContextWindow: modelCatalogInfo?.contextWindow,
         ...(explicitCtx !== undefined ? { explicitContextWindow: explicitCtx } : {}),
@@ -338,7 +355,7 @@ export async function buildLlamaCppProvider(opts) {
             ? { manifestContextSize: manifestEngineConfig.contextSize }
             : {}),
         contextSizing: config.llamaCppContextSizing ?? 'adaptive',
-        minViableContextTokens: minViableTokens,
+        minViableContextTokens: hostFloorTokens,
     });
     // `let`: RAM-aware admission below may lower this (but never below the
     // model-aware minimum) before anything launch-visible consumes it.
@@ -621,18 +638,15 @@ export async function buildLlamaCppProvider(opts) {
     // back to the engine's own `--fit` / `-ngl auto`.
     let offloadDecision;
     let offloadBlockCount;
-    // Whether weights + full-attention KV at the requested context fit the
-    // fast-memory pool — VRAM on a discrete GPU. Gates the Gemma
-    // `--swa-full` auto-default (see `EngineFlagInput.swaFullAutoFits`). Set
-    // false to keep the full context on the windowed cache when Full would
-    // spill or require a slot/context reduction; undefined means it fits or
-    // the exact decision could not be computed.
-    let swaFullAutoFits;
     // Broker-ledger reservation for this launch: resident weights + the KV
     // the engine will actually allocate at the granted window and cache
     // mode. Undefined when the GGUF is unreadable — the pool builder then
     // falls back to the legacy weights-multiplier reservation.
     let plannedReservationBytes;
+    // What prices that reservation, kept for the out-of-memory ladder: when it
+    // drops a slot, the relaunch is charged for the KV it actually allocates.
+    let reservationKvFor;
+    let reservationResidentBytes;
     // Graphics memory the MoE offload plan puts on the card. Device admission
     // charges this rather than the whole card; undefined keeps the old charge.
     let plannedGpuBytes;
@@ -709,21 +723,16 @@ export async function buildLlamaCppProvider(opts) {
             // under GEZEL_LLAMA_NUM_CTX — eval runs lift ceilings deliberately
             // and accept the memory consequences.
             //
-            // The fit verdict additionally gates the Gemma `--swa-full`
-            // auto-default, in BOTH branches: the full cache is a cache-operation
-            // performance trade, while the context window is capability. Auto
-            // therefore requires resident weights + exact full KV to fit the fast
-            // pool (VRAM on a discrete GPU); otherwise it keeps the full window on
-            // the windowed cache. Shared-KV layers and SWA-specific head dimensions
-            // are load-bearing here — E4B owns only 24 KV caches for 42 logical
-            // layers, and pricing all 42 at global dimensions overstated its two-slot
-            // 64K KV allocation as 21 GiB instead of llama.cpp's actual 7 GiB.
-            // When the windowed cache is what will run, the launch is NOT left
-            // ungated: admission re-plans with the windowed-KV linearization
-            // (SWA layers = fixed window-capped bytes, global layers = the only
-            // per-token cost), so a host too small even for the windowed cache
-            // still denies or clamps honestly instead of OOMing one machine
-            // class below the 2026-08-05 incident.
+            // A sliding-window model runs llama.cpp's windowed cache unless
+            // `swaFull` is pinned, and admission prices what runs: it re-plans
+            // with the windowed-KV linearization (SWA layers = fixed window-capped
+            // bytes, global layers = the only per-token cost), so a host too small
+            // even for the windowed cache still denies or clamps honestly instead
+            // of OOMing one machine class below the 2026-08-05 incident.
+            // Shared-KV layers and SWA-specific head dimensions are load-bearing
+            // in that math — E4B owns only 24 KV caches for 42 logical layers, and
+            // pricing all 42 at global dimensions overstated its two-slot 64K KV
+            // allocation as 21 GiB instead of llama.cpp's actual 7 GiB.
             {
                 const REFERENCE_CTX = 4096;
                 const exactKvAtReference = estimateKvReserveBytes({
@@ -769,23 +778,14 @@ export async function buildLlamaCppProvider(opts) {
                         ? {
                             unifiedMemory: liveMemory.gpuMemoryKind === 'integrated' ||
                                 liveMemory.gpuMemoryKind === 'unified',
+                            reservedGpuBytes: liveMemory.gpuReservedBytes ?? null,
+                            gpuAddressableBytes: liveMemory.gpuAddressableBytes ?? null,
                         }
                         : {}),
                 });
                 const fastBudgetBytes = brokerSnap?.enforced
                     ? (opts.broker?.fastBudgetBytes() ?? liveBudget.fastBytes)
                     : liveBudget.fastBytes;
-                const fullKvBytesAtRequested = exactKvAtReference !== undefined
-                    ? (exactKvAtReference / REFERENCE_CTX) * effectiveNumCtx * slots
-                    : undefined;
-                const fullCacheFitsFastMemory = fullKvBytesAtRequested !== undefined
-                    ? fitsSwaFullInFastMemory({
-                        residentWeightsBytes: residentBytes,
-                        fullKvBytes: fullKvBytesAtRequested,
-                        fastBudgetBytes,
-                        committedOtherBytes,
-                    })
-                    : undefined;
                 const admission = planCtxTokensForMemory({
                     requestedPerTurnCtxTokens: effectiveNumCtx,
                     slots,
@@ -797,25 +797,13 @@ export async function buildLlamaCppProvider(opts) {
                     freeSystemRamBytes: availableSystemRamBytes(),
                     vramBytes: liveBudget.vramBytes,
                 });
+                // `--swa-full` runs only when pinned; every other launch of a
+                // sliding-window model gets llama.cpp's windowed cache.
                 const explicitSwaFull = config.llamaCppSwaFull ?? manifestEngineConfig?.swaFull;
-                const swaFullAutoDefault = explicitSwaFull === undefined &&
-                    isGemmaModel({
-                        architecture: modelCatalogInfo?.architecture,
-                        modelId: defaultModelId ?? undefined,
-                    });
-                // A full-size cache past the automatic KV ceiling is declined even
-                // where it fits: gemma4-31b's is 55 GB at 64K, 11x its windowed
-                // cache, for a cross-request reuse gain nobody had measured.
-                const kvCeilingBytes = autoKvCacheMaxBytes();
-                const fullCacheOverCeiling = fullKvBytesAtRequested !== undefined && fullKvBytesAtRequested > kvCeilingBytes;
-                const fullKvOverBudget = fullCacheFitsFastMemory === false ||
-                    fullCacheOverCeiling ||
-                    !admission.minimumSatisfied ||
-                    admission.slots < slots ||
-                    admission.clamped;
+                const fullKvOverBudget = !admission.minimumSatisfied || admission.slots < slots || admission.clamped;
                 // The plan whose ladder (deny → shed slots → clamp) is enforced
                 // below. Defaults to the full-attention plan; the windowed-cache
-                // branches replace it with windowed math or — only when the GGUF
+                // branch replaces it with windowed math or — only when the GGUF
                 // hides its SWA layout — null (no safe estimate; launch untouched,
                 // the pre-windowed-admission behavior).
                 let ladderPlan = admission;
@@ -833,17 +821,17 @@ export async function buildLlamaCppProvider(opts) {
                 // full-attention), and the strict minimum rides inside
                 // `contextRequirement.minimumPerTurnCtxTokens`, so the windowed
                 // re-plan below sheds slots or denies but never shortens the window.
-                const windowedCacheWillRun = fullKvOverBudget && (swaFullAutoDefault || explicitSwaFull === false);
-                if (windowedCacheWillRun) {
-                    // The denial, the slot reduction, and the clamp above are all
-                    // driven by full-attention KV math, which overstates the windowed
-                    // cache's real allocation (Gemma 4: global layers are both fewer
-                    // AND cheaper per token than SWA layers — ~14× on 31b). Re-plan
-                    // with the windowed linearization: SWA layers become a fixed,
-                    // context-independent reservation; only global layers scale.
-                    // Without it a 31b-class Gemma on a ~32 GB host would launch
-                    // with NO context admission at all — the same lazy-Metal-wiring
-                    // OOM this gate exists to prevent, one machine class down.
+                if (explicitSwaFull !== true) {
+                    // The admission above is full-attention KV math, which overstates
+                    // the windowed cache's real allocation (Gemma 4: global layers are
+                    // both fewer AND cheaper per token than SWA layers — ~11× on 31b
+                    // at 64K). Re-plan with the windowed linearization: SWA layers
+                    // become a fixed, context-independent reservation; only global
+                    // layers scale. Without it a 31b-class Gemma on a ~32 GB host
+                    // would launch with NO context admission at all — the same
+                    // lazy-Metal-wiring OOM this gate exists to prevent, one machine
+                    // class down — and growth would price every token at the full
+                    // slope.
                     const windowed = estimateWindowedKvLinearization({
                         blockCount: summary.blockCount,
                         embeddingLength: summary.embeddingLength,
@@ -864,42 +852,6 @@ export async function buildLlamaCppProvider(opts) {
                         ssmConvKernel: summary.ssmConvKernel,
                         kvCacheType,
                     });
-                    if (swaFullAutoDefault) {
-                        // Declining `--swa-full` dominates every full-math remedy:
-                        // the context window is capability, the full cache is a
-                        // session-switch performance trade. Weights-level admission
-                        // stays with the capacity broker.
-                        swaFullAutoFits = false;
-                        const fastFitDetail = fullCacheFitsFastMemory === false && fullKvBytesAtRequested !== undefined
-                            ? `projected weights + full KV ${((residentBytes + fullKvBytesAtRequested) / 1024 ** 3).toFixed(1)} GiB exceeds available fast memory ${(Math.max(0, fastBudgetBytes - committedOtherBytes) / 1024 ** 3).toFixed(1)} GiB`
-                            : undefined;
-                        const overCeilingOnly = fullCacheOverCeiling &&
-                            fullCacheFitsFastMemory !== false &&
-                            admission.minimumSatisfied &&
-                            admission.slots >= slots &&
-                            !admission.clamped;
-                        if (overCeilingOnly && fullKvBytesAtRequested !== undefined) {
-                            // A policy choice on a machine that could hold the cache, not
-                            // a shortage: info, not warn.
-                            log.info([
-                                `[llama-cpp] ${modelCatalogInfo?.id ?? 'model'}: the full SWA cache at the requested `,
-                                `${effectiveNumCtx * slots}-token total context would take `,
-                                `${(fullKvBytesAtRequested / 1024 ** 3).toFixed(1)} GiB, past the `,
-                                `${(kvCeilingBytes / 1024 ** 3).toFixed(1)} GiB automatic KV ceiling — keeping the full `,
-                                'context and declining the --swa-full auto-default instead; the windowed KV cache ',
-                                'holds it (cross-request prefix reuse unavailable).',
-                            ].join(''));
-                        }
-                        else {
-                            log.warn([
-                                `[llama-cpp] ${modelCatalogInfo?.id ?? 'model'}: the full SWA working set at the requested `,
-                                `${effectiveNumCtx * slots}-token total context does not fit fast memory — keeping the full `,
-                                'context and declining the --swa-full auto-default instead; the windowed KV cache ',
-                                'is what actually fits (cross-request prefix reuse unavailable). ',
-                                `Fit detail: ${fastFitDetail ?? admission.reason ?? 'over budget at the requested slot count'}`,
-                            ].join(''));
-                        }
-                    }
                     if (windowed) {
                         ladderPlan = planCtxTokensForMemory({
                             requestedPerTurnCtxTokens: effectiveNumCtx,
@@ -917,16 +869,23 @@ export async function buildLlamaCppProvider(opts) {
                             fixedPerSlotBytes: windowed.fixedBytes,
                         };
                     }
-                    else if ((summary.slidingWindow ?? 0) > 0 || swaFullAutoDefault) {
-                        // A sliding-window model whose GGUF hides the layer layout:
-                        // full math over-states the real cache and there is no exact
-                        // substitute — leave the launch alone rather than over-clamp.
+                    else if (fullKvOverBudget &&
+                        (explicitSwaFull === false
+                            ? (summary.slidingWindow ?? 0) > 0
+                            : isGemmaModel({
+                                architecture: modelCatalogInfo?.architecture,
+                                modelId: defaultModelId ?? undefined,
+                            }))) {
+                        // A sliding-window model whose GGUF hides the layer layout,
+                        // over budget on full math: that math over-states the real cache
+                        // and there is no exact substitute — leave the launch alone
+                        // rather than over-clamp.
                         ladderPlan = null;
                         ladderKvLinearization = null;
                     }
-                    // else: `swaFull: false` pinned on a model with no SWA layers at
-                    // all — the flag is a no-op there and the full-attention plan IS
-                    // the real allocation; fall through with it intact.
+                    // else: no SWA layers at all, or a layout-less model that fits on
+                    // full math — the full-attention plan stands (it IS the real
+                    // allocation, or safely above it).
                 }
                 if (ladderPlan !== null && envNumCtx === undefined) {
                     const windowedNote = ladderPlan === admission ? '' : ' (windowed KV admission)';
@@ -989,19 +948,12 @@ export async function buildLlamaCppProvider(opts) {
                 }
             }
             // Price the KV the engine will ACTUALLY allocate. Mirrors the
-            // `--swa-full` tri-state in buildLlamaCppEngineArgs (explicit config
-            // → manifest → Gemma auto-default gated on the fit verdict): an SWA
-            // model on the default windowed cache carries only its global layers
-            // per token plus a fixed window block per slot. Feeding the offload
-            // planner full-attention math for a windowed launch over-biased
-            // Gemma experts into system RAM for a cache that never materializes.
-            const effectiveSwaFull = config.llamaCppSwaFull ??
-                manifestEngineConfig?.swaFull ??
-                (swaFullAutoFits !== false &&
-                    isGemmaModel({
-                        architecture: modelCatalogInfo?.architecture,
-                        modelId: defaultModelId ?? undefined,
-                    }));
+            // opt-in `--swa-full` in buildLlamaCppEngineArgs: an SWA model on the
+            // default windowed cache carries only its global layers per token
+            // plus a fixed window block per slot. Feeding the offload planner
+            // full-attention math for a windowed launch over-biased Gemma experts
+            // into system RAM for a cache that never materializes.
+            const effectiveSwaFull = config.llamaCppSwaFull ?? manifestEngineConfig?.swaFull ?? false;
             const windowedKvPlan = effectiveSwaFull
                 ? undefined
                 : estimateWindowedKvLinearization({
@@ -1024,9 +976,9 @@ export async function buildLlamaCppProvider(opts) {
                     ssmConvKernel: summary.ssmConvKernel,
                     kvCacheType,
                 });
-            const kvReserveBytes = windowedKvPlan
-                ? Math.round(windowedKvPlan.fixedBytes * slots +
-                    windowedKvPlan.bytesPerToken * effectiveNumCtx * slots)
+            const kvReserveFor = (slotCount) => windowedKvPlan
+                ? Math.round(windowedKvPlan.fixedBytes * slotCount +
+                    windowedKvPlan.bytesPerToken * effectiveNumCtx * slotCount)
                 : estimateKvReserveBytes({
                     blockCount: summary.blockCount,
                     embeddingLength: summary.embeddingLength,
@@ -1044,43 +996,47 @@ export async function buildLlamaCppProvider(opts) {
                     ssmInnerSize: summary.ssmInnerSize,
                     ssmStateSize: summary.ssmStateSize,
                     ssmConvKernel: summary.ssmConvKernel,
-                    ctxTokens: effectiveNumCtx * slots,
+                    ctxTokens: effectiveNumCtx * slotCount,
                     kvCacheType,
                 });
-            // The broker-ledger reservation for this launch: resident weights
-            // plus the KV the engine will allocate at the granted window (M1 —
-            // the weights-only ledger under-reserved dense models whose KV
-            // rivals their weights: qwen3.5-4b at 64K carries more KV than
-            // parameters). Consumed by the pool builder via
-            // `plannedReservationBytes` so co-residency admission can see it.
-            if (kvReserveBytes !== undefined) {
-                plannedReservationBytes = residentBytes + kvReserveBytes;
-            }
+            // Plan against the card as it is now. Sized to the whole card, a plan
+            // counts memory other programs hold: MoE admission then charged the
+            // model the whole card and refused it (2026-10-11), and a dense
+            // 31B planned into 30.3 GiB of a 32 GB card that the desktop and its
+            // apps were already holding ~5 GB of died with a Vulkan out-of-memory
+            // (2026-10-19).
+            const freeGpuBytes = vramBytes > 0 ? await measureAvailableGpuBytes().catch(() => undefined) : undefined;
+            // A lane count the person chose is not the planner's to spend, and
+            // eval runs under GEZEL_LLAMA_NUM_CTX accept the memory consequences.
+            const mayShedSlots = configuredSlots === undefined && envNumCtx === undefined;
+            const placeSlots = (gpuBytes, plan) => mayShedSlots
+                ? shedSlotsForGpuResidency({ slots, vramBytes: gpuBytes, plan })
+                : { slots, decision: plan(slots, gpuBytes), shed: false };
+            let placement;
             if (isMoE) {
-                // Plan against the card as it is now. Sized to the whole card, the
-                // plan counted memory other programs held, and admission then had
-                // to charge the model the whole card and refuse it (2026-10-11).
-                const freeGpuBytes = vramBytes > 0 ? await measureAvailableGpuBytes().catch(() => undefined) : undefined;
-                const moePlan = planMoeOffload({
-                    isMoE,
-                    residentBytes,
-                    vramBytes: freeGpuBytes !== undefined ? Math.min(vramBytes, freeGpuBytes) : vramBytes,
-                    ...(split
-                        ? {
-                            split,
-                            ...(summary.blockCount !== undefined ? { blockCount: summary.blockCount } : {}),
-                            ...(kvReserveBytes !== undefined ? { kvReserveBytes } : {}),
-                        }
-                        : {}),
+                placement = placeSlots(freeGpuBytes !== undefined ? Math.min(vramBytes, freeGpuBytes) : vramBytes, (slotCount, gpuBytes) => {
+                    const kvReserveBytes = kvReserveFor(slotCount);
+                    return planMoeOffload({
+                        isMoE,
+                        residentBytes,
+                        vramBytes: gpuBytes,
+                        ...(split
+                            ? {
+                                split,
+                                ...(summary.blockCount !== undefined ? { blockCount: summary.blockCount } : {}),
+                                ...(kvReserveBytes !== undefined ? { kvReserveBytes } : {}),
+                            }
+                            : {}),
+                    });
                 });
-                offloadDecision = moePlan;
+                offloadDecision = placement.decision;
                 // An explicit offload setting shadows the planner's flags, so its
                 // footprint would describe a launch that is not the one made.
                 const plannerPlacesExperts = (config.llamaCppCpuMoe ?? resolvedManifestEngineConfig?.cpuMoe) === undefined &&
                     (config.llamaCppNCpuMoe ?? resolvedManifestEngineConfig?.nCpuMoe) === undefined &&
                     (config.llamaCppNGpuLayers ?? resolvedManifestEngineConfig?.nGpuLayers) === undefined;
                 if (plannerPlacesExperts)
-                    plannedGpuBytes = moePlan.gpuBytes;
+                    plannedGpuBytes = placement.decision.gpuBytes;
             }
             else {
                 const explicitNCpuFfn = config.llamaCppNCpuFfn ?? resolvedManifestEngineConfig?.nCpuFfn;
@@ -1089,16 +1045,21 @@ export async function buildLlamaCppProvider(opts) {
                 // A finite whole-layer GPU count is a different placement strategy;
                 // don't layer an automatic tensor override on top of it. `-1` means
                 // all and is compatible with the planner's own attention-on-GPU plan.
-                offloadDecision =
-                    explicitNCpuFfn === undefined &&
-                        (explicitNGpuLayers === undefined || explicitNGpuLayers === -1)
-                        ? planDenseFfnOffload({
+                if (explicitNCpuFfn === undefined &&
+                    (explicitNGpuLayers === undefined || explicitNGpuLayers === -1)) {
+                    placement = placeSlots(
+                    // Respect the usable accelerator pool, any explicit capacity
+                    // ceiling, co-resident reservations, and what other programs
+                    // hold on the card now. The raw probe still gates this to a real
+                    // discrete-GPU build rather than treating a CPU/unified fast pool
+                    // as VRAM.
+                    vramBytes > 0
+                        ? Math.max(0, Math.min(budgetBytes - committedOtherBytes, freeGpuBytes ?? Number.POSITIVE_INFINITY))
+                        : 0, (slotCount, gpuBytes) => {
+                        const kvReserveBytes = kvReserveFor(slotCount);
+                        return planDenseFfnOffload({
                             isMoE,
-                            // Respect the usable accelerator pool, any explicit capacity
-                            // ceiling, and co-resident reservations. The raw probe still
-                            // gates this to a real discrete-GPU build rather than treating
-                            // a CPU/unified fast pool as VRAM.
-                            vramBytes: vramBytes > 0 ? Math.max(0, budgetBytes - committedOtherBytes) : 0,
+                            vramBytes: gpuBytes,
                             ...(denseFfnSplit ? { split: denseFfnSplit } : {}),
                             ...(summary.blockCount !== undefined ? { blockCount: summary.blockCount } : {}),
                             ...(kvReserveBytes !== undefined ? { kvReserveBytes } : {}),
@@ -1107,9 +1068,30 @@ export async function buildLlamaCppProvider(opts) {
                                 ? brokerSnap.pools.ramShareBytes
                                 : hostCapacity.ramShareBytes,
                             freeSystemRamBytes: availableSystemRamBytes(),
-                        })
-                        : undefined;
+                        });
+                    });
+                    offloadDecision = placement.decision;
+                }
+                else {
+                    offloadDecision = undefined;
+                }
             }
+            if (placement?.shed) {
+                log.info(`[llama-cpp] ${modelCatalogInfo?.id ?? 'model'}: reducing engine slots ${slots} -> 1 to keep the model on the GPU with room to spare (other programs' graphics memory moves)`);
+                slots = 1;
+            }
+            // The broker-ledger reservation for this launch: resident weights
+            // plus the KV the engine will allocate at the granted window (M1 —
+            // the weights-only ledger under-reserved dense models whose KV
+            // rivals their weights: qwen3.5-4b at 64K carries more KV than
+            // parameters). Consumed by the pool builder via
+            // `plannedReservationBytes` so co-residency admission can see it.
+            const kvReserveBytes = kvReserveFor(slots);
+            if (kvReserveBytes !== undefined) {
+                plannedReservationBytes = residentBytes + kvReserveBytes;
+            }
+            reservationKvFor = kvReserveFor;
+            reservationResidentBytes = residentBytes;
             if (offloadDecision?.reason) {
                 log.info(`[llama-cpp] offload plan (${modelCatalogInfo?.id ?? 'model'}): ${offloadDecision.reason}`);
             }
@@ -1202,44 +1184,105 @@ export async function buildLlamaCppProvider(opts) {
             if (snapshot.expected)
                 return;
             logFile.writeIncident(snapshot);
-            // A build that dies by SIGILL before it ever answers /health has
-            // not failed at a task — it cannot run on this CPU at all, and
-            // relaunching it on every request just reproduces the crash while
-            // a working lower-tier build sits in the same directory. Write it
-            // down so the next launch routes around it.
-            //
-            // Deliberately narrow: only SIGILL, and only before readiness.
-            // A SIGSEGV during startup can be a corrupt model file, and any
-            // crash after readiness is attributable to the work rather than
-            // the binary — quarantining a backend over either would demote
-            // users to slow engines for transient reasons.
-            if (snapshot.signal !== 'SIGILL' || snapshot.reachedReady)
+            if (snapshot.panicKind === 'host-out-of-memory') {
+                noteHostOutOfMemory({
+                    model: modelCatalogInfo?.id ?? defaultModelId,
+                    whileStarting: !snapshot.reachedReady,
+                });
+                log.warn(`[llama-server] Linux's out-of-memory killer stopped the engine (${modelCatalogInfo?.id ?? 'model'}, incident=${snapshot.incidentId}, ${snapshot.reachedReady ? 'while serving' : 'while loading'})`);
                 return;
-            const backend = process.env.GEZEL_LLAMA_SERVER_BACKEND;
-            if (!backend)
+            }
+            // A build that dies before it ever answers /health, without saying
+            // why, may not be able to run here at all — and relaunching it on every
+            // request just reproduces the crash while a working lower-tier build
+            // sits in the next directory. Count it; a few in a row write it down so
+            // the next launch routes around it. Which exits qualify (a silent
+            // SIGILL; a GPU build's silent crash status on Windows or signal on
+            // Linux; a CUDA build with no code for this GPU) is decided in
+            // unrunnable-build.ts, how many in llama-quarantine.ts.
+            const backend = binaryBackend;
+            const unrunnable = unrunnableBuildExit(snapshot, backend);
+            if (!backend || !unrunnable)
                 return;
-            const entry = recordLlamaQuarantine(home, {
+            const { strikes, entry } = recordLlamaStartupCrash(home, {
                 backend,
                 binaryPath: binary,
-                signal: 'SIGILL',
-                reason: 'crashed with SIGILL before the engine became ready — this build uses CPU instructions ' +
-                    'this machine does not support, or faulted inside GPU library startup',
+                signal: unrunnable.signal,
+                reason: unrunnable.reason,
             });
-            if (entry) {
-                log.warn(`[llama-server] quarantined the ${backend} build after SIGILL (incident=${snapshot.incidentId}); the next launch will fall back to another backend`);
+            if (!entry) {
+                if (strikes === 0)
+                    return;
+                lastStartupCrash = {
+                    incidentId: snapshot.incidentId,
+                    verdict: { kind: 'strike', strikes, threshold: LLAMA_QUARANTINE_STRIKES },
+                };
+                log.warn(`[llama-server] the ${backend} build crashed before it was ready (${unrunnable.signal}, incident=${snapshot.incidentId}); ${strikes} of ${LLAMA_QUARANTINE_STRIKES} in a row switch it off`);
+                return;
+            }
+            log.warn(`[llama-server] quarantined the ${backend} build after ${strikes} crashes in a row (${unrunnable.signal}, incident=${snapshot.incidentId}); the next launch will fall back to another backend`);
+            // Discovery reads the quarantine only at startup. Point the env at the
+            // fallback now, so the pool's rebuild of this failed engine on the next
+            // request launches it instead of the build just written down. A pinned
+            // backend is a decision, and discovery never routes around one either;
+            // an env that has already moved on belongs to someone else's fallback.
+            const pinned = config.llamaCppBackendOverride !== undefined && config.llamaCppBackendOverride !== 'auto';
+            const fallback = pinned || process.env.GEZEL_LLAMA_SERVER_BIN !== binary
+                ? null
+                : adoptLlamaFallback(home, binary, backend);
+            lastStartupCrash = {
+                incidentId: snapshot.incidentId,
+                verdict: { kind: 'quarantined', ...(fallback ? { switchedTo: fallback.backend } : {}) },
+            };
+            if (fallback) {
+                log.warn(`[llama-server] the next launch uses the ${fallback.backend} build: ${fallback.path}`);
             }
         },
-        onRawLine: (line) => providerHolder.current?.onStdoutLine(line),
-        // GPU-OOM recovery ladder: when a start dies of VRAM exhaustion and the
-        // planner's offload decision was in play, degrade it one step
-        // (partial split → all expert/FFN weights to RAM → engine-owned fit) and let the
-        // supervisor retry — `resolveLaunch` below re-reads `offloadDecision`
-        // on every spawn. The degraded plan sticks for later restarts of this
-        // provider, so a recovered engine doesn't re-OOM on its next boot.
+        // Any start that reaches readiness proves the build runs here, so the
+        // crashes before it were not in a row. It does not prove the build got
+        // its GPU: a GPU backend that cannot load or initialize leaves the engine
+        // on the CPU without crashing (gpu-startup-watch.ts).
+        onReady: () => {
+            if (binaryBackend)
+                clearLlamaStartupStrikes(home, binaryBackend);
+            const unused = gpuWatch?.verdict() ?? null;
+            noteGpuStartup(unused);
+            if (unused) {
+                log.warn(`[llama-server] the ${unused.backend} build started without its GPU (${unused.reason}${unused.detail ? `: ${unused.detail}` : ''}); every token runs on the CPU`);
+            }
+        },
+        onRawLine: (line) => {
+            gpuWatch?.observe(line);
+            providerHolder.current?.onStdoutLine(line);
+        },
+        // GPU-OOM recovery ladder: when a start dies of VRAM exhaustion, first
+        // give back the extra slots' KV (every weight stays on the GPU), then, if
+        // the planner's offload decision was in play, degrade it one step
+        // (partial split → all expert/FFN weights to RAM → engine-owned fit) and
+        // let the supervisor retry — `resolveLaunch` below re-reads `slots` and
+        // `offloadDecision` on every spawn. The degraded plan sticks for later
+        // restarts of this provider, so a recovered engine doesn't re-OOM on its
+        // next boot.
         recoverStartup: ({ panicKind }) => {
             if (panicKind !== 'cuda-out-of-memory' && panicKind !== 'vulkan-out-of-memory') {
                 return false;
             }
+            // A full-residency plan has no offload rung below it, so before this a
+            // two-slot launch that missed by one KV allocation failed outright
+            // (2026-10-19, Gemma 4 31B on a 32 GB card). This rung spends one of
+            // the supervisor's two retries; an offload rung still has the other.
+            if (slots > 1 && configuredSlots === undefined) {
+                const from = slots;
+                if (providerHolder.current?.narrowEngineSlots(1)) {
+                    slots = 1;
+                    const kvReserveBytes = reservationKvFor?.(1);
+                    if (kvReserveBytes !== undefined && reservationResidentBytes !== undefined) {
+                        plannedReservationBytes = reservationResidentBytes + kvReserveBytes;
+                    }
+                    log.warn(`[llama-cpp] ${panicKind} while starting ${modelCatalogInfo?.id ?? 'model'} — retrying with one engine slot instead of ${from}`);
+                    return true;
+                }
+            }
             // Explicit config/manifest offload settings shadow the planner
             // per-field (see `buildLlamaCppEngineArgs`); when every field the
             // ladder would change is pinned, a retry replays the same argv.
@@ -1275,6 +1318,13 @@ export async function buildLlamaCppProvider(opts) {
             return true;
         },
         resolveLaunch: async () => {
+            gpuWatch = new GpuStartupWatch(binaryBackend);
+            // Again at every launch, not only at build: llama.cpp from the 0.1.51
+            // release refuses a --slot-save-path that does not exist ("not a
+            // directory") and exits before ready, and an eval preflight lost its
+            // build-time directory during a 50 s capacity wait (2026-10-18). The
+            // person saw "no model is installed yet".
+            await mkdirAsync(slotSavePath, { recursive: true }).catch(() => { });
             const port = cachedPort ?? (await pickFreePort());
             cachedPort = port;
             // Prepend the binary's own directory to PATH so the OS finds the
@@ -1301,9 +1351,6 @@ export async function buildLlamaCppProvider(opts) {
                 // model output reaches `delta.content` for provider-side salvage.
                 reasoningFormat: process.env.GEZEL_LLAMA_REASONING_FORMAT?.trim() || undefined,
                 reasoningPreserve,
-                architecture: modelCatalogInfo?.architecture,
-                modelId: defaultModelId ?? undefined,
-                swaFullAutoFits,
                 backend: llamaBuildMetadata?.backend ?? process.env.GEZEL_LLAMA_SERVER_BACKEND,
                 hostCpuCount: availableParallelism(),
             });
@@ -1454,6 +1501,7 @@ export async function buildLlamaCppProvider(opts) {
         supervisor,
         logFile,
         slotSavePath,
+        startupCrashVerdict: (incidentId) => lastStartupCrash?.incidentId === incidentId ? lastStartupCrash.verdict : undefined,
         // Lets `listModels()` enumerate every installed model (not just
         // the resident one) so `/v1/models` + pickers see the full set
         // the engine pool can serve.