@bendyline/gezel-inference 1.0.1 → 1.0.2

package/dist/providers/llama-cpp/backend-quarantine.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The engine process's side of the llama-server quarantine
+ * (`llama-quarantine.ts` in `@bendyline/gezel/native`): which build this
+ * process launches, kept in the env discovery stamps at startup
+ * (`GEZEL_LLAMA_SERVER_BIN`, `GEZEL_LLAMA_SERVER_BACKEND`,
+ * `GEZEL_LLAMA_QUARANTINED`), and the view and undo behind the engine's
+ * Settings tab.
+ *
+ * Discovery reads the quarantine only at startup. These move the env inside
+ * a running process, so a quarantine and its undo both take effect on the
+ * next engine launch instead of the next app start.
+ */
+import type { LlamaCppQuarantineResponse } from '@bendyline/gezel';
+import { type LlamaBackend, type ResolvedLlamaBinary } from '@bendyline/gezel/native';
+export declare function isLlamaBackend(value: string): value is LlamaBackend;
+/**
+ * Point this process at the build that replaces `backend`'s, just
+ * quarantined, so the pool's rebuild of the failed engine launches it. Null,
+ * env untouched, when nothing usable is bundled beside `binary`.
+ */
+export declare function adoptLlamaFallback(home: string, binary: string, backend: LlamaBackend): ResolvedLlamaBinary | null;
+/**
+ * The quarantined builds that still apply. An entry pins its binary's bytes,
+ * so one whose build an update replaced is left out — discovery ignores it
+ * too. Without a resolved build to measure from, entries are shown as written.
+ */
+export declare function llamaQuarantineView(home: string): LlamaCppQuarantineResponse;
+/**
+ * Lift `backend`'s quarantine at a person's request. Unless they pinned a
+ * backend, also point this process back at the best build the hardware
+ * supports, so the next engine launch tries it; `restored` is that build when
+ * the env moved. A pinned backend is launched as pinned and was never routed
+ * around, so there is nothing to move back.
+ */
+export declare function liftLlamaQuarantine(home: string, backend: LlamaBackend, opts: {
+    pinned: boolean;
+}): {
+    cleared: boolean;
+    restored: ResolvedLlamaBinary | null;
+};

package/dist/providers/llama-cpp/backend-quarantine.js

