gitnexus 1.6.12-rc.40 → 1.6.12-rc.42

package/README.md

@@ -161,7 +161,7 @@ GitNexus builds a complete knowledge graph of your codebase through a multi-phas
 5. **Processes** — Traces execution flows from entry points through call chains
 6. **Search** — Builds hybrid search indexes for fast retrieval
 
-The result is a **LadybugDB graph database** stored locally in `.gitnexus/` with full-text search and semantic embeddings.
+The result is a **LadybugDB graph database** stored locally in `.gitnexus/` by default, with full-text search and semantic embeddings.
 
 ### Experimental community detection engine
 
@@ -677,6 +677,9 @@ Configure the behavior with these environment variables:
 | `GITNEXUS_LBUG_EXTENSION_INSTALL_TIMEOUT_MS` | positive integer               | `15000`                | Wall-clock budget for the out-of-process extension-install child before it is killed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `GITNEXUS_FTS_STEMMER`                       | supported LadybugDB stemmer    | `porter`               | Stemmer used when rebuilding BM25/FTS indexes. Use `none` for CJK-heavy repositories, or a language stemmer such as `german`, `french`, or `spanish` when that better matches repository comments and identifiers. Re-run `gitnexus analyze --repair-fts` after changing it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `GITNEXUS_FTS_CJK_SEGMENTATION`              | `none`, `bigram`               | `none`                 | `bigram` inserts overlapping character-bigram boundaries into Chinese/Japanese Han-ideograph spans in `content`/`description` before FTS indexing, so LadybugDB's space-only tokenizer can see sub-phrase word boundaries. Scoped to CJK Unified Ideographs only — Japanese Hiragana/Katakana and Korean Hangul are not currently segmented. Unlike `GITNEXUS_FTS_STEMMER`, this rewrites stored text — enabling it on an already-indexed repo requires a full `gitnexus analyze --force`; neither `--repair-fts` nor a plain incremental `analyze` applies it to previously-indexed files. Set the same value wherever `analyze` and search-serving processes (CLI query, MCP server, web server) run.                                                                                                                                       |
+| `GITNEXUS_STORAGE_PATH`                      | absolute, non-empty directory  | unset (repo-local)     | Complete external index directory. This preserves the existing configuration semantics and takes precedence over `GITNEXUS_STORAGE_ROOT` when both are set.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `GITNEXUS_STORAGE_ROOT`                      | absolute, non-empty directory  | unset (repo-local)     | Absolute root directory for external indexes. GitNexus creates an isolated `<repo-basename>-<canonical-path-hash>/` slot beneath it for each repository, then registers the resolved slot so `status`, MCP, and `serve` can reopen it later.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `GITNEXUS_CONTENT_RETENTION`                 | `full`, `symbol`, `none`       | `full`                 | Source-text retention profile: `full` keeps file and symbol text, `symbol` keeps symbol snippets without full file content, and `none` keeps the structural graph without source body text.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `GITNEXUS_STREAM_GRAPH_EMIT`                 | `0`, `1`                       | `1` (on)               | **On by default** on a full rebuild (`--force`); incremental runs ignore it. Holds structural relationships (CALLS, IMPORTS, ACCESSES, CONTAINS, ...) as CSV-on-disk plus compact in-memory columns instead of as objects in three overlapping indexes, cutting peak in-memory graph heap by ~1.4x at no measurable CPU cost (measured A/B on a synthetic 400k-node / 1.08M-edge graph: 819 MB -> 584 MB, iteration at parity, scaling verified linear from 100k to 800k nodes, with every edge still visible through the graph interface; no end-to-end measurement on a real repository yet). Nothing is traded away — community detection, process extraction, PDG taint summaries and the local-symbol pruner all read a complete relationship set and behave identically. Set to `0` only to bisect a suspected streaming-related fault. |
 | `GITNEXUS_COMMUNITY_ENGINE`                  | `graphology`, `icebug`, `auto` | `graphology`           | Community-detection engine used during analyze. `graphology` is the supported default. `icebug` and `auto` are **experimental** and currently behave identically: both try the optional `@ladybugmem/icebug` native Leiden over a CSR export and fall back to Graphology if it is not installed, cannot load, or lacks the deterministic thread/seed controls. Experimental engines partition differently, so community IDs are not comparable across engines.                                                                                                                                                                                                                                                                                                                                                                                |
 | `GITNEXUS_WAL_CHECKPOINT_THRESHOLD`          | integer `>= -1`                | `67108864` (64 MiB)    | LadybugDB WAL auto-checkpoint threshold during analyze (bytes). Auto-checkpoint remains enabled; `-1` keeps Ladybug's stock ~16 MiB. Larger thresholds reduce checkpoint frequency but increase the WAL size at rotation time — choose a smaller value on disk-constrained environments.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
