@bendyline/gezel-inference 0.0.0-stage → 1.0.0

package/dist/system/memory.js

@@ -0,0 +1,501 @@
+import { execFile } from 'node:child_process';
+import { freemem, platform as osPlatform, totalmem } from 'node:os';
+import { promisify } from 'node:util';
+import { windowsHeadlessSpawnOptions, } from '@bendyline/gezel/native';
+import { detectLlamaGpuVram, } from '../providers/llama-cpp/devices.js';
+import { autoDetectBudgetBytes, computeCapacityBudget, setDetectedGpuVramBytes, } from '../providers/native/capacity-budget.js';
+const exec = promisify(execFile);
+let cachedMemoryProfile = null;
+let pendingMemoryProfile = null;
+/**
+ * Detect the memory available for local LLM inference. Platform-aware:
+ *
+ *   • macOS: unified memory — GPU and CPU share one pool. Use the same
+ *     capacity budget enforced by the native-engine broker: 60% on
+ *     ordinary machines, 80% on 96 GB+ machines, capped at 96 GiB.
+ *
+ *   • Linux / Windows: probe `nvidia-smi` for VRAM. If present, that's
+ *     the primary budget (dedicated GPU inference). If absent, probe the
+ *     bundled `llama-server --list-devices` for a non-NVIDIA GPU (AMD /
+ *     Intel / any Vulkan device) and use ITS VRAM as the budget. Only when
+ *     neither reports a GPU do we fall back to ~50% of system RAM (CPU
+ *     inference — works, but slower, with headroom left for the OS).
+ */
+export async function detectMemoryProfile() {
+    const plat = osPlatform();
+    const totalRam = totalmem();
+    if (plat === 'darwin') {
+        setDetectedGpuVramBytes(null);
+        return {
+            platform: 'darwin',
+            totalRamBytes: totalRam,
+            gpuVramBytes: null,
+            gpuMemoryKind: 'unified',
+            source: 'darwin-unified',
+            usableBytes: autoDetectBudgetBytes(totalRam),
+            budgetBytes: autoDetectBudgetBytes(totalRam),
+        };
+    }
+    // Don't dock a dedicated card — the whole VRAM pool is available in
+    // practice. A small 5% safety margin covers the display framebuffer and
+    // driver overhead. Same budget rule for NVIDIA and non-NVIDIA cards.
+    // `computeCapacityBudget` owns the same 5%, so read both from it rather
+    // than keeping a second copy of the constant here.
+    const gpuBudget = (vram, unifiedMemory) => {
+        const budget = computeCapacityBudget({
+            systemRamBytes: totalRam,
+            gpuVramBytes: vram,
+            unifiedMemory,
+        });
+        return { usableBytes: budget.fastBytes, budgetBytes: budget.budgetBytes };
+    };
+    const nvidia = await probeNvidiaMemory();
+    if (nvidia !== null) {
+        const unified = nvidia.memoryKind === 'unified';
+        setDetectedGpuVramBytes(nvidia.vramBytes, unified);
+        return {
+            platform: plat,
+            totalRamBytes: totalRam,
+            gpuVramBytes: nvidia.vramBytes,
+            // GB10 / DGX Spark reports nearly the whole unified pool through CUDA.
+            // It is shared memory, but it remains a high-performance accelerator and
+            // must not be routed to the consumer-iGPU small-model policy.
+            gpuMemoryKind: nvidia.memoryKind,
+            source: 'gpu-nvidia',
+            ...gpuBudget(nvidia.vramBytes, unified),
+            gpuVendor: 'nvidia',
+            gpuLargestDeviceBytes: nvidia.largestDeviceBytes,
+        };
+    }
+    // Non-NVIDIA GPU (AMD Radeon, Intel Arc, any Vulkan device). nvidia-smi
+    // is blind to these, but the bundled llama-server reports their VRAM via
+    // `--list-devices` — the same number the MoE offload planner uses. Use it
+    // so a Radeon box gets a real GPU budget (and the "runs on CPU" copy stops
+    // lying) instead of the 50%-of-RAM CPU fallback below.
+    const gpu = await detectLlamaGpuVram();
+    if (gpu !== null) {
+        const profile = memoryProfileForLlamaGpu(plat, totalRam, gpu);
+        // The ambient capacity broker accepts only a VRAM byte count. Publishing
+        // an integrated adapter's shared allocation there would add it to RAM a
+        // second time, so publish null for that host class.
+        setDetectedGpuVramBytes(profile.gpuMemoryKind === 'integrated' ? null : gpu.vramBytes, profile.gpuMemoryKind === 'integrated' || profile.gpuMemoryKind === 'unified');
+        // Vendor comes from the device name in the SAME probe (e.g. "AMD Radeon
+        // …" / "Intel Arc …"), so the label always matches the card we sized —
+        // never "AMD" for an Intel GPU. Undefined for unrecognized names → the
+        // UI shows a generic "GPU".
+        return profile;
+    }
+    setDetectedGpuVramBytes(null);
+    return {
+        platform: plat,
+        totalRamBytes: totalRam,
+        gpuVramBytes: null,
+        gpuMemoryKind: 'none',
+        source: 'system-ram-fallback',
+        // CPU inference needs the OS + your apps + inference buffers. Be
+        // conservative — 50% of system RAM is a safer ceiling than 60%.
+        usableBytes: Math.floor(totalRam * 0.5),
+        // The broker will still admit up to its 60% share; a model between the
+        // two runs, just without comfortable headroom ("may run slowly").
+        budgetBytes: autoDetectBudgetBytes(totalRam, { gpuVramBytes: null }),
+    };
+}
+/**
+ * Convert a llama.cpp Vulkan device into the service memory profile without
+ * double-counting an integrated adapter's shared allocation. Exported as the
+ * pure policy seam for regression tests and diagnostics tooling.
+ */
+export function memoryProfileForLlamaGpu(platform, totalRamBytes, gpu) {
+    const ratioLooksUnified = gpu.vramBytes >= totalRamBytes * 0.75;
+    const gpuMemoryKind = gpu.memoryKind === 'integrated'
+        ? 'integrated'
+        : gpu.memoryKind === 'discrete'
+            ? 'discrete'
+            : ratioLooksUnified
+                ? 'unified'
+                : 'unknown';
+    const shared = gpuMemoryKind === 'integrated' || gpuMemoryKind === 'unified';
+    const budget = computeCapacityBudget({
+        systemRamBytes: totalRamBytes,
+        gpuVramBytes: gpu.vramBytes,
+        unifiedMemory: shared,
+    });
+    return {
+        platform,
+        totalRamBytes,
+        gpuVramBytes: gpu.vramBytes,
+        gpuMemoryKind,
+        source: gpuMemoryKind === 'integrated' ? 'gpu-integrated' : 'gpu-vulkan',
+        // A consumer iGPU is effectively system-memory-paced. Keep the same
+        // conservative fast-fit ceiling as CPU fallback while the broker may
+        // admit up to its single-pool unified ceiling.
+        usableBytes: gpuMemoryKind === 'integrated' ? Math.floor(totalRamBytes * 0.5) : budget.fastBytes,
+        budgetBytes: budget.budgetBytes,
+        ...(gpu.vendor ? { gpuVendor: gpu.vendor } : {}),
+    };
+}
+/**
+ * Capacity changes only on GPU hot-plug / VM reconfiguration, while the live
+ * strip may poll once a second. Keep the expensive nvidia-smi / llama device
+ * discovery out of that hot path and refresh the profile occasionally.
+ */
+export async function detectMemoryProfileCached(maxAgeMs = 60_000) {
+    const now = Date.now();
+    if (cachedMemoryProfile && now - cachedMemoryProfile.at <= maxAgeMs) {
+        return cachedMemoryProfile.value;
+    }
+    if (pendingMemoryProfile)
+        return pendingMemoryProfile;
+    pendingMemoryProfile = detectMemoryProfile()
+        .then((value) => {
+        cachedMemoryProfile = { at: Date.now(), value };
+        return value;
+    })
+        .finally(() => {
+        pendingMemoryProfile = null;
+    });
+    return pendingMemoryProfile;
+}
+const WINDOWS_PROCESS_LOCAL_MEMORY_SOURCE = 'windows-gpu-process-local-memory';
+const NVML_PROCESS_MEMORY_SOURCE = 'nvml-process-memory';
+const PROCESS_BREAKDOWN_MIN_BYTES = 16 * 1024 ** 2;
+const PROCESS_RECONCILIATION_ABSOLUTE_TOLERANCE_BYTES = 256 * 1024 ** 2;
+const PROCESS_RECONCILIATION_RELATIVE_TOLERANCE = 0.15;
+function isWindowsDesktopProcess(process) {
+    return ((process.name ?? '')
+        .trim()
+        .replace(/\.exe$/i, '')
+        .toLowerCase() === 'dwm');
+}
+function scaleGpuProcesses(processes, scale) {
+    return processes.map((process) => ({
+        ...process,
+        dedicatedBytes: process.dedicatedBytes * scale,
+    }));
+}
+/**
+ * Windows' resident-local process samples can still overlap where display
+ * surfaces are shared with DWM. Attribute application residency first, then
+ * make Windows Desktop the remainder of the measured non-Gezel pool. This
+ * keeps every displayed estimate inside the adapter-wide physical total.
+ */
+function reconcileWindowsGpuProcesses(processes, usedBytes) {
+    const engineProcesses = processes.filter((process) => process.owner !== 'external');
+    const rawGezelBytes = engineProcesses.reduce((sum, process) => sum + process.dedicatedBytes, 0);
+    const engineScale = rawGezelBytes > usedBytes && rawGezelBytes > 0 ? usedBytes / rawGezelBytes : 1;
+    const reconciledEngines = scaleGpuProcesses(engineProcesses, engineScale);
+    const observedGezelBytes = Math.min(rawGezelBytes, usedBytes);
+    const otherBytes = Math.max(0, usedBytes - observedGezelBytes);
+    const desktopProcesses = processes.filter((process) => process.owner === 'external' && isWindowsDesktopProcess(process));
+    const otherAppProcesses = processes.filter((process) => process.owner === 'external' && !isWindowsDesktopProcess(process));
+    const rawOtherAppBytes = otherAppProcesses.reduce((sum, process) => sum + process.dedicatedBytes, 0);
+    const allowedOverage = Math.max(PROCESS_RECONCILIATION_ABSOLUTE_TOLERANCE_BYTES, otherBytes * PROCESS_RECONCILIATION_RELATIVE_TOLERANCE);
+    // A badly inconsistent sample is not rescued through aggressive scaling.
+    // Keep the Gezel attribution, but leave the remainder to the bar's Other
+    // bucket instead of inventing a plausible-looking application breakdown.
+    if (rawOtherAppBytes > otherBytes + allowedOverage) {
+        return {
+            processes: reconciledEngines.sort((a, b) => b.dedicatedBytes - a.dedicatedBytes),
+            observedGezelBytes,
+        };
+    }
+    const appScale = rawOtherAppBytes > otherBytes && rawOtherAppBytes > 0 ? otherBytes / rawOtherAppBytes : 1;
+    const reconciledApps = scaleGpuProcesses(otherAppProcesses, appScale);
+    const reconciledAppBytes = reconciledApps.reduce((sum, process) => sum + process.dedicatedBytes, 0);
+    const desktopBytes = Math.max(0, otherBytes - reconciledAppBytes);
+    const desktopSource = desktopProcesses[0];
+    const desktop = desktopSource && desktopBytes >= PROCESS_BREAKDOWN_MIN_BYTES
+        ? [
+            {
+                pid: desktopSource.pid,
+                name: 'Windows Desktop',
+                dedicatedBytes: desktopBytes,
+                owner: 'external',
+                ...(desktopProcesses.length === 1 && desktopSource.adapterLuid
+                    ? { adapterLuid: desktopSource.adapterLuid }
+                    : {}),
+            },
+        ]
+        : [];
+    return {
+        processes: [...reconciledEngines, ...reconciledApps, ...desktop].sort((a, b) => b.dedicatedBytes - a.dedicatedBytes),
+        observedGezelBytes,
+    };
+}
+/**
+ * Combine stable capacity detection, cached accelerator health, and cheap OS
+ * RAM counters into the live memory strip's portable wire shape.
+ *
+ * Driver telemetry reliably gives aggregate GPU use. On Windows, the bundled
+ * helper also reads process memory (the OS GPU Process Memory counter on
+ * Windows, NVML on NVIDIA Linux) and classifies Gezel's supervised engine
+ * processes; on macOS, physical-footprint sampling observes gezeld and
+ * same-home engines, including Metal allocations. Other hosts fall back to
+ * the broker reservation + daemon RSS.
+ *
+ * A discrete card uses process accounting when available and otherwise keeps
+ * the older reservation estimate clearly approximate. The reservation itself
+ * still travels separately as `engineReservedBytes`: it spans VRAM and a
+ * system-RAM share and must never be presented as measured placement.
+ */
+export function sampleMachineMemoryUsage(opts) {
+    const profile = opts.profile;
+    const totalRamBytes = profile.totalRamBytes;
+    const unified = profile.source === 'darwin-unified' ||
+        profile.source === 'gpu-integrated' ||
+        profile.gpuMemoryKind === 'unified';
+    const mainMemory = opts.forceMainMemory === true || profile.source === 'system-ram-fallback' || unified;
+    const engineBytes = finiteNonNegative(opts.engineCommittedBytes);
+    const engineModelWeightsBytes = finiteNonNegative(opts.engineModelWeightsBytes);
+    const engineBudgetBytes = typeof opts.engineBudgetBytes === 'number' && Number.isFinite(opts.engineBudgetBytes)
+        ? Math.max(0, opts.engineBudgetBytes)
+        : null;
+    const residentModels = opts.residentModels ?? [];
+    const sampledAt = opts.sampledAt ?? new Date().toISOString();
+    if (mainMemory) {
+        const freeRamBytes = clamp(finiteNonNegative(opts.darwinSystemMemory?.freeBytes ?? opts.freeRamBytes ?? freemem()), 0, totalRamBytes);
+        const cachedBytes = opts.darwinSystemMemory
+            ? clamp(finiteNonNegative(opts.darwinSystemMemory.cachedBytes), 0, totalRamBytes - freeRamBytes)
+            : null;
+        const usedBytes = Math.max(0, totalRamBytes - freeRamBytes - (cachedBytes ?? 0));
+        const serviceRssBytes = finiteNonNegative(opts.serviceRssBytes ?? process.memoryUsage().rss);
+        const observedBytes = opts.gezelProcessMemory &&
+            Number.isFinite(opts.gezelProcessMemory.bytes) &&
+            opts.gezelProcessMemory.bytes >= 0
+            ? clamp(opts.gezelProcessMemory.bytes, 0, usedBytes)
+            : null;
+        const gezelBytesEstimated = clamp(engineBytes + serviceRssBytes, 0, usedBytes);
+        const gezelBytesAttributed = observedBytes ?? gezelBytesEstimated;
+        const breakdown = splitGezelMemory({
+            attributedBytes: gezelBytesAttributed,
+            engineReservedBytes: engineBytes,
+            modelWeightsBytes: engineModelWeightsBytes,
+            coreFloorBytes: serviceRssBytes,
+        });
+        return {
+            kind: opts.forceMainMemory === true && !unified ? 'ram' : 'unified',
+            totalBytes: totalRamBytes,
+            usedBytes,
+            gezelBytesEstimated,
+            gezelBytesObserved: observedBytes,
+            ...breakdown,
+            engineReservedBytes: engineBytes,
+            engineBudgetBytes,
+            residentModels,
+            ...(opts.engineLifecycles ? { engineLifecycles: opts.engineLifecycles } : {}),
+            gezelEngineProcessCount: opts.gezelProcessMemory?.engineProcessCount ?? 0,
+            orphanedGezelEngineProcessCount: opts.gezelProcessMemory?.orphanedEngineProcessCount ?? 0,
+            otherBytes: Math.max(0, usedBytes - gezelBytesAttributed),
+            cachedBytes,
+            freeBytes: freeRamBytes,
+            sampledAt,
+            source: 'system-memory',
+            deviceNames: [],
+        };
+    }
+    const memoryReadings = (opts.deviceHealth?.readings ?? []).filter((reading) => typeof reading.memoryTotalMb === 'number' &&
+        Number.isFinite(reading.memoryTotalMb) &&
+        reading.memoryTotalMb > 0);
+    const measuredTotalBytes = memoryReadings.length > 0
+        ? memoryReadings.reduce((sum, reading) => sum + (reading.memoryTotalMb ?? 0), 0) * 1024 ** 2
+        : null;
+    const totalBytes = measuredTotalBytes ?? profile.gpuVramBytes ?? 0;
+    const hasCompleteUsedReading = memoryReadings.length > 0 &&
+        memoryReadings.every((reading) => typeof reading.memoryUsedMb === 'number' &&
+            Number.isFinite(reading.memoryUsedMb) &&
+            reading.memoryUsedMb >= 0);
+    const usedBytes = hasCompleteUsedReading
+        ? clamp(memoryReadings.reduce((sum, reading) => sum + (reading.memoryUsedMb ?? 0), 0) * 1024 ** 2, 0, totalBytes)
+        : null;
+    // Only a measured pool figure can bound what we attribute to Gezel here.
+    // Without one there is nothing to clamp against but the card's own
+    // capacity, and the reservation exceeds that as soon as a second model
+    // loads — which drew a full bar and a "Gezel ~31.9 GiB" legend on a card
+    // holding a single 5.5 GiB model. Report nothing rather than the total.
+    // A broker reservation spans VRAM and a system-RAM share, so it is not a
+    // fallback measurement of this card. Without OS process accounting, leave
+    // attribution unknown (zero here, with the reservation shown separately).
+    const gezelBytesEstimated = 0;
+    const supervisedEnginePids = new Set((opts.engineLifecycles ?? [])
+        .filter((lifecycle) => lifecycle.running &&
+        typeof lifecycle.pid === 'number' &&
+        Number.isInteger(lifecycle.pid) &&
+        lifecycle.pid > 0)
+        .map((lifecycle) => lifecycle.pid));
+    const rawGpuProcesses = (opts.deviceHealth?.processes ?? [])
+        .filter((process) => Number.isInteger(process.pid) &&
+        process.pid > 0 &&
+        Number.isFinite(process.dedicatedBytes) &&
+        process.dedicatedBytes >= 0)
+        .map((process) => process.owner === 'external' && supervisedEnginePids.has(process.pid)
+        ? { ...process, owner: 'gezel-engine' }
+        : { ...process });
+    const sources = opts.deviceHealth?.sources ?? [];
+    const hasWindowsProcessAccounting = sources.includes(WINDOWS_PROCESS_LOCAL_MEMORY_SOURCE);
+    const hasMeasuredProcessAccounting = sources.includes(NVML_PROCESS_MEMORY_SOURCE);
+    const processAccountingAvailable = rawGpuProcesses.length > 0 && (hasWindowsProcessAccounting || hasMeasuredProcessAccounting);
+    const windowsAttribution = usedBytes !== null && processAccountingAvailable && hasWindowsProcessAccounting
+        ? reconcileWindowsGpuProcesses(rawGpuProcesses, usedBytes)
+        : null;
+    const gpuProcesses = windowsAttribution
+        ? windowsAttribution.processes
+        : hasMeasuredProcessAccounting
+            ? rawGpuProcesses
+            : [];
+    const observedGezelBytes = windowsAttribution
+        ? windowsAttribution.observedGezelBytes
+        : usedBytes !== null && processAccountingAvailable
+            ? clamp(gpuProcesses
+                .filter((process) => process.owner !== 'external')
+                .reduce((sum, process) => sum + process.dedicatedBytes, 0), 0, usedBytes)
+            : null;
+    const gezelBytesAttributed = observedGezelBytes ?? gezelBytesEstimated;
+    const breakdown = splitGezelMemory({
+        attributedBytes: gezelBytesAttributed,
+        engineReservedBytes: engineBytes,
+        modelWeightsBytes: engineModelWeightsBytes,
+        coreFloorBytes: 0,
+    });
+    const deviceNames = [
+        ...new Set(memoryReadings
+            .map((reading) => reading.name?.trim())
+            .filter((name) => !!name)),
+    ];
+    return {
+        kind: 'vram',
+        totalBytes,
+        usedBytes,
+        gezelBytesEstimated,
+        gezelBytesObserved: observedGezelBytes,
+        ...(processAccountingAvailable
+            ? {
+                processAttributionKind: hasWindowsProcessAccounting
+                    ? 'estimated'
+                    : 'measured',
+            }
+            : {}),
+        ...breakdown,
+        engineReservedBytes: engineBytes,
+        engineBudgetBytes,
+        residentModels,
+        ...(opts.engineLifecycles ? { engineLifecycles: opts.engineLifecycles } : {}),
+        ...(gpuProcesses.length > 0 ? { gpuProcesses } : {}),
+        gezelEngineProcessCount: new Set(gpuProcesses.filter((process) => process.owner !== 'external').map((process) => process.pid)).size,
+        orphanedGezelEngineProcessCount: 0,
+        otherBytes: usedBytes === null ? null : Math.max(0, usedBytes - gezelBytesAttributed),
+        cachedBytes: null,
+        freeBytes: usedBytes === null ? null : Math.max(0, totalBytes - usedBytes),
+        sampledAt,
+        source: memoryReadings.length > 0 ? 'device-health' : 'capacity-only',
+        deviceNames,
+    };
+}
+/**
+ * Collapse the engine pool's per-replica entries into one row per model,
+ * heaviest first. Clones of the same model share a row because a reader
+ * looking for "what is holding my memory" wants the model named once with
+ * its whole reservation, not N lines that differ only by replica index.
+ */
+export function summarizeResidentModels(entries) {
+    const byModel = new Map();
+    for (const entry of entries) {
+        const key = `${entry.provider}:${entry.modelId}`;
+        const existing = byModel.get(key);
+        const bytes = finiteNonNegative(entry.residentBytes);
+        if (existing) {
+            existing.reservedBytes += bytes;
+            existing.replicaCount += 1;
+            continue;
+        }
+        byModel.set(key, {
+            provider: entry.provider,
+            modelId: entry.modelId,
+            reservedBytes: bytes,
+            replicaCount: 1,
+        });
+    }
+    return [...byModel.values()].sort((a, b) => b.reservedBytes - a.reservedBytes || a.modelId.localeCompare(b.modelId));
+}
+/**
+ * Split the Gezel-attributed total without claiming unavailable precision.
+ * Installed payload size is our weights estimate; the capacity reservation's
+ * remainder covers KV + compute buffers. On UMA/RAM, daemon RSS is protected
+ * first and any observed footprint beyond the reservation remains core/runtime
+ * overhead. Every output is clamped so the three pieces always sum to the
+ * attributed total, even when an observed sample is below the reservation.
+ */
+function splitGezelMemory(opts) {
+    const attributedBytes = finiteNonNegative(opts.attributedBytes);
+    const coreFloorBytes = clamp(finiteNonNegative(opts.coreFloorBytes), 0, attributedBytes);
+    const modelBudget = Math.max(0, attributedBytes - coreFloorBytes);
+    const engineBytes = clamp(finiteNonNegative(opts.engineReservedBytes), 0, modelBudget);
+    // If installed metadata is unavailable, count the reservation as weights.
+    // This avoids inventing a cache split and still keeps the total truthful.
+    const weightEstimate = opts.modelWeightsBytes > 0 ? finiteNonNegative(opts.modelWeightsBytes) : engineBytes;
+    const gezelModelWeightsBytes = clamp(weightEstimate, 0, engineBytes);
+    const gezelModelCacheBytes = Math.max(0, engineBytes - gezelModelWeightsBytes);
+    const gezelInfraBytes = Math.max(0, attributedBytes - gezelModelWeightsBytes - gezelModelCacheBytes);
+    return { gezelInfraBytes, gezelModelWeightsBytes, gezelModelCacheBytes };
+}
+function finiteNonNegative(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? Math.max(0, value) : 0;
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+/**
+ * Parse the stable `name,memory.total` CSV emitted by nvidia-smi.
+ *
+ * A unified-memory device has no framebuffer of its own, and the GB10 / DGX
+ * Spark reports its memory as `[N/A]`. Its pool IS system RAM, so
+ * `systemRamBytes` stands in for it. Rejecting that line used to drop the
+ * Spark through to the Vulkan probe, which calls it discrete: the capacity
+ * budget then counted the same 128 GB twice (RAM share + "VRAM", 211 GiB) and
+ * held back only ~3 GiB for the OS, so a 95 GB chat model and a 10 GB image
+ * model were co-admitted and the image engine died with a CUDA OOM at init.
+ */
+export function parseNvidiaMemoryProbe(stdout, systemRamBytes = totalmem()) {
+    const devices = [];
+    for (const rawLine of stdout.split(/\r?\n/)) {
+        // GPU names can theoretically contain commas. Split on the final field,
+        // whose nounits form is an integer MiB value or a bracketed placeholder.
+        const match = /^(.*),\s*(\d+|\[[^\]]*\])\s*$/.exec(rawLine.trim());
+        if (!match)
+            continue;
+        const name = match[1]?.trim() ?? '';
+        if (!name)
+            continue;
+        const memoryMiB = Number.parseInt(match[2] ?? '', 10);
+        if (Number.isFinite(memoryMiB) && memoryMiB > 0) {
+            devices.push({ name, bytes: memoryMiB * 1024 * 1024 });
+        }
+        else if (isKnownUnifiedNvidiaDevice(name) && systemRamBytes > 0) {
+            devices.push({ name, bytes: systemRamBytes });
+        }
+    }
+    if (devices.length === 0)
+        return null;
+    const unified = devices.every((device) => isKnownUnifiedNvidiaDevice(device.name));
+    return {
+        vramBytes: devices.reduce((sum, device) => sum + device.bytes, 0),
+        largestDeviceBytes: Math.max(...devices.map((device) => device.bytes)),
+        memoryKind: unified ? 'unified' : 'discrete',
+        deviceNames: devices.map((device) => device.name),
+    };
+}
+function isKnownUnifiedNvidiaDevice(name) {
+    const normalized = name.toLowerCase();
+    return /\bgb10\b/.test(normalized) || normalized.includes('dgx spark');
+}
+async function probeNvidiaMemory() {
+    try {
+        const { stdout } = await exec('nvidia-smi', ['--query-gpu=name,memory.total', '--format=csv,noheader,nounits'], 
+        // Keep this short-lived console probe invisible without detaching it
+        // from the daemon that owns and awaits it.
+        { timeout: 2000, ...windowsHeadlessSpawnOptions() });
+        return parseNvidiaMemoryProbe(stdout);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/transformers-cache.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Shared cache-dir pinning for every `@huggingface/transformers` consumer
+ * in the service (kokoro TTS + memory embeddings).
+ *
+ * transformers.js v3 derives its model cache dir from the transformers
+ * module's OWN on-disk location (`<module>/../.cache/`) and has NO env-var
+ * override — it ignores `TRANSFORMERS_CACHE`. In a packaged/bundled runtime
+ * that directory isn't writable, so a downloaded model never lands as a
+ * cached file and the Node ONNX path-resolver throws "Unable to get model
+ * file path or buffer". Pinning `env.cacheDir` to a writable, gezel-managed
+ * dir before the first `from_pretrained` / `pipeline` call fixes it.
+ *
+ * Both consumers import the same ESM-node transformers build
+ * (`transformers.node.mjs`), so the `env` object we mutate here is the one
+ * the model loader reads `cacheDir` from at download time.
+ */
+/**
+ * Env var carrying the resolved cache dir to processes that don't otherwise
+ * know the gezel home — notably the embed worker thread, which inherits
+ * `process.env` at spawn. Set once at service boot.
+ */
+export declare const HF_CACHE_DIR_ENV = "GEZEL_HF_CACHE_DIR";
+/** Shared writable HF/transformers cache root for on-device model files. */
+export declare function transformersCacheDir(home: string): string;
+/** The optional peer both TTS and memory embeddings load lazily. */
+export declare const TRANSFORMERS_MODULE = "@huggingface/transformers";
+export interface TransformersModelCacheLockOptions {
+    timeoutMs?: number;
+    staleMs?: number;
+    pollMs?: number;
+}
+/**
+ * Serialize first-use model downloads across service/Vitest processes sharing
+ * one transformers cache. `pipelinePromise` prevents duplicate loads inside a
+ * process; this directory lock closes the remaining cross-process race where
+ * two fetches could replace the same ONNX file and leave one worker parsing a
+ * partial protobuf.
+ */
+export declare function withTransformersModelCacheLock<T>(cacheDir: string, modelId: string, run: () => Promise<T>, options?: TransformersModelCacheLockOptions): Promise<T>;
+/** Remove only the named repository directory after a proven cache parse failure. */
+export declare function removeTransformersModelCache(cacheDir: string, modelId: string): Promise<void>;
+/** Failures that mean retrying against the same cached bytes cannot succeed. */
+export declare function isCorruptTransformersCacheFailure(error: unknown): boolean;
+/**
+ * Load a model under its cross-process lock, replacing only its repository
+ * cache and retrying once when the first load proves those bytes corrupt.
+ */
+export declare function loadTransformersModelWithCacheRecovery<T>(cacheDir: string, modelId: string, load: () => Promise<T>, onCorrupt?: () => void | Promise<void>): Promise<T>;
+/**
+ * A model file gezel downloaded itself did not arrive whole or did not match
+ * its pin. Nothing was written to the cache path, so a later attempt starts
+ * clean.
+ */
+export declare class ModelFileDownloadError extends Error {
+    constructor(message: string);
+}
+/** One repository file whose exact bytes are pinned. */
+export interface PinnedModelFile {
+    /** Repo-relative path, e.g. `onnx/model.onnx`. */
+    file: string;
+    /** `sha256:<hex>` the bytes must hash to. */
+    digest: string;
+    /** Revision the bytes are fetched from. The cache path is `main`'s, as transformers reads it. */
+    revision: string;
+}
+/** Where transformers.js would download from (`env.remoteHost` / `env.remotePathTemplate`). */
+export interface ModelFileSource {
+    remoteHost: string;
+    remotePathTemplate: string;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Make sure a pinned model file sits in the transformers cache whole.
+ *
+ * transformers.js streams a download straight into its final cache path and
+ * hands that path to onnxruntime, so a reader that arrives mid-write parses
+ * part of a protobuf. The failure was wild-caught on first-run installs over
+ * slower connections: two "Protobuf parsing failed" loads, then vector memory
+ * off for the whole session, while the file finished correctly moments later.
+ * Here the bytes land in a sibling temp file, are checked against the pin,
+ * and appear at the cache path only by an atomic rename, so transformers
+ * finds a complete file and never downloads it. Call it under
+ * {@link withTransformersModelCacheLock}.
+ */
+export declare function ensureVerifiedModelFile(cacheDir: string, modelId: string, pinned: PinnedModelFile, source: ModelFileSource): Promise<'cached' | 'downloaded'>;
+/**
+ * True when Node is reporting that `specifier` itself is not installed, rather
+ * than the package being present and failing to load.
+ *
+ * `@huggingface/transformers` and `kokoro-js` are optional peers that an
+ * ordinary npm install omits, so absence is a supported configuration and must
+ * be distinguishable from breakage before anything picks a log level. Matched
+ * on the resolver's error code plus the specifier it names, not on a substring
+ * of the message: a genuine failure *inside* transformers also mentions the
+ * package, and used to be misreported as "not installed".
+ */
+export declare function isMissingModule(err: unknown, specifier: string): boolean;
+/** The mutable subset of transformers' `env` we touch. */
+export interface TransformersEnv {
+    cacheDir: string;
+    useFSCache: boolean;
+    allowRemoteModels: boolean;
+}
+export type LoadTransformersEnv = () => Promise<TransformersEnv>;
+/**
+ * Point transformers.js at `cacheDir` (and repair the fetch/Response global
+ * mismatch that otherwise defeats its cache). Idempotent per dir, and
+ * best-effort: on failure we log and let the caller proceed on the upstream
+ * default rather than hard-failing (worst case the original bug resurfaces,
+ * which is no worse than not calling this).
+ */
+export declare function pinTransformersCacheDir(cacheDir: string, loadEnv?: LoadTransformersEnv): Promise<void>;