gitnexus 1.6.4-rc.89 → 1.6.4-rc.90

package/dist/cli/analyze.js

@@ -20,6 +20,7 @@ import { warnMissingOptionalGrammars } from './optional-grammars.js';
 import { glob } from 'glob';
 import fs from 'fs/promises';
 import { cliError } from './cli-message.js';
+import { isHfDownloadFailure } from '../core/embeddings/hf-env.js';
 // Capture stderr.write at module load BEFORE anything (LadybugDB native
 // init, progress bar, console redirection) can monkey-patch it. The
 // fatal handlers below MUST reach the user even when the analyze path
@@ -427,6 +428,22 @@ export const analyzeCommand = async (inputPath, options) => {
             process.exitCode = 1;
             return;
         }
+        // HF download failure — show clean guidance without the raw stack trace.
+        // Checked before writeFatalToStderr so the user sees one focused message
+        // rather than a stack-trace dump followed by a second remediation block.
+        if (isHfDownloadFailure(msg) || msg.includes('Failed to download embedding model')) {
+            cliError(`  The embedding model could not be downloaded.\n` +
+                `  huggingface.co may be unreachable from your network\n` +
+                `  (e.g. behind a corporate proxy or a regional firewall).\n` +
+                `  Suggestions:\n` +
+                `    1. Set HF_ENDPOINT to a mirror and retry:\n` +
+                `         HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings\n` +
+                `         (Windows: set HF_ENDPOINT=https://hf-mirror.com && npx gitnexus analyze --embeddings)\n` +
+                `    2. Check your proxy / VPN settings.\n` +
+                `    3. Once downloaded the model is cached — future runs work offline.\n`, { recoveryHint: 'hf-endpoint-unreachable' });
+            process.exitCode = 1;
+            return;
+        }
         // Bypass the redirected console.error and write the full stack to
         // the real stderr captured at module load. The redirected
         // console.error wraps every line with `\\x1b[2K\\r` (ANSI clear-line)

package/dist/core/embeddings/embedder.js

@@ -12,7 +12,7 @@
 if (!process.env.ORT_LOG_LEVEL) {
     process.env.ORT_LOG_LEVEL = '3';
 }
-import { pipeline, env } from '@huggingface/transformers';
+import { pipeline, env, } from '@huggingface/transformers';
 import { existsSync } from 'fs';
 import { execFileSync } from 'child_process';
 import { join, dirname } from 'path';
