gitnexus 1.6.11-rc.7 → 1.6.11-rc.9

package/README.md

@@ -204,7 +204,7 @@ Your AI agent gets **17 tools** (15 per-repo + 2 group) automatically:
 | `group_list`     | List configured repository groups                                      |
 | `group_sync`     | Rebuild a group's Contract Registry and cross-repo links               |
 
-> With one indexed repo, the `repo` param is optional. With multiple, specify which: `query({search_query: "auth", repo: "my-app"})`. Per-repo tools also take an optional `branch` for indexes pinned with `gitnexus analyze --branch`; omitting it queries the workspace index, which follows your checked-out working tree. `explain` and `pdg_query` need an index built with `gitnexus analyze --pdg`.
+> Read-only tools can omit `repo` when one repo is indexed, an MCP default is configured, or the GitNexus process cwd is inside a registered path without crossing into an unindexed nested Git checkout. Otherwise—and for mutating tools with multiple indexed repos and no MCP default—specify it explicitly: `query({search_query: "auth", repo: "my-app"})`. Per-repo tools also take an optional `branch` for indexes pinned with `gitnexus analyze --branch`; omitting it queries the workspace index, which follows your checked-out working tree. `explain` and `pdg_query` need an index built with `gitnexus analyze --pdg`.
 
 ## MCP Resources
 

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

