gitnexus 1.6.9 → 1.6.10-aptos.0

package/dist/core/augmentation/engine.js

@@ -15,6 +15,7 @@
  */
 import path from 'path';
 import { listRegisteredRepos } from '../../storage/repo-manager.js';
+import { escapeCypherString } from '../lbug/cypher-escape.js';
 /**
  * Find the best matching repo for a given working directory.
  * Matches by checking if cwd is within the repo's path.
@@ -40,11 +41,15 @@ async function findRepoForCwd(cwd) {
             if (normalizedCwd === normalizedRepo) {
                 matched = true;
             }
-            else if (normalizedCwd.startsWith(normalizedRepo + sep)) {
-                matched = true;
-            }
-            else if (normalizedRepo.startsWith(normalizedCwd + sep)) {
-                matched = true;
+            else {
+                const repoPrefix = normalizedRepo.endsWith(sep) ? normalizedRepo : normalizedRepo + sep;
+                const cwdPrefix = normalizedCwd.endsWith(sep) ? normalizedCwd : normalizedCwd + sep;
+                if (normalizedCwd.startsWith(repoPrefix)) {
+                    matched = true;
+                }
+                else if (normalizedRepo.startsWith(cwdPrefix)) {
+                    matched = true;
+                }
             }
             if (matched && normalizedRepo.length > bestLen) {
                 bestMatch = entry;
@@ -76,7 +81,7 @@ async function findRepoForCwd(cwd) {
 export async function augment(pattern, cwd) {
     if (!pattern || pattern.length < 3)
         return '';
-    const patternFirstWord = pattern.trim().replace(/'/g, "''").split(/\s+/)[0];
+    const patternFirstWord = escapeCypherString(pattern.trim()).split(/\s+/)[0];
     if (!patternFirstWord || patternFirstWord.length < 2)
         return '';
     const workDir = cwd || process.cwd();
@@ -97,7 +102,7 @@ export async function augment(pattern, cwd) {
         // Step 2: Map BM25 file results to symbols
         const symbolMatches = [];
         for (const result of bm25Results.slice(0, 5)) {
-            const escaped = result.filePath.replace(/'/g, "''");
+            const escaped = escapeCypherString(result.filePath);
             try {
                 const symbols = await executeQuery(repoId, `
           MATCH (n) WHERE n.filePath = '${escaped}'
@@ -147,7 +152,7 @@ export async function augment(pattern, cwd) {
             .filter((sym, i, arr) => arr.findIndex((s) => s.nodeId === sym.nodeId) === i);
         if (uniqueSymbols.length === 0)
             return '';
-        const idList = uniqueSymbols.map((s) => `'${s.nodeId.replace(/'/g, "''")}'`).join(', ');
+        const idList = uniqueSymbols.map((s) => `'${escapeCypherString(s.nodeId)}'`).join(', ');
         // Batch fetch callers
         const callersMap = new Map();
         try {

package/dist/core/embeddings/embedder.d.ts

@@ -8,6 +8,7 @@
  */
 import type { FeatureExtractionPipeline } from '@huggingface/transformers';
 import { type EmbeddingConfig, type ModelProgress } from './types.js';
+import { type EmbeddingRequestOptions } from './http-client.js';
 /**
  * Progress callback type for model loading
  */
@@ -45,7 +46,7 @@ export declare const getEmbedder: () => FeatureExtractionPipeline;
  * @param text - Text to embed
  * @returns Float32Array of embedding vector
  */
-export declare const embedText: (text: string) => Promise<Float32Array>;
+export declare const embedText: (text: string, options?: EmbeddingRequestOptions) => Promise<Float32Array>;
 /**
  * Embed multiple texts in a single batch
  * More efficient than calling embedText multiple times
@@ -53,7 +54,7 @@ export declare const embedText: (text: string) => Promise<Float32Array>;
  * @param texts - Array of texts to embed
  * @returns Array of Float32Array embedding vectors
  */
-export declare const embedBatch: (texts: string[]) => Promise<Float32Array[]>;
+export declare const embedBatch: (texts: string[], options?: EmbeddingRequestOptions) => Promise<Float32Array[]>;
 /**
  * Convert Float32Array to regular number array (for LadybugDB storage)
  */