@@ -882,7 +885,7 @@ only — the hook's structured stdout (the JSON the agent consumes) is unaffecte
 
 - All processing happens locally on your machine
 - No code is sent to any server
-- Index stored in `.gitnexus/` inside your repo (gitignored)
+- Index stored in `.gitnexus/` inside your repo by default (gitignored), in the complete external directory selected by `GITNEXUS_STORAGE_PATH`, or in a repository-specific slot beneath `GITNEXUS_STORAGE_ROOT`
 - Global registry at `~/.gitnexus/` stores only paths and metadata
 
 ## Web UI

package/dist/cli/analyze-watch.js

@@ -6,6 +6,7 @@ import { createWatchIgnorePredicate } from '../config/ignore-service.js';
 import { analyzeFailureMayHaveMutatedLiveIndex, runFullAnalysis, } from '../core/run-analyze.js';
 import { isIndexLockGuardTimeout } from '../storage/index-lock.js';
 import { getGitRoot, hasGitDir } from '../storage/git.js';
+import { ANALYZE_STORAGE_REQUIREMENTS, requireStoragePath } from '../storage/storage-resolver.js';
 import { GITNEXUS_DIR } from '../storage/repo-meta.js';
 import { loadAnalyzeConfigStrict, mergeAnalyzeOptions, validateBranchName, } from './analyze-config.js';
 import { ensureHeap } from './analyze.js';
@@ -324,6 +325,14 @@ export async function watchCommandWithRunnerIdentity(runnerIdentityAtBootstrap,
         return;
     }
     const repoPath = await fs.realpath(requestedRepoPath);
