@bendyline/gezel-inference 1.0.1 → 1.0.2

package/dist/providers/native/capacity-broker.js

@@ -151,12 +151,16 @@ export class CapacityBroker {
     systemRamBytes;
     unifiedMemory;
     gpuVramBytes;
+    reservedGpuBytes;
+    gpuAddressableBytes;
     explicitAllowRamSpillover;
     reservations = new Map();
     constructor(opts = {}) {
         this.systemRamBytes = (opts.systemRamBytes ?? totalmem)();
         this.unifiedMemory = opts.unifiedMemory;
         this.gpuVramBytes = opts.gpuVramBytes;
+        this.reservedGpuBytes = opts.reservedGpuBytes;
+        this.gpuAddressableBytes = opts.gpuAddressableBytes;
         this.explicitAllowRamSpillover = opts.allowRamSpillover ?? null;
         this.explicitBudgetBytes = opts.budgetBytes ?? null;
         // Assigned by applyBudget; the definite-assignment dance TS wants for
@@ -189,6 +193,12 @@ export class CapacityBroker {
                 : {
                     ...(this.unifiedMemory === undefined ? {} : { unifiedMemory: this.unifiedMemory }),
                     ...(this.gpuVramBytes === undefined ? {} : { gpuVramBytes: this.gpuVramBytes }),
+                    ...(this.reservedGpuBytes === undefined
+                        ? {}
+                        : { reservedGpuBytes: this.reservedGpuBytes }),
+                    ...(this.gpuAddressableBytes === undefined
+                        ? {}
+                        : { gpuAddressableBytes: this.gpuAddressableBytes }),
                 }),
         });
     }
@@ -714,11 +724,9 @@ function envGrowthCeilingTokens() {
     return Number.isFinite(tokens) && tokens > 0 ? tokens : null;
 }
 /**
- * The most KV cache an automatic choice plans for one llama.cpp engine:
- * adaptive growth stops here, and the Gemma `--swa-full` auto-default is
- * declined when its full-size cache would pass it. Explicit settings (a
- * numeric context, a pinned `swaFull`) are the operator's call and bypass it;
- * it never shortens the ladder-settled base window either.
+ * The most KV cache adaptive growth plans for one llama.cpp engine. An
+ * explicit numeric context is the operator's call and skips growth
+ * altogether, and the ceiling never shortens the ladder-settled base window.
  *
  * Past this a bigger cache buys nothing: llama.cpp's prefill and decode cost
  * follows the tokens actually present, not the reservation, so the rest only
@@ -959,11 +967,9 @@ export const ADAPTIVE_GROWTH_TRADE_MIN_GAIN = 1.25;
  * settled slots and granted the un-grown request.
  *
  * Deliberately a second clamp pass rather than a bigger first request:
- * the first ladder pass sizes slot ceilings, the `--swa-full` fit verdict,
- * and RAM-spillover admission, all of which must stay anchored on the
- * practical 64K target — growing the request there would decline
- * `--swa-full` for models whose full cache fits at 64K and grow KV into
- * system-RAM spill on discrete cards.
+ * the first ladder pass sizes slot ceilings and RAM-spillover admission,
+ * both of which must stay anchored on the practical 64K target — growing
+ * the request there would grow KV into system-RAM spill on discrete cards.
  *
  * Slot trade: when `allowSlotTrade` is set and the target is out of reach
  * at the settled slot count, growth walks the count down — taking the

package/dist/providers/native/capacity-budget.d.ts

@@ -5,7 +5,13 @@
  * VRAM and RAM are common on small discrete-GPU machines, so their ratio is
  * not enough to tell a GeForce from a genuinely shared GB10/iGPU pool.
  */
-export declare function setDetectedGpuVramBytes(bytes: number | null, unifiedMemory?: boolean): void;
+export declare function setDetectedGpuVramBytes(bytes: number | null, unifiedMemory?: boolean, reservedGpuBytes?: number | null, gpuAddressableBytes?: number | null): void;
+/**
+ * What engines may hold of memory an integrated GPU owns or can reach — its
+ * carve-out, or carve-out plus GTT — after the share the desktop it also
+ * drives needs.
+ */
+export declare function usableReservedGpuBytes(reservedGpuBytes: number | null | undefined): number;
 /** The published accelerator-memory figure, or null when none was measured. */
 export declare function getDetectedGpuVramBytes(): number | null;
 /**
@@ -26,13 +32,19 @@ export interface CapacityBudget {
     budgetBytes: number;
     /**
      * The FAST pool inside that budget: usable VRAM on a discrete card, the
-     * whole budget on unified / CPU hosts. Size KV slots and prompt caches
+     * whole budget on unified / CPU hosts — except an integrated GPU that can
+     * reach less than that (Linux GTT; see
+     * {@link CapacityBudgetInput.gpuAddressableBytes}). Size KV slots and prompt caches
      * against this, not against {@link budgetBytes} — on a discrete card the
      * rest of the budget is system RAM that weights stream from, and putting
      * more KV there than the card holds is how a GPU OOMs.
      */
     fastBytes: number;
