gitnexus 1.6.12-rc.27 → 1.6.12-rc.28

package/dist/cli/embeddings-sync.d.ts

@@ -0,0 +1,2 @@
+/** Add missing embeddings directly to a healthy index, checkpointing periodically. */
+export declare const embeddingsSyncCommand: (inputPath?: string) => Promise<void>;

package/dist/cli/embeddings-sync.js

@@ -0,0 +1,127 @@
+import { lstat } from 'node:fs/promises';
+import path from 'node:path';
+import { cliInfo } from './cli-message.js';
+import { getGitRoot } from '../storage/git.js';
+import { acquireIndexLock } from '../storage/index-lock.js';
+import { getStoragePaths, loadMeta, saveMeta } from '../storage/repo-manager.js';
+import { closeLbug, executeQuery, executeWithReusedStatement, fetchExistingEmbeddingHashes, initLbug, } from '../core/lbug/lbug-adapter.js';
+import { runEmbeddingPipeline } from '../core/embeddings/embedding-pipeline.js';
+import { resolveEmbeddingIdentity } from '../core/embeddings/embedding-identity.js';
+import { checkpointKind, decideEmbeddingResume, mintInterruptedCheckpoint, mintPartialCheckpoint, mintUnverifiedCountCheckpoint, } from '../core/embedding-checkpoint.js';
+import { measurePersistedEmbeddingCount, persistedEmbeddingCountOrUndefined, } from '../core/embedding-count.js';
+/** Add missing embeddings directly to a healthy index, checkpointing periodically. */
+export const embeddingsSyncCommand = async (inputPath) => {
+    const repoPath = inputPath ? path.resolve(inputPath) : getGitRoot(process.cwd());
+    if (!repoPath)
+        throw new Error('Not inside a git repository. Pass a repository path.');
+    const { lbugPath, metaPath } = getStoragePaths(repoPath);
+    const metaDir = path.dirname(metaPath);
+    const lock = await acquireIndexLock(metaDir);
+    try {
+        const meta = await loadMeta(metaDir);
+        if (!meta)
+            throw new Error(`No GitNexus index found for ${repoPath}. Run gitnexus analyze first.`);
+        if (meta.incrementalInProgress) {
+            throw new Error('The structural index is incomplete. Run gitnexus analyze --force first.');
+        }
+        let lbugStat;
+        try {
+            lbugStat = await lstat(lbugPath);
+        }
+        catch {
+            throw new Error(`The LadybugDB graph store at ${lbugPath} is missing. Run gitnexus analyze first.`);
+        }
+        if (!lbugStat.isFile()) {
+            throw new Error(`The LadybugDB graph store at ${lbugPath} is not a usable database file. Run gitnexus analyze first.`);
+        }
+        const identity = resolveEmbeddingIdentity();
+        let forceReembedNodeIds;
+        let resumedFrom;
+        if (meta.embeddingCheckpoint) {
+            const checkpoint = meta.embeddingCheckpoint;
+            const decision = decideEmbeddingResume(checkpoint, identity);
+            if (decision.action === 'abort')
+                throw new Error(decision.error);
+            const identityDiffers = checkpoint.provider !== identity.provider ||
+                checkpoint.model !== identity.model ||
+                checkpoint.dimensions !== identity.dimensions;
+            // `abandon` on a non-interrupted foreign identity drops the pending set
+            // only. Existing rows stay; sync would then embed the holes under the new
+            // identity and mix vector spaces. Fail closed — rebuild via analyze.
+            if (identityDiffers && checkpointKind(checkpoint) !== 'unverified-count') {
+                throw new Error(`Cannot sync embeddings: the index checkpoint was written by ${checkpoint.model} ` +
+                    `(${checkpoint.provider}) at ${checkpoint.dimensions} dimensions, but this run ` +
+                    `resolves ${identity.model} (${identity.provider}) at ${identity.dimensions}. ` +
+                    'Run `gitnexus analyze --embeddings --force` to rebuild under the new identity.');
+            }
+            cliInfo(decision.log);
+            if (decision.action === 'resume') {
+                forceReembedNodeIds = decision.pendingNodeIds;
+                resumedFrom = decision.resumedFrom;
+            }
+        }
+        await initLbug(lbugPath);
+        try {
+            const existing = await fetchExistingEmbeddingHashes(executeQuery);
+            let lastPercent = -1;
+            const countEmbeddings = async () => persistedEmbeddingCountOrUndefined(await measurePersistedEmbeddingCount(executeQuery));
+            const saveCheckpoint = async (checkpoint, pendingNodeIds, embeddings) => {
+                const latest = (await loadMeta(metaDir)) ?? meta;
+                await saveMeta(metaDir, {
+                    ...latest,
+                    ...(embeddings === undefined ? {} : { stats: { ...latest.stats, embeddings } }),
+                    embeddingCheckpoint: mintInterruptedCheckpoint(identity, checkpoint, pendingNodeIds),
+                });
+            };
+            cliInfo(`Embedding ${repoPath}`);
+            cliInfo(`Checkpointed nodes already present: ${existing?.size ?? 0}`);
+            const result = await runEmbeddingPipeline(executeQuery, executeWithReusedStatement, (progress) => {
+                const percent = Math.floor(progress.percent);
+                if (percent !== lastPercent && (percent % 5 === 0 || percent === 100)) {
+                    lastPercent = percent;
+                    cliInfo(`  ${percent}% — ${progress.nodesProcessed ?? 0}/${progress.totalNodes ?? '?'} nodes`);
+                }
+            }, {}, undefined, existing && existing.size ? existing : undefined, {
+                forceReembedNodeIds,
+                onCheckpointWindowStart: async ({ nodeIds, ...checkpoint }) => {
+                    await saveCheckpoint(checkpoint, nodeIds);
+                },
+                onCheckpoint: async (checkpoint) => {
+                    await saveCheckpoint(checkpoint, [], await countEmbeddings());
+                },
+            });
+            const embeddings = await countEmbeddings();
+            const latest = (await loadMeta(metaDir)) ?? meta;
+            if (embeddings === undefined) {
+                // Keep last-known stats.embeddings. An interrupted window marker would
+                // fail the identity gate on the next run even though this run finished;
+                // unverified-count is the recovery kind that forces a recount (#2790).
+                await saveMeta(metaDir, {
+                    ...latest,
+                    embeddingCheckpoint: result.failedNodeIds.length
+                        ? mintPartialCheckpoint(identity, result, resumedFrom)
+                        : mintUnverifiedCountCheckpoint(identity, {
+                            nodesProcessed: result.nodesProcessed,
+                            totalNodes: result.nodesProcessed,
+                            chunksProcessed: result.chunksProcessed,
+                        }),
+                });
+                throw new Error('Could not verify persisted embedding count.');
+            }
+            await saveMeta(metaDir, {
+                ...latest,
+                stats: { ...latest.stats, embeddings },
+                embeddingCheckpoint: result.failedNodeIds.length
+                    ? mintPartialCheckpoint(identity, result, resumedFrom)
+                    : undefined,
+            });
+            cliInfo(`Embeddings ready: ${embeddings}`);
+        }
+        finally {
+            await closeLbug().catch(() => { });
+        }
+    }
+    finally {
+        lock.release();
+    }
+};

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