+    try {
+        await requireStoragePath(repoPath, ANALYZE_STORAGE_REQUIREMENTS);
+    }
+    catch (error) {
+        cliError(`  ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+        return;
+    }
     const baselineEnvironment = {
         maxFileSize: process.env.GITNEXUS_MAX_FILE_SIZE,
         workerTimeout: process.env.GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS,

package/dist/cli/analyze.js

@@ -18,7 +18,7 @@ import { boundedCheckpointBeforeExit } from '../core/lbug/shutdown-helpers.js';
 import { findUndeclaredRelationPairError } from '../core/lbug/rel-pair-routing.js';
 import { causeChain } from '../lib/utils.js';
 import { getOsPageSize, isLbugCheckpointIoError, isLbugCheckpointBusyError, isLbugPageSizeFrameError, isPageSizeAwareLadybug, isWalCorruptionError, parseWalCheckpointThreshold, WAL_RECOVERY_SUGGESTION, } from '../core/lbug/lbug-config.js';
-import { getStoragePaths, getGlobalRegistryPath, RegistryNameCollisionError, AnalysisNotFinalizedError, assertAnalysisFinalized, } from '../storage/repo-manager.js';
+import { getGlobalRegistryPath, RegistryNameCollisionError, AnalysisNotFinalizedError, assertAnalysisFinalized, } from '../storage/repo-manager.js';
 import { getGitRoot, hasGitDir, getDefaultBranch, selfCommitContextFiles, snapshotSelfCommitSafety, } from '../storage/git.js';
 import { IndexLockTimeoutError, isIndexLockGuardTimeout } from '../storage/index-lock.js';
 import { loadAnalyzeConfig, mergeAnalyzeOptions, resolveDefaultBranch, validateBranchName, GitNexusRcError, } from './analyze-config.js';
@@ -1158,7 +1158,7 @@ const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstr
             // run can write meta.json and then fail before registerRepo(); in
             // that half-finalized state, runFullAnalysis returns alreadyUpToDate
             // on the next invocation unless we check the registry here too.
-            await assertAnalysisFinalized(repoPath);
+            await assertAnalysisFinalized(repoPath, result.storagePath);
             // The fast path skips context regeneration, but a changed `.gitnexusrc`
             // defaultBranch / `--default-branch` must still take effect. Surgically
             // refresh just the `base_ref` line in AGENTS.md/CLAUDE.md in place,
@@ -1225,7 +1225,7 @@ const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstr
         // success so the silent-finalize state surfaces with a non-zero
         // exit code and an actionable error instead of being mistaken for
         // a healthy index.
-        await assertAnalysisFinalized(repoPath);
+        await assertAnalysisFinalized(repoPath, result.storagePath);
         // Skill generation (CLI-only, uses pipeline result from analysis).
         // Gated so `--index-only --skills` skips community skill writes too
         // (`shouldGenerateCommunitySkillFiles` — see unit test).
@@ -1249,8 +1249,7 @@ const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstr
                         }
                         aggregatedClusterCount = Array.from(groups.values()).filter((count) => count >= 5).length;
                     }
-                    const { storagePath: sp } = getStoragePaths(repoPath);
-                    await generateAIContextFiles(repoPath, sp, result.repoName, {
+                    await generateAIContextFiles(repoPath, result.storagePath, result.repoName, {
                         files: s.files ?? 0,
                         nodes: s.nodes ?? 0,
                         edges: s.edges ?? 0,

package/dist/cli/clean.js

@@ -7,7 +7,8 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { logger } from '../core/logger.js';
-import { findRepo, unregisterRepo, listRegisteredRepos, assertSafeStoragePath, getStoragePaths, removeBranchIndex, UnsafeStoragePathError, } from '../storage/repo-manager.js';
+import { findRepo, unregisterRepo, listRegisteredRepos, getStoragePaths, removeBranchIndex, } from '../storage/repo-manager.js';
+import { requireDeletableStoragePath, StorageDeletionError } from '../storage/storage-resolver.js';
 import { cleanParkedLbugSidecars, inspectLbugSidecars, listParkedLbugSidecars, } from '../core/lbug/sidecar-recovery.js';
 import { t } from './i18n/index.js';
 export const cleanCommand = async (options) => {
@@ -28,14 +29,27 @@ export const cleanCommand = async (options) => {
             console.log(t('clean.branchNotIndexed', { branch: options.branch }));
             return;
         }
-        const { storagePath, lbugPath } = getStoragePaths(repo.repoPath, summary.branch);
+        let storagePath;
+        try {
+            storagePath = await requireDeletableStoragePath({
+                path: repo.repoPath,
+                storagePath: repo.storagePath,
+            });
+        }
+        catch (err) {
+            if (err instanceof StorageDeletionError) {
+                logger.error(`Refusing to clean branch index: ${err.message}`);
+                return;
+            }
+            throw err;
+        }
+        const { lbugPath } = getStoragePaths(repo.repoPath, summary.branch, storagePath);
         const branchDir = path.dirname(lbugPath);
-        // Safety guard: the target MUST live under <repo>/.gitnexus/branches/.
-        // assertSafeStoragePath only validates the flat `<repo>/.gitnexus`, so this
-        // is a dedicated branches-sub-dir check before any destructive fs.rm.
+        // Safety guard: the target MUST live under the validated
+        // storage slot's `branches/` directory before any destructive fs.rm.
         const branchesRoot = path.join(storagePath, 'branches') + path.sep;
         if (!branchDir.startsWith(branchesRoot)) {
-            logger.error(`Refusing to clean branch index outside .gitnexus/branches: ${branchDir}`);
+            logger.error(`Refusing to clean branch index outside the validated storage slot: ${branchDir}`);
             return;
         }
         if (!options.force) {
@@ -60,7 +74,21 @@ export const cleanCommand = async (options) => {
             console.log(t('clean.notFoundHere'));
             return;
         }
-        const lbugPath = path.join(repo.storagePath, 'lbug');
+        let storagePath;
+        try {
+            storagePath = await requireDeletableStoragePath({
+                path: repo.repoPath,
+                storagePath: repo.storagePath,
+            });
+        }
+        catch (err) {
+            if (err instanceof StorageDeletionError) {
+                logger.error(`Refusing to clean sidecars: ${err.message}`);
+                return;
+            }
+            throw err;
+        }
+        const { lbugPath } = getStoragePaths(repo.repoPath, undefined, storagePath);
         const state = await inspectLbugSidecars(lbugPath);
         // Single roster authority (this shipping review, FIX 5): the aggregate
         // covers both parked-sidecar families — the timestamped missing-shadow
@@ -96,45 +124,45 @@ export const cleanCommand = async (options) => {
     }
     // --all flag: clean all indexed repos
     if (options?.all) {
+        const entries = await listRegisteredRepos();
         if (!options?.force) {
-            const entries = await listRegisteredRepos();
-            if (entries.length === 0) {
+            const deletableEntries = [];
+            for (const entry of entries) {
+                try {
+                    await requireDeletableStoragePath(entry);
+                    deletableEntries.push(entry);
+                }
+                catch (err) {
+                    if (err instanceof StorageDeletionError) {
+                        logger.error(`Refusing to preview ${entry.name}: ${err.message}`);
+                        continue;
+                    }
+                    throw err;
+                }
+            }
+            if (deletableEntries.length === 0) {
                 console.log(t('common.notIndexed'));
                 return;
             }
-            console.log(t('clean.deleteAll', { count: entries.length }));
-            for (const entry of entries) {
+            console.log(t('clean.deleteAll', { count: deletableEntries.length }));
+            for (const entry of deletableEntries) {
                 console.log(`  - ${entry.name} (${entry.path})`);
             }
             console.log(`\n${t('common.runForceConfirm')}`);
             return;
         }
-        const entries = await listRegisteredRepos();
         for (const entry of entries) {
-            // Safety guard (#1003 review — @magyargergo): same rationale as
-            // remove.ts. `~/.gitnexus/registry.json` is user-writable, so a
-            // corrupted or hand-edited entry could point storagePath at the
-            // repo root, an empty string, or anywhere else — and
-            // fs.rm(recursive: true) on any of those would be catastrophic.
-            // Skip poisoned entries without touching disk, but keep going
-            // through the rest of the registry (preserves the existing
-            // per-repo error-tolerance semantics of `clean --all`).
             try {
-                assertSafeStoragePath(entry);
+                const storagePath = await requireDeletableStoragePath(entry);
+                await fs.rm(storagePath, { recursive: true, force: true });
+                await unregisterRepo(entry.path);
+                console.log(t('clean.deletedRepo', { name: entry.name, storagePath }));
             }
             catch (err) {
-                if (err instanceof UnsafeStoragePathError) {
+                if (err instanceof StorageDeletionError) {
                     logger.error(`Refusing to clean ${entry.name}: ${err.message}`);
                     continue;
                 }
-                throw err;
-            }
-            try {
-                await fs.rm(entry.storagePath, { recursive: true, force: true });
-                await unregisterRepo(entry.path);
-                console.log(t('clean.deletedRepo', { name: entry.name, storagePath: entry.storagePath }));
-            }
-            catch (err) {
                 logger.error({ err }, `Failed to delete ${entry.name}:`);
             }
         }
@@ -148,16 +176,30 @@ export const cleanCommand = async (options) => {
         return;
     }
     const repoName = repo.repoPath.split(/[/\\]/).pop() || repo.repoPath;
+    let storagePath;
+    try {
+        storagePath = await requireDeletableStoragePath({
+            path: repo.repoPath,
+            storagePath: repo.storagePath,
+        });
+    }
+    catch (err) {
+        if (err instanceof StorageDeletionError) {
+            logger.error(`Refusing to clean ${repoName}: ${err.message}`);
+            return;
+        }
+        throw err;
+    }
     if (!options?.force) {
         console.log(t('clean.deleteCurrent', { repoName }));
-        console.log(`   ${t('common.path')}: ${repo.storagePath}`);
+        console.log(`   ${t('common.path')}: ${storagePath}`);
         console.log(`\n${t('common.runForceConfirm')}`);
         return;
     }
     try {
-        await fs.rm(repo.storagePath, { recursive: true, force: true });
+        await fs.rm(storagePath, { recursive: true, force: true });
         await unregisterRepo(repo.repoPath);
-        console.log(t('common.deleted', { target: repo.storagePath }));
+        console.log(t('common.deleted', { target: storagePath }));
     }
     catch (err) {
         logger.error({ err }, 'Failed to delete:');

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

@@ -278,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_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 '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_STORAGE_PATH=/absolute/index  Complete external index directory. Preserves the existing configuration semantics and overrides GITNEXUS_STORAGE_ROOT when both are set.\n  GITNEXUS_STORAGE_ROOT=/absolute/root  External index root; each repository uses an isolated <repo-basename>-<canonical-path-hash>/ slot.\n  GITNEXUS_CONTENT_RETENTION=full  Source-text retention profile: full, symbol, or none. Default full.\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

@@ -280,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_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).',
+    '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_STORAGE_PATH=/absolute/index  Complete external index directory. Preserves the existing configuration semantics and overrides GITNEXUS_STORAGE_ROOT when both are set.\n  GITNEXUS_STORAGE_ROOT=/absolute/root  External index root; each repository uses an isolated <repo-basename>-<canonical-path-hash>/ slot.\n  GITNEXUS_CONTENT_RETENTION=full  Source-text retention profile: full, symbol, or none. Default full.\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

@@ -279,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_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 '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_STORAGE_PATH=/absolute/index  Complete external index directory. Preserves the existing configuration semantics and overrides GITNEXUS_STORAGE_ROOT when both are set.\n  GITNEXUS_STORAGE_ROOT=/absolute/root  External index root; each repository uses an isolated <repo-basename>-<canonical-path-hash>/ slot.\n  GITNEXUS_CONTENT_RETENTION=full  Source-text retention profile: full, symbol, or none. Default full.\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;

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

@@ -278,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_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）。',
+    'help.analyze.environment': '\n环境变量：\n  GITNEXUS_NO_GITIGNORE=1   跳过 .gitignore 解析（仍读取 .gitnexusignore）\n  GITNEXUS_MAX_FILE_SIZE=N  覆盖大文件跳过阈值（KB）。默认 512，最大 32768。\n  GITNEXUS_STORAGE_PATH=/absolute/index  完整外部索引目录。保留既有配置语义；与 GITNEXUS_STORAGE_ROOT 同时设置时优先使用。\n  GITNEXUS_STORAGE_ROOT=/absolute/root  外部索引根目录；每个仓库使用独立的 <仓库名>-<规范路径哈希>/ 子目录。\n  GITNEXUS_CONTENT_RETENTION=full  源码文本保留策略：full、symbol 或 none。默认 full。\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-repo.js

@@ -14,8 +14,9 @@
  */
 import path from 'path';
 import fs from 'fs/promises';
-import { getStoragePaths, INDEX_METADATA_FILE, loadMeta, ensureGitNexusIgnored, registerRepo, } from '../storage/repo-manager.js';
+import { loadMeta, saveMeta, ensureGitNexusIgnored, registerRepo, } from '../storage/repo-manager.js';
 import { getGitRoot, getRemoteUrl, isGitRepo } from '../storage/git.js';
+import { getIndexStorageRequirements, requireStoragePath, StorageRequirementError, } from '../storage/storage-resolver.js';
 export const indexCommand = async (inputPathParts, options) => {
     console.log('\n  GitNexus Index\n');
     const inputPath = inputPathParts?.length ? inputPathParts.join(' ') : undefined;
@@ -53,42 +54,40 @@ export const indexCommand = async (inputPathParts, options) => {
         process.exitCode = 1;
         return;
     }
-    const { storagePath, lbugPath } = getStoragePaths(repoPath);
-    // ── Verify index exists (metadata file, legacy metadata, or restorable DB) ─
-    let hasMetadataIndex = false;
-    let hasLegacyIndex = false;
-    let hasLbugIndex = false;
+    let storagePath;
     try {
-        await fs.access(path.join(storagePath, INDEX_METADATA_FILE));
-        hasMetadataIndex = true;
+        storagePath = await requireStoragePath(repoPath, getIndexStorageRequirements(!!options?.force));
     }
-    catch { }
-    try {
-        await fs.access(path.join(storagePath, 'meta.json'));
-        hasLegacyIndex = true;
-    }
-    catch { }
-    try {
-        await fs.access(lbugPath);
-        hasLbugIndex = true;
-    }
-    catch { }
-    if (!hasMetadataIndex && !hasLegacyIndex && !hasLbugIndex) {
-        console.log(`  No GitNexus index found.`);
-        console.log(`  Expected gitnexus.json, .gitnexus/meta.json, or LadybugDB at: ${storagePath}`);
-        console.log('  Run `gitnexus analyze` to build the index first.\n');
-        process.exitCode = 1;
-        return;
-    }
-    // ── Verify lbug database exists ───────────────────────────────────
-    if (!hasLbugIndex) {
-        console.log(`  Index exists but contains no LadybugDB database.`);
-        console.log('  Run `gitnexus analyze` to build the index.\n');
+    catch (error) {
+        if (!(error instanceof StorageRequirementError)) {
+            console.log(`  ${error instanceof Error ? error.message : String(error)}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const inspection = error.inspection;
+        if (inspection.state === 'missing' || inspection.state === 'empty') {
+            console.log(`  No GitNexus index found.`);
+            console.log(`  Expected gitnexus.json, .gitnexus/meta.json, or LadybugDB at: ${inspection.storagePath}`);
+            console.log('  Run `gitnexus analyze` to build the index first.\n');
+        }
+        else if (inspection.state === 'unowned' && !options?.force) {
+            console.log(`  gitnexus.json or .gitnexus/meta.json is missing.`);
+            console.log('  Use --force to register anyway (stats will be empty),');
+            console.log('  or run `gitnexus analyze` to rebuild properly.\n');
+        }
+        else if (!inspection.hasCodeIndexDB) {
+            console.log(`  Index exists but contains no LadybugDB database.`);
+            console.log('  Run `gitnexus analyze` to build the index.\n');
+        }
+        else {
+            console.log(`  ${error.message}\n`);
+        }
         process.exitCode = 1;
         return;
     }
     // ── Load or reconstruct meta ──────────────────────────────────────
     let meta = await loadMeta(storagePath);
+    let reconstructedMeta = false;
     if (!meta) {
         if (!options?.force) {
             console.log(`  gitnexus.json or .gitnexus/meta.json is missing.`);
@@ -100,9 +99,25 @@ export const indexCommand = async (inputPathParts, options) => {
         // --force: build a minimal meta so the repo can be registered
         meta = {
             repoPath,
+            storagePath,
             lastCommit: '',
             indexedAt: new Date().toISOString(),
         };
+        reconstructedMeta = true;
+    }
+    // `index --force` is the explicit adoption path for an existing external
+    // database whose legacy metadata predates storagePath binding, and for a
+    // repository-local slot whose metadata still names another checkout.
+    if (options?.force) {
+        const adoptedRepoPath = path.resolve(repoPath);
+        const adoptedStoragePath = path.resolve(storagePath);
+        const ownershipChanged = path.resolve(meta.repoPath) !== adoptedRepoPath ||
+            meta.storagePath === undefined ||
+            path.resolve(meta.storagePath) !== adoptedStoragePath;
+        if (ownershipChanged) {
+            meta = { ...meta, repoPath: adoptedRepoPath, storagePath: adoptedStoragePath };
+            reconstructedMeta = true;
+        }
     }
     // ── Register in global registry ───────────────────────────────────
     // Refresh the on-disk meta with a freshly captured `remoteUrl` if
@@ -112,8 +127,11 @@ export const indexCommand = async (inputPathParts, options) => {
     if (!meta.remoteUrl && isGitRepo(repoPath)) {
         meta.remoteUrl = getRemoteUrl(repoPath);
     }
-    await registerRepo(repoPath, meta);
-    await ensureGitNexusIgnored(repoPath);
+    if (reconstructedMeta) {
+        await saveMeta(storagePath, meta);
+    }
+    await registerRepo(repoPath, meta, { storagePath });
+    await ensureGitNexusIgnored(repoPath, storagePath);
     const projectName = path.basename(repoPath);
     const { stats } = meta;
     console.log(`  Repository registered: ${projectName}`);

package/dist/cli/index.js

@@ -173,7 +173,8 @@ program
     .action(createLazyAction(() => import('./list.js'), 'listCommand'));
 program
     .command('status')
-    .description('Show index status for current repo')
+    .description('Show index status for the current repo or a registered index')
+    .option('-r, --repo <name>', 'Registered repository alias or path (works after checkout removal)')
     .option('--json', 'Emit machine-readable index and analyzer provenance')
     .addHelpText('after', () => t('help.identityCache.environment'))
     .action(createLazyAction(() => import('./status.js'), 'statusCommand'));
@@ -258,7 +259,7 @@ program
     .option('-c, --context <text>', 'Task context to improve ranking')
     .option('-g, --goal <text>', 'What you want to find')
     .option('-l, --limit <n>', 'Max processes to return (default: 5)')
-    .option('--content', 'Include full symbol source code')
+    .option('--content', 'Include retained symbol source text (reports availability when disabled by retention)')
     .action(createLbugLazyAction(() => import('./tool.js'), 'queryCommand'));
 program
     .command('context [name]')
@@ -268,7 +269,7 @@ program
     .option('-u, --uid <uid>', 'Direct symbol UID (zero-ambiguity lookup)')
     .option('-f, --file <path>', 'File path to disambiguate common names')
     .option('-l, --limit <n>', 'Max callers/callees/processes to return')
-    .option('--content', 'Include full symbol source code')
+    .option('--content', 'Include retained symbol source text (reports availability when disabled by retention)')
     .action(createLbugLazyAction(() => import('./tool.js'), 'contextCommand'));
 program
     .command('impact [target]')

package/dist/cli/publish.js

@@ -23,7 +23,7 @@
 import path from 'path';
 import { UNDERSTAND_QUICKLY_DISPATCH_URL, UNDERSTAND_QUICKLY_TOKEN_ENV, buildUqDispatchPayload, isValidOwnerRepo, parseOwnerRepoFromRemote, } from '../_shared/index.js';
 import { getGitRoot, getRemoteOriginUrl, getCurrentCommit } from '../storage/git.js';
-import { hasIndex } from '../storage/repo-manager.js';
+import { requireStoragePath, STATUS_STORAGE_REQUIREMENTS, StorageRequirementError, isUnusableIndexInspection, } from '../storage/storage-resolver.js';
 import { cliInfo, cliError } from './cli-message.js';
 const REGISTER_HINT = 'Register your repo once with: npx @understand-quickly/cli add\n' +
     'Or use the wizard: https://looptech-ai.github.io/understand-quickly/add.html';
@@ -69,8 +69,19 @@ export const publishCommand = async (inputPath, options = {}) => {
     // Publishing without an index is almost always a mistake — the
     // registry's nightly sync would fetch a stale or missing graph file
     // and mark the entry `missing`. Refuse loudly with a fix-it hint.
-    if (!(await hasIndex(repoPath))) {
-        cliError(`[understand-quickly] no GitNexus index found at ${repoPath}/.gitnexus.\n` +
+    try {
+        await requireStoragePath(repoPath, STATUS_STORAGE_REQUIREMENTS);
+    }
+    catch (error) {
+        if (!(error instanceof StorageRequirementError))
+            throw error;
+        const inspection = error.inspection;
+        if (!isUnusableIndexInspection(inspection)) {
+            cliError(`[understand-quickly] ${error.message}`);
+            process.exitCode = 1;
+            return;
+        }
+        cliError(`[understand-quickly] no usable GitNexus index found for ${repoPath}.\n` +
             'Run `gitnexus analyze` first, then re-run `gitnexus publish`.');
         process.exitCode = 1;
         return;

package/dist/cli/remove.js

@@ -32,7 +32,8 @@ import fs from 'fs/promises';
 import { logger } from '../core/logger.js';
 import { cliError } from './cli-message.js';
 import { t } from './i18n/index.js';
-import { readRegistry, resolveRegistryEntry, assertSafeStoragePath, unregisterRepo, RegistryNotFoundError, RegistryAmbiguousTargetError, UnsafeStoragePathError, } from '../storage/repo-manager.js';
+import { readRegistry, resolveRegistryEntry, unregisterRepo, RegistryNotFoundError, RegistryAmbiguousTargetError, } from '../storage/repo-manager.js';
+import { requireDeletableStoragePath, StorageDeletionError } from '../storage/storage-resolver.js';
 export const removeCommand = async (target, options) => {
     // Read the registry snapshot once and pass it to the resolver — this
     // lets us render the "before" state in the dry-run path without a
@@ -68,19 +69,14 @@ export const removeCommand = async (target, options) => {
         console.log(`\n${t('common.runForceConfirm')}`);
         return;
     }
-    // Safety guard (#1003 review — @magyargergo): refuse to proceed if
-    // the registry entry's `storagePath` isn't the canonical
-    // `<entry.path>/.gitnexus` subfolder. `~/.gitnexus/registry.json` is
-    // user-writable, so a corrupted or hand-edited entry could point
-    // storagePath at the repo root, an empty string (→ cwd), a parent
-    // dir, or anywhere else; `fs.rm(recursive: true, force: true)` on
-    // any of those would be a runtime disaster. Bail before touching
-    // disk, with an actionable hint for recovering a broken registry.
+    // Validate immediately before deletion. `--force` skips confirmation only;
+    // it does not bypass the ownership and dangerous-path checks.
+    let storagePath;
     try {
-        assertSafeStoragePath(entry);
+        storagePath = await requireDeletableStoragePath(entry);
     }
     catch (err) {
-        if (err instanceof UnsafeStoragePathError) {
+        if (err instanceof StorageDeletionError) {
             cliError(t('common.error', { message: err.message }));
             process.exit(1);
         }
@@ -92,7 +88,7 @@ export const removeCommand = async (target, options) => {
     // orphaned — `listRegisteredRepos({ validate: true })` prunes those on
     // next read, so the failure is self-healing.
     try {
-        await fs.rm(entry.storagePath, { recursive: true, force: true });
+        await fs.rm(storagePath, { recursive: true, force: true });
         await unregisterRepo(entry.path);
         console.log(t('remove.removed', { name: entry.name }));
         console.log(`   ${t('common.path')}:    ${entry.path}`);

package/dist/cli/setup.js

@@ -376,6 +376,7 @@ const HOOK_HELPERS = [
     'hook-db-lock-probe.cjs',
     'win-rm-list-json.ps1',
     'resolve-analyze-cmd.cjs',
+    'registry-query.cjs',
 ];
 // win-rm-list-json.ps1 is best-effort: it is read (not require()'d) by
 // hook-db-lock-probe.cjs only on Windows, and that probe fails open when the

package/dist/cli/status.d.ts

@@ -5,5 +5,7 @@
  */
 export interface StatusOptions {
     json?: boolean;
+    /** Resolve a registered index without requiring its original checkout to remain on disk. */
+    repo?: string;
 }
 export declare const statusCommand: (options?: StatusOptions) => Promise<void>;