@@ -0,0 +1,100 @@
+/**
+ * The engine process's side of the llama-server quarantine
+ * (`llama-quarantine.ts` in `@bendyline/gezel/native`): which build this
+ * process launches, kept in the env discovery stamps at startup
+ * (`GEZEL_LLAMA_SERVER_BIN`, `GEZEL_LLAMA_SERVER_BACKEND`,
+ * `GEZEL_LLAMA_QUARANTINED`), and the view and undo behind the engine's
+ * Settings tab.
+ *
+ * Discovery reads the quarantine only at startup. These move the env inside
+ * a running process, so a quarantine and its undo both take effect on the
+ * next engine launch instead of the next app start.
+ */
+import { LLAMA_QUARANTINE_STRIKES, clearLlamaQuarantine, createLlamaBuildCheck, isBinaryQuarantined, llamaVariantBinaryPath, publishLlamaCudaBlocker, readLlamaQuarantine, resolveLlamaFallbackBinary, resolveLlamaVariantBinary, } from '@bendyline/gezel/native';
+const BACKENDS = ['cuda', 'vulkan', 'metal', 'cpu'];
+export function isLlamaBackend(value) {
+    return BACKENDS.some((backend) => backend === value);
+}
+function envBackend(name) {
+    const raw = process.env[name];
+    return raw !== undefined && isLlamaBackend(raw) ? raw : undefined;
+}
+function updateQuarantinedEnv(update) {
+    const backends = new Set(process.env.GEZEL_LLAMA_QUARANTINED?.split(',').filter(Boolean));
+    update(backends);
+    if (backends.size > 0)
+        process.env.GEZEL_LLAMA_QUARANTINED = [...backends].join(',');
+    else
+        delete process.env.GEZEL_LLAMA_QUARANTINED;
+}
+/**
+ * Point this process at the build that replaces `backend`'s, just
+ * quarantined, so the pool's rebuild of the failed engine launches it. Null,
+ * env untouched, when nothing usable is bundled beside `binary`.
+ */
+export function adoptLlamaFallback(home, binary, backend) {
+    const quarantine = readLlamaQuarantine(home);
+    const fallback = resolveLlamaFallbackBinary(binary, backend, (candidate, path) => !isBinaryQuarantined(quarantine, candidate, path));
+    if (!fallback)
+        return null;
+    process.env.GEZEL_LLAMA_SERVER_BIN = fallback.path;
+    process.env.GEZEL_LLAMA_SERVER_BACKEND = fallback.backend;
+    updateQuarantinedEnv((backends) => backends.add(backend));
+    return fallback;
+}
+/**
+ * The quarantined builds that still apply. An entry pins its binary's bytes,
+ * so one whose build an update replaced is left out — discovery ignores it
+ * too. Without a resolved build to measure from, entries are shown as written.
+ */
+export function llamaQuarantineView(home) {
+    const binary = process.env.GEZEL_LLAMA_SERVER_BIN;
+    const running = envBackend('GEZEL_LLAMA_SERVER_BACKEND');
+    const entries = readLlamaQuarantine(home).filter((entry) => {
+        if (!isLlamaBackend(entry.backend))
+            return false;
+        if (!binary || !running)
+            return true;
+        const path = llamaVariantBinaryPath(binary, running, entry.backend);
+        return path === null || isBinaryQuarantined([entry], entry.backend, path);
+    });
+    return {
+        entries: entries.map(({ backend, signal, reason, at, crashes }) => ({
+            backend,
+            signal,
+            reason,
+            at,
+            ...(crashes !== undefined ? { crashes } : {}),
+        })),
+        strikeThreshold: LLAMA_QUARANTINE_STRIKES,
+        ...(running ? { running } : {}),
+    };
+}
+/**
+ * Lift `backend`'s quarantine at a person's request. Unless they pinned a
+ * backend, also point this process back at the best build the hardware
+ * supports, so the next engine launch tries it; `restored` is that build when
+ * the env moved. A pinned backend is launched as pinned and was never routed
+ * around, so there is nothing to move back.
+ */
+export function liftLlamaQuarantine(home, backend, opts) {
+    const cleared = clearLlamaQuarantine(home, backend);
+    updateQuarantinedEnv((backends) => backends.delete(backend));
+    const binary = process.env.GEZEL_LLAMA_SERVER_BIN;
+    const running = envBackend('GEZEL_LLAMA_SERVER_BACKEND');
+    if (opts.pinned || !binary || !running)
+        return { cleared, restored: null };
+    // Discovery's own check: a CUDA build the driver cannot run stays passed
+    // over, whatever else was lifted.
+    const check = createLlamaBuildCheck({
+        quarantine: readLlamaQuarantine(home),
+        platform: process.platform,
+    });
+    const best = resolveLlamaVariantBinary(binary, running, envBackend('GEZEL_LLAMA_DETECTED_BACKEND') ?? backend, check.isUsable);
+    publishLlamaCudaBlocker(check.cudaBlocker());
+    if (!best || best.backend === running)
+        return { cleared, restored: null };
+    process.env.GEZEL_LLAMA_SERVER_BIN = best.path;
+    process.env.GEZEL_LLAMA_SERVER_BACKEND = best.backend;
+    return { cleared, restored: best };
+}

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, } 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
@@ -621,13 +645,6 @@ 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
@@ -709,21 +726,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 +781,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 +800,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 +824,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 +855,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 +872,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 +951,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({
@@ -1202,34 +1157,77 @@ 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}`);
+            }
+        },
+        // 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) => providerHolder.current?.onStdoutLine(line),
+        onRawLine: (line) => {
+            gpuWatch?.observe(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
@@ -1275,6 +1273,7 @@ export async function buildLlamaCppProvider(opts) {
             return true;
         },
         resolveLaunch: async () => {
+            gpuWatch = new GpuStartupWatch(binaryBackend);
             const port = cachedPort ?? (await pickFreePort());
             cachedPort = port;
             // Prepend the binary's own directory to PATH so the OS finds the
@@ -1301,9 +1300,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 +1450,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.

package/dist/providers/llama-cpp/cache-adapter.js

@@ -306,7 +306,8 @@ export class LlamaCppCacheAdapter {
             if (!entry || typeof entry !== 'object')
                 continue;
             const slot = entry.id;
-            const cachedTokens = entry.n_cache_tokens;
+            // The slot's resident tokens (prompt plus generated); there is no `n_cache_tokens`.
+            const cachedTokens = entry.n_prompt_tokens;
             if (typeof slot !== 'number' || typeof cachedTokens !== 'number' || cachedTokens <= 0) {
                 continue;
             }

package/dist/providers/llama-cpp/devices.d.ts

@@ -31,6 +31,12 @@ export interface LlamaDeviceProbe {
     probedAt: string;
     /** True when returned from the on-disk cache rather than a fresh spawn. */
     cached: boolean;
+    /**
+     * The RAM the OS reported when the probe ran. Changing an integrated GPU's
+     * firmware carve-out changes this figure and the GPU's own, so a mismatch
+     * means the cached devices describe a machine that no longer exists.
+     */
+    systemRamBytes?: number;
 }
 export interface NvidiaRuntimeDevice {
     index: number;
@@ -72,16 +78,19 @@ export declare function pickBestGpuDevice(devices: LlamaDevice[]): LlamaDevice |
 /**
  * Probe device memory by running `<binaryPath> --list-devices`, caching
  * the result. Reads the cache when present (VRAM capacity is stable per
- * machine); pass `force` to re-probe. Any failure (spawn error, no
+ * machine) and the OS still reports the RAM it was probed with; pass
+ * `force` to re-probe. Any failure (spawn error, no
  * cache, unparseable output) resolves to an empty device list — the
  * planner then simply does nothing and the engine's own `--fit`/`-ngl
- * auto` takes over. `nowIso` is injectable for deterministic tests.
+ * auto` takes over. `nowIso` and `systemRamBytes` are injectable for
+ * deterministic tests.
  */
 export declare function probeLlamaDevices(opts: {
     binaryPath: string;
     home: string;
     force?: boolean;
     nowIso?: () => string;
+    systemRamBytes?: number;
 }): Promise<LlamaDeviceProbe>;
 /**
  * Best-effort VRAM for a non-NVIDIA GPU (AMD Radeon, Intel Arc, any Vulkan