@@ -20,7 +20,7 @@ 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 } from './hf-env.js';
+import { applyHfEnvOverrides, isHfDownloadFailure, withHfDownloadRetry } from './hf-env.js';
 import { logger } from '../logger.js';
 /**
  * Check whether the onnxruntime-node package that @huggingface/transformers
@@ -145,11 +145,15 @@ export const initEmbedder = async (onProgress, config = {}, forceDevice) => {
             const progressCallback = onProgress
                 ? (data) => {
                     const progress = {
-                        status: data.status || 'progress',
-                        file: data.file,
-                        progress: data.progress,
-                        loaded: data.loaded,
-                        total: data.total,
+                        // Map the `progress_total` aggregate event (not in ModelProgress.status)
+                        // back to 'progress' so callers don't need to handle it separately.
+                        status: data.status === 'progress_total'
+                            ? 'progress'
+                            : (data.status ?? 'progress'),
+                        file: 'file' in data ? data.file : undefined,
+                        progress: 'progress' in data ? data.progress : undefined,
+                        loaded: 'loaded' in data ? data.loaded : undefined,
+                        total: 'total' in data ? data.total : undefined,
                     };
                     onProgress(progress);
                 }
@@ -173,7 +177,7 @@ export const initEmbedder = async (onProgress, config = {}, forceDevice) => {
                     else if (isDev && device === 'wasm') {
                         logger.info('🔧 Using WASM backend (slower)...');
                     }
-                    embedderInstance = await pipeline('feature-extraction', finalConfig.modelId, {
+                    embedderInstance = await withHfDownloadRetry(() => pipeline('feature-extraction', finalConfig.modelId, {
                         device: device,
                         dtype: 'fp32',
                         progress_callback: progressCallback,
@@ -183,6 +187,10 @@ export const initEmbedder = async (onProgress, config = {}, forceDevice) => {
                             interOpNumThreads: 1,
                             executionMode: 'sequential',
                         },
+                    }), {
+                        onRetry: isDev
+                            ? (attempt, max, err) => logger.warn({ attempt, max, err: err.message }, `⚠️  Model download network error (attempt ${attempt}/${max}), retrying…`)
+                            : undefined,
                     });
                     currentDevice = device;
                     if (isDev) {
@@ -197,6 +205,20 @@ export const initEmbedder = async (onProgress, config = {}, forceDevice) => {
                     return embedderInstance;
                 }
                 catch (deviceError) {
+                    // Network errors and circuit-open errors are not device-specific —
+                    // they will fail the same way on every device. Rethrow immediately
+                    // with actionable HF_ENDPOINT guidance rather than silently falling
+                    // back to the next device.
+                    const errMsg = deviceError instanceof Error ? deviceError.message : String(deviceError);
+                    if (isHfDownloadFailure(errMsg)) {
+                        const endpointHint = process.env.HF_ENDPOINT
+                            ? `The configured endpoint (${process.env.HF_ENDPOINT}) may be unreachable.`
+                            : `huggingface.co may be unreachable from your network.\n` +
+                                `  Set HF_ENDPOINT to a mirror and retry:\n` +
+                                `    HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings\n` +
+                                `    (Windows: set HF_ENDPOINT=https://hf-mirror.com && npx gitnexus analyze --embeddings)`;
+                        throw new Error(`Failed to download embedding model: ${errMsg}\n  ${endpointHint}`);
+                    }
                     if (isDev && (device === 'cuda' || device === 'dml')) {
                         const gpuType = device === 'dml' ? 'DirectML' : 'CUDA';
                         logger.info(`⚠️  ${gpuType} not available, falling back to CPU...`);

package/dist/core/embeddings/hf-env.d.ts

@@ -1,3 +1,17 @@
+/** Per-attempt timeout for the full model download (5 minutes). */
+export declare const HF_DOWNLOAD_TIMEOUT_MS: number;
+/** Maximum total download attempts (1 initial + N-1 retries). */
+export declare const HF_MAX_ATTEMPTS = 3;
+/** Initial delay between retry attempts; doubles on each subsequent retry. */
+export declare const HF_BASE_DELAY_MS = 2000;
+/** Number of consecutive failures required to open the circuit. */
+export declare const CB_FAILURE_THRESHOLD = 3;
+/** How long the circuit stays open before transitioning to half-open. */
+export declare const CB_RESET_TIMEOUT_MS = 60000;
+/** Upper bound clamped on the env-override per-attempt timeout (30 minutes). */
+export declare const HF_MAX_TIMEOUT_MS: number;
+/** Upper bound clamped on the env-override attempt count. */
+export declare const HF_MAX_ATTEMPTS_CAP = 10;
 /**
  * @internal Exported only for unit tests and the two embedder entry points
  * (`core/embeddings/embedder.ts` + `mcp/core/embedder.ts`). Not part of the
@@ -44,3 +58,106 @@ export interface HfEnvSubset {
  * call site a single line at each entry point.
  */
 export declare function applyHfEnvOverrides(env: HfEnvSubset): void;
