gitnexus 1.6.10-rc.2 → 1.6.10-rc.21

package/dist/cli/i18n/en.d.ts

@@ -40,9 +40,10 @@ export declare const en: {
     readonly 'clean.deleteBranch': "This will delete the branch index \"{{branch}}\" at: {{path}}";
     readonly 'clean.deletedBranch': "Deleted branch index: {{branch}}";
     readonly 'clean.lbugSidecars.state': "LadybugDB sidecar state: {{state}}";
-    readonly 'clean.lbugSidecars.none': "No quarantined LadybugDB missing-shadow WAL sidecars found.";
-    readonly 'clean.lbugSidecars.preview': "This will delete {{count}} quarantined LadybugDB missing-shadow WAL sidecar(s):";
-    readonly 'clean.lbugSidecars.deleted': "Deleted {{count}} quarantined LadybugDB missing-shadow WAL sidecar(s).";
+    readonly 'clean.lbugSidecars.none': "No parked LadybugDB recovery sidecars found (missing-shadow WAL quarantines or dirty-recovery parks).";
+    readonly 'clean.lbugSidecars.preview': "This will delete {{count}} parked LadybugDB recovery sidecar(s) (missing-shadow WAL quarantines and dirty-recovery parks):";
+    readonly 'clean.lbugSidecars.deleted': "Deleted {{count}} parked LadybugDB recovery sidecar(s).";
+    readonly 'clean.lbugSidecars.failed': "Could not delete {{count}} locked file(s) — stop the process holding them (GitNexus MCP/serve or an antivirus scan) and re-run:";
     readonly 'remove.nothingToRemove': "Nothing to remove: {{message}}";
     readonly 'remove.deleteTarget': "This will delete the GitNexus index for: {{name}}";
     readonly 'remove.removed': "Removed: {{name}}";
@@ -117,6 +118,8 @@ export declare const en: {
     readonly 'help.command.list.description': "List all indexed repositories";
     readonly 'help.command.status.description': "Show index status for current repo";
     readonly 'help.command.doctor.description': "Show runtime platform capabilities and embedding configuration";
+    readonly 'help.command.embeddings.description': "Manage the on-demand local embedding runtime";
+    readonly 'help.command.embeddings.install.description': "Install the local embedding stack (@huggingface/transformers + onnxruntime-node) on demand. Heals installs where npm skipped the optional packages (e.g. behind an HTTP proxy, #2370). Downloads only from your configured npm registry — mirrors and proxies apply.";
     readonly 'help.command.clean.description': "Delete GitNexus index for current repo";
     readonly 'help.command.remove.description': "Delete the GitNexus index for a registered repo (by alias, name, or absolute path). Unlike `clean`, does not require being inside the repo. Idempotent on unknown targets.";
     readonly 'help.command.wiki.description': "Generate repository wiki from knowledge graph";
@@ -173,7 +176,7 @@ export declare const en: {
     readonly 'help.option.uninstall.force': "Apply the changes (default is a dry-run preview)";
     readonly 'help.option.clean.all': "Clean all indexed repos";
     readonly 'help.option.clean.branch': "Delete only the named branch index (not the workspace index)";
-    readonly 'help.option.clean.lbugSidecars': "Clean quarantined LadybugDB missing-shadow WAL sidecars";
+    readonly 'help.option.clean.lbugSidecars': "Clean parked LadybugDB recovery sidecars (missing-shadow WAL quarantines and dirty-recovery parks)";
     readonly 'help.option.wiki.force': "Force full regeneration even if up to date";
     readonly 'help.option.wiki.provider': "LLM provider: openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: openai)";
     readonly 'help.option.wiki.model': "LLM model or Azure deployment name (default: minimax/minimax-m2.5)";
@@ -220,6 +223,8 @@ export declare const en: {
     readonly 'help.option.check.cycles': "Detect circular imports and fail when any are found";
     readonly 'help.option.evalServer.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 to expose to all interfaces)";
     readonly 'help.option.evalServer.idleTimeout': "Auto-shutdown after N seconds idle (0 = disabled)";
+    readonly 'help.option.embeddings.install.cuda': "Also download the CUDA GPU binaries (runs onnxruntime-node's NuGet postinstall; set GLOBAL_AGENT_HTTPS_PROXY behind a proxy)";
+    readonly 'help.option.embeddings.install.force': "Install into the runtime prefix even when the stack already resolves";
     readonly 'help.option.group.create.force': "Overwrite existing group";
     readonly 'help.option.group.sync.skipEmbeddings': "Exact + BM25 only (no embedding fallback)";
     readonly 'help.option.group.sync.exactOnly': "Exact match only";
@@ -238,5 +243,5 @@ export declare const en: {
     readonly 'help.option.group.contracts.type': "Filter by contract type";
     readonly 'help.option.group.contracts.repo': "Filter by repo";
     readonly 'help.option.group.contracts.unmatched': "Show only unmatched contracts";
-    readonly 'help.analyze.environment': "\nEnvironment variables:\n  GITNEXUS_NO_GITIGNORE=1   Skip .gitignore parsing (still reads .gitnexusignore)\n  GITNEXUS_MAX_FILE_SIZE=N  Override large-file skip threshold (KB). Default 512, max 32768.\n  GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker idle timeout in milliseconds. Default 30000.\n  GITNEXUS_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL auto-checkpoint threshold in bytes (default 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).\n  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker job byte budget. Default 8388608.\n  GITNEXUS_WORKER_POOL_SIZE=N  Parse worker count override. Default cores-1 capped at 16.\n  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  Concurrent in-flight parse chunks. Default 2.\n  GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N  Max replacement spawns per slot before drop. Default 3.\n  GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  Total retry wall-time per job. Default 5x sub-batch timeout.\n  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  Per-slot deaths to trip circuit breaker. Default max(3, poolSize).\n  GITNEXUS_EMBEDDING_THREADS=N  Limit local ONNX CPU threads for --embeddings.\n  GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N  Max embedding chunks for exact-scan fallback. Default 10000.\n  GITNEXUS_VECTOR_MAX_DISTANCE=N  Max accepted semantic/vector cosine distance (0 < N <= 2; higher values clamp to 2). Default 0.6 for MCP, 0.5 elsewhere.\n\nFlags override the corresponding env vars when both are provided.\n\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n     `!__tests__/` to index a directory that is auto-filtered by default (#771).";
+    readonly 'help.analyze.environment': "\nEnvironment variables:\n  GITNEXUS_NO_GITIGNORE=1   Skip .gitignore parsing (still reads .gitnexusignore)\n  GITNEXUS_MAX_FILE_SIZE=N  Override large-file skip threshold (KB). Default 512, max 32768.\n  GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker idle timeout in milliseconds. Default 30000.\n  GITNEXUS_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL auto-checkpoint threshold in bytes (default 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).\n  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker job byte budget. Default 8388608.\n  GITNEXUS_WORKER_POOL_SIZE=N  Parse worker count override. Default cores-1 capped at 16.\n  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  Concurrent in-flight parse chunks. Default 2.\n  GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N  Max replacement spawns per slot before drop. Default 3.\n  GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  Total retry wall-time per job. Default 5x sub-batch timeout.\n  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  Per-slot deaths to trip circuit breaker. Default max(3, poolSize).\n  GITNEXUS_WORKER_SHUTDOWN_DRAIN_MS=N  Max wait at pool shutdown for a retired worker still inside native code (terminated at its next safe point instead of aborting the process). Default 30000.\n  GITNEXUS_CPP_CAPTURE_BUDGET_MS=N  Per-file wall-clock budget for C++ capture extraction; on breach the file keeps partial captures with a warning. Default 20000.\n  GITNEXUS_EMBEDDING_THREADS=N  Limit local ONNX CPU threads for --embeddings.\n  GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N  Max embedding chunks for exact-scan fallback. Default 10000.\n  GITNEXUS_VECTOR_MAX_DISTANCE=N  Max accepted semantic/vector cosine distance (0 < N <= 2; higher values clamp to 2). Default 0.6 for MCP, 0.5 elsewhere.\n\nFlags override the corresponding env vars when both are provided.\n\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n     `!__tests__/` to index a directory that is auto-filtered by default (#771).";
 };

package/dist/cli/i18n/en.js

@@ -40,9 +40,10 @@ export const en = {
     'clean.deleteBranch': 'This will delete the branch index "{{branch}}" at: {{path}}',
     'clean.deletedBranch': 'Deleted branch index: {{branch}}',
     'clean.lbugSidecars.state': 'LadybugDB sidecar state: {{state}}',
-    'clean.lbugSidecars.none': 'No quarantined LadybugDB missing-shadow WAL sidecars found.',
-    'clean.lbugSidecars.preview': 'This will delete {{count}} quarantined LadybugDB missing-shadow WAL sidecar(s):',
-    'clean.lbugSidecars.deleted': 'Deleted {{count}} quarantined LadybugDB missing-shadow WAL sidecar(s).',
+    'clean.lbugSidecars.none': 'No parked LadybugDB recovery sidecars found (missing-shadow WAL quarantines or dirty-recovery parks).',
+    'clean.lbugSidecars.preview': 'This will delete {{count}} parked LadybugDB recovery sidecar(s) (missing-shadow WAL quarantines and dirty-recovery parks):',
+    'clean.lbugSidecars.deleted': 'Deleted {{count}} parked LadybugDB recovery sidecar(s).',
+    'clean.lbugSidecars.failed': 'Could not delete {{count}} locked file(s) — stop the process holding them (GitNexus MCP/serve or an antivirus scan) and re-run:',
     'remove.nothingToRemove': 'Nothing to remove: {{message}}',
     'remove.deleteTarget': 'This will delete the GitNexus index for: {{name}}',
     'remove.removed': 'Removed: {{name}}',
@@ -117,6 +118,8 @@ export const en = {
     'help.command.list.description': 'List all indexed repositories',
     'help.command.status.description': 'Show index status for current repo',
     'help.command.doctor.description': 'Show runtime platform capabilities and embedding configuration',
+    'help.command.embeddings.description': 'Manage the on-demand local embedding runtime',
+    'help.command.embeddings.install.description': 'Install the local embedding stack (@huggingface/transformers + onnxruntime-node) on demand. Heals installs where npm skipped the optional packages (e.g. behind an HTTP proxy, #2370). Downloads only from your configured npm registry — mirrors and proxies apply.',
     'help.command.clean.description': 'Delete GitNexus index for current repo',
     'help.command.remove.description': 'Delete the GitNexus index for a registered repo (by alias, name, or absolute path). Unlike `clean`, does not require being inside the repo. Idempotent on unknown targets.',
     'help.command.wiki.description': 'Generate repository wiki from knowledge graph',
@@ -173,7 +176,7 @@ export const en = {
     'help.option.uninstall.force': 'Apply the changes (default is a dry-run preview)',
     'help.option.clean.all': 'Clean all indexed repos',
     'help.option.clean.branch': 'Delete only the named branch index (not the workspace index)',
-    'help.option.clean.lbugSidecars': 'Clean quarantined LadybugDB missing-shadow WAL sidecars',
+    'help.option.clean.lbugSidecars': 'Clean parked LadybugDB recovery sidecars (missing-shadow WAL quarantines and dirty-recovery parks)',
     'help.option.wiki.force': 'Force full regeneration even if up to date',
     'help.option.wiki.provider': 'LLM provider: openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: openai)',
     'help.option.wiki.model': 'LLM model or Azure deployment name (default: minimax/minimax-m2.5)',
@@ -220,6 +223,8 @@ export const en = {
     'help.option.check.cycles': 'Detect circular imports and fail when any are found',
     'help.option.evalServer.host': 'Bind address (default: 127.0.0.1, use 0.0.0.0 to expose to all interfaces)',
     'help.option.evalServer.idleTimeout': 'Auto-shutdown after N seconds idle (0 = disabled)',
+    'help.option.embeddings.install.cuda': "Also download the CUDA GPU binaries (runs onnxruntime-node's NuGet postinstall; set GLOBAL_AGENT_HTTPS_PROXY behind a proxy)",
+    'help.option.embeddings.install.force': 'Install into the runtime prefix even when the stack already resolves',
     'help.option.group.create.force': 'Overwrite existing group',
     'help.option.group.sync.skipEmbeddings': 'Exact + BM25 only (no embedding fallback)',
     'help.option.group.sync.exactOnly': 'Exact match only',
@@ -238,5 +243,5 @@ export const en = {
     'help.option.group.contracts.type': 'Filter by contract type',
     'help.option.group.contracts.repo': 'Filter by repo',
     'help.option.group.contracts.unmatched': 'Show only unmatched contracts',
-    'help.analyze.environment': '\nEnvironment variables:\n  GITNEXUS_NO_GITIGNORE=1   Skip .gitignore parsing (still reads .gitnexusignore)\n  GITNEXUS_MAX_FILE_SIZE=N  Override large-file skip threshold (KB). Default 512, max 32768.\n  GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker idle timeout in milliseconds. Default 30000.\n  GITNEXUS_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL auto-checkpoint threshold in bytes (default 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).\n  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker job byte budget. Default 8388608.\n  GITNEXUS_WORKER_POOL_SIZE=N  Parse worker count override. Default cores-1 capped at 16.\n  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  Concurrent in-flight parse chunks. Default 2.\n  GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N  Max replacement spawns per slot before drop. Default 3.\n  GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  Total retry wall-time per job. Default 5x sub-batch timeout.\n  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  Per-slot deaths to trip circuit breaker. Default max(3, poolSize).\n  GITNEXUS_EMBEDDING_THREADS=N  Limit local ONNX CPU threads for --embeddings.\n  GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N  Max embedding chunks for exact-scan fallback. Default 10000.\n  GITNEXUS_VECTOR_MAX_DISTANCE=N  Max accepted semantic/vector cosine distance (0 < N <= 2; higher values clamp to 2). Default 0.6 for MCP, 0.5 elsewhere.\n\nFlags override the corresponding env vars when both are provided.\n\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n     `!__tests__/` to index a directory that is auto-filtered by default (#771).',
+    'help.analyze.environment': '\nEnvironment variables:\n  GITNEXUS_NO_GITIGNORE=1   Skip .gitignore parsing (still reads .gitnexusignore)\n  GITNEXUS_MAX_FILE_SIZE=N  Override large-file skip threshold (KB). Default 512, max 32768.\n  GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker idle timeout in milliseconds. Default 30000.\n  GITNEXUS_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL auto-checkpoint threshold in bytes (default 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).\n  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker job byte budget. Default 8388608.\n  GITNEXUS_WORKER_POOL_SIZE=N  Parse worker count override. Default cores-1 capped at 16.\n  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  Concurrent in-flight parse chunks. Default 2.\n  GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N  Max replacement spawns per slot before drop. Default 3.\n  GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  Total retry wall-time per job. Default 5x sub-batch timeout.\n  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  Per-slot deaths to trip circuit breaker. Default max(3, poolSize).\n  GITNEXUS_WORKER_SHUTDOWN_DRAIN_MS=N  Max wait at pool shutdown for a retired worker still inside native code (terminated at its next safe point instead of aborting the process). Default 30000.\n  GITNEXUS_CPP_CAPTURE_BUDGET_MS=N  Per-file wall-clock budget for C++ capture extraction; on breach the file keeps partial captures with a warning. Default 20000.\n  GITNEXUS_EMBEDDING_THREADS=N  Limit local ONNX CPU threads for --embeddings.\n  GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N  Max embedding chunks for exact-scan fallback. Default 10000.\n  GITNEXUS_VECTOR_MAX_DISTANCE=N  Max accepted semantic/vector cosine distance (0 < N <= 2; higher values clamp to 2). Default 0.6 for MCP, 0.5 elsewhere.\n\nFlags override the corresponding env vars when both are provided.\n\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n     `!__tests__/` to index a directory that is auto-filtered by default (#771).',
 };

package/dist/cli/i18n/resources.d.ts

@@ -41,9 +41,10 @@ export declare const cliResources: {
         readonly 'clean.deleteBranch': "This will delete the branch index \"{{branch}}\" at: {{path}}";
         readonly 'clean.deletedBranch': "Deleted branch index: {{branch}}";
         readonly 'clean.lbugSidecars.state': "LadybugDB sidecar state: {{state}}";
-        readonly 'clean.lbugSidecars.none': "No quarantined LadybugDB missing-shadow WAL sidecars found.";
-        readonly 'clean.lbugSidecars.preview': "This will delete {{count}} quarantined LadybugDB missing-shadow WAL sidecar(s):";
-        readonly 'clean.lbugSidecars.deleted': "Deleted {{count}} quarantined LadybugDB missing-shadow WAL sidecar(s).";
+        readonly 'clean.lbugSidecars.none': "No parked LadybugDB recovery sidecars found (missing-shadow WAL quarantines or dirty-recovery parks).";
+        readonly 'clean.lbugSidecars.preview': "This will delete {{count}} parked LadybugDB recovery sidecar(s) (missing-shadow WAL quarantines and dirty-recovery parks):";
+        readonly 'clean.lbugSidecars.deleted': "Deleted {{count}} parked LadybugDB recovery sidecar(s).";
+        readonly 'clean.lbugSidecars.failed': "Could not delete {{count}} locked file(s) — stop the process holding them (GitNexus MCP/serve or an antivirus scan) and re-run:";
         readonly 'remove.nothingToRemove': "Nothing to remove: {{message}}";
         readonly 'remove.deleteTarget': "This will delete the GitNexus index for: {{name}}";
         readonly 'remove.removed': "Removed: {{name}}";
@@ -118,6 +119,8 @@ export declare const cliResources: {
         readonly 'help.command.list.description': "List all indexed repositories";
         readonly 'help.command.status.description': "Show index status for current repo";
         readonly 'help.command.doctor.description': "Show runtime platform capabilities and embedding configuration";
+        readonly 'help.command.embeddings.description': "Manage the on-demand local embedding runtime";
+        readonly 'help.command.embeddings.install.description': "Install the local embedding stack (@huggingface/transformers + onnxruntime-node) on demand. Heals installs where npm skipped the optional packages (e.g. behind an HTTP proxy, #2370). Downloads only from your configured npm registry — mirrors and proxies apply.";
         readonly 'help.command.clean.description': "Delete GitNexus index for current repo";
         readonly 'help.command.remove.description': "Delete the GitNexus index for a registered repo (by alias, name, or absolute path). Unlike `clean`, does not require being inside the repo. Idempotent on unknown targets.";
         readonly 'help.command.wiki.description': "Generate repository wiki from knowledge graph";
@@ -174,7 +177,7 @@ export declare const cliResources: {
         readonly 'help.option.uninstall.force': "Apply the changes (default is a dry-run preview)";
         readonly 'help.option.clean.all': "Clean all indexed repos";
         readonly 'help.option.clean.branch': "Delete only the named branch index (not the workspace index)";
-        readonly 'help.option.clean.lbugSidecars': "Clean quarantined LadybugDB missing-shadow WAL sidecars";
+        readonly 'help.option.clean.lbugSidecars': "Clean parked LadybugDB recovery sidecars (missing-shadow WAL quarantines and dirty-recovery parks)";
         readonly 'help.option.wiki.force': "Force full regeneration even if up to date";
         readonly 'help.option.wiki.provider': "LLM provider: openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: openai)";
         readonly 'help.option.wiki.model': "LLM model or Azure deployment name (default: minimax/minimax-m2.5)";
@@ -221,6 +224,8 @@ export declare const cliResources: {
         readonly 'help.option.check.cycles': "Detect circular imports and fail when any are found";
         readonly 'help.option.evalServer.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 to expose to all interfaces)";
         readonly 'help.option.evalServer.idleTimeout': "Auto-shutdown after N seconds idle (0 = disabled)";
+        readonly 'help.option.embeddings.install.cuda': "Also download the CUDA GPU binaries (runs onnxruntime-node's NuGet postinstall; set GLOBAL_AGENT_HTTPS_PROXY behind a proxy)";
+        readonly 'help.option.embeddings.install.force': "Install into the runtime prefix even when the stack already resolves";
         readonly 'help.option.group.create.force': "Overwrite existing group";
         readonly 'help.option.group.sync.skipEmbeddings': "Exact + BM25 only (no embedding fallback)";
         readonly 'help.option.group.sync.exactOnly': "Exact match only";
@@ -239,7 +244,7 @@ export declare const cliResources: {
         readonly 'help.option.group.contracts.type': "Filter by contract type";
         readonly 'help.option.group.contracts.repo': "Filter by repo";
         readonly 'help.option.group.contracts.unmatched': "Show only unmatched contracts";
-        readonly 'help.analyze.environment': "\nEnvironment variables:\n  GITNEXUS_NO_GITIGNORE=1   Skip .gitignore parsing (still reads .gitnexusignore)\n  GITNEXUS_MAX_FILE_SIZE=N  Override large-file skip threshold (KB). Default 512, max 32768.\n  GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker idle timeout in milliseconds. Default 30000.\n  GITNEXUS_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL auto-checkpoint threshold in bytes (default 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).\n  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker job byte budget. Default 8388608.\n  GITNEXUS_WORKER_POOL_SIZE=N  Parse worker count override. Default cores-1 capped at 16.\n  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  Concurrent in-flight parse chunks. Default 2.\n  GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N  Max replacement spawns per slot before drop. Default 3.\n  GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  Total retry wall-time per job. Default 5x sub-batch timeout.\n  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  Per-slot deaths to trip circuit breaker. Default max(3, poolSize).\n  GITNEXUS_EMBEDDING_THREADS=N  Limit local ONNX CPU threads for --embeddings.\n  GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N  Max embedding chunks for exact-scan fallback. Default 10000.\n  GITNEXUS_VECTOR_MAX_DISTANCE=N  Max accepted semantic/vector cosine distance (0 < N <= 2; higher values clamp to 2). Default 0.6 for MCP, 0.5 elsewhere.\n\nFlags override the corresponding env vars when both are provided.\n\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n     `!__tests__/` to index a directory that is auto-filtered by default (#771).";
+        readonly 'help.analyze.environment': "\nEnvironment variables:\n  GITNEXUS_NO_GITIGNORE=1   Skip .gitignore parsing (still reads .gitnexusignore)\n  GITNEXUS_MAX_FILE_SIZE=N  Override large-file skip threshold (KB). Default 512, max 32768.\n  GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker idle timeout in milliseconds. Default 30000.\n  GITNEXUS_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL auto-checkpoint threshold in bytes (default 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).\n  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker job byte budget. Default 8388608.\n  GITNEXUS_WORKER_POOL_SIZE=N  Parse worker count override. Default cores-1 capped at 16.\n  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  Concurrent in-flight parse chunks. Default 2.\n  GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N  Max replacement spawns per slot before drop. Default 3.\n  GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  Total retry wall-time per job. Default 5x sub-batch timeout.\n  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  Per-slot deaths to trip circuit breaker. Default max(3, poolSize).\n  GITNEXUS_WORKER_SHUTDOWN_DRAIN_MS=N  Max wait at pool shutdown for a retired worker still inside native code (terminated at its next safe point instead of aborting the process). Default 30000.\n  GITNEXUS_CPP_CAPTURE_BUDGET_MS=N  Per-file wall-clock budget for C++ capture extraction; on breach the file keeps partial captures with a warning. Default 20000.\n  GITNEXUS_EMBEDDING_THREADS=N  Limit local ONNX CPU threads for --embeddings.\n  GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N  Max embedding chunks for exact-scan fallback. Default 10000.\n  GITNEXUS_VECTOR_MAX_DISTANCE=N  Max accepted semantic/vector cosine distance (0 < N <= 2; higher values clamp to 2). Default 0.6 for MCP, 0.5 elsewhere.\n\nFlags override the corresponding env vars when both are provided.\n\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n     `!__tests__/` to index a directory that is auto-filtered by default (#771).";
     };
     readonly 'zh-CN': {
         'common.notIndexed': string;
@@ -286,6 +291,7 @@ export declare const cliResources: {
         'clean.lbugSidecars.none': string;
         'clean.lbugSidecars.preview': string;
         'clean.lbugSidecars.deleted': string;
+        'clean.lbugSidecars.failed': string;
         'remove.nothingToRemove': string;
         'remove.deleteTarget': string;
         'remove.removed': string;
@@ -360,6 +366,8 @@ export declare const cliResources: {
         'help.command.list.description': string;
         'help.command.status.description': string;
         'help.command.doctor.description': string;
+        'help.command.embeddings.description': string;
+        'help.command.embeddings.install.description': string;
         'help.command.clean.description': string;
         'help.command.remove.description': string;
         'help.command.wiki.description': string;
@@ -463,6 +471,8 @@ export declare const cliResources: {
         'help.option.check.cycles': string;
         'help.option.evalServer.host': string;
         'help.option.evalServer.idleTimeout': string;
+        'help.option.embeddings.install.cuda': string;
+        'help.option.embeddings.install.force': string;
         'help.option.group.create.force': string;
         'help.option.group.sync.skipEmbeddings': string;
         'help.option.group.sync.exactOnly': string;

package/dist/cli/i18n/zh-CN.d.ts

@@ -43,6 +43,7 @@ export declare const zhCN: {
     'clean.lbugSidecars.none': string;
     'clean.lbugSidecars.preview': string;
     'clean.lbugSidecars.deleted': string;
+    'clean.lbugSidecars.failed': string;
     'remove.nothingToRemove': string;
     'remove.deleteTarget': string;
     'remove.removed': string;
@@ -117,6 +118,8 @@ export declare const zhCN: {
     'help.command.list.description': string;
     'help.command.status.description': string;
     'help.command.doctor.description': string;
+    'help.command.embeddings.description': string;
+    'help.command.embeddings.install.description': string;
     'help.command.clean.description': string;
     'help.command.remove.description': string;
     'help.command.wiki.description': string;
@@ -220,6 +223,8 @@ export declare const zhCN: {
     'help.option.check.cycles': string;
     'help.option.evalServer.host': string;
     'help.option.evalServer.idleTimeout': string;
+    'help.option.embeddings.install.cuda': string;
+    'help.option.embeddings.install.force': string;
     'help.option.group.create.force': string;
     'help.option.group.sync.skipEmbeddings': string;
     'help.option.group.sync.exactOnly': string;

package/dist/cli/i18n/zh-CN.js

@@ -40,9 +40,10 @@ export const zhCN = {
     'clean.deleteBranch': '将删除分支索引 “{{branch}}”，路径：{{path}}',
     'clean.deletedBranch': '已删除分支索引：{{branch}}',
     'clean.lbugSidecars.state': 'LadybugDB sidecar 状态：{{state}}',
-    'clean.lbugSidecars.none': '未找到已隔离的 LadybugDB missing-shadow WAL sidecar。',
-    'clean.lbugSidecars.preview': '将删除 {{count}} 个已隔离的 LadybugDB missing-shadow WAL sidecar：',
-    'clean.lbugSidecars.deleted': '已删除 {{count}} 个已隔离的 LadybugDB missing-shadow WAL sidecar。',
+    'clean.lbugSidecars.none': '未找到已暂存的 LadybugDB 恢复 sidecar（missing-shadow WAL 隔离文件或 dirty-recovery 暂存文件）。',
+    'clean.lbugSidecars.preview': '将删除 {{count}} 个已暂存的 LadybugDB 恢复 sidecar（missing-shadow WAL 隔离文件与 dirty-recovery 暂存文件）：',
+    'clean.lbugSidecars.deleted': '已删除 {{count}} 个已暂存的 LadybugDB 恢复 sidecar。',
+    'clean.lbugSidecars.failed': '有 {{count}} 个文件被锁定而无法删除 — 请停止占用它们的进程（GitNexus MCP/serve 或杀毒软件扫描）后重试：',
     'remove.nothingToRemove': '无需移除：{{message}}',
     'remove.deleteTarget': '将删除该仓库的 GitNexus 索引：{{name}}',
     'remove.removed': '已移除：{{name}}',
@@ -117,6 +118,8 @@ export const zhCN = {
     'help.command.list.description': '列出所有已索引仓库',
     'help.command.status.description': '显示当前仓库的索引状态',
     'help.command.doctor.description': '显示运行平台能力和嵌入配置',
+    'help.command.embeddings.description': '管理按需安装的本地嵌入运行时',
+    'help.command.embeddings.install.description': '按需安装本地嵌入组件（@huggingface/transformers + onnxruntime-node）。修复 npm 跳过可选包的安装（例如在 HTTP 代理后，#2370）。仅从你配置的 npm registry 下载 — 镜像和代理均生效。',
     'help.command.clean.description': '删除当前仓库的 GitNexus 索引',
     'help.command.remove.description': '删除已注册仓库的 GitNexus 索引（按别名、名称或绝对路径）。与 `clean` 不同，不要求位于仓库内；未知目标会幂等处理。',
     'help.command.wiki.description': '从知识图谱生成仓库 Wiki',
@@ -173,7 +176,7 @@ export const zhCN = {
     'help.option.uninstall.force': '应用更改（默认仅为预演预览）',
     'help.option.clean.all': '清理所有已索引仓库',
     'help.option.clean.branch': '仅删除指定分支的索引（不影响工作区索引）',
-    'help.option.clean.lbugSidecars': '清理已隔离的 LadybugDB missing-shadow WAL sidecar',
+    'help.option.clean.lbugSidecars': '清理已暂存的 LadybugDB 恢复 sidecar（missing-shadow WAL 隔离文件与 dirty-recovery 暂存文件）',
     'help.option.wiki.force': '即使已是最新也强制完整重新生成',
     'help.option.wiki.provider': 'LLM 提供商：openai、openrouter、azure、custom、cursor、claude、codex 或 opencode（默认：openai）',
     'help.option.wiki.model': 'LLM 模型或 Azure deployment 名称（默认：minimax/minimax-m2.5）',
@@ -220,6 +223,8 @@ export const zhCN = {
     'help.option.check.cycles': '检测循环导入，并在发现循环时失败',
     'help.option.evalServer.host': '绑定地址（默认：127.0.0.1；用 0.0.0.0 暴露到所有网卡）',
     'help.option.evalServer.idleTimeout': '空闲 N 秒后自动关闭（0 = 禁用）',
+    'help.option.embeddings.install.cuda': '同时下载 CUDA GPU 二进制文件（运行 onnxruntime-node 的 NuGet postinstall；代理后请设置 GLOBAL_AGENT_HTTPS_PROXY）',
+    'help.option.embeddings.install.force': '即使嵌入组件已可解析，也强制安装到运行时目录',
     'help.option.group.create.force': '覆盖现有仓库组',
     'help.option.group.sync.skipEmbeddings': '仅使用 exact + BM25（不使用嵌入回退）',
     'help.option.group.sync.exactOnly': '仅精确匹配',
@@ -238,5 +243,5 @@ export const zhCN = {
     'help.option.group.contracts.type': '按契约类型过滤',
     'help.option.group.contracts.repo': '按仓库过滤',
     'help.option.group.contracts.unmatched': '仅显示未匹配契约',
-    'help.analyze.environment': '\n环境变量：\n  GITNEXUS_NO_GITIGNORE=1   跳过 .gitignore 解析（仍读取 .gitnexusignore）\n  GITNEXUS_MAX_FILE_SIZE=N  覆盖大文件跳过阈值（KB）。默认 512，最大 32768。\n  GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker 空闲超时（毫秒）。默认 30000。\n  GITNEXUS_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL 自动 checkpoint 阈值（字节，默认 67108864 = 64 MiB；-1 保持 Ladybug 默认约 16 MiB）。\n  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker 作业字节预算。默认 8388608。\n  GITNEXUS_WORKER_POOL_SIZE=N  解析 worker 数量覆盖值。默认 cores-1，最多 16。\n  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  并发进行中的解析分块数。默认 2。\n  GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N  每个 slot 丢弃前允许的最大替换进程数。默认 3。\n  GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  每个作业的总重试墙钟时间。默认 5 倍子批次超时。\n  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  每个 slot 触发熔断的死亡次数。默认 max(3, poolSize)。\n  GITNEXUS_EMBEDDING_THREADS=N  限制 --embeddings 的本地 ONNX CPU 线程数。\n  GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N  exact-scan 回退的最大嵌入分块数。默认 10000。\n  GITNEXUS_VECTOR_MAX_DISTANCE=N  语义/向量搜索接受的最大余弦距离（0 < N <= 2；超出则钳制为 2）。MCP 默认 0.6，其他路径默认 0.5。\n\n当参数和对应环境变量同时提供时，参数优先。\n\n提示：`.gitnexusignore` 支持 `.gitignore` 风格的取反。比如添加\n     `!__tests__/` 可以索引默认自动过滤的目录（#771）。',
+    'help.analyze.environment': '\n环境变量：\n  GITNEXUS_NO_GITIGNORE=1   跳过 .gitignore 解析（仍读取 .gitnexusignore）\n  GITNEXUS_MAX_FILE_SIZE=N  覆盖大文件跳过阈值（KB）。默认 512，最大 32768。\n  GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker 空闲超时（毫秒）。默认 30000。\n  GITNEXUS_WAL_CHECKPOINT_THRESHOLD=N  LadybugDB WAL 自动 checkpoint 阈值（字节，默认 67108864 = 64 MiB；-1 保持 Ladybug 默认约 16 MiB）。\n  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker 作业字节预算。默认 8388608。\n  GITNEXUS_WORKER_POOL_SIZE=N  解析 worker 数量覆盖值。默认 cores-1，最多 16。\n  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  并发进行中的解析分块数。默认 2。\n  GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N  每个 slot 丢弃前允许的最大替换进程数。默认 3。\n  GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  每个作业的总重试墙钟时间。默认 5 倍子批次超时。\n  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  每个 slot 触发熔断的死亡次数。默认 max(3, poolSize)。\n  GITNEXUS_WORKER_SHUTDOWN_DRAIN_MS=N  线程池关闭时等待仍在原生代码中的已退役 worker 的最长时间（到达安全点后再终止，避免进程级 abort）。默认 30000。\n  GITNEXUS_CPP_CAPTURE_BUDGET_MS=N  C++ 捕获提取的每文件墙钟预算；超出后该文件保留部分捕获并输出警告。默认 20000。\n  GITNEXUS_EMBEDDING_THREADS=N  限制 --embeddings 的本地 ONNX CPU 线程数。\n  GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N  exact-scan 回退的最大嵌入分块数。默认 10000。\n  GITNEXUS_VECTOR_MAX_DISTANCE=N  语义/向量搜索接受的最大余弦距离（0 < N <= 2；超出则钳制为 2）。MCP 默认 0.6，其他路径默认 0.5。\n\n当参数和对应环境变量同时提供时，参数优先。\n\n提示：`.gitnexusignore` 支持 `.gitignore` 风格的取反。比如添加\n     `!__tests__/` 可以索引默认自动过滤的目录（#771）。',
 };

package/dist/cli/index.js

@@ -153,13 +153,24 @@ program
     .command('doctor')
     .description('Show runtime platform capabilities and embedding configuration')
     .action(createLazyAction(() => import('./doctor.js'), 'doctorCommand'));
+program
+    .command('embeddings')
+    .description('Manage the on-demand local embedding runtime')
+    .command('install')
+    .description('Install the local embedding stack (@huggingface/transformers + onnxruntime-node) on demand. ' +
+    'Heals installs where npm skipped the optional packages (e.g. behind an HTTP proxy, #2370). ' +
+    'Downloads only from your configured npm registry — mirrors and proxies apply.')
+    .option('--cuda', "Also download the CUDA GPU binaries (runs onnxruntime-node's NuGet postinstall; " +
+    'set GLOBAL_AGENT_HTTPS_PROXY behind a proxy)')
+    .option('--force', 'Install into the runtime prefix even when the stack already resolves')
+    .action(createLazyAction(() => import('./embeddings.js'), 'embeddingsInstallCommand'));
 program
     .command('clean')
     .description('Delete GitNexus index for current repo')
     .option('-f, --force', 'Skip confirmation prompt')
     .option('--all', 'Clean all indexed repos')
     .option('--branch <name>', 'Delete only the named branch index (not the workspace index)')
-    .option('--lbug-sidecars', 'Clean quarantined LadybugDB missing-shadow WAL sidecars')
+    .option('--lbug-sidecars', 'Clean parked LadybugDB recovery sidecars (missing-shadow WAL quarantines and dirty-recovery parks)')
     .action(createLazyAction(() => import('./clean.js'), 'cleanCommand'));
 program
     .command('remove <target>')

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.
@@ -76,7 +77,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 +98,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 +148,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.js

@@ -16,8 +16,9 @@ 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 { 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 →

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

@@ -51,6 +51,26 @@ 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;

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';
@@ -163,8 +164,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()
@@ -536,7 +544,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

@@ -11,7 +11,13 @@
  * via `AbortSignal.timeout` on the underlying fetch.
  */
 /**
- * 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 +32,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.