@bendyline/gezel-inference 1.0.1 → 1.0.2

package/dist/knowledge/spatial-query.js

@@ -1,8 +1,7 @@
 /**
  * Radius pagination binds offsets to the authorized catalog snapshot and
  * query. Cursors confer no authority; the manager recalculates scope on
- * every request. Regional replicas share identity only under Qualla's
- * declared regional catalog and source-document naming convention.
+ * every request.
  */
 export class KnowledgeSpatialCursorError extends Error {
 }
@@ -24,10 +23,17 @@ export function nearbyCursorOffset(cursor, snapshot) {
         throw new KnowledgeSpatialCursorError('Invalid or stale nearby cursor; restart the query.');
     }
 }
-export function regionalDocumentIdentity(publisherId, catalogId, documentId) {
-    const regional = catalogId.startsWith('qualla-region-') &&
-        /^qualla-(wikipedia|wikivoyage)-[0-9]+$/.test(documentId);
-    return regional
+/**
+ * Source-article ids (`wikipedia-<page-id>`) name the same article in every
+ * catalog of one publisher, and regional catalogs overlap heavily — Pacific
+ * Northwest and Canada & Alaska share 683 of the former's 1,106 articles — so
+ * those copies are one result. Any other id is unique only within its catalog.
+ * Keyed on the id, not the catalog name: an earlier catalog-name match never
+ * fired for the published `regional-*` catalogs, so every copy came through.
+ */
+const SOURCE_ARTICLE_ID = /^(wikipedia|wikivoyage)-[0-9]+$/;
+export function spatialDocumentIdentity(publisherId, catalogId, documentId) {
+    return SOURCE_ARTICLE_ID.test(documentId)
         ? `${publisherId}\u0000${documentId}`
         : `${publisherId}\u0000${catalogId}\u0000${documentId}`;
 }

package/dist/knowledge/worker-host.js

@@ -141,6 +141,8 @@ export function createWorkerCatalogHost() {
         documentsPage: async (key, opts) => 
         // biome-ignore lint/suspicious/noExplicitAny: structured-clone round trip preserves the shape
         (await call('documentsPage', [key, opts])),
+        documentInitials: async (key, opts) => (await call('documentInitials', [key, opts])),
+        documentPosition: async (key, documentId, opts) => (await call('documentPosition', [key, documentId, opts])),
         nearbyDocuments: async (key, radius, opts) => (await call('nearbyDocuments', [key, radius, opts])),
         getDocument: async (key, documentId) => 
         // biome-ignore lint/suspicious/noExplicitAny: structured-clone round trip preserves the shape

package/dist/memory/embed-core.d.ts

@@ -106,6 +106,22 @@ export declare function isRetryablePipelineLoadFailure(error: unknown): boolean;
  * will not parse is a runtime problem instead, and retrying cannot fix it.
  */
 export declare function isFreshDownloadFailure(error: unknown, graphVerified: boolean): boolean;
+/** Work abandoned because the host asked, at service shutdown. Not a model fault. */
+export declare class ModelWorkCancelledError extends Error {
+    constructor();
+}
+/**
+ * Abandon the model download in flight and stop embedding runs at their next
+ * sub-batch, so the worker reaches idle and can be terminated safely.
+ *
+ * Shutdown cannot simply terminate a busy worker (that aborts the process
+ * inside onnxruntime), and a first-run model download outlasted every drain:
+ * quitting during it held the app for 30 s, until the quit timeout. A download
+ * is plain network I/O, outside onnxruntime, so stopping it is safe; session
+ * creation and a single sub-batch still finish. Work that starts afterwards
+ * gets a fresh signal.
+ */
+export declare function cancelInFlightModelWork(): void;
 /** Lazily create the feature-extraction pipeline; cached for the process. */
 export declare function loadPipeline(): Promise<Pipeline>;
 /**

package/dist/memory/embed-core.js

@@ -191,6 +191,29 @@ export function isFreshDownloadFailure(error, graphVerified) {
 /** Fresh starts after a failed download, per process, before vector memory is switched off. */
 const MAX_FRESH_DOWNLOAD_RETRIES = 3;
 let freshDownloadFailures = 0;
+/** Work abandoned because the host asked, at service shutdown. Not a model fault. */
+export class ModelWorkCancelledError extends Error {
+    constructor() {
+        super('model work was cancelled for shutdown');
+        this.name = 'ModelWorkCancelledError';
+    }
+}
+let cancelController = new AbortController();
+/**
+ * Abandon the model download in flight and stop embedding runs at their next
+ * sub-batch, so the worker reaches idle and can be terminated safely.
+ *
+ * Shutdown cannot simply terminate a busy worker (that aborts the process
+ * inside onnxruntime), and a first-run model download outlasted every drain:
+ * quitting during it held the app for 30 s, until the quit timeout. A download
+ * is plain network I/O, outside onnxruntime, so stopping it is safe; session
+ * creation and a single sub-batch still finish. Work that starts afterwards
+ * gets a fresh signal.
+ */
+export function cancelInFlightModelWork() {
+    cancelController.abort();
+    cancelController = new AbortController();
+}
 /** The daemon pin's ONNX graph, when it names one with a digest. */
 function pinnedGraph() {
     const pin = daemonEmbedderPin();
@@ -203,6 +226,7 @@ let pipelinePromise = null;
 /** Lazily create the feature-extraction pipeline; cached for the process. */
 export async function loadPipeline() {
     if (!pipelinePromise) {
+        const signal = cancelController.signal;
         pipelinePromise = (async () => {
             let graphVerified = false;
             try {
@@ -230,6 +254,7 @@ export async function loadPipeline() {
                         const outcome = await ensureVerifiedModelFile(cacheDir, modelId, graph, {
                             remoteHost: env.remoteHost,
                             remotePathTemplate: env.remotePathTemplate,
+                            signal,
                         });
                         graphVerified = true;
                         if (outcome === 'downloaded')
@@ -241,6 +266,9 @@ export async function loadPipeline() {
                 });
             }
             catch (err) {
+                // Before the retry bookkeeping: a cancelled download is not a failed one.
+                if (signal.aborted)
+                    throw new ModelWorkCancelledError();
                 const missing = isMissingModule(err, TRANSFORMERS_MODULE);
                 const message = missing
                     ? 'Local memory embeddings are an optional npm feature. Install @huggingface/transformers@^4.3.1 alongside @bendyline/gezel-service (see the service README).'
@@ -272,9 +300,12 @@ export async function loadPipeline() {
 export async function runEmbed(texts) {
     if (texts.length === 0)
         return [];
+    const signal = cancelController.signal;
     const pipe = await loadPipeline();
     const out = [];
     for (let i = 0; i < texts.length; i += MAX_BATCH) {
+        if (signal.aborted)
+            throw new ModelWorkCancelledError();
         const slice = texts.slice(i, i + MAX_BATCH).map(capText);
         const result = await pipe(slice, { pooling: 'mean', normalize: true });
         for (const v of result.tolist())

package/dist/memory/embed-worker.d.ts

@@ -11,13 +11,17 @@
  *                                                     with that profile;
  *                                                     reportProgress: send the
  *                                                     model download's bytes
+ *                   { cancel: true }                — shutdown: stop the
+ *                                                     download and runs in flight
  *   worker → host:  { id, progress }                — interim, zero or more
  *                   { id, vectors }                 — success
  *                   { id, error, fatal,             — failure (fatal ⇒ model
- *                     retryable, optionalPeerMissing } unloadable, disable for
- *                                                     good; optionalPeerMissing
+ *                     retryable, optionalPeerMissing, unloadable, disable for
+ *                     cancelled }                     good; optionalPeerMissing
  *                                                     ⇒ the peer is just not
  *                                                     installed; retryable ⇒ a
- *                                                     short host-side cooldown)
+ *                                                     short host-side cooldown;
+ *                                                     cancelled ⇒ stopped by a
+ *                                                     cancel, not a fault)
  */
 export {};

package/dist/memory/embed-worker.js

@@ -11,22 +11,30 @@
  *                                                     with that profile;
  *                                                     reportProgress: send the
  *                                                     model download's bytes
+ *                   { cancel: true }                — shutdown: stop the
+ *                                                     download and runs in flight
  *   worker → host:  { id, progress }                — interim, zero or more
  *                   { id, vectors }                 — success
  *                   { id, error, fatal,             — failure (fatal ⇒ model
- *                     retryable, optionalPeerMissing } unloadable, disable for
- *                                                     good; optionalPeerMissing
+ *                     retryable, optionalPeerMissing, unloadable, disable for
+ *                     cancelled }                     good; optionalPeerMissing
  *                                                     ⇒ the peer is just not
  *                                                     installed; retryable ⇒ a
- *                                                     short host-side cooldown)
+ *                                                     short host-side cooldown;
+ *                                                     cancelled ⇒ stopped by a
+ *                                                     cancel, not a fault)
  */
 import { parentPort } from 'node:worker_threads';
-import { PipelineLoadError, runEmbed, runProfileQueryEmbed } from './embed-core.js';
+import { ModelWorkCancelledError, PipelineLoadError, cancelInFlightModelWork, runEmbed, runProfileQueryEmbed, } from './embed-core.js';
 if (!parentPort) {
     throw new Error('embed-worker must be run as a worker thread');
 }
 const port = parentPort;
 port.on('message', (msg) => {
+    if ('cancel' in msg) {
+        cancelInFlightModelWork();
+        return;
+    }
     void (async () => {
         try {
             const vectors = msg.profile
@@ -43,6 +51,7 @@ port.on('message', (msg) => {
                 fatal: err instanceof PipelineLoadError && !err.retryable,
                 retryable: err instanceof PipelineLoadError && err.retryable,
                 optionalPeerMissing: err instanceof PipelineLoadError && err.optionalPeerMissing,
+                cancelled: err instanceof ModelWorkCancelledError,
             });
         }
     })();

package/dist/memory/embeddings.d.ts

@@ -35,6 +35,15 @@ export declare class EmbeddingsUnavailableError extends EmbeddingsDisabledError
     readonly retryable = true;
     constructor(reason: string);
 }
+/**
+ * The service is stopping. Callers that keep per-item retry budgets check
+ * `shuttingDown` so a quit never counts against a file the way a real model
+ * failure does.
+ */
+export declare class EmbeddingsShuttingDownError extends EmbeddingsUnavailableError {
+    readonly shuttingDown = true;
+    constructor();
+}
 export type EmbeddingPipelineStatus = 'cold' | 'warming' | 'ready' | 'disabled' | 'unavailable';
 export declare function embeddingsDisabledReason(): string | null;
 export declare function embeddingPipelineStatus(): EmbeddingPipelineStatus;
@@ -49,8 +58,14 @@ export declare function embeddingsHealth(): {
 };
 /**
  * Close for service shutdown: refuse new work (it would start a worker, or
- * load the model in-process, as the process exits), then terminate the worker
- * once its in-flight work has finished, waiting at most `drainMs`.
+ * load the model in-process, as the process exits), cancel what is in flight,
+ * then terminate the worker once it is idle, waiting at most `drainMs`.
+ *
+ * The cancel is what makes the wait short: a first-run model download stops at
+ * once, and an embedding run stops at its next sub-batch. Without it the drain
+ * expired with the download still going, and every caller awaiting that
+ * embedding (index enrichment among them) held shutdown until the app's quit
+ * timeout.
  */
 export declare function shutdownEmbeddings(drainMs: number): Promise<void>;
 /** Reopen after shutdown — an embedded service can be started again in the same process. */

package/dist/memory/embeddings.js

@@ -21,7 +21,7 @@ import { Worker } from 'node:worker_threads';
 import { createLogger, sameVectorSpace } from '@bendyline/gezel';
 import { retireModelWorker } from '../utils/retire-model-worker.js';
 import { findServiceWorkerEntry } from '../utils/service-worker-entry.js';
-import { PipelineLoadError, daemonEmbedderPin, daemonEmbedderVerified, passageInstruction, queryInstruction, runEmbed, runProfileQueryEmbed, } from './embed-core.js';
+import { ModelWorkCancelledError, PipelineLoadError, cancelInFlightModelWork, daemonEmbedderPin, daemonEmbedderVerified, passageInstruction, queryInstruction, runEmbed, runProfileQueryEmbed, } from './embed-core.js';
 const log = createLogger('memory');
 /**
  * Marker class so callers can tell "the indexer is off on purpose" apart from a
@@ -46,6 +46,18 @@ export class EmbeddingsUnavailableError extends EmbeddingsDisabledError {
         this.message = `memory embeddings temporarily unavailable: ${reason}`;
     }
 }
+/**
+ * The service is stopping. Callers that keep per-item retry budgets check
+ * `shuttingDown` so a quit never counts against a file the way a real model
+ * failure does.
+ */
+export class EmbeddingsShuttingDownError extends EmbeddingsUnavailableError {
+    shuttingDown = true;
+    constructor() {
+        super('the service is shutting down');
+        this.name = 'EmbeddingsShuttingDownError';
+    }
+}
 // Once the model fails to load, we permanently flip into a disabled state.
 // Every subsequent call throws the short marker error instead of re-attempting
 // the import and re-printing the full model-load error on every chat turn.
@@ -142,6 +154,11 @@ function onMessage(msg) {
     pending.delete(msg.id);
     if (pending.size === 0)
         worker?.unref();
+    if (msg.cancelled) {
+        // Our own shutdown cancel: no cooldown, no profile outage, nothing disabled.
+        p.reject(new EmbeddingsShuttingDownError());
+        return;
+    }
     if (msg.error) {
         if (p.profileId) {
             if (!p.localFilesOnly && (msg.fatal || msg.retryable))
@@ -214,6 +231,8 @@ async function embedInProcess(texts) {
         return await runEmbed(texts);
     }
     catch (err) {
+        if (err instanceof ModelWorkCancelledError)
+            throw new EmbeddingsShuttingDownError();
         if (err instanceof PipelineLoadError) {
             if (err.retryable) {
                 markTemporarilyUnavailable(err.message);
@@ -256,17 +275,27 @@ function markDisabled(message, optionalPeerMissing = false) {
     log.error('[memory] failed to load embedding pipeline; vector memory is now disabled for this process.');
     log.error('[memory] underlying error:', message);
 }
-const SHUTTING_DOWN = 'the service is shutting down';
 /**
  * Close for service shutdown: refuse new work (it would start a worker, or
- * load the model in-process, as the process exits), then terminate the worker
- * once its in-flight work has finished, waiting at most `drainMs`.
+ * load the model in-process, as the process exits), cancel what is in flight,
+ * then terminate the worker once it is idle, waiting at most `drainMs`.
+ *
+ * The cancel is what makes the wait short: a first-run model download stops at
+ * once, and an embedding run stops at its next sub-batch. Without it the drain
+ * expired with the download still going, and every caller awaiting that
+ * embedding (index enrichment among them) held shutdown until the app's quit
+ * timeout.
  */
 export async function shutdownEmbeddings(drainMs) {
     closed = true;
     const w = worker;
-    if (!w)
+    if (!w) {
+        // In-process fallback: any run in flight is on this thread.
+        cancelInFlightModelWork();
         return;
+    }
+    if (pending.size > 0)
+        w.postMessage({ cancel: true });
     if (await retireModelWorker(w, () => pending.size === 0, drainMs)) {
         if (worker === w)
             worker = null;
@@ -281,7 +310,7 @@ export function openEmbeddings() {
 /** Embed `texts`, preferring the worker and degrading to in-process. */
 async function embedMany(texts) {
     if (closed)
-        throw new EmbeddingsUnavailableError(SHUTTING_DOWN);
+        throw new EmbeddingsShuttingDownError();
     if (disabledByEnv())
         throw new EmbeddingsDisabledError(ENV_DISABLED_REASON);
     if (disabledReason)
@@ -368,7 +397,7 @@ export function sharesDaemonEmbedder(profile) {
 export async function embedKnowledgeQuery(text, profile, opts = {}) {
     const { onDownloadProgress, localFilesOnly = false } = opts;
     if (closed)
-        throw new EmbeddingsUnavailableError(SHUTTING_DOWN);
+        throw new EmbeddingsShuttingDownError();
     // The default daemon pipeline may fetch weights on a cold load.
     if (!localFilesOnly && sharesDaemonEmbedder(profile)) {
         const vector = await embedQuery(text);

package/dist/models/ensure.d.ts

@@ -111,6 +111,8 @@ export interface CreateEnsureModelOptions {
         backend: EnsureBackend;
         catalogId: string;
     }) => void;
+    /** Test seam for catalog backend exclusions — defaults to the process's own. */
+    resolveLlamaBackend?: () => string | undefined;
 }
 /**
  * Parse a qualified id (`<backend>:<catalogId>`) into its parts. Bare

package/dist/models/ensure.js

@@ -1,4 +1,6 @@
 import { randomUUID } from 'node:crypto';
+import { llamaCppBackendExclusion, llamaCppBackendLabel } from '@bendyline/gezel';
+import { currentLlamaCppBackend } from '../providers/llama-cpp/backend-health.js';
 /**
  * Error class with a structured `code` so the route can pick the
  * right HTTP status. Avoids regex-matching error message strings.
@@ -160,6 +162,13 @@ export async function createEnsureModelOrchestrator(opts) {
                 ].filter((id) => Boolean(id));
                 throw new KnownEnsureError('no_source_for_backend', `chat-model "${catalogId}" has no ${backend} source${alternatives.length > 0 ? ` — try ${alternatives.map((id) => `"${id}"`).join(' or ')}` : ''}`);
             }
+            if (backend === 'llama-cpp') {
+                const engineBackend = (opts.resolveLlamaBackend ?? currentLlamaCppBackend)();
+                const excluded = llamaCppBackendExclusion(detail.manifest.llamaCpp, engineBackend);
+                if (excluded && engineBackend) {
+                    throw new KnownEnsureError('no_source_for_backend', `chat-model "${catalogId}" is not available on the ${llamaCppBackendLabel(engineBackend)} llama.cpp engine: ${excluded}${detail.manifest.mlx ? ` Try "mlx:${catalogId}".` : ''}`);
+                }
+            }
             if (await isInstalled(backend, catalogId)) {
                 return { status: 'ready', modelId: qualifiedModelId };
             }

package/dist/perf/responsiveness.d.ts

@@ -2,7 +2,7 @@ import { type ClientPerfReport, type PerfSnapshot, type PerfWork } from '@bendyl
 /**
  * A gap is measured to within one beat, so this has to stay well inside
  * `STALL_RECORD_MS`. At the same period, a pause long enough to log leaves the
- * watchdog late by more than half the gap, which is what `isMainThreadBlock`
+ * watchdog late by more than half the heartbeat's lateness, which is what `isMainThreadBlock`
  * needs to rule the main thread out.
  */
 export declare const BEAT_MS = 250;
@@ -18,8 +18,21 @@ interface WatchdogReport {
  * A stale heartbeat is a main-thread block only when the watchdog itself kept
  * time. When the watchdog was late by a comparable amount, the process or the
  * host was paused, and blaming whatever was in flight would be a false lead.
+ *
+ * Lateness against lateness: both threads sleep a beat between checks, so a
+ * pause delays each by about its length. Comparing the watchdog's lateness
+ * with the whole gap, beat included, filed short pauses as blocks.
  */
 export declare function isMainThreadBlock(report: WatchdogReport): boolean;
+/** What a gap cost: the main thread's CPU, and the process's major page faults. */
+export interface StallCost {
+    /** Null where the runtime has no per-thread CPU accounting. */
+    cpuMs: number | null;
+    pageFaults: number;
+}
+/** Running code when it used at least half the stall; otherwise paging or waiting on something. */
+export declare function stallVerdict(durationMs: number, cost: StallCost): 'running code' | 'paging' | 'blocked waiting' | undefined;
+export declare function describeStallCost(durationMs: number, cost: StallCost): string;
 interface ActiveWork {
     label: string;
     startedAt: number;

package/dist/perf/responsiveness.js

@@ -33,7 +33,7 @@ const log = createLogger('perf');
 /**
  * A gap is measured to within one beat, so this has to stay well inside
  * `STALL_RECORD_MS`. At the same period, a pause long enough to log leaves the
- * watchdog late by more than half the gap, which is what `isMainThreadBlock`
+ * watchdog late by more than half the heartbeat's lateness, which is what `isMainThreadBlock`
  * needs to rule the main thread out.
  */
 export const BEAT_MS = 250;
@@ -55,10 +55,17 @@ const PROFILE_WINDOW_MS = 60_000;
 const PROFILE_SAMPLING_US = 5_000;
 const PROFILE_KEEP = 20;
 const LABEL_MAX = 200;
+/**
+ * A watchdog tick later than this is kept. Half the smallest recordable
+ * lateness: a shorter one cannot rule the main thread out. The floor was a
+ * whole period, which threw away the witness's own evidence of a sub-second
+ * pause of the whole process, so such pauses were filed as main-thread blocks
+ * (idle processes on a swapping machine collected dozens a minute).
+ */
+const WATCHDOG_KEEP_LATE_MS = (STALL_RECORD_MS - BEAT_MS) / 2;
 /**
  * The witness. It keeps its own late ticks and, asked about a gap, answers
- * with the worst one since the gap began. A tick late by less than a period is
- * not kept: it cannot reach half of a recordable gap.
+ * with the worst one since the gap began.
  *
  * It sleeps on a futex instead of running an event loop: a worker woken by its
  * own timer cost about 1.6 context switches per tick on Windows, against 1.0
@@ -69,6 +76,7 @@ const LABEL_MAX = 200;
 const WATCHDOG_SOURCE = `
 const { parentPort, receiveMessageOnPort, workerData } = require('node:worker_threads');
 const tickMs = workerData.tickMs;
+const keepLateMs = workerData.keepLateMs;
 const asked = new Int32Array(workerData.asked);
 const lateTicks = [];
 let lastTick = Date.now();
@@ -78,7 +86,7 @@ for (;;) {
   if (now - lastTick >= tickMs) {
     const lateMs = now - lastTick - tickMs;
     lastTick = now;
-    if (lateMs >= tickMs) {
+    if (lateMs >= keepLateMs) {
       lateTicks.push({ at: now, lateMs });
       if (lateTicks.length > 32) lateTicks.shift();
     }
@@ -98,9 +106,52 @@ for (;;) {
  * A stale heartbeat is a main-thread block only when the watchdog itself kept
  * time. When the watchdog was late by a comparable amount, the process or the
  * host was paused, and blaming whatever was in flight would be a false lead.
+ *
+ * Lateness against lateness: both threads sleep a beat between checks, so a
+ * pause delays each by about its length. Comparing the watchdog's lateness
+ * with the whole gap, beat included, filed short pauses as blocks.
  */
 export function isMainThreadBlock(report) {
-    return report.watchdogLateMs < report.durationMs / 2;
+    return report.watchdogLateMs < (report.durationMs - BEAT_MS) / 2;
+}
+/** Fewer page faults than this in a stall is ordinary; more, with the thread idle, is swap. */
+const PAGING_MIN_FAULTS = 10;
+/**
+ * Read at every beat. Both are single syscalls and add no wakeups. A stall's
+ * duration alone cannot say whether code ran: on a memory-starved machine most
+ * logged stalls were the thread waiting for its own pages to come back from
+ * swap, and their CPU profiles held no samples at all.
+ */
+function readStallCounters() {
+    const threadCpuUsage = process.threadCpuUsage;
+    const cpu = typeof threadCpuUsage === 'function' ? threadCpuUsage() : null;
+    return {
+        cpuMs: cpu ? (cpu.user + cpu.system) / 1_000 : null,
+        pageFaults: process.resourceUsage().majorPageFault,
+    };
+}
+function stallCostBetween(before, after) {
+    return {
+        cpuMs: before.cpuMs !== null && after.cpuMs !== null
+            ? Math.max(0, Math.round(after.cpuMs - before.cpuMs))
+            : null,
+        pageFaults: Math.max(0, after.pageFaults - before.pageFaults),
+    };
+}
+/** Running code when it used at least half the stall; otherwise paging or waiting on something. */
+export function stallVerdict(durationMs, cost) {
+    if (cost.cpuMs === null)
+        return undefined;
+    if (cost.cpuMs >= durationMs / 2)
+        return 'running code';
+    return cost.pageFaults >= PAGING_MIN_FAULTS ? 'paging' : 'blocked waiting';
+}
+export function describeStallCost(durationMs, cost) {
+    const faults = `${cost.pageFaults} page fault${cost.pageFaults === 1 ? '' : 's'}`;
+    const verdict = stallVerdict(durationMs, cost);
+    if (cost.cpuMs === null)
+        return faults;
+    return `cpu ${formatPerfMs(cost.cpuMs)}, ${faults}${verdict ? `: ${verdict}` : ''}`;
 }
 /**
  * Work that overlapped `[start, end]`, most suspicious first. Running work
@@ -295,6 +346,10 @@ class ResponsivenessMonitor {
      */
     awaitingVerdicts = 0;
     rollDeferred = false;
+    /** Counters at the last beat, so a gap's cost is the difference at the next one. */
+    lastBeatCost = readStallCounters();
+    /** What each gap awaiting a verdict cost, keyed by its start. */
+    gapCosts = new Map();
     constructor(opts) {
         this.beatTimer = setInterval(() => this.beat(), BEAT_MS);
         this.beatTimer.unref?.();
@@ -396,11 +451,15 @@ class ResponsivenessMonitor {
         this.lastBeatAt = now;
         const gapMs = now - startedAt;
         this.delay.record(Math.max(1, Math.round((gapMs - BEAT_MS) * 1e6)));
+        const counters = readStallCounters();
+        const before = this.lastBeatCost;
+        this.lastBeatCost = counters;
         if (gapMs < STALL_RECORD_MS || !this.watchdog) {
             if (this.rollDeferred && this.awaitingVerdicts === 0)
                 this.rollProfile();
             return;
         }
+        this.gapCosts.set(startedAt, stallCostBetween(before, counters));
         this.awaitingVerdicts += 1;
         this.watchdog.postMessage({ startedAt, durationMs: gapMs });
         Atomics.store(this.watchdogAsked, 0, 1);
@@ -420,7 +479,11 @@ class ResponsivenessMonitor {
         try {
             const worker = new Worker(WATCHDOG_SOURCE, {
                 eval: true,
-                workerData: { tickMs: WATCHDOG_TICK_MS, asked: this.watchdogAsked.buffer },
+                workerData: {
+                    tickMs: WATCHDOG_TICK_MS,
+                    keepLateMs: WATCHDOG_KEEP_LATE_MS,
+                    asked: this.watchdogAsked.buffer,
+                },
             });
             worker.on('message', (report) => this.onWatchdogReport(report));
             worker.on('error', (err) => {
@@ -440,13 +503,19 @@ class ResponsivenessMonitor {
             this.rollProfile();
     }
     handleReport(report) {
+        const cost = this.gapCosts.get(report.startedAt);
+        this.gapCosts.delete(report.startedAt);
         if (!isMainThreadBlock(report))
             return;
         const now = Date.now();
+        const verdict = cost ? stallVerdict(report.durationMs, cost) : undefined;
         const stall = {
             at: new Date(report.startedAt).toISOString(),
             durationMs: report.durationMs,
             during: workDuring(report.startedAt, report.startedAt + report.durationMs, this.active.values(), this.finished, now),
+            ...(cost?.cpuMs != null ? { cpuMs: cost.cpuMs } : {}),
+            ...(cost ? { pageFaults: cost.pageFaults } : {}),
+            ...(verdict ? { verdict } : {}),
         };
         pushRing(this.stalls, stall);
         if (report.durationMs < STALL_LOG_MS)
@@ -454,7 +523,8 @@ class ResponsivenessMonitor {
         const running = stall.during.length > 0
             ? stall.during.map((w) => `${w.label} (${formatPerfMs(w.durationMs)})`).join(', ')
             : 'nothing tracked';
-        const line = `main thread blocked for ${formatPerfMs(report.durationMs)} — running: ${running}`;
+        const costText = cost ? ` (${describeStallCost(report.durationMs, cost)})` : '';
+        const line = `main thread blocked for ${formatPerfMs(report.durationMs)}${costText} — running: ${running}`;
         if (report.durationMs >= STALL_WARN_MS)
             log.warn(line);
         else

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

@@ -0,0 +1,30 @@
+/**
+ * Whether llama-server is getting the hardware this machine has, as the
+ * engine process sees it: the CUDA build discovery passed over for the
+ * driver (`GEZEL_LLAMA_CUDA_BLOCKER`), a GPU build that started without its
+ * GPU (gpu-startup-watch.ts), and Linux's out-of-memory killer stopping the
+ * engine. Each is invisible otherwise — the engine keeps answering, slower,
+ * or a chat fails with a crash that reads like any other.
+ *
+ * Process-wide like the backend env it sits beside: every llama provider in
+ * this process launches the same build.
+ */
+import type { LlamaCppBackendHealthResponse } from '@bendyline/gezel';
+import type { GpuUnused } from './gpu-startup-watch.js';
+/** Record what the latest start of a build found; null clears it. */
+export declare function noteGpuStartup(verdict: GpuUnused | null, now?: Date): void;
+export declare function noteHostOutOfMemory(input: {
+    model?: string | undefined;
+    whileStarting: boolean;
+}, now?: Date): void;
+declare const BACKENDS: readonly ["cuda", "vulkan", "metal", "cpu"];
+/**
+ * The backend this process's on-device llama-server runs, for catalog
+ * backend exclusions: the build discovery resolved, else what the probe
+ * found, else the only build macOS ships. Undefined when an external server
+ * is configured through the environment — its backend is not ours to know.
+ */
+export declare function currentLlamaCppBackend(): (typeof BACKENDS)[number] | undefined;
+export declare function llamaBackendHealthView(): LlamaCppBackendHealthResponse;
+export declare function __resetLlamaBackendHealthForTest(): void;
+export {};

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

@@ -0,0 +1,64 @@
+/**
+ * Whether llama-server is getting the hardware this machine has, as the
+ * engine process sees it: the CUDA build discovery passed over for the
+ * driver (`GEZEL_LLAMA_CUDA_BLOCKER`), a GPU build that started without its
+ * GPU (gpu-startup-watch.ts), and Linux's out-of-memory killer stopping the
+ * engine. Each is invisible otherwise — the engine keeps answering, slower,
+ * or a chat fails with a crash that reads like any other.
+ *
+ * Process-wide like the backend env it sits beside: every llama provider in
+ * this process launches the same build.
+ */
+import { readLlamaCudaBlocker } from '@bendyline/gezel/native';
+let gpuUnused = null;
+let outOfMemory = null;
+/** Record what the latest start of a build found; null clears it. */
+export function noteGpuStartup(verdict, now = new Date()) {
+    gpuUnused = verdict ? { ...verdict, at: now.toISOString() } : null;
+}
+export function noteHostOutOfMemory(input, now = new Date()) {
+    outOfMemory = {
+        count: (outOfMemory?.count ?? 0) + 1,
+        at: now.toISOString(),
+        ...(input.model ? { model: input.model } : {}),
+        whileStarting: input.whileStarting,
+    };
+}
+const BACKENDS = ['cuda', 'vulkan', 'metal', 'cpu'];
+/**
+ * The backend this process's on-device llama-server runs, for catalog
+ * backend exclusions: the build discovery resolved, else what the probe
+ * found, else the only build macOS ships. Undefined when an external server
+ * is configured through the environment — its backend is not ours to know.
+ */
+export function currentLlamaCppBackend() {
+    if (process.env.GEZEL_LLAMA_SERVER_URL)
+        return undefined;
+    for (const raw of [
+        process.env.GEZEL_LLAMA_SERVER_BACKEND,
+        process.env.GEZEL_LLAMA_DETECTED_BACKEND,
+    ]) {
+        const backend = BACKENDS.find((b) => b === raw);
+        if (backend)
+            return backend;
+    }
+    return process.platform === 'darwin' ? 'metal' : undefined;
+}
+export function llamaBackendHealthView() {
+    const runningRaw = process.env.GEZEL_LLAMA_SERVER_BACKEND;
+    const running = BACKENDS.find((backend) => backend === runningRaw);
+    const cudaBlocker = readLlamaCudaBlocker();
+    // A verdict about a build the process has since moved off (a quarantine
+    // fallback, a lifted quarantine) no longer describes what runs.
+    const unused = gpuUnused && gpuUnused.backend === running ? gpuUnused : null;
+    return {
+        ...(running ? { running } : {}),
+        ...(cudaBlocker ? { cudaBlocker } : {}),
+        ...(unused ? { gpuUnused: unused } : {}),
+        ...(outOfMemory ? { outOfMemory } : {}),
+    };
+}
+export function __resetLlamaBackendHealthForTest() {
+    gpuUnused = null;
+    outOfMemory = null;
+}