+/**
+ * @internal Exported for unit tests and the two embedder entry points.
+ *
+ * Returns true when an error message indicates a network-level fetch failure
+ * during HuggingFace model download (e.g. `TypeError: fetch failed`,
+ * `ECONNREFUSED`, `ENOTFOUND`, `ETIMEDOUT`, `ECONNRESET`).
+ *
+ * These errors are not device-specific and cannot be fixed by falling back to
+ * a different ONNX device — the caller should rethrow immediately with
+ * guidance about `HF_ENDPOINT`.
+ */
+export declare function isNetworkFetchError(message: string): boolean;
+/** @internal Used by `withHfDownloadRetry` to mark a circuit-open rejection. */
+export declare const CIRCUIT_OPEN_TAG = "hf-circuit-open";
+/** Circuit-breaker states. */
+type CircuitState = 'closed' | 'open' | 'half-open';
+/**
+ * Circuit breaker for HuggingFace model downloads.
+ *
+ * After `failureThreshold` consecutive network failures the circuit opens and
+ * all subsequent calls to `withHfDownloadRetry` fail immediately without
+ * issuing any network requests. After `resetTimeoutMs` the circuit enters the
+ * half-open state and the next call is attempted — if it succeeds the circuit
+ * closes again; if it fails the circuit re-opens.
+ *
+ * Exported for unit-testing; production code should use the module-level
+ * `hfDownloadCircuit` singleton.
+ */
+export declare class HfDownloadCircuitBreaker {
+    readonly failureThreshold: number;
+    readonly resetTimeoutMs: number;
+    private _state;
+    private _failures;
+    /** Timestamp of the last recorded failure (ms since epoch). */
+    lastFailureAt: number;
+    constructor(failureThreshold?: number, resetTimeoutMs?: number);
+    /** Effective state, factoring in the reset-timeout transition. */
+    get state(): CircuitState;
+    /** Returns true when the circuit is open and calls should be rejected. */
+    isOpen(): boolean;
+    /** Record a successful call — resets the failure counter and closes the circuit. */
+    recordSuccess(): void;
+    /** Record a failed call — increments the counter and opens the circuit when the threshold is reached. */
+    recordFailure(): void;
+    /** @internal Reset to initial state (used in tests). */
+    reset(): void;
+}
+/** Module-level singleton shared by both embedder entry points. */
+export declare const hfDownloadCircuit: HfDownloadCircuitBreaker;
+/** @internal Returns true for errors that should abort without retry (circuit-open). */
+export declare function isHfCircuitOpenError(message: string): boolean;
+/**
+ * Returns true for any HuggingFace download failure that warrants showing the
+ * `HF_ENDPOINT` remediation hint: either a raw network error or a
+ * circuit-open rejection (which itself was caused by repeated network errors).
+ */
+export declare function isHfDownloadFailure(message: string): boolean;
+/** @internal Wraps `fn` in a hard time-limit. The timeout error contains
+ *  `ETIMEDOUT` so that `isNetworkFetchError` classifies it correctly.
+ */
+export declare function withDownloadTimeout<T>(fn: () => Promise<T>, timeoutMs: number): Promise<T>;
+/** @internal Async sleep (exposed for testing). */
+export declare function sleep(ms: number): Promise<void>;
+export interface HfRetryOptions {
+    /** Maximum total attempts including the initial one (default: `HF_MAX_ATTEMPTS`). */
+    maxAttempts?: number;
+    /** Delay before the first retry; doubles on each subsequent attempt (default: `HF_BASE_DELAY_MS`). */
+    baseDelayMs?: number;
+    /** Per-attempt wall-clock timeout in ms (default: `HF_DOWNLOAD_TIMEOUT_MS`). */
+    timeoutMs?: number;
+    /**
+     * Circuit-breaker instance to use. Defaults to the module-level
+     * `hfDownloadCircuit` singleton. Pass a fresh instance in tests.
+     */
+    circuit?: HfDownloadCircuitBreaker;
+    /**
+     * Optional callback invoked before each retry (not the initial attempt).
+     * @param attempt - 1-based retry number
+     * @param max - total allowed attempts
+     * @param error - the error that triggered the retry
+     */
+    onRetry?: (attempt: number, max: number, error: Error) => void;
+}
+/**
+ * Retry wrapper for HuggingFace model downloads with per-attempt timeout and
+ * circuit-breaker protection.
+ *
+ * Behaviour:
+ * - If the circuit is **open**, fails immediately with a `CIRCUIT_OPEN_TAG`
+ *   message (so `isHfDownloadFailure` still returns true and the caller can
+ *   show `HF_ENDPOINT` guidance).
+ * - Each attempt is wrapped in `withDownloadTimeout`.
+ * - On a network-level error (`isNetworkFetchError`) the attempt is retried
+ *   with exponential back-off; non-network errors (e.g. ONNX device failure)
+ *   are rethrown immediately without retry.
+ * - Every network failure is recorded on the circuit breaker; a success resets
+ *   it.
+ * - After all attempts are exhausted, the last network error is rethrown
+ *   so the existing `isNetworkFetchError` / `isHfDownloadFailure` guards in
+ *   the calling code still fire.
+ */
+export declare function withHfDownloadRetry<T>(fn: () => Promise<T>, options?: HfRetryOptions): Promise<T>;
+export {};

package/dist/core/embeddings/hf-env.js

@@ -1,5 +1,22 @@
 import os from 'node:os';
 import { join } from 'node:path';