package/dist/core/embeddings/embedder.js

@@ -13,11 +13,12 @@ if (!process.env.ORT_LOG_LEVEL) {
     process.env.ORT_LOG_LEVEL = '3';
 }
 import { DEFAULT_EMBEDDING_CONFIG } from './types.js';
-import { isHttpMode, getHttpDimensions, httpEmbed } from './http-client.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 { getLocalEmbeddingRuntimeBlocker, getMissingLocalEmbeddingStackMessage, } from './runtime-support.js';
 import { ensureOnnxRuntimeCommonResolvable } from './onnxruntime-common-resolver.js';
+import { ensureEmbeddingStackResolvable } from './runtime-install.js';
 import { ensureOnnxRuntimeNodeMatchesSystem, isEffectiveCudaAvailable, } from './onnxruntime-node-resolver.js';
 import { logger } from '../logger.js';
 // Module-level state for singleton pattern
@@ -73,6 +74,11 @@ export const initEmbedder = async (onProgress, config = {}, forceDevice) => {
         try {
             // Lazy-load transformers.js only after the runtime guard has passed, so
             // unsupported platforms never reach the native ONNX import (#1515).
+            // Registered FIRST so it sits last in the hook chain (registerHooks runs
+            // the most recent hook first): when the optional stack was pruned at
+            // install time (#2370), its bare specifiers fall back to the on-demand
+            // runtime prefix.
+            ensureEmbeddingStackResolvable();
             // Under pnpm-strict / `pnpm dlx`, transformers' phantom `onnxruntime-common`
             // import is unresolvable; register the fallback resolver first (#307).
             ensureOnnxRuntimeCommonResolvable();
@@ -82,7 +88,15 @@ export const initEmbedder = async (onProgress, config = {}, forceDevice) => {
             // 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');
+            // The stack is an optionalDependency: npm prunes it when onnxruntime-node's
+            // postinstall can't reach api.nuget.org (#2370). Rethrow with actionable
+            // reinstall guidance instead of a raw ERR_MODULE_NOT_FOUND.
+            const { pipeline, env } = await import('@huggingface/transformers').catch((err) => {
+                const missing = getMissingLocalEmbeddingStackMessage(err);
+                if (missing)
+                    throw new Error(missing);
+                throw err;
+            });
             // Configure transformers.js environment
             env.allowLocalModels = false;
             // Bridge user-controlled env vars to transformers.js: HF_HOME →
@@ -229,9 +243,10 @@ export const getEmbedder = () => {
  * @param text - Text to embed
  * @returns Float32Array of embedding vector
  */
-export const embedText = async (text) => {
+export const embedText = async (text, options = {}) => {
+    options.signal?.throwIfAborted();
     if (isHttpMode()) {
-        const [vec] = await httpEmbed([text]);
+        const [vec] = await httpEmbed([text], options);
         return vec;
     }
     const embedder = getEmbedder();
@@ -249,12 +264,13 @@ export const embedText = async (text) => {
  * @param texts - Array of texts to embed
  * @returns Array of Float32Array embedding vectors
  */
-export const embedBatch = async (texts) => {
+export const embedBatch = async (texts, options = {}) => {
+    options.signal?.throwIfAborted();
     if (texts.length === 0) {
         return [];
     }
     if (isHttpMode()) {
-        return httpEmbed(texts);
+        return httpEmbed(texts, options);
     }
     const embedder = getEmbedder();
     // Process batch
@@ -262,6 +278,7 @@ export const embedBatch = async (texts) => {
         pooling: 'mean',
         normalize: true,
     });
+    options.signal?.throwIfAborted();
     // Result shape is [batch_size, dimensions]
     // Need to split into individual vectors
     const data = result.data;

package/dist/core/embeddings/embedding-identity.d.ts

@@ -0,0 +1,11 @@
+export interface EmbeddingIdentity {
+    model: string;
+    dimensions: number;
+    provider: string;
+}
+/**
+ * Identify the vector space strongly enough to resume without mixing providers.
+ * The HTTP fingerprint excludes URL credentials and query parameters before
+ * hashing, so metadata contains neither an endpoint nor a secret-derived hash.
+ */
+export declare function resolveEmbeddingIdentity(): EmbeddingIdentity;

package/dist/core/embeddings/embedding-identity.js

@@ -0,0 +1,24 @@
+import { createHash } from 'node:crypto';
+import { getEmbeddingDimensions } from './embedder.js';
+import { resolveEmbeddingConfig } from './config.js';
+import { isHttpMode, safeUrl } from './http-client.js';
+/**
+ * Identify the vector space strongly enough to resume without mixing providers.
+ * The HTTP fingerprint excludes URL credentials and query parameters before
+ * hashing, so metadata contains neither an endpoint nor a secret-derived hash.
+ */
+export function resolveEmbeddingIdentity() {
+    const httpMode = isHttpMode();
+    const provider = httpMode
+        ? `http:${createHash('sha256')
+            .update(safeUrl(process.env.GITNEXUS_EMBEDDING_URL ?? ''))
+            .digest('hex')}`
+        : 'local';
+    return {
+        model: httpMode
+            ? process.env.GITNEXUS_EMBEDDING_MODEL
+            : resolveEmbeddingConfig().modelId,
+        dimensions: getEmbeddingDimensions(),
+        provider,
+    };
+}

package/dist/core/embeddings/embedding-pipeline.d.ts

@@ -51,12 +51,47 @@ export declare const batchInsertEmbeddings: (executeWithReusedStatement: (cypher
     embedding: number[];
     contentHash?: string;
 }>) => Promise<void>;
+/**
+ * Create the vector index for semantic search (indexes the CodeEmbedding table).
+ *
+ * Keeps the embedding-specific extension-install policy gate here
+ * (ensureVectorExtensionAvailable → resolveEmbeddingInstallPolicy, default
+ * `auto` for the analyze write path), then delegates the actual
+ * `CALL CREATE_VECTOR_INDEX(...)` to the adapter, which runs it through the
+ * unprepared `conn.query()` path. It must NOT go through the injected
+ * `executeQuery` (prepared `conn.prepare()`): LadybugDB cannot prepare that
+ * procedure and fails with "We do not support prepare multiple statements" —
+ * the silent degrade in #2114.
+ *
+ * Exported for run-analyze's wipe-and-restore seam (tri-review 4669518496
+ * P1): a full-rebuild/escalated write wipes the DB files — index included —
+ * and a preserve-only run restores embedding ROWS without ever reaching the
+ * pipeline call sites below, so the orchestrator recreates the index through
+ * this same policy-gated, warn-on-failure entry point. Consumed there via
+ * dynamic import only (lazy-embeddings convention, #2370).
+ */
+export declare const buildVectorIndex: () => Promise<boolean>;
 export interface EmbeddingPipelineResult {
     nodesProcessed: number;
     chunksProcessed: number;
     vectorIndexReady: boolean;
     semanticMode: 'vector-index' | 'exact-scan';
 }
+export interface EmbeddingPipelineCheckpoint {
+    nodesProcessed: number;
+    totalNodes: number;
+    chunksProcessed: number;
+}
+export interface EmbeddingPipelineCheckpointWindow extends EmbeddingPipelineCheckpoint {
+    nodeIds: string[];
+}
+export interface EmbeddingPipelineOptions {
+    signal?: AbortSignal;
+    checkpointEveryNodes?: number;
+    forceReembedNodeIds?: ReadonlySet<string>;
+    onCheckpointWindowStart?: (window: EmbeddingPipelineCheckpointWindow) => Promise<void>;
+    onCheckpoint?: (checkpoint: EmbeddingPipelineCheckpoint) => Promise<void>;
+}
 /**
  * Run the embedding pipeline
  *
@@ -69,7 +104,7 @@ export interface EmbeddingPipelineResult {
  *        Nodes whose hash matches are skipped; nodes with a changed hash are DELETE'd
  *        and re-embedded; nodes not in the map are embedded fresh.
  */
-export declare const runEmbeddingPipeline: (executeQuery: (cypher: string) => Promise<any[]>, executeWithReusedStatement: (cypher: string, paramsList: Array<Record<string, any>>) => Promise<void>, onProgress: EmbeddingProgressCallback, config?: Partial<EmbeddingConfig>, skipNodeIds?: Set<string>, existingEmbeddings?: Map<string, string>) => Promise<EmbeddingPipelineResult>;
+export declare const runEmbeddingPipeline: (executeQuery: (cypher: string) => Promise<any[]>, executeWithReusedStatement: (cypher: string, paramsList: Array<Record<string, any>>) => Promise<void>, onProgress: EmbeddingProgressCallback, config?: Partial<EmbeddingConfig>, skipNodeIds?: Set<string>, existingEmbeddings?: Map<string, string>, pipelineOptions?: EmbeddingPipelineOptions) => Promise<EmbeddingPipelineResult>;
 /**
  * Perform semantic search using the vector index with chunk deduplication
  */

package/dist/core/embeddings/embedding-pipeline.js

@@ -18,6 +18,7 @@ import { DEFAULT_VECTOR_MAX_DISTANCE, getVectorMaxDistance, resolveEmbeddingConf
 import { rankExactEmbeddingRows } from './exact-search.js';
 import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME, STALE_HASH_SENTINEL } from '../lbug/schema.js';
 import { loadVectorExtension, createVectorIndex } from '../lbug/lbug-adapter.js';
+import { escapeCypherString } from '../lbug/cypher-escape.js';
 import { getExactScanLimit } from '../platform/capabilities.js';
 import { logger } from '../logger.js';
 const isDev = process.env.NODE_ENV === 'development';
@@ -134,13 +135,49 @@ const queryEmbeddableNodes = async (executeQuery) => {
             }
         }
     }
-    return allNodes;
+    return allNodes.length > 0 ? allNodes : queryFallbackFileNodes(executeQuery);
+};
+/**
+ * Static and documentation repositories may contain no code symbols while
+ * still persisting useful text on File nodes. Keep File embeddings as a
+ * zero-symbol fallback so code repositories retain symbol-first selection.
+ */
+const queryFallbackFileNodes = async (executeQuery) => {
+    try {
+        const rows = await executeQuery(`
+      MATCH (n:File)
+      RETURN n.id AS id, n.name AS name, 'File' AS label,
+             n.filePath AS filePath, n.content AS content
+    `);
+        return rows
+            .map((row) => {
+            const content = row.content ?? row[4] ?? '';
+            return {
+                id: row.id ?? row[0],
+                name: row.name ?? row[1],
+                label: row.label ?? row[2] ?? 'File',
+                filePath: row.filePath ?? row[3],
+                content,
+                startLine: 1,
+                endLine: Math.max(1, content.split('\n').length),
+            };
+        })
+            .filter((node) => node.id &&
+            node.filePath &&
+            node.content.trim() &&
+            node.content !== '[Binary file - content not stored]');
+    }
+    catch (error) {
+        if (isDev) {
+            logger.warn({ error }, 'Fallback File-node embedding query failed:');
+        }
+        return [];
+    }
 };
 /**
  * Batch INSERT chunk-aware embeddings into CodeEmbedding table
  */
 export const batchInsertEmbeddings = async (executeWithReusedStatement, updates) => {
-    const cypher = `CREATE (e:${EMBEDDING_TABLE_NAME} {id: $id, nodeId: $nodeId, chunkIndex: $chunkIndex, startLine: $startLine, endLine: $endLine, embedding: $embedding, contentHash: $contentHash})`;
     const paramsList = updates.map((u) => ({
         id: `${u.nodeId}:${u.chunkIndex}`,
         nodeId: u.nodeId,
@@ -150,6 +187,10 @@ export const batchInsertEmbeddings = async (executeWithReusedStatement, updates)
         embedding: u.embedding,
         contentHash: u.contentHash ?? STALE_HASH_SENTINEL,
     }));
+    if (paramsList.length === 0)
+        return;
+    await executeWithReusedStatement(`MATCH (e:${EMBEDDING_TABLE_NAME} {id: $id}) DELETE e`, paramsList.map(({ id }) => ({ id })));
+    const cypher = `CREATE (e:${EMBEDDING_TABLE_NAME} {id: $id, nodeId: $nodeId, chunkIndex: $chunkIndex, startLine: $startLine, endLine: $endLine, embedding: $embedding, contentHash: $contentHash})`;
     await executeWithReusedStatement(cypher, paramsList);
 };
 /**
@@ -163,8 +204,15 @@ export const batchInsertEmbeddings = async (executeWithReusedStatement, updates)
  * `executeQuery` (prepared `conn.prepare()`): LadybugDB cannot prepare that
  * procedure and fails with "We do not support prepare multiple statements" —
  * the silent degrade in #2114.
+ *
+ * Exported for run-analyze's wipe-and-restore seam (tri-review 4669518496
+ * P1): a full-rebuild/escalated write wipes the DB files — index included —
+ * and a preserve-only run restores embedding ROWS without ever reaching the
+ * pipeline call sites below, so the orchestrator recreates the index through
+ * this same policy-gated, warn-on-failure entry point. Consumed there via
+ * dynamic import only (lazy-embeddings convention, #2370).
  */
-const buildVectorIndex = async () => {
+export const buildVectorIndex = async () => {
     // This pre-check applies the embedding-specific install policy
     // (resolveEmbeddingInstallPolicy, default `auto` for analyze) before reaching
     // the adapter. The adapter's createVectorIndex() calls loadVectorExtension()
@@ -223,11 +271,18 @@ const deleteStaleEmbeddingRows = async (executeWithReusedStatement, nodeIds) =>
  *        Nodes whose hash matches are skipped; nodes with a changed hash are DELETE'd
  *        and re-embedded; nodes not in the map are embedded fresh.
  */
-export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatement, onProgress, config = {}, skipNodeIds, existingEmbeddings) => {
+export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatement, onProgress, config = {}, skipNodeIds, existingEmbeddings, pipelineOptions = {}) => {
     const finalConfig = resolveEmbeddingConfig(config);
     let totalChunks = 0;
+    const checkpointEveryNodes = pipelineOptions.checkpointEveryNodes ?? 5_000;
+    if (!Number.isSafeInteger(checkpointEveryNodes) || checkpointEveryNodes <= 0) {
+        throw new Error('checkpointEveryNodes must be a positive integer');
+    }
+    const throwIfCancelled = () => pipelineOptions.signal?.throwIfAborted();
     try {
+        throwIfCancelled();
         const vectorAvailable = await ensureVectorExtensionAvailable();
+        throwIfCancelled();
         if (!vectorAvailable) {
             logger.warn(vectorUnavailableMessage);
         }
@@ -246,6 +301,7 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
                     modelDownloadPercent: downloadPercent,
                 });
             }, finalConfig);
+            throwIfCancelled();
         }
         onProgress({
             phase: 'loading-model',
@@ -257,6 +313,8 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
         }
         // Phase 2: Query embeddable nodes
         let nodes = await queryEmbeddableNodes(executeQuery);
+        throwIfCancelled();
+        const embeddableNodeIds = new Set(nodes.map((node) => node.id));
         // Incremental mode: compare content hashes, delete stale rows, skip fresh ones.
         // Computed hashes for stale nodes are cached so batchInsertEmbeddings can reuse them
         // (avoids double computation).
@@ -265,16 +323,18 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
         // than all up front — see U6 / KTD7. `staleNodeIds` is consulted inside the
         // batch loop; it stays empty in full (non-incremental) mode so no deletes fire.
         const staleNodeIds = new Set();
-        if (existingEmbeddings && existingEmbeddings.size > 0) {
+        const forceReembedNodeIds = pipelineOptions.forceReembedNodeIds;
+        if ((existingEmbeddings && existingEmbeddings.size > 0) ||
+            (forceReembedNodeIds && forceReembedNodeIds.size > 0)) {
             const beforeCount = nodes.length;
             nodes = nodes.filter((n) => {
-                const existingHash = existingEmbeddings.get(n.id);
+                const existingHash = existingEmbeddings?.get(n.id);
                 if (existingHash === undefined) {
                     // New node — needs embedding
                     return true;
                 }
                 const currentHash = contentHashForNode(n, finalConfig);
-                if (currentHash !== existingHash) {
+                if (currentHash !== existingHash || forceReembedNodeIds?.has(n.id)) {
                     // Content changed — cache hash for reuse during insert, mark for DELETE + re-embed
                     computedStaleHashes.set(n.id, currentHash);
                     staleNodeIds.add(n.id);
@@ -287,11 +347,17 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
                 logger.info(`📦 Incremental embeddings: ${beforeCount} total, ${existingEmbeddings.size} cached, ${staleNodeIds.size} stale, ${nodes.length} to embed`);
             }
         }
+        if (forceReembedNodeIds && forceReembedNodeIds.size > 0) {
+            const removedPendingNodeIds = [...forceReembedNodeIds].filter((nodeId) => !embeddableNodeIds.has(nodeId));
+            await deleteStaleEmbeddingRows(executeWithReusedStatement, removedPendingNodeIds);
+            throwIfCancelled();
+        }
         const totalNodes = nodes.length;
         if (isDev) {
             logger.info(`📊 Found ${totalNodes} embeddable nodes`);
         }
         if (totalNodes === 0) {
+            throwIfCancelled();
             // Ensure the vector index exists even when no new nodes need embedding.
             // A prior crash or first-time incremental run may have left CodeEmbedding
             // rows without ever reaching index creation.
@@ -313,6 +379,7 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
         const batchSize = finalConfig.batchSize;
         const chunkSize = finalConfig.chunkSize;
         const overlap = finalConfig.overlap;
+        const checkpointWindowNodeCount = Math.max(batchSize, Math.ceil(checkpointEveryNodes / batchSize) * batchSize);
         let processedNodes = 0;
         onProgress({
             phase: 'embedding',
@@ -324,6 +391,18 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
         });
         // Process in batches of nodes
         for (let batchIndex = 0; batchIndex < totalNodes; batchIndex += batchSize) {
+            throwIfCancelled();
+            if (pipelineOptions.onCheckpointWindowStart && batchIndex % checkpointWindowNodeCount === 0) {
+                await pipelineOptions.onCheckpointWindowStart({
+                    nodesProcessed: processedNodes,
+                    totalNodes,
+                    chunksProcessed: totalChunks,
+                    nodeIds: nodes
+                        .slice(batchIndex, batchIndex + checkpointWindowNodeCount)
+                        .map((node) => node.id),
+                });
+                throwIfCancelled();
+            }
             const batch = nodes.slice(batchIndex, batchIndex + batchSize);
             // Chunk each node and generate text
             const allTexts = [];
@@ -379,6 +458,7 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
             // Preserves Kuzu's required DELETE-before-INSERT for vector-indexed rows.
             const batchStaleIds = batch.filter((n) => staleNodeIds.has(n.id)).map((n) => n.id);
             await deleteStaleEmbeddingRows(executeWithReusedStatement, batchStaleIds);
+            throwIfCancelled();
             // Embed chunk texts in sub-batches to control memory
             const EMBED_SUB_BATCH = finalConfig.subBatchSize;
             for (let si = 0; si < allTexts.length; si += EMBED_SUB_BATCH) {
@@ -386,7 +466,7 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
                 const subUpdates = allUpdates.slice(si, si + EMBED_SUB_BATCH);
                 let embeddings;
                 try {
-                    embeddings = await embedBatch(subTexts);
+                    embeddings = await embedBatch(subTexts, { signal: pipelineOptions.signal });
                 }
                 catch (embedErr) {
                     logger.error({ embedErr }, `❌ embedBatch failed for ${subTexts.length} texts (first: "${subTexts[0]?.substring(0, 80)}..."):`);
@@ -397,6 +477,7 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
                     embedding: embeddingToArray(embeddings[i]),
                 }));
                 await batchInsertEmbeddings(executeWithReusedStatement, dbUpdates);
+                throwIfCancelled();
             }
             processedNodes += batch.length;
             totalChunks += allUpdates.length;
@@ -409,8 +490,18 @@ export const runEmbeddingPipeline = async (executeQuery, executeWithReusedStatem
                 currentBatch: Math.floor(batchIndex / batchSize) + 1,
                 totalBatches: Math.ceil(totalNodes / batchSize),
             });
+            if (pipelineOptions.onCheckpoint &&
+                (processedNodes % checkpointWindowNodeCount === 0 || processedNodes === totalNodes)) {
+                await pipelineOptions.onCheckpoint({
+                    nodesProcessed: processedNodes,
+                    totalNodes,
+                    chunksProcessed: totalChunks,
+                });
+                throwIfCancelled();
+            }
         }
         // Phase 4: Create vector index
+        throwIfCancelled();
         onProgress({
             phase: 'indexing',
             percent: 90,
@@ -536,7 +627,7 @@ export const semanticSearch = async (executeQuery, query, k = 10, maxDistance =
     // Batch-fetch metadata per label
     const results = [];
     for (const [label, items] of byLabel) {
-        const idList = items.map((i) => `'${i.nodeId.replace(/'/g, "''")}'`).join(', ');
+        const idList = items.map((i) => `'${escapeCypherString(i.nodeId)}'`).join(', ');
         try {
             const nodeQuery = `
         MATCH (n:\`${label}\`) WHERE n.id IN [${idList}]

package/dist/core/embeddings/http-client.d.ts

@@ -10,8 +10,17 @@
  * fails fast on a flapping endpoint. Per-attempt timeout is enforced
  * via `AbortSignal.timeout` on the underlying fetch.
  */
+export interface EmbeddingRequestOptions {
+    signal?: AbortSignal;
+}
 /**
- * Check whether HTTP embedding mode is active (env vars are set).
+ * Whether HTTP embedding mode is active — i.e. both `GITNEXUS_EMBEDDING_URL` and
+ * `GITNEXUS_EMBEDDING_MODEL` are set. A pure presence probe: it deliberately does
+ * NOT call {@link readConfig}, so it never throws on a malformed
+ * `GITNEXUS_EMBEDDING_DIMS`. This lets its ~13 call sites (analyze, doctor,
+ * run-analyze, embedder, mcp) probe the mode without a defensive try/catch; the
+ * DIMS value is validated where it is actually used (`readConfig` in
+ * `httpEmbed`/`httpEmbedQuery`), surfacing a recognizable config error. See #2385.
  */
 export declare const isHttpMode: () => boolean;
 /**
@@ -26,6 +35,27 @@ export declare const getHttpDimensions: () => number | undefined;
  * custom-endpoint confirmation can mask the same way.
  */
 export declare const safeUrl: (url: string) => string;
+/**
+ * Error thrown by this module's HTTP embedding path (`httpEmbedBatch` /
+ * `httpEmbed` / `httpEmbedQuery`) for any endpoint failure — a
+ * connection/timeout/DNS error, an open circuit, a non-OK status, an
+ * unparseable or wrong-shape response body, an empty response, or a dimension
+ * mismatch.
+ *
+ * Carrying a distinct type (rather than a plain `Error`) lets the CLI tell a
+ * *custom endpoint* failure apart from a HuggingFace *model download* failure
+ * without matching message text: the two share the same underlying network
+ * substrings (`fetch failed`, `ECONNREFUSED`, …), which is exactly why
+ * `isNetworkFetchError` in `hf-env.ts` cannot tell them apart. Keying on the
+ * type instead of the message is also locale-proof and survives message
+ * rewording. The human-readable `.message` (built with `safeUrl` and the
+ * underlying reason) is what the CLI surfaces to the user. See #2385.
+ */
+export declare class HttpEmbeddingError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
 /**
  * Embed texts via the HTTP backend, splitting into batches.
  * Reads config from env vars on every call.
@@ -33,7 +63,7 @@ export declare const safeUrl: (url: string) => string;
  * @param texts - Array of texts to embed
  * @returns Array of Float32Array embedding vectors
  */
-export declare const httpEmbed: (texts: string[]) => Promise<Float32Array[]>;
+export declare const httpEmbed: (texts: string[], requestOptions?: EmbeddingRequestOptions) => Promise<Float32Array[]>;
 /**
  * Embed a single query text via the HTTP backend.
  * Convenience for MCP search where only one vector is needed.
@@ -41,4 +71,4 @@ export declare const httpEmbed: (texts: string[]) => Promise<Float32Array[]>;
  * @param text - Query text to embed
  * @returns Embedding vector as number array
  */
-export declare const httpEmbedQuery: (text: string) => Promise<number[]>;
+export declare const httpEmbedQuery: (text: string, requestOptions?: EmbeddingRequestOptions) => Promise<number[]>;