@@ -32,6 +32,14 @@ export declare const en: {
     readonly 'status.detached': "(detached HEAD)";
     readonly 'status.workspaceIndexLabel': "Workspace index: last analyzed on '{{primary}}' (re-run gitnexus analyze to follow the current branch)";
     readonly 'status.status': "Status";
+    readonly 'status.indexContentCurrent': "Index content: matches all {{count}} covered file(s)";
+    readonly 'status.indexContentDrifted': "Index content: {{changed}} changed, {{added}} added, {{deleted}} deleted";
+    readonly 'status.indexContentMore': "  ...and {{count}} more {{label}}";
+    readonly 'status.indexContentUnmeasurable': "Index content: not comparable ({{reason}}); fell back to the working-tree check";
+    readonly 'status.indexContentScanFailed': "Index content: coverage scan failed; treating the index as stale";
+    readonly 'status.driftChanged': "changed";
+    readonly 'status.driftAdded': "added";
+    readonly 'status.driftDeleted': "deleted";
     readonly 'status.upToDate': "✅ up-to-date";
     readonly 'status.stale': "⚠️ stale (re-run gitnexus analyze)";
     readonly 'clean.deleteAll': "This will delete GitNexus indexes for {{count}} repo(s):";

package/dist/cli/i18n/en.js

@@ -32,6 +32,14 @@ export const en = {
     'status.detached': '(detached HEAD)',
     'status.workspaceIndexLabel': "Workspace index: last analyzed on '{{primary}}' (re-run gitnexus analyze to follow the current branch)",
     'status.status': 'Status',
+    'status.indexContentCurrent': 'Index content: matches all {{count}} covered file(s)',
+    'status.indexContentDrifted': 'Index content: {{changed}} changed, {{added}} added, {{deleted}} deleted',
+    'status.indexContentMore': '  ...and {{count}} more {{label}}',
+    'status.indexContentUnmeasurable': 'Index content: not comparable ({{reason}}); fell back to the working-tree check',
+    'status.indexContentScanFailed': 'Index content: coverage scan failed; treating the index as stale',
+    'status.driftChanged': 'changed',
+    'status.driftAdded': 'added',
+    'status.driftDeleted': 'deleted',
     'status.upToDate': '✅ up-to-date',
     'status.stale': '⚠️ stale (re-run gitnexus analyze)',
     'clean.deleteAll': 'This will delete GitNexus indexes for {{count}} repo(s):',

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

@@ -33,6 +33,14 @@ export declare const cliResources: {
         readonly 'status.detached': "(detached HEAD)";
         readonly 'status.workspaceIndexLabel': "Workspace index: last analyzed on '{{primary}}' (re-run gitnexus analyze to follow the current branch)";
         readonly 'status.status': "Status";
+        readonly 'status.indexContentCurrent': "Index content: matches all {{count}} covered file(s)";
+        readonly 'status.indexContentDrifted': "Index content: {{changed}} changed, {{added}} added, {{deleted}} deleted";
+        readonly 'status.indexContentMore': "  ...and {{count}} more {{label}}";
+        readonly 'status.indexContentUnmeasurable': "Index content: not comparable ({{reason}}); fell back to the working-tree check";
+        readonly 'status.indexContentScanFailed': "Index content: coverage scan failed; treating the index as stale";
+        readonly 'status.driftChanged': "changed";
+        readonly 'status.driftAdded': "added";
+        readonly 'status.driftDeleted': "deleted";
         readonly 'status.upToDate': "✅ up-to-date";
         readonly 'status.stale': "⚠️ stale (re-run gitnexus analyze)";
         readonly 'clean.deleteAll': "This will delete GitNexus indexes for {{count}} repo(s):";
@@ -289,6 +297,14 @@ export declare const cliResources: {
         'status.detached': string;
         'status.workspaceIndexLabel': string;
         'status.status': string;
+        'status.indexContentCurrent': string;
+        'status.indexContentDrifted': string;
+        'status.indexContentMore': string;
+        'status.indexContentUnmeasurable': string;
+        'status.indexContentScanFailed': string;
+        'status.driftChanged': string;
+        'status.driftAdded': string;
+        'status.driftDeleted': string;
         'status.upToDate': string;
         'status.stale': string;
         'clean.deleteAll': string;

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

@@ -32,6 +32,14 @@ export declare const zhCN: {
     'status.detached': string;
     'status.workspaceIndexLabel': string;
     'status.status': string;
+    'status.indexContentCurrent': string;
+    'status.indexContentDrifted': string;
+    'status.indexContentMore': string;
+    'status.indexContentUnmeasurable': string;
+    'status.indexContentScanFailed': string;
+    'status.driftChanged': string;
+    'status.driftAdded': string;
+    'status.driftDeleted': string;
     'status.upToDate': string;
     'status.stale': string;
     'clean.deleteAll': string;

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

@@ -32,6 +32,14 @@ export const zhCN = {
     'status.detached': '（分离 HEAD）',
     'status.workspaceIndexLabel': "工作区索引：最近在 '{{primary}}' 分支上分析（重新运行 gitnexus analyze 以跟随当前分支）",
     'status.status': '状态',
+    'status.indexContentCurrent': '索引内容：与覆盖的全部 {{count}} 个文件一致',
+    'status.indexContentDrifted': '索引内容：{{changed}} 个已修改，{{added}} 个新增，{{deleted}} 个已删除',
+    'status.indexContentMore': '  ……另有 {{count}} 个 {{label}}',
+    'status.indexContentUnmeasurable': '索引内容：无法比对（{{reason}}），已回退到工作区检查',
+    'status.indexContentScanFailed': '索引内容：覆盖扫描失败，按过期处理',
+    'status.driftChanged': '已修改',
+    'status.driftAdded': '新增',
+    'status.driftDeleted': '已删除',
     'status.upToDate': '✅ 已是最新',
     'status.stale': '⚠️ 已过期（重新运行 gitnexus analyze）',
     'clean.deleteAll': '将删除 {{count}} 个仓库的 GitNexus 索引：',

package/dist/cli/status.js

@@ -8,7 +8,64 @@ import { findRepo, getStoragePaths, loadMeta, hasKuzuIndex } from '../storage/re
 import { getCurrentCommit, getCurrentBranch, isGitRepo, getGitRoot, isWorkingTreeDirty, } from '../storage/git.js';
 import { analyzerRunnerIdentitiesEqual, resolveAnalyzerRunnerIdentity, } from '../core/analyzer-identity.js';
 import { getIndexIncompleteReasons } from '../core/index-freshness.js';
+import { detectIndexContentDrift } from '../core/index-content-drift.js';
 import { t } from './i18n/index.js';
+/** How many drifted paths the report names before summarizing the rest. */
+const DRIFT_SAMPLE_LIMIT = 10;
+/**
+ * Machine-readable form of the per-file comparison. `'not-checked'` is its own
+ * value rather than a silent omission: it says the index was already stale on
+ * metadata alone, so the scan was skipped, which is not the same claim as a
+ * scan that ran and found nothing.
+ */
+const describeContentDrift = (drift) => {
+    if (!drift)
+        return { status: 'not-checked' };
+    if (drift.kind === 'current') {
+        return { status: 'current', coveredFiles: drift.coveredFileCount };
+    }
+    if (drift.kind === 'unmeasurable') {
+        return { status: 'unmeasurable', reason: drift.reason };
+    }
+    return {
+        status: 'drifted',
+        counts: {
+            changed: drift.changed.length,
+            added: drift.added.length,
+            deleted: drift.deleted.length,
+        },
+        changed: drift.changed.slice(0, DRIFT_SAMPLE_LIMIT),
+        added: drift.added.slice(0, DRIFT_SAMPLE_LIMIT),
+        deleted: drift.deleted.slice(0, DRIFT_SAMPLE_LIMIT),
+        truncated: {
+            changed: drift.changed.length > DRIFT_SAMPLE_LIMIT,
+            added: drift.added.length > DRIFT_SAMPLE_LIMIT,
+            deleted: drift.deleted.length > DRIFT_SAMPLE_LIMIT,
+        },
+    };
+};
+/** Escape control characters in repo-relative paths before printing. */
+const formatDriftPath = (rel) => /[\u0000-\u001f\u007f]/.test(rel) ? JSON.stringify(rel) : rel;
+const printDriftDetail = (drift) => {
+    console.log(t('status.indexContentDrifted', {
+        changed: drift.changed.length,
+        added: drift.added.length,
+        deleted: drift.deleted.length,
+    }));
+    const labelled = [
+        [t('status.driftChanged'), drift.changed],
+        [t('status.driftAdded'), drift.added],
+        [t('status.driftDeleted'), drift.deleted],
+    ];
+    for (const [label, paths] of labelled) {
+        for (const p of paths.slice(0, DRIFT_SAMPLE_LIMIT)) {
+            console.log(`  ${label}: ${formatDriftPath(p)}`);
+        }
+        const remaining = paths.length - DRIFT_SAMPLE_LIMIT;
+        if (remaining > 0)
+            console.log(t('status.indexContentMore', { count: remaining, label }));
+    }
+};
 export const statusCommand = async (options = {}) => {
     const cwd = process.cwd();
     if (!isGitRepo(cwd)) {
@@ -63,13 +120,26 @@ export const statusCommand = async (options = {}) => {
     const currentRunnerIdentity = resolveAnalyzerRunnerIdentity(import.meta.url);
     const runnerIdentityIsCurrent = analyzerRunnerIdentitiesEqual(activeMeta.runnerIdentity, currentRunnerIdentity);
     const incompleteReasons = getIndexIncompleteReasons(activeMeta);
-    // A matching HEAD is not enough: `analyze` re-indexes a dirty working tree,
-    // so a repo with uncommitted source changes is stale even at the same commit.
-    // Skip the check for non-git folders (currentCommit === '') to match analyze.
-    const isUpToDate = currentCommit === activeMeta.lastCommit &&
+    const metadataIsCurrent = currentCommit === activeMeta.lastCommit &&
         runnerIdentityIsCurrent &&
-        incompleteReasons.length === 0 &&
-        (currentCommit === '' || !isWorkingTreeDirty(repo.repoPath));
+        incompleteReasons.length === 0;
+    // A matching HEAD is not enough: `analyze` re-indexes changed content at the
+    // same commit, so the files the index covers must still be compared against
+    // disk. Only worth the scan once the cheap metadata checks agree, and skipped
+    // for non-git folders (currentCommit === '') to match analyze.
+    const contentDrift = metadataIsCurrent && currentCommit !== ''
+        ? await detectIndexContentDrift(repo.repoPath, activeMeta.fileHashes, activeMeta.indexCoverage)
+        : undefined;
+    // The repo-wide dirty flag survives only as the fallback for metadata written
+    // before `fileHashes` existed. Where the per-file comparison can run it
+    // decides, so a file the index does not cover no longer pins a byte-current
+    // index to a "stale" verdict that `analyze` is powerless to clear (#3077).
+    const contentIsCurrent = contentDrift === undefined ||
+        contentDrift.kind === 'current' ||
+        (contentDrift.kind === 'unmeasurable' &&
+            contentDrift.reason === 'no-file-hashes' &&
+            !isWorkingTreeDirty(repo.repoPath));
+    const isUpToDate = metadataIsCurrent && contentIsCurrent;
     if (options.json) {
         console.log(JSON.stringify({
             schemaVersion: 1,
@@ -87,6 +157,7 @@ export const statusCommand = async (options = {}) => {
                 commit: currentCommit,
                 runnerIdentity: currentRunnerIdentity,
             },
+            contentDrift: describeContentDrift(contentDrift),
             status: isUpToDate ? 'up-to-date' : 'stale',
         }));
         return;
@@ -107,5 +178,19 @@ export const statusCommand = async (options = {}) => {
         console.log(`Index incomplete reasons: ${JSON.stringify(incompleteReasons)}`);
     }
     console.log(`${t('status.currentRunnerIdentity')}: ${JSON.stringify(currentRunnerIdentity)}`);
+    if (contentDrift?.kind === 'current') {
+        console.log(t('status.indexContentCurrent', { count: contentDrift.coveredFileCount }));
+    }
+    else if (contentDrift?.kind === 'drifted') {
+        printDriftDetail(contentDrift);
+    }
+    else if (contentDrift?.kind === 'unmeasurable') {
+        if (contentDrift.reason === 'scan-failed') {
+            console.log(t('status.indexContentScanFailed'));
+        }
+        else if (!isUpToDate) {
+            console.log(t('status.indexContentUnmeasurable', { reason: contentDrift.reason }));
+        }
+    }
     console.log(`${t('status.status')}: ${isUpToDate ? t('status.upToDate') : t('status.stale')}`);
 };

package/dist/core/index-content-drift.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Does the index still reflect the files it actually covers?
+ *
+ * `status` used to answer this with a repo-wide `git status --porcelain`
+ * boolean, which says something different: whether the working tree differs
+ * from HEAD. Those two questions diverge in both directions. A scratch file,
+ * a build artifact, or a tracked file under a tool directory the indexer
+ * never reads makes the tree dirty while every indexed file is byte-current —
+ * and because `analyze` cannot commit or delete that file, the resulting
+ * "stale (re-run gitnexus analyze)" verdict was unclearable (#3077). It also
+ * misses the reverse case: reverting a file that was indexed while dirty
+ * leaves a clean tree over an index holding the pre-revert content.
+ *
+ * `meta.fileHashes` already records the exact set of files the last run
+ * covered, so the question can be answered directly. This module recomputes
+ * the coverage set with the same `walkRepositoryPaths` scan (ignore rules and
+ * dotfile handling stay shared) and the large-file cap recorded in
+ * `meta.indexCoverage`, hashes only the paths that can actually have changed
+ * since that run, and diffs against what was recorded.
+ */
+import type { RepoMeta } from '../storage/repo-meta.js';
+/** Why the recorded coverage set could not be compared against disk at all. */
+export type IndexContentUnmeasurableReason = 
+/** Metadata predates per-file hashes, or the run recorded none (non-git). */
+'no-file-hashes'
+/** The repository scan or hashing pass threw. */
+ | 'scan-failed';
+/**
+ * A three-way verdict. `'unmeasurable'` is kept apart from `'current'` on
+ * purpose: it means the comparison never ran, which is not evidence the index
+ * is fresh. Legacy metadata without hashes still falls back to the working-tree
+ * check; a failed scan must not.
+ */
+export type IndexContentDrift = {
+    kind: 'current';
+    coveredFileCount: number;
+} | {
+    kind: 'drifted';
+    changed: string[];
+    added: string[];
+    deleted: string[];
+} | {
+    kind: 'unmeasurable';
+    reason: IndexContentUnmeasurableReason;
+};
+export type IndexCoveragePolicy = NonNullable<RepoMeta['indexCoverage']>;
+/**
+ * Compare the files recorded in `fileHashes` against the current working tree.
+ *
+ * `added` covers files the index would pick up but has never seen, so a new
+ * source file still reports stale — the index is genuinely incomplete then,
+ * and comparing only the recorded entries would wave that through.
+ */
+export declare const detectIndexContentDrift: (repoPath: string, fileHashes: Readonly<Record<string, string>> | undefined, coverage?: IndexCoveragePolicy) => Promise<IndexContentDrift>;

package/dist/core/index-content-drift.js

@@ -0,0 +1,127 @@
+/**
+ * Does the index still reflect the files it actually covers?
+ *
+ * `status` used to answer this with a repo-wide `git status --porcelain`
+ * boolean, which says something different: whether the working tree differs
+ * from HEAD. Those two questions diverge in both directions. A scratch file,
+ * a build artifact, or a tracked file under a tool directory the indexer
+ * never reads makes the tree dirty while every indexed file is byte-current —
+ * and because `analyze` cannot commit or delete that file, the resulting
+ * "stale (re-run gitnexus analyze)" verdict was unclearable (#3077). It also
+ * misses the reverse case: reverting a file that was indexed while dirty
+ * leaves a clean tree over an index holding the pre-revert content.
+ *
+ * `meta.fileHashes` already records the exact set of files the last run
+ * covered, so the question can be answered directly. This module recomputes
+ * the coverage set with the same `walkRepositoryPaths` scan (ignore rules and
+ * dotfile handling stay shared) and the large-file cap recorded in
+ * `meta.indexCoverage`, hashes only the paths that can actually have changed
+ * since that run, and diffs against what was recorded.
+ */
+import { constants as fsConstants } from 'node:fs';
+import { access } from 'node:fs/promises';
+import path from 'node:path';
+import { walkRepositoryPaths } from './ingestion/filesystem-walker.js';
+import { computeFileHashesDetailed } from '../storage/file-hash.js';
+import { listWorkingTreeDirtyPaths } from '../storage/git.js';
+import { isGitNexusManagedPath } from '../storage/gitnexus-managed-paths.js';
+import { chunk } from '../lib/utils.js';
+import { logger } from './logger.js';
+const HASH_BATCH = 100;
+const collectUnreadablePaths = async (repoPath, relPaths) => {
+    const unreadable = [];
+    for (const batch of chunk(relPaths, HASH_BATCH)) {
+        await Promise.all(batch.map(async (rel) => {
+            try {
+                await access(path.join(repoPath, rel), fsConstants.R_OK);
+            }
+            catch {
+                unreadable.push(rel);
+            }
+        }));
+    }
+    unreadable.sort();
+    return unreadable;
+};
+/**
+ * Compare the files recorded in `fileHashes` against the current working tree.
+ *
+ * `added` covers files the index would pick up but has never seen, so a new
+ * source file still reports stale — the index is genuinely incomplete then,
+ * and comparing only the recorded entries would wave that through.
+ */
+export const detectIndexContentDrift = async (repoPath, fileHashes, coverage) => {
+    if (!fileHashes || Object.keys(fileHashes).length === 0) {
+        return { kind: 'unmeasurable', reason: 'no-file-hashes' };
+    }
+    // Excluded from BOTH sides, or GitNexus's own output guarantees a mismatch:
+    // analyze rewrites AGENTS.md/CLAUDE.md after recording hashes, so they read
+    // as `added` on a first run and `changed` on every run after that — a fresh
+    // index would report itself stale forever.
+    const recorded = Object.fromEntries(Object.entries(fileHashes).filter(([rel]) => !isGitNexusManagedPath(rel)));
+    if (Object.keys(recorded).length === 0) {
+        return { kind: 'unmeasurable', reason: 'no-file-hashes' };
+    }
+    try {
+        const scanned = await walkRepositoryPaths(repoPath, undefined, {
+            quiet: true,
+            maxFileSizeBytes: coverage?.maxFileSizeBytes,
+        });
+        const scannedPaths = scanned.map((file) => file.path).filter((p) => !isGitNexusManagedPath(p));
+        const scannedSet = new Set(scannedPaths);
+        const recordedSet = new Set(Object.keys(recorded));
+        // Legacy indexes have `fileHashes` but no `indexCoverage`. A later default
+        // cap would omit a still-present hashed file and call it deleted. Recorded
+        // paths that still exist stay in the coverage set even if this walk skipped
+        // them for size.
+        const recovered = new Set();
+        for (const rel of recordedSet) {
+            if (scannedSet.has(rel))
+                continue;
+            try {
+                await access(path.join(repoPath, rel), fsConstants.R_OK);
+                recovered.add(rel);
+                scannedSet.add(rel);
+            }
+            catch {
+                // Missing or unreadable: stays deleted / changed below.
+            }
+        }
+        const added = scannedPaths.filter((p) => !recordedSet.has(p)).sort();
+        const deleted = [...recordedSet].filter((p) => !scannedSet.has(p)).sort();
+        const intersection = [...recordedSet].filter((p) => scannedSet.has(p));
+        const dirtyNow = listWorkingTreeDirtyPaths(repoPath);
+        const dirtyAtIndex = coverage?.dirtyPaths;
+        const dirtyNowSet = dirtyNow === null ? null : new Set(dirtyNow);
+        const dirtyAtIndexSet = dirtyAtIndex === undefined ? undefined : new Set(dirtyAtIndex);
+        const hashCandidates = dirtyNowSet === null || dirtyAtIndexSet === undefined
+            ? intersection
+            : intersection.filter((p) => dirtyAtIndexSet.has(p) || dirtyNowSet.has(p) || recovered.has(p));
+        const hashCandidateSet = new Set(hashCandidates);
+        const skipHash = intersection.filter((p) => !hashCandidateSet.has(p));
+        const unreadableFromAccess = await collectUnreadablePaths(repoPath, skipHash);
+        const unreadableSet = new Set(unreadableFromAccess);
+        const { hashes: hashed, unreadable: unreadableFromHash } = await computeFileHashesDetailed(repoPath, hashCandidates);
+        for (const p of unreadableFromHash)
+            unreadableSet.add(p);
+        const changed = [];
+        for (const p of intersection) {
+            if (unreadableSet.has(p)) {
+                changed.push(p);
+                continue;
+            }
+            const currentHash = hashed.get(p) ?? recorded[p];
+            if (currentHash !== recorded[p])
+                changed.push(p);
+        }
+        changed.sort();
+        if (changed.length === 0 && added.length === 0 && deleted.length === 0) {
+            return { kind: 'current', coveredFileCount: scannedSet.size };
+        }
+        return { kind: 'drifted', changed, added, deleted };
+    }
+    catch (err) {
+        logger.warn({ err, repoPath }, 'index content drift scan failed');
+        return { kind: 'unmeasurable', reason: 'scan-failed' };
+    }
+};

package/dist/core/ingestion/filesystem-walker.d.ts

@@ -7,11 +7,21 @@ export interface ScannedFile {
 export interface FilePath {
     path: string;
 }
-/**
- * Phase 1: Scan repository — stat files to get paths + sizes, no content loaded.
- * Memory: ~10MB for 100K files vs ~1GB+ with content.
- */
-export declare const walkRepositoryPaths: (repoPath: string, onProgress?: (current: number, total: number, filePath: string) => void) => Promise<ScannedFile[]>;
+export interface WalkRepositoryOptions {
+    /**
+     * Suppress the operator-facing large-file notice. Set by read-only callers
+     * such as `status`, which reuse this scan purely to learn which files the
+     * index covers and must not emit analyze's progress commentary.
+     */
+    quiet?: boolean;
+    /**
+     * Override the large-file cap. `status` replays the bytes recorded at
+     * analyze time so `--max-file-size` / `GITNEXUS_MAX_FILE_SIZE` cannot
+     * silently drop a file that the index actually covers.
+     */
+    maxFileSizeBytes?: number;
+}
+export declare const walkRepositoryPaths: (repoPath: string, onProgress?: (current: number, total: number, filePath: string) => void, options?: WalkRepositoryOptions) => Promise<ScannedFile[]>;
 /**
  * Phase 2: Read file contents for a specific set of relative paths.
  * Returns a Map for O(1) lookup. Silently skips files that fail to read.

package/dist/core/ingestion/filesystem-walker.js

@@ -39,9 +39,26 @@ const warnLargeFileSkip = (message) => {
  * Phase 1: Scan repository — stat files to get paths + sizes, no content loaded.
  * Memory: ~10MB for 100K files vs ~1GB+ with content.
  */
-export const walkRepositoryPaths = async (repoPath, onProgress) => {
+const assertWalkRootIsDirectory = async (repoPath) => {
+    let st;
+    try {
+        st = await fs.stat(repoPath);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR') {
+            throw new Error(`walkRepositoryPaths: path does not exist: ${repoPath}`);
+        }
+        throw err;
+    }
+    if (!st.isDirectory()) {
+        throw new Error(`walkRepositoryPaths: not a directory: ${repoPath}`);
+    }
+};
+export const walkRepositoryPaths = async (repoPath, onProgress, options = {}) => {
+    await assertWalkRootIsDirectory(repoPath);
     const ignoreFilter = await createIgnoreFilter(repoPath);
-    const maxFileSizeBytes = getMaxFileSizeBytes();
+    const maxFileSizeBytes = options.maxFileSizeBytes ?? getMaxFileSizeBytes();
     const filtered = await glob('**/*', {
         cwd: repoPath,
         nodir: true,
@@ -81,7 +98,7 @@ export const walkRepositoryPaths = async (repoPath, onProgress) => {
     // scans. Canonicalize once at the scan boundary so every downstream phase sees
     // the same repository order.
     deduplicatedEntries.sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
-    if (skippedLarge > 0) {
+    if (skippedLarge > 0 && !options.quiet) {
         const isDefault = maxFileSizeBytes === DEFAULT_MAX_FILE_SIZE_BYTES;
         const isOverrideUnset = !process.env.GITNEXUS_MAX_FILE_SIZE;
         const suffix = isDefault ? ', likely generated/vendored' : '';

package/dist/core/ingestion/pipeline-phases/scan.js

@@ -19,20 +19,32 @@ export const scanPhase = {
             percent: 0,
             message: 'Scanning repository...',
         });
-        const scannedFiles = await walkRepositoryPaths(ctx.repoPath, (current, total, filePath) => {
-            const scanProgress = Math.round((current / total) * 15);
-            ctx.onProgress({
-                phase: 'extracting',
-                percent: scanProgress,
-                message: 'Scanning repository...',
-                detail: filePath,
-                stats: {
-                    filesProcessed: current,
-                    totalFiles: total,
-                    nodesCreated: ctx.graph.nodeCount,
-                },
+        let scannedFiles;
+        try {
+            scannedFiles = await walkRepositoryPaths(ctx.repoPath, (current, total, filePath) => {
+                const scanProgress = Math.round((current / total) * 15);
+                ctx.onProgress({
+                    phase: 'extracting',
+                    percent: scanProgress,
+                    message: 'Scanning repository...',
+                    detail: filePath,
+                    stats: {
+                        filesProcessed: current,
+                        totalFiles: total,
+                        nodesCreated: ctx.graph.nodeCount,
+                    },
+                });
             });
-        });
+        }
+        catch (err) {
+            // Missing roots throw so status cannot treat an empty glob as "every
+            // covered file was deleted". The pipeline still reports an empty scan
+            // for a path that is not a directory, matching analyze of a bad cwd.
+            if (err instanceof Error && err.message.startsWith('walkRepositoryPaths:')) {
+                return { scannedFiles: [], allPaths: [], totalFiles: 0 };
+            }
+            throw err;
+        }
         const totalFiles = scannedFiles.length;
         const allPaths = scannedFiles.map((f) => f.path);
         ctx.onProgress({

package/dist/core/run-analyze.js

@@ -45,7 +45,9 @@ import { shadowCandidatesFor } from './incremental/shadow-candidates.js';
 import { shouldEscalateIncrementalWrite } from './incremental/escalation-gate.js';
 import { loadParseCache, saveParseCache, pruneCache, PARSE_CACHE_VERSION, } from '../storage/parse-cache.js';
 import { getDurableParsedFileDir, pruneAndSaveDurableParsedFileStore, } from '../storage/parsedfile-store.js';
-import { getCurrentCommit, getCurrentBranch, getRemoteUrl, hasGitDir, getInferredRepoName, isWorkingTreeDirty, resolveRepoIdentityRoot, } from '../storage/git.js';
+import { getCurrentCommit, getCurrentBranch, getRemoteUrl, hasGitDir, getInferredRepoName, isWorkingTreeDirty, listWorkingTreeDirtyPaths, resolveRepoIdentityRoot, } from '../storage/git.js';
+import { isGitNexusManagedPath } from '../storage/gitnexus-managed-paths.js';
+import { getMaxFileSizeBytes } from './ingestion/utils/max-file-size.js';
 import { generateAIContextFiles } from '../cli/ai-context.js';
 import { sanitizeDetectedBranch } from '../cli/analyze-config.js';
 import { EMBEDDING_TABLE_NAME, EMBEDDING_DIMS, STALE_HASH_SENTINEL, SCHEMA_FINGERPRINT, schemaFingerprintMismatch, isSchemaFingerprintShaped, embeddingDimsMismatch, } from './lbug/schema.js';
@@ -2878,6 +2880,12 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, r
             // absence has exactly one meaning — an index older than the field.
             embeddingDims: EMBEDDING_DIMS,
             fileHashes: hasGitDir(repoPath) ? newFileHashesRecord : undefined,
+            indexCoverage: hasGitDir(repoPath)
+                ? {
+                    maxFileSizeBytes: getMaxFileSizeBytes(),
+                    dirtyPaths: (listWorkingTreeDirtyPaths(repoPath) ?? Object.keys(newFileHashesRecord)).filter((rel) => newFileHashesRecord[rel] !== undefined && !isGitNexusManagedPath(rel)),
+                }
+                : undefined,
             // This branch's full live chunk-key set (#2106 R6). `usedKeys` is every
             // chunk hash touched in this scan — cache HITS included (see parse-impl
             // usedKeys.add) — so it's complete even on an incremental run. Persisted

package/dist/mcp/local/local-backend.d.ts

@@ -371,10 +371,26 @@ export declare class LocalBackend {
      * - If only 1 repo, use it
      * - If 0 or multiple without param, throw with helpful message
      *
-     * On a miss, re-reads the registry once in case a new repo was indexed
-     * while the MCP server was running.
+     * Re-reads the registry before an omitted implicit target or after an
+     * explicit miss, so long-running servers see newly indexed repositories.
      */
     resolveRepo(repoParam?: string, branch?: string): Promise<RepoHandle>;
+    /**
+     * Internal resolver variant for CLI/MCP tool routing and discovery.
+     * - If repoParam is given, match by name or path
+     * - If only 1 repo, use it
+     * - If multiple repos exist and repoParam is omitted, callers may opt in to
+     *   the registered repo containing process.cwd()
+     * - If 0 repos exist, or cwd cannot disambiguate multiple repos, throw
+     *
+     * Omitted-repo resolution re-reads the registry before accepting any
+     * implicit target, including a cached singleton. A caller that just obtained
+     * a fresh registry snapshot may disable that refresh explicitly.
+     */
+    selectToolRepository(repoParam?: string, branch?: string, options?: {
+        allowCwdDefault?: boolean;
+        refreshRegistry?: boolean;
+    }): Promise<RepoHandle>;
     /**
      * Re-point a resolved repo handle at a specific branch index (#2106).
      *
@@ -409,12 +425,13 @@ export declare class LocalBackend {
      */
     private resolveRepoFromCache;
     /**
-     * Prefer the indexed repo whose path matches the git root of process.cwd().
+     * Match process.cwd() against indexed repositories.
      *
-     * In MCP stdio server mode, `process.cwd()` is the server's launch directory,
-     * not the agent client's cwd. If the server was started from an unrelated
-     * directory, `getGitRoot` returns null and duplicate-name resolution throws
-     * {@link RegistryAmbiguousTargetError} — callers should pass an absolute path.
+     * Explicit duplicate aliases use exact Git-root matching only. Omitted
+     * read-only calls opt into deepest containing-path selection. In that mode a
+     * candidate must not sit above cwd's Git root, so an unindexed nested checkout
+     * cannot fall through to an indexed ancestor. The `.git` ancestor fallback
+     * preserves that boundary when the git executable is unavailable.
      */
     private pickRepoHandleForCwd;
     private handleToRegistryEntry;