-    /** Usable VRAM on a discrete card; 0 on unified / CPU-only hosts. */
+    /**
+     * Usable VRAM on a discrete card. On a unified host, the usable part of an
+     * integrated GPU's firmware carve-out — memory the GPU owns that free-RAM
+     * readings never include — and 0 when there is none. 0 on CPU-only hosts.
+     */
     vramBytes: number;
     /** The system-RAM share of the budget. */
     ramShareBytes: number;
@@ -59,6 +71,26 @@ export interface CapacityBudgetInput {
      */
     gpuVramBytes?: number | null;
     unifiedMemory?: boolean;
+    /**
+     * Memory firmware sets aside for an integrated GPU (an AMD "UMA frame
+     * buffer"): carved out before the OS counts RAM, so it is NOT inside
+     * `systemRamBytes`, and only the GPU can use it. Credited on a unified host
+     * only — an engine on the CPU build cannot reach it. Without this, raising
+     * the carve-out shrank the budget: the bytes left the RAM figure and were
+     * counted nowhere. Omit to fall back to the last published probe, under the
+     * same rule as `gpuVramBytes`.
+     */
+    reservedGpuBytes?: number | null;
+    /**
+     * The most memory an integrated GPU can reach: on Linux amdgpu, its
+     * carve-out plus GTT, the window of system RAM the kernel lets it map
+     * (half of RAM by default). Caps the FAST pool on a unified host — the GPU
+     * cannot hold more KV or weights than this, whatever the RAM share says —
+     * while the admission budget keeps the rest for layers the CPU runs. Omit
+     * to fall back to the last published probe, under the same rule as
+     * `gpuVramBytes`.
+     */
+    gpuAddressableBytes?: number | null;
 }
 /**
  * Resolve the memory a host can give resident local engines, per pool.

package/dist/providers/native/capacity-budget.js

@@ -67,6 +67,13 @@ const VRAM_USABLE_FRACTION = 0.95;
  * bytes, so those hosts take the unified curve instead.
  */
 const UNIFIED_VRAM_RATIO = 0.75;
+/**
+ * Held back from an integrated GPU's firmware carve-out (see
+ * {@link CapacityBudgetInput.reservedGpuBytes}) for the desktop it also
+ * drives. The discrete card's 5% margin is too thin here: on a 512 MiB
+ * carve-out it would leave the compositor 25 MiB.
+ */
+const CARVE_OUT_DISPLAY_RESERVE_BYTES = 512 * 1024 ** 2;
 /**
  * Last accelerator-memory figure `detectMemoryProfile` measured on this host,
  * or null when nothing has probed yet / no GPU memory figure was published.
@@ -81,6 +88,8 @@ const UNIFIED_VRAM_RATIO = 0.75;
  */
 let detectedGpuVramBytes = null;
 let detectedGpuUnifiedMemory;
+let detectedGpuReservedBytes = null;
+let detectedGpuAddressableBytes = null;
 /**
  * Publish the measured accelerator pool. Called by `detectMemoryProfile`.
  *
@@ -88,10 +97,26 @@ let detectedGpuUnifiedMemory;
  * VRAM and RAM are common on small discrete-GPU machines, so their ratio is
  * not enough to tell a GeForce from a genuinely shared GB10/iGPU pool.
  */