+// ---------------------------------------------------------------------------
+// Download resilience defaults
+// ---------------------------------------------------------------------------
+/** Per-attempt timeout for the full model download (5 minutes). */
+export const HF_DOWNLOAD_TIMEOUT_MS = 5 * 60 * 1_000;
+/** Maximum total download attempts (1 initial + N-1 retries). */
+export const HF_MAX_ATTEMPTS = 3;
+/** Initial delay between retry attempts; doubles on each subsequent retry. */
+export const HF_BASE_DELAY_MS = 2_000;
+/** Number of consecutive failures required to open the circuit. */
+export const CB_FAILURE_THRESHOLD = 3;
+/** How long the circuit stays open before transitioning to half-open. */
+export const CB_RESET_TIMEOUT_MS = 60_000;
+/** Upper bound clamped on the env-override per-attempt timeout (30 minutes). */
+export const HF_MAX_TIMEOUT_MS = 30 * 60 * 1_000;
+/** Upper bound clamped on the env-override attempt count. */
+export const HF_MAX_ATTEMPTS_CAP = 10;
 /**
  * @internal Exported only for unit tests and the two embedder entry points
  * (`core/embeddings/embedder.ts` + `mcp/core/embedder.ts`). Not part of the
@@ -44,3 +61,190 @@ export function applyHfEnvOverrides(env) {
         env.remoteHost = endpoint.endsWith('/') ? endpoint : endpoint + '/';
     }
 }
+/**
+ * @internal Exported for unit tests and the two embedder entry points.
+ *
+ * Returns true when an error message indicates a network-level fetch failure
+ * during HuggingFace model download (e.g. `TypeError: fetch failed`,
+ * `ECONNREFUSED`, `ENOTFOUND`, `ETIMEDOUT`, `ECONNRESET`).
+ *
+ * These errors are not device-specific and cannot be fixed by falling back to
+ * a different ONNX device — the caller should rethrow immediately with
+ * guidance about `HF_ENDPOINT`.
+ */
+export function isNetworkFetchError(message) {
+    return (message.includes('fetch failed') ||
+        message.includes('ECONNREFUSED') ||
+        message.includes('ENOTFOUND') ||
+        message.includes('ETIMEDOUT') ||
+        message.includes('ECONNRESET'));
+}
+// ---------------------------------------------------------------------------
+// Circuit breaker
+// ---------------------------------------------------------------------------
+/** @internal Used by `withHfDownloadRetry` to mark a circuit-open rejection. */
+export const CIRCUIT_OPEN_TAG = 'hf-circuit-open';
+/**
+ * Circuit breaker for HuggingFace model downloads.
+ *
+ * After `failureThreshold` consecutive network failures the circuit opens and
+ * all subsequent calls to `withHfDownloadRetry` fail immediately without
+ * issuing any network requests. After `resetTimeoutMs` the circuit enters the
+ * half-open state and the next call is attempted — if it succeeds the circuit
+ * closes again; if it fails the circuit re-opens.
+ *
+ * Exported for unit-testing; production code should use the module-level
+ * `hfDownloadCircuit` singleton.
+ */
+export class HfDownloadCircuitBreaker {
+    failureThreshold;
+    resetTimeoutMs;
+    _state = 'closed';
+    _failures = 0;
+    /** Timestamp of the last recorded failure (ms since epoch). */
+    lastFailureAt = 0;
+    constructor(failureThreshold = CB_FAILURE_THRESHOLD, resetTimeoutMs = CB_RESET_TIMEOUT_MS) {
+        this.failureThreshold = failureThreshold;
+        this.resetTimeoutMs = resetTimeoutMs;
+    }
+    /** Effective state, factoring in the reset-timeout transition. */
+    get state() {
+        if (this._state === 'open' && Date.now() - this.lastFailureAt > this.resetTimeoutMs) {
+            this._state = 'half-open';
+        }
+        return this._state;
+    }
+    /** Returns true when the circuit is open and calls should be rejected. */
+    isOpen() {
+        return this.state === 'open';
+    }
+    /** Record a successful call — resets the failure counter and closes the circuit. */
+    recordSuccess() {
+        this._failures = 0;
+        this._state = 'closed';
+    }
+    /** Record a failed call — increments the counter and opens the circuit when the threshold is reached. */
+    recordFailure() {
+        this._failures++;
+        this.lastFailureAt = Date.now();
+        if (this._failures >= this.failureThreshold) {
+            this._state = 'open';
+        }
+    }
+    /** @internal Reset to initial state (used in tests). */
+    reset() {
+        this._failures = 0;
+        this._state = 'closed';
+        this.lastFailureAt = 0;
+    }
+}
+/** Module-level singleton shared by both embedder entry points. */
+export const hfDownloadCircuit = new HfDownloadCircuitBreaker();
+// ---------------------------------------------------------------------------
+// Retry + timeout wrapper
+// ---------------------------------------------------------------------------
+/** @internal Returns true for errors that should abort without retry (circuit-open). */
+export function isHfCircuitOpenError(message) {
+    return message.includes(CIRCUIT_OPEN_TAG);
+}
+/**
+ * Returns true for any HuggingFace download failure that warrants showing the
+ * `HF_ENDPOINT` remediation hint: either a raw network error or a
+ * circuit-open rejection (which itself was caused by repeated network errors).
+ */
+export function isHfDownloadFailure(message) {
+    return isNetworkFetchError(message) || isHfCircuitOpenError(message);
+}
+/** @internal Wraps `fn` in a hard time-limit. The timeout error contains
+ *  `ETIMEDOUT` so that `isNetworkFetchError` classifies it correctly.
+ */
+export function withDownloadTimeout(fn, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`ETIMEDOUT: model download timed out after ${Math.round(timeoutMs / 1000)}s — ` +
+            `check your network speed or set HF_ENDPOINT to a faster mirror`)), timeoutMs);
+        fn().then((v) => {
+            clearTimeout(timer);
+            resolve(v);
+        }, (e) => {
+            clearTimeout(timer);
+            reject(e);
+        });
+    });
+}
+/** @internal Async sleep (exposed for testing). */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Retry wrapper for HuggingFace model downloads with per-attempt timeout and
+ * circuit-breaker protection.
+ *
+ * Behaviour:
+ * - If the circuit is **open**, fails immediately with a `CIRCUIT_OPEN_TAG`
+ *   message (so `isHfDownloadFailure` still returns true and the caller can
+ *   show `HF_ENDPOINT` guidance).
+ * - Each attempt is wrapped in `withDownloadTimeout`.
+ * - On a network-level error (`isNetworkFetchError`) the attempt is retried
+ *   with exponential back-off; non-network errors (e.g. ONNX device failure)
+ *   are rethrown immediately without retry.
+ * - Every network failure is recorded on the circuit breaker; a success resets
+ *   it.
+ * - After all attempts are exhausted, the last network error is rethrown
+ *   so the existing `isNetworkFetchError` / `isHfDownloadFailure` guards in
+ *   the calling code still fire.
+ */
+export async function withHfDownloadRetry(fn, options = {}) {
+    // Resolve effective values — explicit options take precedence over env vars,
+    // which take precedence over built-in defaults. This lets users lower the
+    // per-attempt timeout without rebuilding (e.g.
+    //   HF_DOWNLOAD_TIMEOUT_MS=60000 npx gitnexus analyze --embeddings
+    // reduces the worst-case wait from 15 minutes to ~3 minutes).
+    //
+    // Upper bounds are clamped to prevent accidental runaway configuration:
+    //   - timeoutMs is capped at HF_MAX_TIMEOUT_MS (30 min)
+    //   - maxAttempts is floored (fractional values → integer) and capped at
+    //     HF_MAX_ATTEMPTS_CAP (10).  Values ≤ 0, NaN, or Infinity fall back to
+    //     the built-in defaults.
+    const envTimeout = Number(process.env.HF_DOWNLOAD_TIMEOUT_MS);
+    const envMaxAttempts = Number(process.env.HF_MAX_ATTEMPTS);
+    const resolvedTimeout = Number.isFinite(envTimeout) && envTimeout > 0
+        ? Math.min(envTimeout, HF_MAX_TIMEOUT_MS)
+        : HF_DOWNLOAD_TIMEOUT_MS;
+    const resolvedMaxAttempts = Number.isFinite(envMaxAttempts) && envMaxAttempts > 0
+        ? Math.min(Math.floor(envMaxAttempts), HF_MAX_ATTEMPTS_CAP)
+        : HF_MAX_ATTEMPTS;
+    const { maxAttempts = resolvedMaxAttempts, baseDelayMs = HF_BASE_DELAY_MS, timeoutMs = resolvedTimeout, circuit = hfDownloadCircuit, onRetry, } = options;
+    if (circuit.isOpen()) {
+        const secsUntilReset = Math.ceil((circuit.resetTimeoutMs - (Date.now() - circuit.lastFailureAt)) / 1000);
+        throw new Error(`${CIRCUIT_OPEN_TAG}: HuggingFace download circuit is open after repeated network failures` +
+            (secsUntilReset > 0 ? ` — will reset in ~${secsUntilReset}s` : ''));
+    }
+    let lastError = new Error('unknown error');
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        try {
+            const result = await withDownloadTimeout(fn, timeoutMs);
+            circuit.recordSuccess();
+            return result;
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+            if (!isNetworkFetchError(lastError.message)) {
+                // Non-network error (e.g. CUDA unavailable) — propagate without retry
+                throw lastError;
+            }
+            circuit.recordFailure();
+            if (circuit.isOpen()) {
+                // Circuit just tripped — fail fast, no more retries
+                throw new Error(`${CIRCUIT_OPEN_TAG}: HuggingFace download circuit opened after ${circuit.failureThreshold} consecutive failures`);
+            }
+            if (attempt < maxAttempts - 1) {
+                const delay = baseDelayMs * Math.pow(2, attempt);
+                onRetry?.(attempt + 1, maxAttempts, lastError);
+                await sleep(delay);
+            }
+        }
+    }
+    // All retries exhausted — throw the last network error so isNetworkFetchError
+    // patterns in the calling code still match and surface HF_ENDPOINT guidance.
+    throw lastError;
+}

