gitnexus 1.6.8-rc.2 → 1.6.8-rc.21

package/dist/core/run-analyze.d.ts

@@ -8,6 +8,7 @@
  * IMPORTANT: This module must NEVER call process.exit(). The caller (CLI
  * wrapper or server worker) is responsible for process lifecycle.
  */
+import { type RepoMeta } from '../storage/repo-manager.js';
 export interface AnalyzeCallbacks {
     onProgress: (phase: string, percent: number, message: string) => void;
     onLog?: (message: string) => void;
@@ -48,6 +49,29 @@ export interface AnalyzeOptions {
     noStats?: boolean;
     /** Skip installing standard GitNexus skill files to .claude/skills/gitnexus/. */
     skipSkills?: boolean;
+    /**
+     * Build the CFG/PDG substrate (#2081 M1). Forwarded to `PipelineOptions.pdg`,
+     * which threads to BOTH the worker (CFG build, via workerData) AND
+     * scope-resolution (BasicBlock/CFG emit gate). Off by default.
+     */
+    pdg?: boolean;
+    /** Per-function source-line cap for worker-side CFG construction (#2081 M1).
+     *  Forwarded to `PipelineOptions.pdgMaxFunctionLines`. No CLI flag in M1 —
+     *  programmatic / server analyze-worker path only; the worker applies
+     *  `DEFAULT_PDG_MAX_FUNCTION_LINES` when unset. */
+    pdgMaxFunctionLines?: number;
+    /** Per-function CFG edge cap. Forwarded to `PipelineOptions.pdgMaxEdgesPerFunction`. */
+    pdgMaxEdgesPerFunction?: number;
+    /** Per-function REACHING_DEF edge cap (#2082 M2). Forwarded to
+     *  `PipelineOptions.pdgMaxReachingDefEdgesPerFunction`. */
+    pdgMaxReachingDefEdgesPerFunction?: number;
+    /** Per-function taint findings cap (#2083 M3). Forwarded to
+     *  `PipelineOptions.pdgMaxTaintFindingsPerFunction`. No CLI flag or rc key
+     *  (KTD8) — programmatic / server path only, like the other pdg caps. */
+    pdgMaxTaintFindingsPerFunction?: number;
+    /** Per-finding taint hop cap (#2083 M3, KTD6). Forwarded to
+     *  `PipelineOptions.pdgMaxTaintHops`. No CLI flag or rc key (KTD8). */
+    pdgMaxTaintHops?: number;
     /**
      * Default branch threaded into generated AGENTS.md / CLAUDE.md so the
      * regression-compare example uses the configured branch instead of a
@@ -55,6 +79,16 @@ export interface AnalyzeOptions {
      * "main" fallback for non-CLI callers (e.g. the server analyze worker).
      */
     defaultBranch?: string;
+    /**
+     * Index-branch selector (#2106). Distinct from `defaultBranch` (which only
+     * affects generated AGENTS.md/CLAUDE.md base_ref text). When set, this run is
+     * labelled as that branch and routed to a per-branch index slot unless it is
+     * the primary branch. When `undefined`, the branch is auto-detected from the
+     * checked-out HEAD (the flat/primary slot for the first-indexed branch, a
+     * `branches/<slug>/` sub-directory otherwise). Detached HEAD / non-git always
+     * maps to the flat slot.
+     */
+    branch?: string;
     /**
      * User-provided alias for the registry `name` (#829). When set,
      * forwarded to `registerRepo` so the indexed repo is stored under
@@ -78,6 +112,13 @@ export interface AnalyzeOptions {
      * removed); `undefined` defers to the env / auto-formula fallback.
      */
     workerPoolSize?: number;
+    /**
+     * Extra fetch-wrapper function names to treat as HTTP consumers, forwarded to
+     * `PipelineOptions.fetchWrappers` (#1589/#1852 residual). Sourced from the CLI
+     * `.gitnexusrc` `fetchWrappers` list. `undefined`/empty leaves the route
+     * consumer scan unchanged.
+     */
+    fetchWrappers?: string[];
 }
 export interface AnalyzeResult {
     repoName: string;
@@ -102,6 +143,13 @@ export interface AnalyzeResult {
      * the persisted meta surface the degraded state instead of reporting healthy.
      */
     ftsSkipped?: boolean;
+    /**
+     * True when the index this run produced/validated is the primary/flat slot
+     * (#2106 R2). `false` for a non-primary branch index. Lets the CLI skip
+     * repo-root AGENTS.md/CLAUDE.md refreshes (e.g. the base_ref fast-path) for a
+     * branch analyze, mirroring the in-pipeline `if (!placement.branch)` gate.
+     */
+    isPrimaryBranch?: boolean;
 }
 export { deriveEmbeddingMode, DEFAULT_EMBEDDING_NODE_LIMIT } from './embedding-mode.js';
 export type { EmbeddingMode } from './embedding-mode.js';
@@ -117,4 +165,43 @@ export declare const PHASE_LABELS: Record<string, string>;
  * the {@link AnalyzeCallbacks} interface — it never writes to stdout/stderr
  * directly and never calls `process.exit()`.
  */
+/**
+ * Build the primary-inversion warning (#2106 R8), or `undefined` when there is
+ * nothing to warn about. Pure + exported for testing. Both inputs are trimmed
+ * (a diagnostic — a missed warning is low-harm; a false warning is the thing to
+ * avoid). `defaultBranch` is the repo's `origin/HEAD` branch (null when unset,
+ * e.g. fresh clones / CI), `flatOwner` is the branch that owns the flat slot.
+ */
+export declare const primaryInversionWarning: (defaultBranch: string | null | undefined, flatOwner: string | null | undefined) => string | undefined;
+/**
+ * Collect the recorded parse-cache chunk keys across the flat + every branch
+ * meta under a flat `.gitnexus` storage, EXCLUDING `excludeDir` (the current
+ * run's own meta dir) so a single-branch repo collects nothing and its prune
+ * stays byte-identical to today (#2106 R6). `complete` is false when a sibling
+ * meta.json exists but fails to parse — callers then retain the whole shared
+ * cache rather than over-evict another branch's still-live shards. Exported for
+ * testing.
+ */
+export declare const collectBranchCacheKeys: (storagePath: string, excludeDir?: string) => Promise<{
+    keys: Set<string>;
+    complete: boolean;
+}>;
+/**
+ * Resolve the requested `--pdg` configuration to the shape recorded in
+ * `RepoMeta.pdg`, or `undefined` for a pdg-off run. Caps resolve to their
+ * defaults so an explicit-default run compares equal to a default run
+ * (`0` = unlimited is preserved as `0`). Pure + exported for testing.
+ */
+type PdgOptions = Pick<AnalyzeOptions, 'pdg' | 'pdgMaxFunctionLines' | 'pdgMaxEdgesPerFunction' | 'pdgMaxReachingDefEdgesPerFunction' | 'pdgMaxTaintFindingsPerFunction' | 'pdgMaxTaintHops'>;
+export declare const resolvePdgConfig: (options: PdgOptions) => RepoMeta["pdg"];
+/**
+ * Whether the requested `--pdg` configuration differs from the one the
+ * existing index's DB rows were built under (#2099 F1). An absent recorded
+ * stamp means pdg-off (every legacy meta — `--pdg` shipped opt-in). Any
+ * mismatch means the incremental writeback (which only persists changed-file
+ * nodes) cannot produce a coherent index: off→on would silently drop the
+ * freshly built CFG layer, on→off would strand zombie BasicBlocks — so the
+ * caller forces a full writeback. Pure + exported for testing.
+ */
+export declare const pdgModeMismatch: (recorded: RepoMeta["pdg"], options: PdgOptions) => boolean;
 export declare function runFullAnalysis(repoPath: string, options: AnalyzeOptions, callbacks: AnalyzeCallbacks): Promise<AnalyzeResult>;

package/dist/core/run-analyze.js

@@ -17,14 +17,19 @@ import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReuse
 import { createSearchFTSIndexes, verifySearchFTSIndexes } from './search/fts-indexes.js';
 import { resolveAnalyzeInstallPolicy } from './lbug/extension-loader.js';
 import { startWalCheckpointDriver, } from './lbug/wal-checkpoint-driver.js';
-import { getStoragePaths, saveMeta, loadMeta, ensureGitNexusIgnored, registerRepo, cleanupOldKuzuFiles, INCREMENTAL_SCHEMA_VERSION, } from '../storage/repo-manager.js';
+import { getStoragePaths, resolveBranchPlacement, saveMeta, loadMeta, ensureGitNexusIgnored, registerRepo, cleanupOldKuzuFiles, INCREMENTAL_SCHEMA_VERSION, } from '../storage/repo-manager.js';
+import { DEFAULT_PDG_MAX_FUNCTION_LINES } from './ingestion/cfg/collect.js';
+import { DEFAULT_MAX_CFG_EDGES_PER_FUNCTION, DEFAULT_PDG_MAX_REACHING_DEF_EDGES_PER_FUNCTION, } from './ingestion/cfg/emit.js';
+import { DEFAULT_PDG_MAX_TAINT_FINDINGS_PER_FUNCTION, DEFAULT_PDG_MAX_TAINT_HOPS, } from './ingestion/taint/propagate.js';
+import { taintModelVersion } from './ingestion/taint/typescript-model.js';
 import { computeFileHashes, diffFileHashes } from '../storage/file-hash.js';
 import { extractChangedSubgraph, computeEffectiveWriteSet, } from './incremental/subgraph-extract.js';
 import { shadowCandidatesFor } from './incremental/shadow-candidates.js';
 import { loadParseCache, saveParseCache, pruneCache, PARSE_CACHE_VERSION, } from '../storage/parse-cache.js';
 import { getDurableParsedFileDir, pruneAndSaveDurableParsedFileStore, } from '../storage/parsedfile-store.js';
-import { getCurrentCommit, getRemoteUrl, hasGitDir, getInferredRepoName, resolveRepoIdentityRoot, } from '../storage/git.js';
+import { getCurrentCommit, getCurrentBranch, getDefaultBranch, getRemoteUrl, hasGitDir, getInferredRepoName, resolveRepoIdentityRoot, } from '../storage/git.js';
 import { generateAIContextFiles } from '../cli/ai-context.js';
+import { sanitizeDetectedBranch } from '../cli/analyze-config.js';
 import { EMBEDDING_TABLE_NAME } from './lbug/schema.js';
 import { STALE_HASH_SENTINEL } from './lbug/schema.js';
 /**
@@ -70,6 +75,112 @@ export const PHASE_LABELS = {
  * the {@link AnalyzeCallbacks} interface — it never writes to stdout/stderr
  * directly and never calls `process.exit()`.
  */
+/**
+ * Build the primary-inversion warning (#2106 R8), or `undefined` when there is
+ * nothing to warn about. Pure + exported for testing. Both inputs are trimmed
+ * (a diagnostic — a missed warning is low-harm; a false warning is the thing to
+ * avoid). `defaultBranch` is the repo's `origin/HEAD` branch (null when unset,
+ * e.g. fresh clones / CI), `flatOwner` is the branch that owns the flat slot.
+ */
+export const primaryInversionWarning = (defaultBranch, flatOwner) => {
+    const norm = (s) => s?.trim() || undefined;
+    const d = norm(defaultBranch);
+    const o = norm(flatOwner);
+    if (!d || !o || d === o)
+        return undefined;
+    return (`Warning: the default branch "${d}" is not the primary index — "${o}" owns the flat slot. ` +
+        `Run \`gitnexus clean --branch ${o}\` then re-index on "${d}", or query it explicitly with \`--branch ${d}\`.`);
+};
+/**
+ * Collect the recorded parse-cache chunk keys across the flat + every branch
+ * meta under a flat `.gitnexus` storage, EXCLUDING `excludeDir` (the current
+ * run's own meta dir) so a single-branch repo collects nothing and its prune
+ * stays byte-identical to today (#2106 R6). `complete` is false when a sibling
+ * meta.json exists but fails to parse — callers then retain the whole shared
+ * cache rather than over-evict another branch's still-live shards. Exported for
+ * testing.
+ */
+export const collectBranchCacheKeys = async (storagePath, excludeDir) => {
+    const keys = new Set();
+    let complete = true;
+    const metaDirs = [storagePath];
+    const branchesDir = path.join(storagePath, 'branches');
+    const slugs = await fs.readdir(branchesDir).catch(() => []);
+    for (const slug of slugs)
+        metaDirs.push(path.join(branchesDir, slug));
+    for (const dir of metaDirs) {
+        if (excludeDir && path.resolve(dir) === path.resolve(excludeDir))
+            continue;
+        let raw;
+        try {
+            raw = await fs.readFile(path.join(dir, 'meta.json'), 'utf-8');
+        }
+        catch {
+            continue; // no meta here — not a branch index, not a failure
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed.cacheKeys)) {
+                for (const k of parsed.cacheKeys)
+                    if (typeof k === 'string')
+                        keys.add(k);
+            }
+        }
+        catch {
+            complete = false; // present but corrupt → fail-safe toward retention
+        }
+    }
+    return { keys, complete };
+};
+export const resolvePdgConfig = (options) => options.pdg === true
+    ? {
+        maxFunctionLines: options.pdgMaxFunctionLines ?? DEFAULT_PDG_MAX_FUNCTION_LINES,
+        maxEdgesPerFunction: options.pdgMaxEdgesPerFunction ?? DEFAULT_MAX_CFG_EDGES_PER_FUNCTION,
+        maxReachingDefEdgesPerFunction: options.pdgMaxReachingDefEdgesPerFunction ??
+            DEFAULT_PDG_MAX_REACHING_DEF_EDGES_PER_FUNCTION,
+        // #2083 M3: taint caps + model identity. The key-union comparator in
+        // pdgModeMismatch picks these up structurally — an M2-era stamp lacks
+        // all three, so the first M3 run over an M2 `--pdg` index trips a full
+        // writeback that populates TAINTED/SANITIZES rows without `--force`.
+        maxTaintFindingsPerFunction: options.pdgMaxTaintFindingsPerFunction ?? DEFAULT_PDG_MAX_TAINT_FINDINGS_PER_FUNCTION,
+        maxTaintHops: options.pdgMaxTaintHops ?? DEFAULT_PDG_MAX_TAINT_HOPS,
+        // Built-in model digest (KTD7/R7): persisted findings must never
+        // outlive the model that produced them — ANY model-content change
+        // ships as a new digest and repopulates the taint edges.
+        taintModelVersion,
+    }
+    : undefined;
+/**
+ * Whether the requested `--pdg` configuration differs from the one the
+ * existing index's DB rows were built under (#2099 F1). An absent recorded
+ * stamp means pdg-off (every legacy meta — `--pdg` shipped opt-in). Any
+ * mismatch means the incremental writeback (which only persists changed-file
+ * nodes) cannot produce a coherent index: off→on would silently drop the
+ * freshly built CFG layer, on→off would strand zombie BasicBlocks — so the
+ * caller forces a full writeback. Pure + exported for testing.
+ */
+export const pdgModeMismatch = (recorded, options) => {
+    const requested = resolvePdgConfig(options);
+    if (!requested && !recorded)
+        return false;
+    if (!requested || !recorded)
+        return true;
+    // Structural comparison over the KEY UNION of both resolved records — not a
+    // hand-maintained field list. Both sides come fully resolved from
+    // resolvePdgConfig, so any new emit-affecting knob added there joins the
+    // comparison automatically (M1's hand-extended comparator was the trap this
+    // closes: a knob it missed would silently strand a stale projection). It is
+    // also what makes the M1→M2 upgrade work with zero extra code: an M1-era
+    // stamp lacks maxReachingDefEdgesPerFunction, so `4000 !== undefined` trips
+    // a full writeback that populates REACHING_DEF rows without `--force`.
+    const reqRecord = requested;
+    const recRecord = recorded;
+    for (const key of new Set([...Object.keys(reqRecord), ...Object.keys(recRecord)])) {
+        if (reqRecord[key] !== recRecord[key])
+            return true;
+    }
+    return false;
+};
 export async function runFullAnalysis(repoPath, options, callbacks) {
     const log = (msg) => callbacks.onLog?.(msg);
     const progress = (phase, percent, message) => callbacks.onProgress(phase, percent, message);
@@ -80,7 +191,10 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     // counter in its own module instance and is process-scoped, so no separate
     // worker-side reset is needed (see safe-parse.ts ParseTimeoutError contract).
     resetDegradedParseCounter();
-    const { storagePath, lbugPath } = getStoragePaths(repoPath);
+    // `storagePath` is ALWAYS the flat `.gitnexus` — content-addressed caches
+    // (parse-cache, parsedfile-store) and the kuzu-migration cleanup live there
+    // and are shared across branches (#2106 KTD7).
+    const { storagePath } = getStoragePaths(repoPath);
     // Clean up stale KuzuDB files from before the LadybugDB migration.
     const kuzuResult = await cleanupOldKuzuFiles(storagePath);
     if (kuzuResult.found && kuzuResult.needsReindex) {
@@ -88,7 +202,53 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     }
     const repoHasGit = hasGitDir(repoPath);
     const currentCommit = repoHasGit ? getCurrentCommit(repoPath) : '';
-    const existingMeta = await loadMeta(storagePath);
+    // ── #2106: resolve which branch slot this run writes to ───────────────
+    // `branchLabel` is the branch identity recorded in meta.json (incl. the
+    // primary). `placement.branch` is undefined for the flat/primary slot (the
+    // lbug/meta paths stay byte-identical to single-branch behavior) and set for
+    // a `branches/<slug>/` sub-directory. Explicit `--branch` is always honored;
+    // otherwise auto-detect the checked-out branch (null for detached HEAD /
+    // non-git → flat slot).
+    // Normalize the auto-detected branch the same way an explicit `--branch` is
+    // validated (#2106 R1): a git ref the branch-name rules forbid (backtick,
+    // `~ ^ : ? *`, leading `-`, `..`) becomes `null` → the flat slot, matching
+    // that a later `--branch <that-ref>` query would also be rejected. A normal
+    // ref passes through unchanged so index-time and query-time labels round-trip.
+    const checkedOutBranch = repoHasGit
+        ? (sanitizeDetectedBranch(getCurrentBranch(repoPath)) ?? null)
+        : null;
+    // Analyze indexes the working tree, not an arbitrary ref. An explicit
+    // `--branch X` while a DIFFERENT branch Y is checked out would write Y's
+    // content (and Y's commit) into X's index slot, corrupting X (#2106). Refuse
+    // the mismatch. Detached HEAD / non-git (checkedOutBranch === null) still
+    // allow an explicit label so CI checkouts can name their snapshot.
+    if (options.branch && checkedOutBranch && options.branch !== checkedOutBranch) {
+        throw new Error(`--branch "${options.branch}" does not match the checked-out branch "${checkedOutBranch}". ` +
+            `Check out "${options.branch}" before indexing it, or omit --branch to index the current branch.`);
+    }
+    const branchLabel = options.branch ?? checkedOutBranch;
+    const placement = await resolveBranchPlacement(repoPath, branchLabel);
+    const { lbugPath, metaPath } = getStoragePaths(repoPath, placement.branch);
+    // Directory that owns this run's meta.json (flat `.gitnexus` for the primary
+    // slot, `branches/<slug>/` otherwise). loadMeta/saveMeta operate on it so
+    // each branch keeps its own lastCommit / fileHashes / incremental dirty flag.
+    const metaDir = path.dirname(metaPath);
+    const existingMeta = await loadMeta(metaDir);
+    // ── #2106 (R8): warn when the repo's default branch is not the primary ──
+    // A non-default branch can own the flat slot (it was indexed first). That
+    // index is still fully queryable via `--branch`, so this is an ergonomics
+    // wart, not data loss — we only warn (no risky relocation of a live DB).
+    if (repoHasGit) {
+        // Who owns the flat slot after this run? For a flat/primary run it is this
+        // run's resolved label (carrying an existing stamp forward); for a branch
+        // run the flat owner is unchanged, so read the flat meta.
+        const flatOwner = placement.branch
+            ? (await loadMeta(storagePath))?.branch
+            : (branchLabel ?? existingMeta?.branch);
+        const warning = primaryInversionWarning(getDefaultBranch(repoPath), flatOwner);
+        if (warning)
+            log(warning);
+    }
     // ── FTS-only repair path ────────────────────────────────────────────
     if (options.repairFts) {
         if (!existingMeta) {
@@ -158,13 +318,37 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     // clear it, the on-disk index may be in a half-state. Cheapest path
     // back to a known-good index is to wipe + rebuild from scratch.
     if (existingMeta?.incrementalInProgress) {
-        log('Previous incremental run did not complete cleanly (incrementalInProgress flag set); ' +
+        log(
+        // "analyze run", not "incremental run" — since #2099 F1 the flag is a
+        // generic dirty marker written by BOTH writeback branches.
+        'Previous analyze run did not complete cleanly (incrementalInProgress flag set); ' +
             'forcing full rebuild to restore a known-good index.');
         options = { ...options, force: true };
         // Reload meta after clearing the flag in-memory; we still want fileHashes
         // for the post-rebuild meta carry-over, but force=true ensures the
         // rebuild path executes.
     }
+    // ── pdg-mode flip forces full writeback (#2099 F1) ─────────────────
+    // The incremental writeback persists only changed-file nodes, so a pdg
+    // config differing from the one the DB rows were built under cannot be
+    // reconciled incrementally: off→on silently drops the freshly built CFG
+    // layer ("Incremental: changed=0", zero BasicBlock rows), on→off strands
+    // zombie blocks for unchanged files. MUST sit before the alreadyUpToDate
+    // fast path below — a clean-tree flip would otherwise early-return without
+    // running the pipeline at all. The notice is deliberately NOT gated on
+    // options.force: --skills implies force with no message of its own, and a
+    // mode change deserves a diagnostic regardless of why a rebuild happens.
+    if (existingMeta && pdgModeMismatch(existingMeta.pdg, options)) {
+        const pdgOn = options.pdg === true;
+        const capsOnly = !!existingMeta.pdg && pdgOn; // both-on can only mismatch via caps
+        const was = existingMeta.pdg ? 'with --pdg' : 'without --pdg';
+        const now = pdgOn ? 'with --pdg' : 'without --pdg';
+        log(`pdg mode changed (index built ${was}, this run is ${now}` +
+            `${capsOnly ? ', but with different caps' : ''}); forcing a full ` +
+            `rebuild so the CFG layer is ${pdgOn ? 'fully persisted' : 'fully removed'}. ` +
+            `Tip: set \`pdg: ${pdgOn}\` in .gitnexusrc to pin the mode across runs.`);
+        options = { ...options, force: true };
+    }
     // ── Early-return: already up to date ──────────────────────────────
     if (existingMeta && !options.force && existingMeta.lastCommit === currentCommit) {
         // Non-git folders have currentCommit = '' — always rebuild since we can't detect changes
@@ -220,6 +404,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                     repoPath,
                     stats: existingMeta.stats ?? {},
                     alreadyUpToDate: true,
+                    isPrimaryBranch: !placement.branch,
                 };
             }
         }
@@ -308,6 +493,15 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     }, {
         parseCache,
         workerPoolSize: options.workerPoolSize,
+        // CFG/PDG opt-in (#2081 M1). PipelineOptions.pdg fans out to the worker
+        // build gate (workerData.pdg) and the scope-resolution emit gate.
+        pdg: options.pdg === true,
+        pdgMaxFunctionLines: options.pdgMaxFunctionLines,
+        pdgMaxEdgesPerFunction: options.pdgMaxEdgesPerFunction,
+        pdgMaxReachingDefEdgesPerFunction: options.pdgMaxReachingDefEdgesPerFunction,
+        pdgMaxTaintFindingsPerFunction: options.pdgMaxTaintFindingsPerFunction,
+        pdgMaxTaintHops: options.pdgMaxTaintHops,
+        fetchWrappers: options.fetchWrappers,
     });
     // ── Phase 2: LadybugDB (60–85%) ──────────────────────────────────
     progress('lbug', 60, 'Loading into LadybugDB...');
