gitnexus 1.6.9-rc.40 → 1.6.9-rc.41

package/dist/cli/doctor.js

@@ -2,6 +2,7 @@ import { getRuntimeCapabilities, getRuntimeFingerprint } from '../core/platform/
 import { resolveEmbeddingConfig } from '../core/embeddings/config.js';
 import { isHttpMode } from '../core/embeddings/http-client.js';
 import { getLocalEmbeddingRuntimeBlocker } from '../core/embeddings/runtime-support.js';
+import { cudaRedirectDoctorStatus } from '../core/embeddings/onnxruntime-node-resolver.js';
 import { checkLbugNative } from '../core/lbug/native-check.js';
 import { getExtensionInstallPolicy } from '../core/lbug/extension-loader.js';
 import { t } from './i18n/index.js';
@@ -119,4 +120,14 @@ export const doctorCommand = async () => {
     if (support.detail) {
         process.stderr.write(`\n${support.detail.replace(/^/gm, '  ')}\n\n`);
     }
+    // Surface the CUDA-build-redirect decision so "why is my CUDA-13 host
+    // still on CPU" is visible without digging through debug logs (#2341
+    // follow-up). Only meaningful on the local runtime path.
+    if (!isHttpMode()) {
+        const cudaRedirect = cudaRedirectDoctorStatus();
+        console.log(`  ${padDisplayEnd('CUDA:', 12)}${cudaRedirect.status}`);
+        if (cudaRedirect.detail) {
+            console.log(`  ${padDisplayEnd('', 12)}${cudaRedirect.detail}`);
+        }
+    }
 };

package/dist/core/embeddings/embedder.js

@@ -12,89 +12,14 @@
 if (!process.env.ORT_LOG_LEVEL) {
     process.env.ORT_LOG_LEVEL = '3';
 }
-import { existsSync } from 'fs';
-import { execFileSync } from 'child_process';
-import { join, dirname } from 'path';
-import { createRequire } from 'module';
 import { DEFAULT_EMBEDDING_CONFIG } from './types.js';
 import { isHttpMode, getHttpDimensions, httpEmbed } from './http-client.js';
 import { resolveEmbeddingConfig } from './config.js';
 import { applyHfEnvOverrides, isHfDownloadFailure, withHfDownloadRetry } from './hf-env.js';
 import { getLocalEmbeddingRuntimeBlocker } from './runtime-support.js';
 import { ensureOnnxRuntimeCommonResolvable } from './onnxruntime-common-resolver.js';
+import { ensureOnnxRuntimeNodeMatchesSystem, isEffectiveCudaAvailable, } from './onnxruntime-node-resolver.js';
 import { logger } from '../logger.js';