package/dist/mcp/core/embedder.js

@@ -7,7 +7,7 @@
 import { pipeline, env } from '@huggingface/transformers';
 import { isHttpMode, getHttpDimensions, httpEmbedQuery, } from '../../core/embeddings/http-client.js';
 import { resolveEmbeddingConfig } from '../../core/embeddings/config.js';
-import { applyHfEnvOverrides } from '../../core/embeddings/hf-env.js';
+import { applyHfEnvOverrides, isHfDownloadFailure, withHfDownloadRetry, } from '../../core/embeddings/hf-env.js';
 import { silenceStdout, restoreStdout, realStderrWrite } from '../../core/lbug/pool-adapter.js';
 import { logger } from '../../core/logger.js';
 // Model config
@@ -53,7 +53,7 @@ export const initEmbedder = async () => {
                     silenceStdout();
                     process.stderr.write = (() => true);
                     try {
-                        embedderInstance = await pipeline('feature-extraction', MODEL_ID, {
+                        embedderInstance = await withHfDownloadRetry(() => pipeline('feature-extraction', MODEL_ID, {
                             device: device,
                             dtype: 'fp32',
                             session_options: {
@@ -62,7 +62,7 @@ export const initEmbedder = async () => {
                                 interOpNumThreads: 1,
                                 executionMode: 'sequential',
                             },
-                        });
+                        }));
                     }
                     finally {
                         restoreStdout();
@@ -71,7 +71,21 @@ export const initEmbedder = async () => {
                     logger.info({ device }, 'GitNexus: Embedding model loaded');
                     return embedderInstance;
                 }
-                catch {
+                catch (deviceError) {
+                    // Network errors and circuit-open errors are not device-specific —
+                    // they will fail the same way on every device. Rethrow immediately
+                    // with actionable HF_ENDPOINT guidance rather than silently falling
+                    // back to the next device.
+                    const errMsg = deviceError instanceof Error ? deviceError.message : String(deviceError);
+                    if (isHfDownloadFailure(errMsg)) {
+                        const endpointHint = process.env.HF_ENDPOINT
+                            ? `The configured endpoint (${process.env.HF_ENDPOINT}) may be unreachable.`
+                            : `huggingface.co may be unreachable from your network.\n` +
+                                `  Set HF_ENDPOINT to a mirror and retry:\n` +
+                                `    HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings\n` +
+                                `    (Windows: set HF_ENDPOINT=https://hf-mirror.com && npx gitnexus analyze --embeddings)`;
+                        throw new Error(`Failed to download embedding model: ${errMsg}\n  ${endpointHint}`);
+                    }
                     if (device === 'cpu')
                         throw new Error('Failed to load embedding model');
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.4-rc.89",
+  "version": "1.6.4-rc.90",
   "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",