@@ -140,6 +140,7 @@ export declare const en: {
     readonly 'help.watch.details': "\n`gitnexus watch` does not start a watcher.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n";
     readonly 'error.watch.ambiguous': "`gitnexus watch` is ambiguous.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n";
     readonly 'help.command.analyze.description': "Index a repository (full analysis)";
+    readonly 'help.command.embeddings.sync.description': "Add missing embeddings to an existing index, checkpointing periodically for safe resume";
     readonly 'help.command.index.description': "Register an existing .gitnexus/ folder into the global registry (no re-analysis needed)";
     readonly 'help.command.serve.description': "Start local HTTP server for web UI connection";
     readonly 'help.command.mcp.description': "Start MCP server. Default: stdio. Use --http for a remote HTTP server (Streamable HTTP at POST /mcp + legacy SSE at GET /sse, POST /messages).";
@@ -277,5 +278,5 @@ export declare const en: {
     readonly 'help.option.group.contracts.repo': "Filter by repo";
     readonly 'help.option.group.contracts.unmatched': "Show only unmatched contracts";
     readonly 'help.identityCache.environment': "\nAnalyzer identity cache:\n  GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir\n    Operator-trusted persistent cache for warm cross-process status. The directory must pre-exist, be outside the GitNexus package/build roots, and contain no symlink or junction components. Defaults remain fail-closed on platforms without POSIX ownership APIs.";
-    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_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir  Operator-trusted persistent analyzer identity cache; must pre-exist, be outside package/build roots, and contain no symlink/junction components.\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 '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_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir  Operator-trusted persistent analyzer identity cache; must pre-exist, be outside package/build roots, and contain no symlink/junction components.\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_EMBEDDING_RETRY_TIMEOUTS=1  Retry per-attempt HTTP embedding timeouts through GITNEXUS_EMBEDDING_MAX_ATTEMPTS (default off; timeouts stay terminal).\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

@@ -142,6 +142,7 @@ export const en = {
     'help.watch.details': '\n`gitnexus watch` does not start a watcher.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n',
     'error.watch.ambiguous': '`gitnexus watch` is ambiguous.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n',
     'help.command.analyze.description': 'Index a repository (full analysis)',
+    'help.command.embeddings.sync.description': 'Add missing embeddings to an existing index, checkpointing periodically for safe resume',
     'help.command.index.description': 'Register an existing .gitnexus/ folder into the global registry (no re-analysis needed)',
     'help.command.serve.description': 'Start local HTTP server for web UI connection',
     'help.command.mcp.description': 'Start MCP server. Default: stdio. Use --http for a remote HTTP server (Streamable HTTP at POST /mcp + legacy SSE at GET /sse, POST /messages).',
@@ -279,5 +280,5 @@ export const en = {
     'help.option.group.contracts.repo': 'Filter by repo',
     'help.option.group.contracts.unmatched': 'Show only unmatched contracts',
     'help.identityCache.environment': '\nAnalyzer identity cache:\n  GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir\n    Operator-trusted persistent cache for warm cross-process status. The directory must pre-exist, be outside the GitNexus package/build roots, and contain no symlink or junction components. Defaults remain fail-closed on platforms without POSIX ownership APIs.',
-    '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_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir  Operator-trusted persistent analyzer identity cache; must pre-exist, be outside package/build roots, and contain no symlink/junction components.\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).',
+    '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_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir  Operator-trusted persistent analyzer identity cache; must pre-exist, be outside package/build roots, and contain no symlink/junction components.\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_EMBEDDING_RETRY_TIMEOUTS=1  Retry per-attempt HTTP embedding timeouts through GITNEXUS_EMBEDDING_MAX_ATTEMPTS (default off; timeouts stay terminal).\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

@@ -141,6 +141,7 @@ export declare const cliResources: {
         readonly 'help.watch.details': "\n`gitnexus watch` does not start a watcher.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n";
         readonly 'error.watch.ambiguous': "`gitnexus watch` is ambiguous.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n";
         readonly 'help.command.analyze.description': "Index a repository (full analysis)";
+        readonly 'help.command.embeddings.sync.description': "Add missing embeddings to an existing index, checkpointing periodically for safe resume";
         readonly 'help.command.index.description': "Register an existing .gitnexus/ folder into the global registry (no re-analysis needed)";
         readonly 'help.command.serve.description': "Start local HTTP server for web UI connection";
         readonly 'help.command.mcp.description': "Start MCP server. Default: stdio. Use --http for a remote HTTP server (Streamable HTTP at POST /mcp + legacy SSE at GET /sse, POST /messages).";
@@ -278,7 +279,7 @@ export declare const cliResources: {
         readonly 'help.option.group.contracts.repo': "Filter by repo";
         readonly 'help.option.group.contracts.unmatched': "Show only unmatched contracts";
         readonly 'help.identityCache.environment': "\nAnalyzer identity cache:\n  GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir\n    Operator-trusted persistent cache for warm cross-process status. The directory must pre-exist, be outside the GitNexus package/build roots, and contain no symlink or junction components. Defaults remain fail-closed on platforms without POSIX ownership APIs.";
-        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_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir  Operator-trusted persistent analyzer identity cache; must pre-exist, be outside package/build roots, and contain no symlink/junction components.\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 '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_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir  Operator-trusted persistent analyzer identity cache; must pre-exist, be outside package/build roots, and contain no symlink/junction components.\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_EMBEDDING_RETRY_TIMEOUTS=1  Retry per-attempt HTTP embedding timeouts through GITNEXUS_EMBEDDING_MAX_ATTEMPTS (default off; timeouts stay terminal).\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;
@@ -422,6 +423,7 @@ export declare const cliResources: {
         'help.watch.details': string;
         'error.watch.ambiguous': string;
         'help.command.analyze.description': string;
+        'help.command.embeddings.sync.description': string;
         'help.command.index.description': string;
         'help.command.serve.description': string;
         'help.command.mcp.description': string;

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

@@ -140,6 +140,7 @@ export declare const zhCN: {
     'help.watch.details': string;
     'error.watch.ambiguous': string;
     'help.command.analyze.description': string;
+    'help.command.embeddings.sync.description': string;
     'help.command.index.description': string;
     'help.command.serve.description': string;
     'help.command.mcp.description': string;

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

@@ -140,6 +140,7 @@ export const zhCN = {
     'help.watch.details': '\n`gitnexus watch` 不会启动监视器。\n  本地工作区增量索引：gitnexus analyze --watch\n  定时远程 clone/pull 并分析：gitnexus auto-sync start\n',
     'error.watch.ambiguous': '`gitnexus watch` 含义不明确。\n  本地工作区增量索引：gitnexus analyze --watch\n  定时远程 clone/pull 并分析：gitnexus auto-sync start\n',
     'help.command.analyze.description': '索引仓库（完整分析）',
+    'help.command.embeddings.sync.description': '向现有索引添加缺失的嵌入，并定期保存检查点以安全续跑',
     'help.command.index.description': '将现有 .gitnexus/ 文件夹注册到全局注册表（无需重新分析）',
     'help.command.serve.description': '启动供 Web UI 连接的本地 HTTP 服务器',
     'help.command.mcp.description': '启动 MCP 服务器。默认为 stdio。使用 --http 启动远程 HTTP 服务器（Streamable HTTP: POST /mcp + 遗留 SSE: GET /sse, POST /messages）。',
@@ -277,5 +278,5 @@ export const zhCN = {
     'help.option.group.contracts.repo': '按仓库过滤',
     'help.option.group.contracts.unmatched': '仅显示未匹配契约',
     'help.identityCache.environment': '\n分析器身份缓存：\n  GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir\n    由操作员明确信任的持久缓存，用于跨进程快速查询状态。目录必须预先存在、位于 GitNexus 包/构建根目录之外，且路径中不得包含符号链接或 junction。缺少 POSIX 所有权 API 的平台默认保持故障关闭。',
-    'help.analyze.environment': '\n环境变量：\n  GITNEXUS_NO_GITIGNORE=1   跳过 .gitignore 解析（仍读取 .gitnexusignore）\n  GITNEXUS_MAX_FILE_SIZE=N  覆盖大文件跳过阈值（KB）。默认 512，最大 32768。\n  GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir  由操作员明确信任的持久分析器身份缓存；目录必须预先存在、位于包/构建根目录之外，且路径中不得包含符号链接或 junction。\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）。',
+    'help.analyze.environment': '\n环境变量：\n  GITNEXUS_NO_GITIGNORE=1   跳过 .gitignore 解析（仍读取 .gitnexusignore）\n  GITNEXUS_MAX_FILE_SIZE=N  覆盖大文件跳过阈值（KB）。默认 512，最大 32768。\n  GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir  由操作员明确信任的持久分析器身份缓存；目录必须预先存在、位于包/构建根目录之外，且路径中不得包含符号链接或 junction。\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_EMBEDDING_RETRY_TIMEOUTS=1  将单次 HTTP 嵌入超时纳入 GITNEXUS_EMBEDDING_MAX_ATTEMPTS 重试（默认关闭，超时仍为终止错误）。\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

@@ -184,17 +184,21 @@ program
     .command('update')
     .description('Install the latest published GitNexus globally (`npm i -g gitnexus@<x.y.z>`).')
     .action(createLazyAction(() => import('./update.js'), 'updateCommand'));
-program
+const embeddings = program
     .command('embeddings')
-    .description('Manage the on-demand local embedding runtime')
+    .description(t('help.command.embeddings.description'));
+embeddings
     .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.')
+    .description(t('help.command.embeddings.install.description'))
     .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'));
+embeddings
+    .command('sync [path]')
+    .description(t('help.command.embeddings.sync.description'))
+    .addHelpText('after', () => t('help.analyze.environment'))
+    .action(createLbugLazyAction(() => import('./embeddings-sync.js'), 'embeddingsSyncCommand'));
 program
     .command('clean')
     .description('Delete GitNexus index for current repo')

package/dist/core/embeddings/http-client.js

@@ -157,6 +157,7 @@ const readConfig = () => {
         retryCapMs: parsePositiveIntegerEnv('GITNEXUS_EMBEDDING_RETRY_CAP_MS', HTTP_RETRY_CAP_MS, 300_000),
         minIntervalMs: parseNonNegativeIntegerEnv('GITNEXUS_EMBEDDING_MIN_INTERVAL_MS', 0, 300_000),
         timeoutMs: parsePositiveIntegerEnv(HTTP_TIMEOUT_ENV, DEFAULT_HTTP_TIMEOUT_MS, MAX_HTTP_TIMEOUT_MS),
+        retryTimeouts: parseNonNegativeIntegerEnv('GITNEXUS_EMBEDDING_RETRY_TIMEOUTS', 0, 1) === 1,
         requestDimensions,
     };
 };
@@ -277,6 +278,23 @@ class RetryableEmbeddingBodyError extends Error {
         this.name = 'RetryableEmbeddingBodyError';
     }
 }
+class RetryableEmbeddingTimeoutError extends Error {
+    timeoutMs;
+    constructor(timeoutMs, options) {
+        super(`Embedding request timed out after ${timeoutMs}ms`, options?.cause !== undefined ? { cause: options.cause } : undefined);
+        this.timeoutMs = timeoutMs;
+        this.name = 'RetryableEmbeddingTimeoutError';
+    }
+}
+/** Re-wrap an opt-in TimeoutError so `resilientFetch` retries it. Abort stays terminal. */
+const throwIfRetryableTimeout = (err, retryTimeouts, callerAborted, timeoutMs) => {
+    if (retryTimeouts &&
+        !callerAborted &&
+        isTerminalNetworkError(err) &&
+        err.name === 'TimeoutError') {
+        throw new RetryableEmbeddingTimeoutError(timeoutMs, { cause: err });
+    }
+};
 /**
  * Build the message for a 2xx body carrying the wrong number of vectors.
  *
@@ -304,7 +322,7 @@ const countMismatchMessage = (received, expected, safeEndpoint, batchIndex) => `
  *   `GITNEXUS_EMBEDDING_REQUEST_DIMS=omit` for strict backends while keeping
  *   `GITNEXUS_EMBEDDING_DIMS` set to the returned vector size.
  */
-const httpEmbedBatch = async (url, batch, model, apiKey, batchIndex = 0, dimensions, requestOptions = {}, maxAttempts = HTTP_MAX_RETRIES + 1, retryCapMs = HTTP_RETRY_CAP_MS, minIntervalMs = 0, timeoutMs = DEFAULT_HTTP_TIMEOUT_MS) => {
+const httpEmbedBatch = async (url, batch, model, apiKey, batchIndex = 0, dimensions, requestOptions = {}, maxAttempts = HTTP_MAX_RETRIES + 1, retryCapMs = HTTP_RETRY_CAP_MS, minIntervalMs = 0, timeoutMs = DEFAULT_HTTP_TIMEOUT_MS, retryTimeouts = false) => {
     const requestBody = {
         input: batch,
         model,
@@ -341,7 +359,14 @@ const httpEmbedBatch = async (url, batch, model, apiKey, batchIndex = 0, dimensi
                 const signal = requestOptions.signal
                     ? AbortSignal.any([requestOptions.signal, timeoutSignal])
                     : timeoutSignal;
-                const attemptResp = await globalThis.fetch(input, { ...init, signal });
+                let attemptResp;
+                try {
+                    attemptResp = await globalThis.fetch(input, { ...init, signal });
+                }
+                catch (err) {
+                    throwIfRetryableTimeout(err, retryTimeouts, requestOptions.signal?.aborted, timeoutMs);
+                    throw err;
+                }
                 // Non-OK bodies are none of our business: hand the response straight
                 // back so `resilientFetch` keeps classifying 4xx/5xx/429 unchanged.
                 if (!attemptResp.ok)
@@ -361,15 +386,19 @@ const httpEmbedBatch = async (url, batch, model, apiKey, batchIndex = 0, dimensi
                     // Not every `.json()` rejection is a parse error: the per-attempt
                     // signal (`AbortSignal.any([caller, AbortSignal.timeout(...)])`) is
                     // wired to the body stream, so a stalled body rejects with the abort
-                    // reason. Re-raise those untouched — `isTerminalNetworkError` is
-                    // `resilientFetch`'s own predicate, so this test agrees with
-                    // `classifyOutcome` by construction. Wrapping one would flip its
-                    // verdict from `terminal-network` (returned without retry AND
-                    // without touching the breaker, via `recordNeutral()`) to
-                    // `retryable-network` (retried, then `breaker.recordFailure()`): the
-                    // same timeout would take 3 attempts instead of 1, count toward the
-                    // process-global `embeddings-http` breaker, and reach the operator as
-                    // "unparseable response" so they never reach for the timeout knob.
+                    // reason. Re-raise AbortError (and TimeoutError when retry is off)
+                    // untouched — `isTerminalNetworkError` is `resilientFetch`'s own
+                    // predicate, so this test agrees with `classifyOutcome` by
+                    // construction. Wrapping one would flip its verdict from
+                    // `terminal-network` (returned without retry AND without touching
+                    // the breaker, via `recordNeutral()`) to `retryable-network`
+                    // (retried, then `breaker.recordFailure()`): the same timeout would
+                    // take 3 attempts instead of 1, count toward the process-global
+                    // `embeddings-http` breaker, and reach the operator as "unparseable
+                    // response" so they never reach for the timeout knob.
+                    // Opt-in `GITNEXUS_EMBEDDING_RETRY_TIMEOUTS=1` is the exception:
+                    // TimeoutError is re-wrapped so the existing retry loop can retry it.
+                    throwIfRetryableTimeout(err, retryTimeouts, requestOptions.signal?.aborted, timeoutMs);
                     if (isTerminalNetworkError(err))
                         throw err;
                     throw new RetryableEmbeddingBodyError(unparseableMessage(), { cause: err });
@@ -411,6 +440,9 @@ const httpEmbedBatch = async (url, batch, model, apiKey, batchIndex = 0, dimensi
         if (err instanceof RetryableEmbeddingBodyError) {
             throw new HttpEmbeddingError(err.terminalMessage, { cause: err.cause });
         }
+        if (err instanceof RetryableEmbeddingTimeoutError) {
+            throw new HttpEmbeddingError(`${err.message} after ${maxAttempts} attempt(s) (${safeUrl(url)}, batch ${batchIndex})`, { cause: err.cause });
+        }
         if (err instanceof CircuitOpenError) {
             throw new HttpEmbeddingError(`Embedding endpoint circuit open (${safeUrl(url)}, batch ${batchIndex}): retry in ${Math.ceil(err.retryAfterMs / 1000)}s`, { cause: err });
         }
@@ -455,7 +487,7 @@ export const httpEmbed = async (texts, requestOptions = {}) => {
     const url = `${config.baseUrl}/embeddings`;
     const allVectors = [];
     for (const [batchIndex, batch] of chunk(texts, HTTP_BATCH_SIZE).entries()) {
-        const items = await httpEmbedBatch(url, batch, config.model, config.apiKey, batchIndex, config.requestDimensions, requestOptions, config.maxAttempts, config.retryCapMs, config.minIntervalMs, config.timeoutMs);
+        const items = await httpEmbedBatch(url, batch, config.model, config.apiKey, batchIndex, config.requestDimensions, requestOptions, config.maxAttempts, config.retryCapMs, config.minIntervalMs, config.timeoutMs, config.retryTimeouts);
         // Defensive backstop, deliberately kept: `httpEmbedBatch` now rejects a
         // short body from *inside* the retry loop (through the same
         // `countMismatchMessage`), so in practice this branch is unreachable. It
@@ -506,7 +538,7 @@ export const httpEmbedQuery = async (text, requestOptions = {}) => {
     if (!config)
         throw new Error('HTTP embedding not configured');
     const url = `${config.baseUrl}/embeddings`;
-    const items = await httpEmbedBatch(url, [text], config.model, config.apiKey, 0, config.requestDimensions, requestOptions, config.maxAttempts, config.retryCapMs, config.minIntervalMs, config.timeoutMs);
+    const items = await httpEmbedBatch(url, [text], config.model, config.apiKey, 0, config.requestDimensions, requestOptions, config.maxAttempts, config.retryCapMs, config.minIntervalMs, config.timeoutMs, config.retryTimeouts);
     // Defensive backstop like the `httpEmbed` one above: an empty `data` array is
     // now a cardinality mismatch (0 vectors for 1 text) rejected and retried
     // inside `httpEmbedBatch`, so this branch is unreachable in practice.

package/dist/mcp/local/local-backend.js

@@ -25,7 +25,7 @@ import { isWalCorruptionError, WAL_RECOVERY_SUGGESTION } from '../../core/lbug/l
 // at MCP server startup — crashes on unsupported Node ABI versions (#89)
 // git utilities available if needed
 // import { isGitRepo, getCurrentCommit, getGitRoot } from '../../storage/git.js';
-import { parseDiffHunks, coalesceHunksByPath, hunksOverlapRange, findGitRootByDotGit, getCanonicalRepoRoot, getGitRoot, } from '../../storage/git.js';
+import { parseDiffHunksResult, coalesceHunksByPath, hunksOverlapRange, findGitRootByDotGit, getCanonicalRepoRoot, getGitRoot, } from '../../storage/git.js';
 import { realpathSync } from 'fs';
 import { listRegisteredRepos, cleanupOldKuzuFiles, canonicalizePath, getStoragePaths, loadMeta, RegistryAmbiguousTargetError, } from '../../storage/repo-manager.js';
 import { GroupService, } from '../../core/group/service.js';
@@ -795,6 +795,12 @@ export function buildDetectChangesDiffArgs(scope, baseRef) {
     // not `--default-prefix`, which needs git >= 2.42. `--no-ext-diff` stops a
     // configured external diff driver from replacing the unified output we parse.
     const args = [
+        // Before the subcommand: default core.quotePath C-quotes non-ASCII so
+        // `diff --git` / `+++` tokens no longer match the unquoted `a/` `b/` forms
+        // the parser also accepts. The parser still decodes quoted tokens; this
+        // pin keeps production git from emitting them.
+        '-c',
+        'core.quotePath=false',
         'diff',
         '--ignore-cr-at-eol',
         '--no-ext-diff',
@@ -4464,10 +4470,10 @@ export class LocalBackend {
         catch (err) {
             return { error: `Git diff failed: ${err.message}` };
         }
-        const fileDiffs = parseDiffHunks(diffOutput);
+        const { files: fileDiffs, unparsedGitHeaders } = parseDiffHunksResult(diffOutput);
         if (fileDiffs.length === 0) {
-            // Git printed a diff but none of it parsed: the `+++ b/` headers were not
-            // where `parseDiffHunks` looks. That is a PARSE failure, not a clean tree,
+            // Git printed a diff but none of it parsed: no `diff --git` / `+++`
+            // file header was recognised. That is a PARSE failure, not a clean tree,
             // and the clean branch below would report it to the pre-commit gate as
             // `risk_level:'none'`, no `partial`, exit 0 — a false all-clear (#2915).
             const parseFailed = diffOutput.trim().length > 0;
@@ -4499,7 +4505,9 @@ export class LocalBackend {
         const changedSymbols = new Map();
         // Set if a swallowed graph query fails below — surfaces `partial:true` so a
         // degraded run cannot report a false-clean `risk_level:'low'` (#2283).
-        let queryDegraded = false;
+        // An unparsed `diff --git` is the same class: later hunks must not make
+        // the gate look complete.
+        let queryDegraded = unparsedGitHeaders > 0;
         // Hunks arrive grouped per path and already in the graph's 0-based line
         // space, so every comparison below is base-neutral (#2377).
         const hunksByPath = coalesceHunksByPath(fileDiffs);

package/dist/storage/git.d.ts

@@ -268,10 +268,20 @@ export interface FileDiff {
     filePath: string;
     hunks: DiffHunk[];
 }
+/** `parseDiffHunks` plus how many `diff --git` headers could not be decoded. */
+export interface DiffHunkParseResult {
+    files: FileDiff[];
+    unparsedGitHeaders: number;
+}
 /**
  * Parse unified diff output (with -U0) into per-file hunk ranges.
  * Extracts the new-file line ranges from @@ hunk headers.
  *
+ * The `diff --git` header is also retained as a file entry. This matters for
+ * binary, rename-only, and mode-only changes, which have no `+++ b/` header.
+ * Such entries intentionally have no hunks: callers can count the changed
+ * path without pretending that a symbol line range was touched.
+ *
  * A pure deletion adds no new lines, and unified diff spells that empty range
  * as the line BEFORE it: `@@ -4,2 +3,0 @@` removed old lines 4–5 from between
  * new lines 3 and 4 (git emits `+0,0` when the deletion is at the head of the
@@ -287,6 +297,13 @@ export interface FileDiff {
  * gap — the widening {@link coalesceHunks} is careful never to do.
  */
 export declare function parseDiffHunks(diffOutput: string): FileDiff[];
+/**
+ * Same as {@link parseDiffHunks}, plus a count of `diff --git` lines that
+ * could not be decoded. `detect_changes` uses the count to fail closed
+ * (`partial` + `risk_level:'unknown'`) instead of attaching later hunks to a
+ * previous file.
+ */
+export declare function parseDiffHunksResult(diffOutput: string): DiffHunkParseResult;
 /**
  * Merge a file's hunks into sorted, non-touching ranges.
  *

package/dist/storage/git.js

@@ -696,10 +696,183 @@ export const parseRepoNameFromUrl = (url) => {
 export const getInferredRepoName = (repoPath) => {
     return parseRepoNameFromUrl(getRemoteOriginUrl(repoPath));
 };
+const DIFF_GIT_PREFIX = 'diff --git ';
+/**
+ * Decode one Git C-quoted token (`"a/\\344\\270\\255.png"`). Returns
+ * `undefined` when the quotes are unbalanced or a trailing escape is bare.
+ */
+function unquoteCStyleGitToken(quoted) {
+    if (quoted.length < 2 || quoted[0] !== '"' || quoted[quoted.length - 1] !== '"') {
+        return undefined;
+    }
+    // Git C-quotes are byte-oriented: non-ASCII is `\nnn` octal of the UTF-8
+    // code units, not JS UTF-16 characters.
+    const bytes = [];
+    const pushChar = (ch) => {
+        const code = ch.charCodeAt(0);
+        if (code < 0x80)
+            bytes.push(code);
+        else
+            bytes.push(...new TextEncoder().encode(ch));
+    };
+    for (let i = 1; i < quoted.length - 1; i++) {
+        const ch = quoted[i];
+        if (ch !== '\\') {
+            pushChar(ch);
+            continue;
+        }
+        const next = quoted[++i];
+        if (next === undefined)
+            return undefined;
+        switch (next) {
+            case '\\':
+            case '"':
+                pushChar(next);
+                break;
+            case 'n':
+                bytes.push(0x0a);
+                break;
+            case 't':
+                bytes.push(0x09);
+                break;
+            case 'r':
+                bytes.push(0x0d);
+                break;
+            case 'a':
+                bytes.push(0x07);
+                break;
+            case 'b':
+                bytes.push(0x08);
+                break;
+            case 'v':
+                bytes.push(0x0b);
+                break;
+            case 'f':
+                bytes.push(0x0c);
+                break;
+            default: {
+                if (next < '0' || next > '7') {
+                    pushChar(next);
+                    break;
+                }
+                let oct = next;
+                while (oct.length < 3 && i + 1 < quoted.length - 1) {
+                    const digit = quoted[i + 1];
+                    if (digit < '0' || digit > '7')
+                        break;
+                    oct += digit;
+                    i++;
+                }
+                bytes.push(parseInt(oct, 8));
+            }
+        }
+    }
+    return new TextDecoder('utf-8').decode(Uint8Array.from(bytes));
+}
+function takeCQuotedToken(source, start) {
+    if (source[start] !== '"')
+        return undefined;
+    for (let i = start + 1; i < source.length; i++) {
+        if (source[i] === '\\') {
+            i++;
+            continue;
+        }
+        if (source[i] === '"')
+            return { token: source.slice(start, i + 1), end: i + 1 };
+    }
+    return undefined;
+}
+function stripGitDstPrefix(raw) {
+    return raw.startsWith('b/') ? raw.slice(2) : undefined;
+}
+/** Unified-diff paths end at the first TAB (timestamp / empty terminator). */
+function stripUnifiedDiffTab(pathWithOptionalTab) {
+    const tab = pathWithOptionalTab.indexOf('\t');
+    return tab === -1 ? pathWithOptionalTab : pathWithOptionalTab.slice(0, tab);
+}
+function decodeGitPathToken(raw) {
+    const trimmed = stripUnifiedDiffTab(raw);
+    if (trimmed.startsWith('"'))
+        return unquoteCStyleGitToken(trimmed);
+    return trimmed;
+}
+/**
+ * Destination path from `diff --git a/<src> b/<dst>`.
+ *
+ * Same-path headers recover `name` from `a/${name} b/${name}` so a dest that
+ * itself contains ` b/` is not split at the last occurrence. C-quoted tokens
+ * (default `core.quotePath`) are decoded. Renames that the greedy split would
+ * mis-parse stay a best-effort dest; `rename to` / `+++` correct them.
+ */
+function takeGitHeaderPathToken(source, start) {
+    if (start >= source.length)
+        return undefined;
+    if (source[start] === '"') {
+        const tok = takeCQuotedToken(source, start);
+        if (!tok)
+            return undefined;
+        const path = unquoteCStyleGitToken(tok.token);
+        if (path === undefined)
+            return undefined;
+        return { path, end: tok.end };
+    }
+    if (source.startsWith('b/', start)) {
+        return { path: stripUnifiedDiffTab(source.slice(start)), end: source.length };
+    }
+    if (source.startsWith('a/', start)) {
+        for (let i = start + 2; i < source.length; i++) {
+            if (source.startsWith(' b/', i) || source.startsWith(' "', i)) {
+                return { path: source.slice(start, i), end: i };
+            }
+        }
+    }
+    return undefined;
+}
+function filePathFromGitHeader(line) {
+    if (!line.startsWith(DIFF_GIT_PREFIX))
+        return undefined;
+    const rest = line.slice(DIFF_GIT_PREFIX.length);
+    if (rest.startsWith('a/')) {
+        for (let i = 2; i < rest.length; i++) {
+            if (!rest.startsWith(' b/', i))
+                continue;
+            const nameA = rest.slice(2, i);
+            const nameB = rest.slice(i + 3);
+            if (nameA.length > 0 && nameA === nameB)
+                return nameA;
+        }
+    }
+    const src = takeGitHeaderPathToken(rest, 0);
+    if (!src)
+        return undefined;
+    let i = src.end;
+    while (rest[i] === ' ')
+        i++;
+    const dest = takeGitHeaderPathToken(rest, i);
+    return dest ? stripGitDstPrefix(dest.path) : undefined;
+}
+function pathFromPlusPlusPlus(line) {
+    if (!line.startsWith('+++ '))
+        return undefined;
+    const raw = decodeGitPathToken(line.slice(4));
+    if (!raw || raw === '/dev/null')
+        return undefined;
+    return stripGitDstPrefix(raw);
+}
+function pathFromRenameTo(line) {
+    if (!line.startsWith('rename to '))
+        return undefined;
+    return decodeGitPathToken(line.slice('rename to '.length));
+}
 /**
  * Parse unified diff output (with -U0) into per-file hunk ranges.
  * Extracts the new-file line ranges from @@ hunk headers.
  *
+ * The `diff --git` header is also retained as a file entry. This matters for
+ * binary, rename-only, and mode-only changes, which have no `+++ b/` header.
+ * Such entries intentionally have no hunks: callers can count the changed
+ * path without pretending that a symbol line range was touched.
+ *
  * A pure deletion adds no new lines, and unified diff spells that empty range
  * as the line BEFORE it: `@@ -4,2 +3,0 @@` removed old lines 4–5 from between
  * new lines 3 and 4 (git emits `+0,0` when the deletion is at the head of the
@@ -715,14 +888,58 @@ export const getInferredRepoName = (repoPath) => {
  * gap — the widening {@link coalesceHunks} is careful never to do.
  */
 export function parseDiffHunks(diffOutput) {
+    return parseDiffHunksResult(diffOutput).files;
+}
+/**
+ * Same as {@link parseDiffHunks}, plus a count of `diff --git` lines that
+ * could not be decoded. `detect_changes` uses the count to fail closed
+ * (`partial` + `risk_level:'unknown'`) instead of attaching later hunks to a
+ * previous file.
+ */
+export function parseDiffHunksResult(diffOutput) {
     const files = [];
     let current = null;
+    let unparsedGitHeaders = 0;
+    // `+++` after the first `@@` of a file is hunk body (`+` plus source text
+    // that itself starts `++ …`), not another file header.
+    let inHunk = false;
     for (const line of diffOutput.split('\n')) {
-        if (line.startsWith('+++ b/')) {
-            current = { filePath: line.slice(6), hunks: [] };
-            files.push(current);
+        if (line.startsWith(DIFF_GIT_PREFIX)) {
+            // Drop the previous file first: an unparsed header must not leave
+            // `current` live for a later `@@` / quoted `+++` to steal.
+            current = null;
+            inHunk = false;
+            const filePath = filePathFromGitHeader(line);
+            if (filePath) {
+                current = { filePath, hunks: [] };
+                files.push(current);
+            }
+            else {
+                unparsedGitHeaders++;
+            }
+        }
+        else if (line.startsWith('rename to ')) {
+            const filePath = pathFromRenameTo(line);
+            if (!filePath)
+                continue;
+            if (current)
+                current.filePath = filePath;
+            else {
+                current = { filePath, hunks: [] };
+                files.push(current);
+            }
+        }
+        else if (!inHunk && line.startsWith('+++ ')) {
+            const filePath = pathFromPlusPlusPlus(line);
+            if (!filePath)
+                continue;
+            if (!current || current.filePath !== filePath) {
+                current = { filePath, hunks: [] };
+                files.push(current);
+            }
         }
         else if (line.startsWith('@@') && current) {
+            inHunk = true;
             const match = line.match(/@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/);
             if (match) {
                 const start = parseInt(match[1], 10);
@@ -739,7 +956,7 @@ export function parseDiffHunks(diffOutput) {
             }
         }
     }
-    return files;
+    return { files, unparsedGitHeaders };
 }
 /**
  * Merge a file's hunks into sorted, non-touching ranges.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.12-rc.27",
+  "version": "1.6.12-rc.28",
   "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",