@@ -345,8 +539,8 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             `deleted=${hashDiff.deleted.length} ` +
             `(skipping wipe + ${allFilePaths.length - hashDiff.toWrite.length} unchanged file rows preserved)`);
         // Set the dirty flag BEFORE any destructive DB mutation. Cleared on
-        // success at the meta-save step.
-        await saveMeta(storagePath, {
+        // success at the meta-save step. Scoped to this branch's meta.json.
+        await saveMeta(metaDir, {
             ...existingMeta,
             incrementalInProgress: {
                 startedAt: Date.now(),
@@ -356,6 +550,19 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     }
     else {
         // Full rebuild path: wipe DB files first.
+        // Set the dirty flag BEFORE the wipe whenever a prior meta exists,
+        // mirroring the incremental branch above (#2099 F1, KTD2b). Without it a
+        // full rebuild crashing between the wipe and the end-of-run saveMeta
+        // leaves a meta that vouches for a DB it no longer matches — the next
+        // clean-tree run's fast path would certify a destroyed DB (or, after a
+        // pdg flip, certify zombie/missing BasicBlock rows indefinitely).
+        // toWriteCount: 0 is the full-path sentinel (no incremental write set).
+        if (existingMeta) {
+            await saveMeta(metaDir, {
+                ...existingMeta,
+                incrementalInProgress: { startedAt: Date.now(), toWriteCount: 0 },
+            });
+        }
         await closeLbug();
         const lbugFiles = [lbugPath, `${lbugPath}.wal`, `${lbugPath}.lock`];
         for (const f of lbugFiles) {
@@ -685,6 +892,14 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             repoPath,
             lastCommit: currentCommit,
             indexedAt: new Date().toISOString(),
+            // Branch identity this index represents (#2106). Recorded for the flat
+            // slot too (so resolveBranchPlacement knows which branch owns it). When
+            // the label is null (detached HEAD / non-git re-analyze) we PRESERVE an
+            // existing stamp rather than stripping it — otherwise a detached re-index
+            // of the primary (e.g. CI's `actions/checkout` default) would un-claim the
+            // flat slot and let the next branch analyze overwrite the primary index.
+            // Stays absent only when never stamped (fresh detached/non-git repo).
+            branch: branchLabel ?? existingMeta?.branch,
             // Captured here (not at registration) so it travels with the
             // on-disk meta.json — sibling-clone fingerprinting works for
             // out-of-tree consumers (group-status, future tooling) without
@@ -723,9 +938,20 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             // dirty flag (full and incremental success paths converge here).
             schemaVersion: hasGitDir(repoPath) ? INCREMENTAL_SCHEMA_VERSION : undefined,
             fileHashes: hasGitDir(repoPath) ? newFileHashesRecord : 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
+            // so a sibling branch's prune can union it and not evict our shards.
+            cacheKeys: [...parseCache.usedKeys],
             incrementalInProgress: undefined,
+            // The effective pdg config this run's DB rows were built under
+            // (#2099 F1). `undefined` on pdg-off runs — this meta is a fresh
+            // literal (no spread of existingMeta), so omission is what CLEARS the
+            // stamp after an on→off flip; the next pdgModeMismatch then compares
+            // off==off and incremental eligibility is restored.
+            pdg: resolvePdgConfig(options),
         };
-        await saveMeta(storagePath, meta);
+        await saveMeta(metaDir, meta);
         // Persist the incremental parse cache for the next run. Wraps in
         // try/catch so a cache-write failure never breaks an otherwise
         // successful indexing run. Prune stale chunk-hash entries first so
@@ -734,6 +960,25 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         // dead weight; the parse phase populates `usedKeys` as it processes
         // chunks).
         try {
+            // #2106 R6: the parse cache + durable store are shared across branches.
+            // Before pruning to this run's keys, fold in the OTHER branches' recorded
+            // chunk keys so a branch switch doesn't evict their still-live shards.
+            // Adding to usedKeys makes them survive pruneCache AND land in the saved
+            // index (saveParseCache builds the index from usedKeys). Excludes this
+            // run's own meta dir, so a single-branch repo folds in nothing → prune
+            // set byte-identical to today.
+            const { keys: siblingKeys, complete } = await collectBranchCacheKeys(storagePath, metaDir);
+            if (complete) {
+                for (const k of siblingKeys)
+                    parseCache.usedKeys.add(k);
+            }
+            else {
+                // Fail-safe toward retention: a sibling meta was unreadable, so keep
+                // everything currently loaded rather than evict on incomplete info.
+                log('Parse cache: a branch meta was unreadable — retaining all cached chunks (#2106).');
+                for (const k of parseCache.entries.keys())
+                    parseCache.usedKeys.add(k);
+            }
             const pruned = pruneCache(parseCache, parseCache.usedKeys);
             if (pruned > 0) {
                 log(`Parse cache: pruned ${pruned} stale chunk entries`);
@@ -763,6 +1008,10 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         const projectName = await registerRepo(repoPath, meta, {
             name: options.registryName,
             allowDuplicateName: options.allowDuplicateName,
+            // Non-primary branch runs upsert into the entry's branches[]; the
+            // primary/flat run (placement.branch === undefined) refreshes the
+            // top-level fields (#2106).
+            branch: placement.branch,
         });
         // Keep generated .gitnexus contents ignored without editing the user's root .gitignore.
         await ensureGitNexusIgnored(repoPath);
@@ -776,23 +1025,28 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             }
             aggregatedClusterCount = Array.from(groups.values()).filter((count) => count >= 5).length;
         }
-        try {
-            await generateAIContextFiles(repoPath, storagePath, projectName, {
-                files: pipelineResult.totalFileCount,
-                nodes: stats.nodes,
-                edges: stats.edges,
-                communities: pipelineResult.communityResult?.stats.totalCommunities,
-                clusters: aggregatedClusterCount,
-                processes: pipelineResult.processResult?.stats.totalProcesses,
-            }, undefined, {
-                skipAgentsMd: options.skipAgentsMd,
-                skipSkills: options.skipSkills,
-                noStats: options.noStats,
-                defaultBranch: options.defaultBranch,
-            });
-        }
-        catch {
-            // Best-effort — don't fail the entire analysis for context file issues
+        // Only (re)generate the repo-root AI context files (AGENTS.md / CLAUDE.md /
+        // skills) for the primary/flat index (#2106). A non-primary branch analyze
+        // must not churn the repo's committed AGENTS.md with branch-specific stats.
+        if (!placement.branch) {
+            try {
+                await generateAIContextFiles(repoPath, storagePath, projectName, {
+                    files: pipelineResult.totalFileCount,
+                    nodes: stats.nodes,
+                    edges: stats.edges,
+                    communities: pipelineResult.communityResult?.stats.totalCommunities,
+                    clusters: aggregatedClusterCount,
+                    processes: pipelineResult.processResult?.stats.totalProcesses,
+                }, undefined, {
+                    skipAgentsMd: options.skipAgentsMd,
+                    skipSkills: options.skipSkills,
+                    noStats: options.noStats,
+                    defaultBranch: options.defaultBranch,
+                });
+            }
+            catch {
+                // Best-effort — don't fail the entire analysis for context file issues
+            }
         }
         // ── Close LadybugDB ──────────────────────────────────────────────
         // Stop the manual checkpoint driver before closeLbug so its
@@ -806,6 +1060,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             stats: meta.stats,
             pipelineResult,
             ftsSkipped: !ftsAvailable,
+            isPrimaryBranch: !placement.branch,
         };
     }
     catch (err) {

package/dist/core/tree-sitter/parser-loader.js

@@ -2,6 +2,7 @@ import Parser from 'tree-sitter';
 import { createRequire } from 'node:module';
 import { SupportedLanguages } from '../../_shared/index.js';
 import { logger } from '../logger.js';
+import { requireVendoredGrammar } from './vendored-grammars.js';
 const _require = createRequire(import.meta.url);
 const ISSUES_URL = 'https://github.com/abhigyanpatwari/GitNexus/issues';
 const SOURCES = {
@@ -71,7 +72,7 @@ const SOURCES = {
     // user-opt-out grammar like Swift/Dart/Kotlin: a failure here is always an
     // install/platform problem the user needs to see.
     [SupportedLanguages.C]: {
-        load: () => _require('tree-sitter-c'),
+        load: () => requireVendoredGrammar('tree-sitter-c'),
         optional: true,
         severity: 'error',
         unavailableNote: 'C parsing disabled: vendored `tree-sitter-c` (under ' +
@@ -85,7 +86,7 @@ const SOURCES = {
     // optionalDependencies — may be absent on platforms without prebuilds
     // or when users skip optional installs.
     [SupportedLanguages.Swift]: {
-        load: () => _require('tree-sitter-swift'),
+        load: () => requireVendoredGrammar('tree-sitter-swift'),
         optional: true,
         userSkippable: true,
         unavailableNote: 'Swift parsing disabled: vendored `tree-sitter-swift` (under ' +
@@ -94,7 +95,7 @@ const SOURCES = {
             `See ${ISSUES_URL}/1130.`,
     },
     [SupportedLanguages.Dart]: {
-        load: () => _require('tree-sitter-dart'),
+        load: () => requireVendoredGrammar('tree-sitter-dart'),
         optional: true,
         userSkippable: true,
         unavailableNote: 'Dart parsing disabled: vendored `tree-sitter-dart` (under ' +
@@ -103,7 +104,7 @@ const SOURCES = {
             `See ${ISSUES_URL}/1125.`,
     },
     [SupportedLanguages.Kotlin]: {
-        load: () => _require('tree-sitter-kotlin'),
+        load: () => requireVendoredGrammar('tree-sitter-kotlin'),
         optional: true,
         userSkippable: true,
         unavailableNote: 'Kotlin parsing disabled: vendored `tree-sitter-kotlin` (under ' +

package/dist/core/tree-sitter/vendored-grammars.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Absolute path to the vendored grammar tree (`<pkg>/vendor`).
+ *
+ * This module compiles to `<pkg>/dist/core/tree-sitter/vendored-grammars.js`
+ * and runs from `<pkg>/src/core/tree-sitter/...` under tsx in dev — both sit
+ * three directories below the package root, and the build (`tsc`) never bundles,
+ * so `import.meta.url` resolves the same way in both. `vendor/` ships in the
+ * published package via package.json `files`.
+ */
+export declare const VENDOR_ROOT: string;
+/**
+ * The tree-sitter grammars GitNexus vendors inside its own package (NOT npm
+ * dependencies). Kept in one place so consumers (runtime loaders, the CLI
+ * availability probe, and the test grammar-introspection helper) agree on which
+ * grammars resolve from `vendor/` rather than `node_modules`.
+ */
+export declare const VENDORED_GRAMMAR_PACKAGES: ReadonlySet<string>;
+/** Absolute directory of a vendored grammar package under `vendor/`. */
+export declare const vendoredGrammarDir: (packageName: string) => string;
+/**
+ * Load a vendored tree-sitter grammar by its absolute path under `vendor/`.
+ *
+ * GitNexus vendors five grammars (c/dart/proto/swift/kotlin) inside its own
+ * package under `vendor/`, each shipping committed per-platform prebuilds. They
+ * are deliberately NOT npm dependencies and must NEVER be copied into
+ * `node_modules`: an undeclared package under `node_modules` is "extraneous" to
+ * every subsequent `npm`/`npx` arborist reify, which prunes or relocates it.
+ * That is the root cause of #2111 / #1728 — on Windows the relocation throws
+ * `EPERM: operation not permitted, symlink` (errno -4048) during the npx-cache
+ * reify Antigravity triggers when it launches the MCP server, and on every OS
+ * the second run silently deletes the materialized grammars.
+ *
+ * Resolving the grammar by absolute path runs its own `bindings/node` entry,
+ * which calls `node-gyp-build(<grammarDir>)` and loads
+ * `vendor/<name>/prebuilds/<platform>-<arch>/…` directly — no build, no write,
+ * no `node_modules` copy. (`node-gyp-build` itself IS an npm dependency and
+ * resolves normally from the grammar directory.)
+ */
+export declare const requireVendoredGrammar: (packageName: string) => unknown;