-/**
- * Check whether the onnxruntime-node package that @huggingface/transformers
- * will actually load at runtime ships the CUDA execution provider.
- *
- * Critical: we resolve from transformers' own module scope, NOT from ours.
- * npm may install two copies — a top-level 1.24.x (our dep) and a nested
- * 1.21.0 (transformers' pinned dep). The guard must inspect whichever copy
- * transformers.js will dlopen, otherwise the check is meaningless.
- */
-function hasOrtCudaProvider() {
-    try {
-        const require = createRequire(import.meta.url);
-        // Resolve from @huggingface/transformers' scope so we find the same
-        // onnxruntime-node binary that transformers.js will use at runtime
-        const transformersDir = dirname(require.resolve('@huggingface/transformers/package.json'));
-        const ortRequire = createRequire(join(transformersDir, 'package.json'));
-        const ortPath = dirname(ortRequire.resolve('onnxruntime-node/package.json'));
-        // ORT 1.24.x only ships CUDA binaries for linux/x64 (downloaded from NuGet
-        // at postinstall). arm64 will correctly return false here until ORT adds support.
-        const arch = process.arch;
-        return existsSync(join(ortPath, 'bin', 'napi-v6', 'linux', arch, 'libonnxruntime_providers_cuda.so'));
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Check whether CUDA libraries are actually available on this system.
- * ONNX Runtime's native layer crashes (uncatchable) if we attempt CUDA
- * without the required shared libraries, so we probe first.
- *
- * Checks both:
- * 1. That system CUDA libraries (libcublasLt) are present
- * 2. That onnxruntime-node ships the CUDA execution provider binary
- *
- * Both conditions must be true — system CUDA libs alone are not enough
- * if onnxruntime-node is a CPU-only build (versions < 1.24.0).
- */
-function isCudaAvailable() {
-    // First, verify onnxruntime-node has the CUDA provider binary.
-    // Without this, requesting CUDA causes an uncatchable native crash.
-    if (!hasOrtCudaProvider())
-        return false;
-    // Primary: query the dynamic linker cache — covers all architectures,
-    // distro layouts, and custom install paths registered with ldconfig
-    try {
-        const out = execFileSync('ldconfig', ['-p'], {
-            timeout: 3000,
-            encoding: 'utf-8',
-            windowsHide: true,
-        });
-        if (out.includes('libcublasLt.so.12'))
-            return true;
-    }
-    catch {
-        // ldconfig not available (e.g. non-standard container)
-    }
-    // Fallback: check CUDA_PATH and LD_LIBRARY_PATH for environments where
-    // ldconfig doesn't know about the CUDA install (conda, manual /opt/cuda, etc.)
-    for (const envVar of ['CUDA_PATH', 'LD_LIBRARY_PATH']) {
-        const val = process.env[envVar];
-        if (!val)
-            continue;
-        for (const dir of val.split(':').filter(Boolean)) {
-            if (existsSync(join(dir, 'lib64', 'libcublasLt.so.12')) ||
-                existsSync(join(dir, 'lib', 'libcublasLt.so.12')) ||
-                existsSync(join(dir, 'libcublasLt.so.12')))
-                return true;
-        }
-    }
-    return false;
-}
 // Module-level state for singleton pattern
 let embedderInstance = null;
 let isInitializing = false;
@@ -142,7 +67,7 @@ export const initEmbedder = async (onProgress, config = {}, forceDevice) => {
     // provider libraries are missing. DirectML stays opt-in for the same reason.
     // Probe for CUDA first — ONNX Runtime crashes (uncatchable native error)
     // if we attempt CUDA without the required shared libraries
-    const gpuDevice = isCudaAvailable() ? 'cuda' : 'cpu';
+    const gpuDevice = isEffectiveCudaAvailable() ? 'cuda' : 'cpu';
     const requestedDevice = forceDevice || (finalConfig.device === 'auto' ? gpuDevice : finalConfig.device);
     initPromise = (async () => {
         try {
@@ -151,6 +76,12 @@ export const initEmbedder = async (onProgress, config = {}, forceDevice) => {
             // Under pnpm-strict / `pnpm dlx`, transformers' phantom `onnxruntime-common`
             // import is unresolvable; register the fallback resolver first (#307).
             ensureOnnxRuntimeCommonResolvable();
+            // Registered AFTER the common fallback so this hook resolves FIRST (Node
+            // runs the most-recently-registered hook first): on CUDA-13 hosts it
+            // redirects onnxruntime-node (and its version-matched onnxruntime-common)
+            // to the CUDA-13 build before transformers imports them. No-op on matching
+            // layouts, non-CUDA, Windows/DirectML, and macOS.
+            ensureOnnxRuntimeNodeMatchesSystem();
             const { pipeline, env } = await import('@huggingface/transformers');
             // Configure transformers.js environment
             env.allowLocalModels = false;

package/dist/core/embeddings/onnxruntime-common-resolver.js

@@ -21,14 +21,18 @@
  * Install a synchronous, in-thread ESM resolution hook (`module.registerHooks`,
  * Node >= 22.15) that redirects `onnxruntime-common` to a copy gitnexus can
  * resolve — but only when the default resolver fails. The redirect target is
- * preferentially the `onnxruntime-common` that `onnxruntime-node` (the native
- * binding transformers actually loads) itself depends on, so the redirected copy
- * is version-matched to that binding even under `pnpm dlx` — where gitnexus'
- * npm-style `overrides` block does NOT apply, because it is honoured only from a
- * root manifest and gitnexus is a transitive dependency there. It falls back to
- * gitnexus' own direct `onnxruntime-common` dependency when that chain can't be
- * walked. onnxruntime-common is a stable, pure-JS package whose `Tensor` surface
- * is unchanged across 1.24–1.26, so either target is API-compatible. On working
+ * preferentially the `onnxruntime-common` that `onnxruntime-node` depends on —
+ * specifically {@link getEffectiveOnnxRuntimeNodeDir}, the SAME onnxruntime-node
+ * copy the sibling {@link ./onnxruntime-node-resolver.ts} CUDA-major redirect
+ * will actually load (transformers' own default when no redirect is active,
+ * or the CUDA-build-matched copy when one is) — so this hook and that one can
+ * never disagree about which onnxruntime-node's own onnxruntime-common
+ * dependency to pair with, even under `pnpm dlx` where gitnexus' npm-style
+ * `overrides` block does NOT apply (honoured only from a root manifest, and
+ * gitnexus is a transitive dependency there). Falls back to gitnexus' own
+ * direct `onnxruntime-common` dependency when that chain can't be walked.
+ * onnxruntime-common is a stable, pure-JS package whose `Tensor` surface is
+ * unchanged across 1.24–1.26, so either target is API-compatible. On working
  * layouts the default resolver succeeds first and the hook never fires, so
  * behaviour is unchanged.
  *
@@ -55,26 +59,27 @@
  */
 import { registerHooks, createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
+import { join } from 'node:path';
+import { getEffectiveOnnxRuntimeNodeDir } from './onnxruntime-node-resolver.js';
 import { logger } from '../logger.js';
 let attempted = false;
 /**
  * Compute the file: URL the hook redirects `onnxruntime-common` to.
  *
- * Prefer the copy `onnxruntime-node` (the native binding transformers loads)
- * depends on, so the redirected module is version-matched to the binding even
- * under `pnpm dlx`, where transformers keeps its own pinned onnxruntime-node.
- * The walk resolves transformers' MAIN entry — NOT `@huggingface/transformers/
- * package.json`, which transformers' `exports` map blocks
- * (`ERR_PACKAGE_PATH_NOT_EXPORTED`) — then onnxruntime-node, then its
- * onnxruntime-common. Falls back to gitnexus' own direct dependency (always
- * resolvable from our scope) when any step fails.
+ * Pair with {@link getEffectiveOnnxRuntimeNodeDir}'s onnxruntime-node copy —
+ * NOT independently re-derived — so the redirected module is version-matched
+ * to whichever onnxruntime-node will actually load, even under `pnpm dlx`
+ * (where transformers keeps its own pinned onnxruntime-node) and even when
+ * the sibling CUDA-major redirect is active. Falls back to gitnexus' own
+ * direct dependency (always resolvable from our scope) when that fails.
  */
 const resolveOnnxRuntimeCommonUrl = () => {
     const require = createRequire(import.meta.url);
     try {
-        const transformersMain = require.resolve('@huggingface/transformers');
-        const ortNodePkg = createRequire(transformersMain).resolve('onnxruntime-node/package.json');
-        const common = createRequire(ortNodePkg).resolve('onnxruntime-common');
+        const effectiveDir = getEffectiveOnnxRuntimeNodeDir();
+        if (!effectiveDir)
+            throw new Error('no effective onnxruntime-node dir resolved');
+        const common = createRequire(join(effectiveDir, 'package.json')).resolve('onnxruntime-common');
         return pathToFileURL(common).href;
     }
     catch {

package/dist/core/embeddings/onnxruntime-node-resolver.d.ts

@@ -0,0 +1,40 @@
+export type CudaMajor = 12 | 13;
+/** The CUDA major an onnxruntime-node copy's CUDA provider links against, or null (Linux/x64 only ships one). */
+export declare const ortCudaMajor: (ortNodeDir: string) => CudaMajor | null;
+/** The cuBLASLt major installed on this system, or null. Linux only. */
+export declare const detectSystemCudaMajor: () => CudaMajor | null;
+/**
+ * The onnxruntime-node dir that will actually back transformers at runtime once
+ * {@link ensureOnnxRuntimeNodeMatchesSystem} has run — i.e. the redirected copy
+ * when a redirect applies, otherwise transformers' default. The CUDA probe must
+ * inspect THIS dir (not transformers' CJS-resolved default) so probe and
+ * runtime agree. Returns null only when neither copy resolves.
+ */
+export declare const getEffectiveOnnxRuntimeNodeDir: () => string | null;
+/**
+ * Whether the onnxruntime-node copy that will actually load ships a CUDA
+ * provider matching this host's CUDA major — reads straight from the cached
+ * `decide()` result rather than re-probing `ortCudaMajor`/`detectSystemCudaMajor`
+ * a second time (both are already computed above). `systemMajor` is checked
+ * for non-null explicitly so two absent majors (null === null) never count
+ * as a match.
+ */
+export declare const isEffectiveCudaAvailable: () => boolean;
+/**
+ * CUDA-build-redirect status for the `doctor` Embeddings section — pure
+ * summary of decide()'s already-computed decision, matching
+ * doctor.ts's `localEmbeddingDoctorStatus`'s `{status, detail}` shape so an
+ * operator can tell "why is my CUDA-13 host still on CPU" apart from
+ * "there's no system CUDA to redirect for" at a glance.
+ */
+export declare const cudaRedirectDoctorStatus: () => {
+    status: string;
+    detail: string | null;
+};
+/**
+ * Idempotently install the CUDA-build-matching redirect. Call once immediately
+ * before the dynamic `import('@huggingface/transformers')` on the local
+ * embedding path (after the runtime guard, alongside the onnxruntime-common
+ * fallback). No-op unless a strictly-better matching copy exists.
+ */
+export declare const ensureOnnxRuntimeNodeMatchesSystem: () => void;

package/dist/core/embeddings/onnxruntime-node-resolver.js

@@ -0,0 +1,297 @@
+/**
+ * Redirect `@huggingface/transformers`' `onnxruntime-node` import to whichever
+ * bundled copy's CUDA build matches this host's CUDA runtime (CUDA 12 vs 13).
+ *
+ * ## Why
+ * transformers exact-pins `onnxruntime-node` (e.g. `1.24.3`, a CUDA **12**
+ * build), while gitnexus' own `onnxruntime-node: ^1.24.0` floats to the latest
+ * 1.x (a CUDA **13** build). npm/pnpm cannot dedupe an exact pin against a
+ * range, so a `npm i -g` install ends up with TWO copies: gitnexus' top-level
+ * CUDA-13 build (unused) and transformers' nested CUDA-12 build (the one that
+ * actually loads). gitnexus' `overrides` block that would collapse them is
+ * honoured only from a *root* manifest, so it is inert once gitnexus is a
+ * dependency — the same transitive-override limitation documented in
+ * {@link ./onnxruntime-common-resolver.ts} (#307).
+ *
+ * The consequence on a CUDA-13-only host: the nested CUDA-12 provider cannot
+ * find `libcublasLt.so.12`, the CUDA execution provider fails to load, and
+ * embeddings silently fall back to CPU (~5-6x slower) even with
+ * `--embedding-device cuda`.
+ *
+ * ## What this does
+ * Best-effort, before transformers is imported: if the system's cuBLASLt major
+ * (12 or 13) does NOT match the CUDA build transformers would load by default,
+ * but gitnexus' own top-level `onnxruntime-node` copy DOES match, install a
+ * synchronous ESM resolution hook (`module.registerHooks`, Node >= 22.15) that
+ * redirects both `onnxruntime-node` and `onnxruntime-common` to that matching
+ * copy. onnxruntime-common is redirected alongside so the `Tensor` surface
+ * stays a single identity, version-matched to the redirected binding.
+ *
+ * ## Safety
+ * Detection-based and conservative — it acts ONLY when it is a net improvement:
+ *   - system CUDA major == default build major  -> NO-OP (already correct)
+ *   - no system CUDA libs / non-linux           -> NO-OP (CPU path)
+ *   - only one copy present                     -> NO-OP
+ *   - neither copy matches the system           -> NO-OP (never makes it worse)
+ * So CUDA-12 hosts, Windows (DirectML), macOS, and CPU-only hosts are
+ * untouched. Idempotent; any failure is swallowed and leaves the default
+ * resolution exactly as before. `module.registerHooks` requires Node >= 22.15
+ * (the gitnexus engines floor is >= 22.0.0); on older runtimes the redirect is
+ * a no-op, but the default copy's CUDA major is still probed so an
+ * already-matching host (e.g. CUDA 12 + transformers' CUDA-12 build) keeps
+ * auto-selecting the GPU.
+ * `npm link` / symlinked local-dev checkouts are a known caveat: `resolveOurOrtNodeDir`/
+ * `resolveDefaultOrtNodeDir` are anchored to this module's own real (post-symlink)
+ * location via `import.meta.url`, so a linked dev checkout may resolve against
+ * its own `node_modules` rather than the consuming app's — narrow, dev-only
+ * blast radius; regular npm/pnpm installs are unaffected.
+ *
+ * The CUDA-major decision is exposed via {@link getEffectiveOnnxRuntimeNodeDir}
+ * so the embedder's CUDA probe can inspect the SAME copy that will actually be
+ * loaded (the probe uses CJS `require.resolve`, which an ESM hook does not
+ * affect) — keeping probe and runtime consistent.
+ */
+import { registerHooks, createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { logger } from '../logger.js';
+const require = createRequire(import.meta.url);
+/**
+ * Read a shared object's NEEDED entries, tolerating ldd's non-zero exit when a
+ * lib is unresolved (that case still yields a usable "=> not found" stdout).
+ * `failed: true` means ldd produced no usable output at all (missing `ldd`
+ * binary, permission-denied `.so`, sandboxed exec) — distinct from "ldd ran
+ * fine and simply found no matching NEEDED entry" (`failed: false`, `needed: ''`),
+ * so callers don't have to treat "detection failed" identically to "definitely
+ * no CUDA provider".
+ */
+const readSoNeeded = (soPath) => {
+    try {
+        return {
+            needed: execFileSync('ldd', [soPath], {
+                timeout: 5000,
+                encoding: 'utf-8',
+                windowsHide: true,
+            }),
+            failed: false,
+        };
+    }
+    catch (err) {
+        const out = err?.stdout;
+        if (typeof out === 'string' && out.length > 0)
+            return { needed: out, failed: false };
+        return { needed: '', failed: true };
+    }
+};
+/** The CUDA major an onnxruntime-node copy's CUDA provider links against, or null (Linux/x64 only ships one). */
+export const ortCudaMajor = (ortNodeDir) => {
+    const so = join(ortNodeDir, 'bin', 'napi-v6', 'linux', process.arch, 'libonnxruntime_providers_cuda.so');
+    // A pre-PR CUDA-12 host relied only on this existence check (no `ldd`
+    // dependency) — retained here as the first, unconditional signal so a host
+    // whose CUDA provider `.so` is genuinely present but merely un-inspectable
+    // (see the `failed` case below) is never treated identically to a host that
+    // never shipped a CUDA provider at all.
+    if (!existsSync(so))
+        return null;
+    const { needed, failed } = readSoNeeded(so);
+    if (failed) {
+        logger.warn({ so }, 'Could not read CUDA provider dependencies (ldd failed to run) — CUDA-major detection ' +
+            'is unknown, not necessarily absent; embeddings will fall back to CPU either way');
+    }
+    if (/libcublasLt\.so\.13/.test(needed))
+        return 13;
+    if (/libcublasLt\.so\.12/.test(needed))
+        return 12;
+    return null;
+};
+/** The cuBLASLt major installed on this system, or null. Linux only. */
+export const detectSystemCudaMajor = () => {
+    if (process.platform !== 'linux')
+        return null;
+    try {
+        const out = execFileSync('ldconfig', ['-p'], {
+            timeout: 3000,
+            encoding: 'utf-8',
+            windowsHide: true,
+        });
+        if (out.includes('libcublasLt.so.13'))
+            return 13;
+        if (out.includes('libcublasLt.so.12'))
+            return 12;
+    }
+    catch {
+        // ldconfig not available (e.g. non-standard container) — fall through to path scan.
+    }
+    // Prefer CUDA 13 across the ENTIRE search space, not just within one
+    // dir/sub pair — a `.so.12` found early (e.g. a stale CUDA_PATH entry from
+    // a prior install) must not shadow a genuine `.so.13` found later in
+    // LD_LIBRARY_PATH. Return immediately on a 13 (the best possible answer);
+    // remember a 12 and keep scanning in case a later entry still has a 13.
+    let found = null;
+    for (const envVar of ['CUDA_PATH', 'LD_LIBRARY_PATH']) {
+        const val = process.env[envVar];
+        if (!val)
+            continue;
+        for (const dir of val.split(':').filter(Boolean))
+            for (const sub of ['lib64', 'lib', ''])
+                for (const maj of [13, 12])
+                    if (existsSync(join(dir, sub, `libcublasLt.so.${maj}`))) {
+                        if (maj === 13)
+                            return 13;
+                        found = maj;
+                    }
+    }
+    return found;
+};
+/** onnxruntime-node dir transformers loads by default (its own nested/pinned copy). */
+const resolveDefaultOrtNodeDir = () => {
+    try {
+        const transformersMain = require.resolve('@huggingface/transformers');
+        return dirname(createRequire(transformersMain).resolve('onnxruntime-node/package.json'));
+    }
+    catch {
+        return null;
+    }
+};
+/** gitnexus' own direct top-level onnxruntime-node dir. */
+const resolveOurOrtNodeDir = () => {
+    try {
+        return dirname(require.resolve('onnxruntime-node/package.json'));
+    }
+    catch {
+        return null;
+    }
+};
+let cached = null;
+const decide = () => {
+    if (cached)
+        return cached;
+    const defaultDir = resolveDefaultOrtNodeDir();
+    // Node < 22.15 has no `registerHooks` API, so a redirect can never actually
+    // install (see ensureOnnxRuntimeNodeMatchesSystem below) — the probe must
+    // agree with that up front, never reporting a redirect target that won't be
+    // loaded. But the DEFAULT copy still loads and needs no hook, so its CUDA
+    // major is still probed: a CUDA-12 host on Node 22.0–22.14 whose default
+    // build already matches must keep auto-selecting the GPU exactly as it did
+    // before this redirect existed.
+    const canRedirect = typeof registerHooks === 'function';
+    const systemMajor = detectSystemCudaMajor();
+    // `defaultDir` resolving is NOT a precondition for checking `ourDir` below —
+    // if transformers' own resolution fails outright (defaultMajor stays null),
+    // that still counts as "the default doesn't match", so a working `ourDir`
+    // should still be picked up as the effective target instead of leaving
+    // `effectiveDir` stuck at `null`. Gated behind `systemMajor != null` (as
+    // before) so a non-CUDA host never pays for a provider-.so probe at all.
+    const defaultMajor = systemMajor != null && defaultDir ? ortCudaMajor(defaultDir) : null;
+    let decision = {
+        redirect: false,
+        effectiveDir: defaultDir,
+        effectiveMajor: defaultMajor,
+        systemMajor,
+    };
+    if (canRedirect && systemMajor != null && defaultMajor !== systemMajor) {
+        const ourDir = resolveOurOrtNodeDir();
+        if (ourDir && ourDir !== defaultDir) {
+            const ourMajor = ortCudaMajor(ourDir);
+            if (ourMajor === systemMajor) {
+                decision = { redirect: true, effectiveDir: ourDir, effectiveMajor: ourMajor, systemMajor };
+            }
+        }
+    }
+    cached = decision;
+    return decision;
+};
+/**
+ * The onnxruntime-node dir that will actually back transformers at runtime once
+ * {@link ensureOnnxRuntimeNodeMatchesSystem} has run — i.e. the redirected copy
+ * when a redirect applies, otherwise transformers' default. The CUDA probe must
+ * inspect THIS dir (not transformers' CJS-resolved default) so probe and
+ * runtime agree. Returns null only when neither copy resolves.
+ */
+export const getEffectiveOnnxRuntimeNodeDir = () => decide().effectiveDir;
+/**
+ * Whether the onnxruntime-node copy that will actually load ships a CUDA
+ * provider matching this host's CUDA major — reads straight from the cached
+ * `decide()` result rather than re-probing `ortCudaMajor`/`detectSystemCudaMajor`
+ * a second time (both are already computed above). `systemMajor` is checked
+ * for non-null explicitly so two absent majors (null === null) never count
+ * as a match.
+ */
+export const isEffectiveCudaAvailable = () => {
+    const d = decide();
+    return d.systemMajor !== null && d.systemMajor === d.effectiveMajor;
+};
+/**
+ * CUDA-build-redirect status for the `doctor` Embeddings section — pure
+ * summary of decide()'s already-computed decision, matching
+ * doctor.ts's `localEmbeddingDoctorStatus`'s `{status, detail}` shape so an
+ * operator can tell "why is my CUDA-13 host still on CPU" apart from
+ * "there's no system CUDA to redirect for" at a glance.
+ */
+export const cudaRedirectDoctorStatus = () => {
+    const d = decide();
+    if (d.systemMajor === null) {
+        return { status: 'n/a (no system CUDA detected)', detail: null };
+    }
+    if (d.redirect) {
+        return {
+            status: `✓ redirected onnxruntime-node to the CUDA ${d.systemMajor} build`,
+            detail: d.effectiveDir,
+        };
+    }
+    if (d.systemMajor === d.effectiveMajor) {
+        return {
+            status: `✓ default onnxruntime-node build already matches CUDA ${d.systemMajor}`,
+            detail: null,
+        };
+    }
+    return {
+        status: `✗ no CUDA ${d.systemMajor}-matched onnxruntime-node build found (falling back to CPU)`,
+        detail: d.effectiveDir,
+    };
+};
+let attempted = false;
+/**
+ * Idempotently install the CUDA-build-matching redirect. Call once immediately
+ * before the dynamic `import('@huggingface/transformers')` on the local
+ * embedding path (after the runtime guard, alongside the onnxruntime-common
+ * fallback). No-op unless a strictly-better matching copy exists.
+ */
+export const ensureOnnxRuntimeNodeMatchesSystem = () => {
+    if (attempted)
+        return;
+    attempted = true;
+    try {
+        if (typeof registerHooks !== 'function')
+            return; // Node < 22.15: graceful no-op
+        const d = decide();
+        if (!d.redirect || !d.effectiveDir)
+            return;
+        const nodeUrl = pathToFileURL(createRequire(join(d.effectiveDir, 'package.json')).resolve('onnxruntime-node')).href;
+        let commonUrl = null;
+        try {
+            commonUrl = pathToFileURL(createRequire(join(d.effectiveDir, 'package.json')).resolve('onnxruntime-common')).href;
+        }
+        catch {
+            commonUrl = null; // fall back to the onnxruntime-common-resolver for common
+        }
+        registerHooks({
+            resolve(specifier, context, nextResolve) {
+                if (specifier === 'onnxruntime-node')
+                    return { url: nodeUrl, shortCircuit: true };
+                if (commonUrl && specifier === 'onnxruntime-common')
+                    return { url: commonUrl, shortCircuit: true };
+                return nextResolve(specifier, context);
+            },
+        });
+        // info (not debug): this is the one signal an operator has that CUDA
+        // embeddings are actually using the GPU on this host — the common/no-op
+        // paths below stay at debug since they're the expected default.
+        logger.info({ systemMajor: d.systemMajor, effectiveDir: d.effectiveDir }, 'Redirected onnxruntime-node to system-matched CUDA build');
+    }
+    catch (err) {
+        logger.debug({ err: err instanceof Error ? err.message : String(err) }, 'onnxruntime-node CUDA-build redirect not installed');
+    }
+};

package/dist/mcp/core/embedder.js

@@ -9,6 +9,7 @@ import { resolveEmbeddingConfig } from '../../core/embeddings/config.js';
 import { applyHfEnvOverrides, isHfDownloadFailure, withHfDownloadRetry, } from '../../core/embeddings/hf-env.js';
 import { getLocalEmbeddingRuntimeBlocker } from '../../core/embeddings/runtime-support.js';
 import { ensureOnnxRuntimeCommonResolvable } from '../../core/embeddings/onnxruntime-common-resolver.js';
+import { ensureOnnxRuntimeNodeMatchesSystem } from '../../core/embeddings/onnxruntime-node-resolver.js';
 import { silenceStdout, restoreStdout, realStderrWrite } from '../../core/lbug/pool-adapter.js';
 import { logger } from '../../core/logger.js';
 // Model config
@@ -47,6 +48,13 @@ export const initEmbedder = async () => {
             // Under pnpm-strict / `pnpm dlx`, transformers' phantom `onnxruntime-common`
             // import is unresolvable; register the fallback resolver first (#307).
             ensureOnnxRuntimeCommonResolvable();
+            // Registered AFTER the common fallback so this hook resolves FIRST (Node
+            // runs the most-recently-registered hook first): on CUDA-13 hosts it
+            // redirects onnxruntime-node to the system-matched build before
+            // transformers imports it. No-op on matching layouts, non-CUDA,
+            // Windows/DirectML, and macOS. Mirrors the core embedder's call site so
+            // MCP query-time embedding gets the same CUDA-13 fix.
+            ensureOnnxRuntimeNodeMatchesSystem();
             const { pipeline, env } = await import('@huggingface/transformers');
             env.allowLocalModels = false;
             // Bridge user-controlled env vars to transformers.js: HF_HOME →

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.9-rc.40",
+  "version": "1.6.9-rc.41",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",

package/scripts/cross-platform-tests.ts

@@ -47,6 +47,7 @@ const PLATFORM_LOGIC = [
   'test/unit/ignore-service.test.ts',
   'test/unit/group/bridge-db.test.ts',
   'test/unit/group/bridge-db-edge.test.ts',
+  'test/unit/onnxruntime-node-resolver.test.ts',
 ];
 
 // Native LadybugDB integration tests — exercise the @ladybugdb/core