-export function setDetectedGpuVramBytes(bytes, unifiedMemory) {
-    detectedGpuVramBytes =
-        typeof bytes === 'number' && Number.isFinite(bytes) && bytes > 0 ? bytes : null;
+export function setDetectedGpuVramBytes(bytes, unifiedMemory, reservedGpuBytes, gpuAddressableBytes) {
+    detectedGpuVramBytes = positiveOrNull(bytes);
     detectedGpuUnifiedMemory = unifiedMemory;
+    detectedGpuReservedBytes = positiveOrNull(reservedGpuBytes);
+    detectedGpuAddressableBytes = positiveOrNull(gpuAddressableBytes);
+}
+function positiveOrNull(bytes) {
+    return typeof bytes === 'number' && Number.isFinite(bytes) && bytes > 0 ? bytes : null;
+}
+/**
+ * What engines may hold of memory an integrated GPU owns or can reach — its
+ * carve-out, or carve-out plus GTT — after the share the desktop it also
+ * drives needs.
+ */
+export function usableReservedGpuBytes(reservedGpuBytes) {
+    const reserved = positiveOrNull(reservedGpuBytes);
+    if (reserved === null)
+        return 0;
+    const display = Math.max(CARVE_OUT_DISPLAY_RESERVE_BYTES, Math.ceil(reserved * (1 - VRAM_USABLE_FRACTION)));
+    return Math.max(0, reserved - display);
 }
 /** The published accelerator-memory figure, or null when none was measured. */
 export function getDetectedGpuVramBytes() {
@@ -144,6 +169,16 @@ export function computeCapacityBudget(input = {}) {
     const sharedPool = hasCard && measuredVram >= systemRamBytes * UNIFIED_VRAM_RATIO;
     const unified = measuredUnifiedMemory ?? (isUnifiedMemoryHost() || sharedPool);
     const discrete = hasCard && !unified;
+    const reservedGpuBytes = input.reservedGpuBytes !== undefined
+        ? input.reservedGpuBytes
+        : input.unifiedMemory === undefined && input.gpuVramBytes === undefined
+            ? detectedGpuReservedBytes
+            : null;
+    const gpuAddressableBytes = input.gpuAddressableBytes !== undefined
+        ? input.gpuAddressableBytes
+        : input.unifiedMemory === undefined && input.gpuVramBytes === undefined
+            ? detectedGpuAddressableBytes
+            : null;
     const highMemory = systemRamBytes >= HIGH_MEMORY_THRESHOLD_BYTES;
     // Whichever bound leaves the host MORE memory wins between the fraction and
     // the capped reserve, then the 4 GiB floor reserve caps them both. Written
@@ -153,7 +188,11 @@ export function computeCapacityBudget(input = {}) {
     const unifiedShare = Math.max(0, Math.min(Math.max(unifiedFractionShare, systemRamBytes - UNIFIED_OS_RESERVE_MAX_BYTES), systemRamBytes - UNIFIED_OS_RESERVE_BYTES));
     const nonUnifiedShare = Math.min(Math.floor(systemRamBytes * (highMemory ? 0.8 : 0.6)), BUDGET_CAP_BYTES);
     const ramShareBytes = unified ? unifiedShare : nonUnifiedShare;
-    const vramBytes = discrete ? Math.floor(measuredVram * VRAM_USABLE_FRACTION) : 0;
+    const vramBytes = discrete
+        ? Math.floor(measuredVram * VRAM_USABLE_FRACTION)
+        : unified
+            ? usableReservedGpuBytes(reservedGpuBytes)
+            : 0;
     // The pre-cap curve, retained for slot sizing only.
     const concurrencyRamShare = unified
         ? Math.max(0, Math.min(unifiedFractionShare, systemRamBytes - UNIFIED_OS_RESERVE_BYTES, BUDGET_CAP_BYTES))
@@ -175,7 +214,12 @@ export function computeCapacityBudget(input = {}) {
             overriddenByEnv: true,
         };
     }
-    const fastBytes = discrete ? vramBytes : auto;
+    const addressable = positiveOrNull(gpuAddressableBytes);
+    const fastBytes = discrete
+        ? vramBytes
+        : unified && addressable !== null
+            ? Math.min(auto, usableReservedGpuBytes(addressable))
+            : auto;
     return {
         budgetBytes: auto,
         fastBytes,

package/dist/providers/native/device-capacity.d.ts

@@ -73,7 +73,7 @@ export declare function configuredEngineMemoryBytes(config: {
  * download pages hide is exactly one the launch path refuses. Omit
  * `configuredBytes` for the machine's automatic ceilings.
  */
-export declare function staticCapacityCeilings(budget: Pick<CapacityBudget, 'budgetBytes' | 'fastBytes' | 'kind'>, ramBytes: number, configuredBytes?: number): {
+export declare function staticCapacityCeilings(budget: Pick<CapacityBudget, 'budgetBytes' | 'fastBytes' | 'kind' | 'vramBytes'>, ramBytes: number, configuredBytes?: number, platform?: NodeJS.Platform): {
     budgetBytes: number;
     gpuBudgetBytes: number;
 };

package/dist/providers/native/device-capacity.js

@@ -2,7 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { readdir, stat } from 'node:fs/promises';
 import { homedir, totalmem } from 'node:os';
 import { join } from 'node:path';
-import { GEZEL_VERSION, NativeCapacityCommandSchema, NativeCapacityReplySchema, awakeNow, createLogger, isUnstampedDevBuild, } from '@bendyline/gezel';
+import { DS4_FULL_RESIDENCY_HEADROOM_BYTES, GEZEL_VERSION, NativeCapacityCommandSchema, NativeCapacityReplySchema, awakeNow, createLogger, isUnstampedDevBuild, } from '@bendyline/gezel';
 import { readSystemServiceRuntime, systemServiceHome } from '@bendyline/gezel-client/node';
 import { ConfigStore } from '../../fs/config-store.js';
 import { createPinnedFetch } from '../../remotes/pinned-fetch.js';
@@ -119,21 +119,39 @@ export function configuredEngineMemoryBytes(config) {
         ? config.localEngineMemoryGb * GIB
         : undefined;
 }
+/**
+ * GPU bytes a unified host may commit to one launch. macOS keeps 0.75 × RAM,
+ * near where Metal's recommended GPU working set sits. Linux unified hosts
+ * (DGX Spark GB10) have no such limit, so a large one may commit all but the
+ * OS reserve ds4's residency gate keeps: on a 121.6 GiB Spark, 0.75 × RAM
+ * (91.2 GiB) refused a GLM 5.3 Q2 launch that runs at 105 GiB with ~9 GiB to
+ * spare. Smaller Linux hosts stay on the 0.75 curve, which is the larger one there.
+ */
+function unifiedGpuCeilingBytes(ramBytes, platform) {
+    const curve = ramBytes * 0.75;
+    return platform === 'linux'
+        ? Math.max(curve, ramBytes - DS4_FULL_RESIDENCY_HEADROOM_BYTES)
+        : curve;
+}
 /**
  * The ledger's static ceilings: a request above either is refused at acquire,
  * whatever else is running. Shared with the media fit check so a model the
  * download pages hide is exactly one the launch path refuses. Omit
  * `configuredBytes` for the machine's automatic ceilings.
  */
-export function staticCapacityCeilings(budget, ramBytes, configuredBytes) {
+export function staticCapacityCeilings(budget, ramBytes, configuredBytes, platform = process.platform) {
     const budgetBytes = configuredBytes === undefined
         ? budget.budgetBytes
         : Math.min(configuredBytes, budget.budgetBytes);
     return {
         budgetBytes,
-        // Keep non-reclaimable accelerator commitments on the conservative curve;
-        // a larger RAM budget is not permission to wire the whole machine.
-        gpuBudgetBytes: Math.min(budgetBytes, budget.kind === 'unified' ? Math.min(budget.fastBytes, ramBytes * 0.75) : budget.fastBytes),
+        // Non-reclaimable accelerator commitments get their own ceiling: a larger
+        // RAM budget is not permission to wire the whole machine. An integrated
+        // GPU's carve-out (`vramBytes` on a unified host) is already the GPU's,
+        // and sits outside `ramBytes`.
+        gpuBudgetBytes: Math.min(budgetBytes, budget.kind === 'unified'
+            ? Math.min(budget.fastBytes, unifiedGpuCeilingBytes(ramBytes, platform) + budget.vramBytes)
+            : budget.fastBytes),
     };
 }
 export async function sampleDeviceCapacity(home) {

package/dist/providers/native/local-engine-runtime.js

@@ -260,6 +260,8 @@ export class LocalEngineRuntime {
                 ? {
                     unifiedMemory: memoryProfile.gpuMemoryKind === 'integrated' ||
                         memoryProfile.gpuMemoryKind === 'unified',
+                    reservedGpuBytes: memoryProfile.gpuReservedBytes ?? null,
+                    gpuAddressableBytes: memoryProfile.gpuAddressableBytes ?? null,
                 }
                 : {}),
             allowRamSpillover: config.allowRamSpillover ?? null,
@@ -1161,7 +1163,7 @@ export class LocalEngineRuntime {
         // engine: the full plan must run so a stale resident window surfaces as
         // restart-required instead of masquerading as the applied setting.
         const shortCircuit = (residentContextWindow !== undefined && !overrideActive) || envNumCtx !== undefined;
-        const { autoKvCacheMaxBytes, defaultLocalEngineSlots, estimatePerSlotKvBytes, kvQuantScale, llamaCppSlotCeiling, planAdaptiveContextGrowth, planCtxTokensForMemory, plannedLocalEngineSlots, } = await import('./capacity-broker.js');
+        const { defaultLocalEngineSlots, estimatePerSlotKvBytes, kvQuantScale, llamaCppSlotCeiling, planAdaptiveContextGrowth, planCtxTokensForMemory, plannedLocalEngineSlots, } = await import('./capacity-broker.js');
         const capacity = await this.previewCapacityInputs('llama-cpp', modelId, capacityOpts);
         const { budgetBytes: admissionBudgetBytes, fastBudgetBytes, committedOtherBytes } = capacity;
         const configuredSlots = config.providerConcurrency?.['llama-cpp'];
@@ -1481,27 +1483,18 @@ export class LocalEngineRuntime {
                     vramBytes: capacity.vramBytes,
                 });
                 // Mirror the launch path's windowed-cache admission (see
-                // buildLlamaCppProvider): when the launch will decline the Gemma
-                // `--swa-full` auto-default (or the windowed cache is pinned), the
-                // full-attention plan above overstates the real allocation — re-plan
-                // with the windowed linearization so the previewed window matches
-                // what the engine will actually grant.
+                // buildLlamaCppProvider): unless `swaFull` is pinned, a
+                // sliding-window model runs the windowed cache, which the
+                // full-attention plan above overstates — re-plan with the windowed
+                // linearization so the previewed window matches what the engine will
+                // actually grant.
                 // Strict model-max deliberately does NOT gate this: for SWA models
                 // the windowed cache is the only layout whose native-window KV can
                 // fit real machines, and the strict minimum rides inside
                 // `requirement.minimumPerTurnCtxTokens`, so the windowed
                 // re-plan sheds slots or denies but never shortens the window.
                 const explicitSwaFull = config.llamaCppSwaFull ?? manifestEngineConfig?.swaFull;
-                const fullCacheOverCeiling = exactKvAtReference !== undefined &&
-                    (exactKvAtReference / referenceCtx) * grantedCtx * slots > autoKvCacheMaxBytes();
-                const windowedCacheWillRun = (!admission.minimumSatisfied ||
-                    admission.clamped ||
-                    admission.slots < slots ||
-                    fullCacheOverCeiling) &&
-                    (explicitSwaFull === false ||
-                        (explicitSwaFull === undefined &&
-                            isGemmaModel({ architecture: installed.architecture, modelId })));
-                if (windowedCacheWillRun) {
+                if (explicitSwaFull !== true) {
                     const windowed = estimateWindowedKvLinearization({
                         blockCount: summary.blockCount,
                         embeddingLength: summary.embeddingLength,
@@ -1541,9 +1534,13 @@ export class LocalEngineRuntime {
                             fixedPerSlotBytes: windowed.fixedBytes,
                         };
                     }
-                    else if ((summary.slidingWindow ?? 0) > 0 || explicitSwaFull === undefined) {
-                        // SWA model without a readable layout: the launch path leaves
-                        // such a launch untouched — preview the requested window.
+                    else if ((!admission.minimumSatisfied || admission.clamped || admission.slots < slots) &&
+                        (explicitSwaFull === false
+                            ? (summary.slidingWindow ?? 0) > 0
+                            : isGemmaModel({ architecture: installed.architecture, modelId }))) {
+                        // SWA model without a readable layout, over budget on full
+                        // math: the launch path leaves such a launch untouched — preview
+                        // the requested window.
                         return { grantedCtx, slots, kvCacheType: kv, plannedFieldsOk: false };
                     }
                 }

package/dist/providers/native/measured-budget.js

@@ -50,5 +50,7 @@ export async function measuredCapacityBudget() {
         systemRamBytes: profile.totalRamBytes,
         gpuVramBytes: profile.gpuVramBytes,
         unifiedMemory: profile.gpuMemoryKind === 'integrated' || profile.gpuMemoryKind === 'unified',
+        reservedGpuBytes: profile.gpuReservedBytes ?? null,
+        gpuAddressableBytes: profile.gpuAddressableBytes ?? null,
     });
 }

package/dist/providers/native/supervisor.d.ts

@@ -158,6 +158,11 @@ export interface NativeEngineSupervisorOptions {
     onLog?: (line: string) => void;
     /** Called for both expected and unexpected exits after a snapshot is sealed. */
     onExit?: (snapshot: NativeEngineExitSnapshot) => void | Promise<void>;
+    /**
+     * Called each time a start reaches readiness. Errors are caught and logged;
+     * a failing hook never fails the start.
+     */
+    onReady?: (launch: NativeEngineLaunch) => void;
     /**
      * Consulted after a start attempt fails (child died or never became
      * ready — not spawn errors, and not crashes after readiness). Return
@@ -214,6 +219,13 @@ export interface NativeEngineSupervisorOptions {
     psRunner?: () => Promise<NativeProcessSnapshot[]>;
     /** Platform seam for Windows owner-liveness semantics in orphan tests. */
     platform?: NodeJS.Platform;
+    /**
+     * The kernel's running count of out-of-memory kills, or null when it
+     * cannot be read. Compared across a child's life to tell Linux's
+     * out-of-memory killer from any other SIGKILL. Defaults to `oom_kill` in
+     * `/proc/vmstat` on Linux (any account can read it) and null elsewhere.
+     */
+    readOomKillCount?: () => number | null;
     /**
      * Test seam paired with `psRunner` — invoked instead of
      * `process.kill(pid, 'SIGKILL')`. Lets unit tests assert which pids
@@ -263,6 +275,7 @@ export declare class NativeEngineSupervisor {
     private readonly fetchImpl;
     private readonly onLog;
     private readonly onExit?;
+    private readonly onReady?;
     private readonly recoverStartup?;
     private readonly onRawLine?;
     private readonly logPrefix;
@@ -271,6 +284,9 @@ export declare class NativeEngineSupervisor {
     private readonly psRunner;
     private readonly killProcess;
     private readonly platform;
+    private readonly readOomKillCount;
+    /** `oom_kill` when the current child spawned; null where it cannot be read. */
+    private currentOomKills;
     private readonly logListeners;
     private recentStarts;
     private lastUsedAt;
@@ -482,6 +498,13 @@ export declare class NativeEngineSupervisor {
      */
     private runFreeze;
     private clearIdleTimer;
+    /**
+     * The counter's movement since `before`, when it rose. Another process
+     * killed in the same window would also move it, but a child that died by a
+     * SIGKILL this supervisor did not send while the counter rose is, in
+     * practice, the one the killer chose.
+     */
+    private oomKillsSince;
     private clearFreezeTimer;
     private clearHealthTimer;
 }
@@ -490,6 +513,8 @@ export declare function classifyNativeEnginePanic(line: string): {
     kind: NativeEnginePanicKind;
     line: string;
 } | undefined;
+/** `oom_kill` from `/proc/vmstat` (Linux 4.13+), or null when it cannot be read. */
+export declare function readLinuxOomKillCount(): number | null;
 /** Parse the portable `ps -axo pid=,ppid=,command=` shape. */
 export declare function parseNativeProcessSnapshot(stdout: string): NativeProcessSnapshot[];
 /** `code` stamped on every engine-launch failure. See {@link isEngineLaunchError}. */

package/dist/providers/native/supervisor.js

@@ -21,6 +21,7 @@
  * so we can drive the lifecycle without a real binary.
  */
 import { spawn as nodeSpawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 import { basename } from 'node:path';
 import { awakeNow, createLogger } from '@bendyline/gezel';
 import { listProcessSnapshots } from '@bendyline/gezel-client/node';
@@ -179,6 +180,7 @@ export class NativeEngineSupervisor {
     fetchImpl;
     onLog;
     onExit;
+    onReady;
     recoverStartup;
     onRawLine;
     logPrefix;
@@ -187,6 +189,9 @@ export class NativeEngineSupervisor {
     psRunner;
     killProcess;
     platform;
+    readOomKillCount;
+    /** `oom_kill` when the current child spawned; null where it cannot be read. */
+    currentOomKills = null;
     // Ad-hoc log listeners attached at runtime (vs. the construction-time
     // `onLog` / `onRawLine` hooks). Used by the owning provider to
     // subscribe to engine log lines for the duration of a single request
@@ -274,6 +279,8 @@ export class NativeEngineSupervisor {
         this.onLog = opts.onLog ?? ((line) => log.info(line));
         if (opts.onExit)
             this.onExit = opts.onExit;
+        if (opts.onReady)
+            this.onReady = opts.onReady;
         if (opts.recoverStartup)
             this.recoverStartup = opts.recoverStartup;
         if (opts.onRawLine)
@@ -282,6 +289,8 @@ export class NativeEngineSupervisor {
         this.readinessPath = opts.readinessPath ?? '/health';
         this.readyOnAnyResponse = opts.readyOnAnyResponse ?? false;
         this.platform = opts.platform ?? process.platform;
+        this.readOomKillCount =
+            opts.readOomKillCount ?? (this.platform === 'linux' ? readLinuxOomKillCount : () => null);
         this.psRunner = opts.psRunner ?? (() => defaultPsRunner(this.platform));
         this.killProcess = opts.killProcess ?? ((pid, sig) => process.kill(pid, sig));
     }
@@ -600,6 +609,7 @@ export class NativeEngineSupervisor {
         this.currentDiagnostics = launch.diagnostics ? { ...launch.diagnostics } : undefined;
         this.currentOutput = '';
         this.currentPanic = undefined;
+        this.currentOomKills = this.readOomKillCount();
         this.expectedExitReason = undefined;
         this.onLog(`${this.logPrefix} launch ${JSON.stringify({
             pid: this.currentPid ?? null,
@@ -698,6 +708,12 @@ export class NativeEngineSupervisor {
             this.state = { kind: 'running', launch, child, healthFails: 0 };
             this.resetIdleTimer();
             this.startHealthWatch();
+            try {
+                this.onReady?.(launch);
+            }
+            catch (hookErr) {
+                this.onLog(`${this.logPrefix} onReady hook threw: ${hookErr instanceof Error ? hookErr.message : hookErr}`);
+            }
         }
         catch (err) {
             // The panic classifier state is cleared by handleExit — read it now,
@@ -998,13 +1014,23 @@ export class NativeEngineSupervisor {
         // the output didn't already explain the death more precisely: an
         // engine that printed `CUDA error: …` and then took SIGILL on the
         // way down is a CUDA fault, not an unrunnable build.
-        const panic = this.currentPanic ??
-            (signal === 'SIGILL'
-                ? {
-                    kind: 'illegal-instruction',
-                    line: 'engine terminated by SIGILL (illegal instruction) with no diagnostic output',
-                }
-                : undefined);
+        // An out-of-memory kill outranks anything the engine printed: a CUDA or
+        // Vulkan allocation line on the way there is a symptom of the same
+        // shortage, and the GPU-to-RAM ladder those lines trigger cannot help
+        // when RAM is what ran out.
+        const oomKilled = signal === 'SIGKILL' && !expected ? this.oomKillsSince(this.currentOomKills) : null;
+        const panic = oomKilled
+            ? {
+                kind: 'host-out-of-memory',
+                line: `engine killed by the Linux out-of-memory killer (oom_kill ${oomKilled.before} -> ${oomKilled.after})`,
+            }
+            : (this.currentPanic ??
+                (signal === 'SIGILL'
+                    ? {
+                        kind: 'illegal-instruction',
+                        line: 'engine terminated by SIGILL (illegal instruction) with no diagnostic output',
+                    }
+                    : undefined));
         const snapshot = {
             incidentId: `native-${pid ?? 'unknown'}-${exitedAt}`,
             ...(pid !== undefined ? { pid } : {}),
@@ -1062,6 +1088,7 @@ export class NativeEngineSupervisor {
         this.currentDiagnostics = undefined;
         this.currentOutput = '';
         this.currentPanic = undefined;
+        this.currentOomKills = null;
         this.expectedExitReason = undefined;
         if (priorState.kind === 'stopped')
             return;
@@ -1313,6 +1340,18 @@ export class NativeEngineSupervisor {
             this.idleTimer = undefined;
         }
     }
+    /**
+     * The counter's movement since `before`, when it rose. Another process
+     * killed in the same window would also move it, but a child that died by a
+     * SIGKILL this supervisor did not send while the counter rose is, in
+     * practice, the one the killer chose.
+     */
+    oomKillsSince(before) {
+        if (before === null)
+            return null;
+        const after = this.readOomKillCount();
+        return after !== null && after > before ? { before, after } : null;
+    }
     clearFreezeTimer() {
         if (this.freezeTimer) {
             clearTimeout(this.freezeTimer);
@@ -1346,6 +1385,9 @@ export function classifyNativeEnginePanic(line) {
     if (/CUDA error:.*device-side assert/i.test(line)) {
         return { kind: 'cuda-device-assert', line: clipped };
     }
+    if (/CUDA error:\s*(?:no kernel image is available|the provided PTX was compiled with an unsupported toolchain)/i.test(line)) {
+        return { kind: 'cuda-unsupported-device', line: clipped };
+    }
     if (/CUDA error:/i.test(line))
         return { kind: 'cuda-error', line: clipped };
     if (/assert(?:ion)? failed|GGML_ASSERT/i.test(line)) {
@@ -1353,6 +1395,16 @@ export function classifyNativeEnginePanic(line) {
     }
     return undefined;
 }
+/** `oom_kill` from `/proc/vmstat` (Linux 4.13+), or null when it cannot be read. */
+export function readLinuxOomKillCount() {
+    try {
+        const match = /^oom_kill (\d+)$/m.exec(readFileSync('/proc/vmstat', 'utf8'));
+        return match?.[1] ? Number(match[1]) : null;
+    }
+    catch {
+        return null;
+    }
+}
 function panicPriority(kind) {
     if (kind === 'cuda-error')
         return 1;

package/dist/system/amdgpu-adapters.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The amdgpu devices Linux describes in sysfs, for the carve-out decision in
+ * gpu-carve-out.ts — the Linux counterpart of the DXCore adapter listing the
+ * device-health helper reads on Windows. Everything read here is
+ * world-readable, so the machine service's unprivileged account sees it too.
+ */
+import type { GpuAdapterFacts } from './gpu-carve-out.js';
+export interface SysfsIo {
+    readFile?: (path: string) => string;
+    readDir?: (path: string) => string[];
+}
+/**
+ * One entry per amdgpu device: `dedicatedBytes` from `mem_info_vram_total`,
+ * `sharedSystemBytes` from `mem_info_gtt_total` (the system RAM the kernel
+ * lets it map). Connector entries (`card0-HDMI-A-1`) and render nodes are
+ * skipped. Empty off Linux, without amdgpu, or when sysfs cannot be read.
+ */
+export declare function readAmdgpuAdapters(io?: SysfsIo): GpuAdapterFacts[];

package/dist/system/amdgpu-adapters.js

@@ -0,0 +1,55 @@
+/**
+ * The amdgpu devices Linux describes in sysfs, for the carve-out decision in
+ * gpu-carve-out.ts — the Linux counterpart of the DXCore adapter listing the
+ * device-health helper reads on Windows. Everything read here is
+ * world-readable, so the machine service's unprivileged account sees it too.
+ */
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+const DRM_ROOT = '/sys/class/drm';
+const AMD_PCI_VENDOR = 0x1002;
+/**
+ * One entry per amdgpu device: `dedicatedBytes` from `mem_info_vram_total`,
+ * `sharedSystemBytes` from `mem_info_gtt_total` (the system RAM the kernel
+ * lets it map). Connector entries (`card0-HDMI-A-1`) and render nodes are
+ * skipped. Empty off Linux, without amdgpu, or when sysfs cannot be read.
+ */
+export function readAmdgpuAdapters(io = {}) {
+    const readFile = io.readFile ?? ((path) => readFileSync(path, 'utf8'));
+    const readDir = io.readDir ?? ((path) => readdirSync(path));
+    const read = (path) => {
+        try {
+            return readFile(path).trim();
+        }
+        catch {
+            return undefined;
+        }
+    };
+    let cards;
+    try {
+        cards = readDir(DRM_ROOT).filter((entry) => /^card\d+$/.test(entry));
+    }
+    catch {
+        return [];
+    }
+    const adapters = [];
+    for (const card of cards) {
+        const device = join(DRM_ROOT, card, 'device');
+        if (Number.parseInt(read(join(device, 'vendor')) ?? '', 16) !== AMD_PCI_VENDOR)
+            continue;
+        const vram = byteCount(read(join(device, 'mem_info_vram_total')));
+        if (vram === undefined)
+            continue;
+        const gtt = byteCount(read(join(device, 'mem_info_gtt_total')));
+        adapters.push({
+            vendorId: AMD_PCI_VENDOR,
+            dedicatedBytes: vram,
+            ...(gtt !== undefined ? { sharedSystemBytes: gtt } : {}),
+        });
+    }
+    return adapters;
+}
+function byteCount(raw) {
+    const value = raw ? Number(raw) : Number.NaN;
+    return Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}