gitnexus 1.6.11-rc.7 → 1.6.11-rc.8

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/storage/file-hash.d.ts

@@ -27,6 +27,11 @@ export declare const computeFileHash: (absPath: string) => Promise<string | null
  * fail to read are omitted from the result map.
  */
 export declare const computeFileHashes: (repoPath: string, relPaths: readonly string[]) => Promise<Map<string, string>>;
+/** Like {@link computeFileHashes}, but keeps paths whose content could not be read. */
+export declare const computeFileHashesDetailed: (repoPath: string, relPaths: readonly string[]) => Promise<{
+    hashes: Map<string, string>;
+    unreadable: string[];
+}>;
 /** Result of comparing the current on-disk hashes against stored ones. */
 export interface FileHashDiff {
     /** Files whose content hash differs from stored. */

package/dist/storage/file-hash.js

@@ -39,18 +39,28 @@ export const computeFileHash = async (absPath) => {
  * fail to read are omitted from the result map.
  */
 export const computeFileHashes = async (repoPath, relPaths) => {
-    const out = new Map();
+    const { hashes } = await computeFileHashesDetailed(repoPath, relPaths);
+    return hashes;
+};
+/** Like {@link computeFileHashes}, but keeps paths whose content could not be read. */
+export const computeFileHashesDetailed = async (repoPath, relPaths) => {
+    const hashes = new Map();
+    const unreadable = [];
     const BATCH = 100;
     for (const batch of chunk(relPaths, BATCH)) {
         const results = await Promise.all(batch.map(async (rel) => {
             const h = await computeFileHash(path.join(repoPath, rel));
-            return h ? [rel, h] : null;
+            return { rel, h };
         }));
-        for (const r of results)
-            if (r)
-                out.set(r[0], r[1]);
+        for (const { rel, h } of results) {
+            if (h)
+                hashes.set(rel, h);
+            else
+                unreadable.push(rel);
+        }
     }
-    return out;
+    unreadable.sort();
+    return { hashes, unreadable };
 };
 /**
  * Diff a current hash map against a previously stored one.

package/dist/storage/git.d.ts

@@ -1,15 +1,26 @@
 /**
  * True when the working tree has uncommitted changes that analyze would
- * re-index, even at a matching HEAD. Excludes the paths GitNexus writes during
- * analyze (.gitnexus/, .claude/, .cursor/, AGENTS.md, CLAUDE.md, and the
- * repo-local .agents/ mirror) so its own output never counts as dirty
- * (regression vs PR #1233 behavior). The entire .agents/ tree is excluded,
- * matching the .claude/ treatment, because the skill mirror writes across
- * .agents/skills/ and deeper paths. Conservative on any git failure. Shared
- * so `analyze`'s fast-path gate and `status`'s freshness report agree on what
- * "dirty" means.
+ * re-index, even at a matching HEAD. Excludes GITNEXUS_MANAGED_PATHS so
+ * GitNexus's own analyze output never counts as dirty (regression vs PR #1233
+ * behavior); whole directory trees are excluded, not just their root entries,
+ * because the skill mirror writes across .agents/skills/ and deeper paths.
+ * Conservative on any git failure.
+ *
+ * This drives `analyze`'s up-to-date fast path. It is deliberately coarse:
+ * a false "dirty" here costs only a hash diff that finds nothing. `status`
+ * reaches for the per-file comparison in core/index-content-drift.ts instead,
+ * because there the same false positive is a verdict the user cannot clear
+ * (#3077), and falls back to this only when that comparison cannot run.
  */
 export declare const isWorkingTreeDirty: (repoPath: string) => boolean;
+/**
+ * Repo-relative paths `git status` reports as dirty or untracked, using the
+ * same managed-path excludes as {@link isWorkingTreeDirty}, plus tracked paths
+ * whose assume-unchanged or skip-worktree bits can hide content changes from
+ * porcelain. `null` means either query failed — callers must not treat that as
+ * a clean tree.
+ */
+export declare const listWorkingTreeDirtyPaths: (repoPath: string) => string[] | null;
 /**
  * Snapshot, per candidate file, whether it is safe for `selfCommitContextFiles`
  * to auto-commit — call this BEFORE `analyze` writes AGENTS.md/CLAUDE.md.

package/dist/storage/git.js

@@ -4,37 +4,27 @@ import path from 'path';
 import os from 'os';
 import { logger } from '../core/logger.js';
 import { toZeroBasedLine } from '../core/ingestion/utils/line-base.js';
+import { GITNEXUS_MANAGED_PATH_EXCLUDES, isGitNexusManagedPath } from './gitnexus-managed-paths.js';
 // Git utilities for repository detection, commit tracking, and diff analysis
 const chompGitOutput = (value) => value.toString().replace(/\r?\n$/, '');
+const GIT_PATH_LIST_MAX_BUFFER = 64 * 1024 * 1024;
 /**
  * True when the working tree has uncommitted changes that analyze would
- * re-index, even at a matching HEAD. Excludes the paths GitNexus writes during
- * analyze (.gitnexus/, .claude/, .cursor/, AGENTS.md, CLAUDE.md, and the
- * repo-local .agents/ mirror) so its own output never counts as dirty
- * (regression vs PR #1233 behavior). The entire .agents/ tree is excluded,
- * matching the .claude/ treatment, because the skill mirror writes across
- * .agents/skills/ and deeper paths. Conservative on any git failure. Shared
- * so `analyze`'s fast-path gate and `status`'s freshness report agree on what
- * "dirty" means.
+ * re-index, even at a matching HEAD. Excludes GITNEXUS_MANAGED_PATHS so
+ * GitNexus's own analyze output never counts as dirty (regression vs PR #1233
+ * behavior); whole directory trees are excluded, not just their root entries,
+ * because the skill mirror writes across .agents/skills/ and deeper paths.
+ * Conservative on any git failure.
+ *
+ * This drives `analyze`'s up-to-date fast path. It is deliberately coarse:
+ * a false "dirty" here costs only a hash diff that finds nothing. `status`
+ * reaches for the per-file comparison in core/index-content-drift.ts instead,
+ * because there the same false positive is a verdict the user cannot clear
+ * (#3077), and falls back to this only when that comparison cannot run.
  */
 export const isWorkingTreeDirty = (repoPath) => {
     try {
-        const out = execFileSync('git', [
-            'status',
-            '--porcelain',
-            '--',
-            '.',
-            ':(exclude).gitnexus',
-            ':(exclude).gitnexus/**',
-            ':(exclude).claude',
-            ':(exclude).claude/**',
-            ':(exclude).cursor',
-            ':(exclude).cursor/**',
-            ':(exclude)AGENTS.md',
-            ':(exclude)CLAUDE.md',
-            ':(exclude).agents',
-            ':(exclude).agents/**',
-        ], {
+        const out = execFileSync('git', ['status', '--porcelain', '--', '.', ...GITNEXUS_MANAGED_PATH_EXCLUDES], {
             cwd: repoPath,
             stdio: ['ignore', 'pipe', 'ignore'],
             windowsHide: true,
@@ -46,6 +36,75 @@ export const isWorkingTreeDirty = (repoPath) => {
         return true; // conservative on git failure
     }
 };
+const parsePorcelainPaths = (porcelain) => {
+    const paths = new Set();
+    const records = porcelain.split('\0');
+    for (let i = 0; i < records.length; i++) {
+        const record = records[i];
+        if (record.length < 4)
+            continue;
+        const status = record.slice(0, 2);
+        paths.add(record.slice(3));
+        // In porcelain v1 `-z` mode, rename/copy source and destination paths are
+        // separate NUL records (with no human-facing ` -> ` delimiter). Keep both:
+        // either side may be present in the previous coverage set.
+        if (status.includes('R') || status.includes('C')) {
+            const pairedPath = records[++i];
+            if (pairedPath)
+                paths.add(pairedPath);
+        }
+    }
+    return [...paths];
+};
+const gitPathListExec = {
+    stdio: ['ignore', 'pipe', 'ignore'],
+    encoding: 'utf8',
+    maxBuffer: GIT_PATH_LIST_MAX_BUFFER,
+};
+const listHiddenIndexPaths = (repoPath) => {
+    const out = execFileSync('git', ['ls-files', '-v', '-z', '--'], {
+        cwd: repoPath,
+        windowsHide: true,
+        ...gitPathListExec,
+    });
+    const paths = [];
+    for (const record of out.split('\0')) {
+        if (record.length < 3 || record[1] !== ' ')
+            continue;
+        const tag = record[0];
+        // `S` marks skip-worktree. With `-v`, an assume-unchanged entry's
+        // ordinary tag is lower-cased (`H` -> `h`, `S` -> `s`, etc.).
+        if (tag === 'S' || (tag >= 'a' && tag <= 'z'))
+            paths.push(record.slice(2));
+    }
+    return paths;
+};
+/**
+ * Repo-relative paths `git status` reports as dirty or untracked, using the
+ * same managed-path excludes as {@link isWorkingTreeDirty}, plus tracked paths
+ * whose assume-unchanged or skip-worktree bits can hide content changes from
+ * porcelain. `null` means either query failed — callers must not treat that as
+ * a clean tree.
+ */
+export const listWorkingTreeDirtyPaths = (repoPath) => {
+    try {
+        const out = execFileSync('git', [
+            'status',
+            '--porcelain=v1',
+            '-z',
+            '--untracked-files=all',
+            '--',
+            '.',
+            ...GITNEXUS_MANAGED_PATH_EXCLUDES,
+        ], { cwd: repoPath, windowsHide: true, ...gitPathListExec });
+        return [
+            ...new Set([...parsePorcelainPaths(out), ...listHiddenIndexPaths(repoPath)].filter((rel) => !isGitNexusManagedPath(rel))),
+        ];
+    }
+    catch {
+        return null;
+    }
+};
 /**
  * Snapshot, per candidate file, whether it is safe for `selfCommitContextFiles`
  * to auto-commit — call this BEFORE `analyze` writes AGENTS.md/CLAUDE.md.

package/dist/storage/gitnexus-managed-paths.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The paths GitNexus itself writes during `analyze`.
+ *
+ * `analyze` rewrites the stats blocks in AGENTS.md/CLAUDE.md and refreshes the
+ * agent skill mirrors as its final step — after it has recorded the per-file
+ * hashes for the run. Counting its own output as a repository change makes
+ * every completed run look immediately out of date, which is the regression
+ * PR #1233 introduced and #1233's fix excluded these paths to prevent.
+ *
+ * Two freshness checks depend on this list agreeing: `isWorkingTreeDirty`
+ * (analyze's up-to-date fast-path gate) and the per-file comparison behind
+ * `status`. They used to hold separate copies of it, so a path added to one
+ * silently became a permanent "stale" verdict in the other. One list, imported
+ * by both.
+ */
+/**
+ * Repository-root-relative. A directory entry covers everything beneath it;
+ * a file entry matches only itself. Prefix collisions are NOT matches —
+ * `.agentsrc` is an ordinary file, not part of the `.agents` tree.
+ */
+export declare const GITNEXUS_MANAGED_PATHS: readonly [".gitnexus", ".claude", ".cursor", ".agents", "AGENTS.md", "CLAUDE.md"];
+/**
+ * Git pathspecs excluding {@link GITNEXUS_MANAGED_PATHS} from a `git status`
+ * run rooted at the repository. Patterns include `./` so they match only at
+ * the repo root: a slash-free `:(exclude)AGENTS.md` would also drop
+ * `docs/AGENTS.md`, which {@link isGitNexusManagedPath} does not treat as
+ * managed. Both forms are emitted per entry: the root path itself, and `/**`
+ * for directory contents.
+ */
+export declare const GITNEXUS_MANAGED_PATH_EXCLUDES: readonly string[];
+/**
+ * True when a repository-relative path is GitNexus's own output. Mirrors the
+ * pathspec semantics above: root-relative, whole path segments only, so
+ * neither `.agentsrc` nor a nested `subdir/.agents/` is treated as managed.
+ */
+export declare const isGitNexusManagedPath: (relPath: string) => boolean;

package/dist/storage/gitnexus-managed-paths.js

@@ -0,0 +1,46 @@
+/**
+ * The paths GitNexus itself writes during `analyze`.
+ *
+ * `analyze` rewrites the stats blocks in AGENTS.md/CLAUDE.md and refreshes the
+ * agent skill mirrors as its final step — after it has recorded the per-file
+ * hashes for the run. Counting its own output as a repository change makes
+ * every completed run look immediately out of date, which is the regression
+ * PR #1233 introduced and #1233's fix excluded these paths to prevent.
+ *
+ * Two freshness checks depend on this list agreeing: `isWorkingTreeDirty`
+ * (analyze's up-to-date fast-path gate) and the per-file comparison behind
+ * `status`. They used to hold separate copies of it, so a path added to one
+ * silently became a permanent "stale" verdict in the other. One list, imported
+ * by both.
+ */
+/**
+ * Repository-root-relative. A directory entry covers everything beneath it;
+ * a file entry matches only itself. Prefix collisions are NOT matches —
+ * `.agentsrc` is an ordinary file, not part of the `.agents` tree.
+ */
+export const GITNEXUS_MANAGED_PATHS = [
+    '.gitnexus',
+    '.claude',
+    '.cursor',
+    '.agents',
+    'AGENTS.md',
+    'CLAUDE.md',
+];
+/**
+ * Git pathspecs excluding {@link GITNEXUS_MANAGED_PATHS} from a `git status`
+ * run rooted at the repository. Patterns include `./` so they match only at
+ * the repo root: a slash-free `:(exclude)AGENTS.md` would also drop
+ * `docs/AGENTS.md`, which {@link isGitNexusManagedPath} does not treat as
+ * managed. Both forms are emitted per entry: the root path itself, and `/**`
+ * for directory contents.
+ */
+export const GITNEXUS_MANAGED_PATH_EXCLUDES = GITNEXUS_MANAGED_PATHS.flatMap((managed) => [`:(exclude,glob)./${managed}`, `:(exclude,glob)./${managed}/**`]);
+/**
+ * True when a repository-relative path is GitNexus's own output. Mirrors the
+ * pathspec semantics above: root-relative, whole path segments only, so
+ * neither `.agentsrc` nor a nested `subdir/.agents/` is treated as managed.
+ */
+export const isGitNexusManagedPath = (relPath) => {
+    const normalized = relPath.replace(/\\/g, '/');
+    return GITNEXUS_MANAGED_PATHS.some((managed) => normalized === managed || normalized.startsWith(`${managed}/`));
+};

package/dist/storage/repo-meta.d.ts

@@ -279,6 +279,18 @@ export interface RepoMeta {
      * Map keys are repo-relative paths.
      */
     fileHashes?: Record<string, string>;
+    /**
+     * Coverage policy used when `fileHashes` was recorded. `status` replays it
+     * so analyze-time `--max-file-size` / `GITNEXUS_MAX_FILE_SIZE` cannot make
+     * a later default-cap walk drop a file the index actually covers.
+     * `dirtyPaths` are covered files that were dirty vs HEAD at that moment —
+     * status must re-hash those even after Git becomes clean (indexed-dirty then
+     * restore). Absent on indexes written before this field.
+     */
+    indexCoverage?: {
+        maxFileSizeBytes: number;
+        dirtyPaths?: string[];
+    };
     /**
      * Set when a run finished but the persisted edge count came back far short
      * of what the pipeline produced — the B2 "refresh reports SUCCESS while the

package/package.json

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