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

package/dist/server/upload-paths.js

@@ -0,0 +1,51 @@
+/**
+ * Upload working-directory paths.
+ *
+ * Browser folder uploads are written into ~/.gitnexus/uploads/{name}/ — a
+ * sibling of the clone root (git-clone.ts CLONE_ROOT) — so an uploaded repo
+ * persists and behaves like a cloned one (the graph UI's /api/file reads its
+ * files after analysis, and DELETE /api/repo removes it). Staging happens in
+ * an mkdtemp dir *under* UPLOAD_ROOT so the promote rename stays on one
+ * filesystem and remains atomic (a rename from os.tmpdir() could trip EXDEV —
+ * the exact Docker case this feature targets; see bridge-db.ts for the same
+ * anchored-staging pattern).
+ */
+import path from 'path';
+import os from 'os';
+import { sanitizeRepoName } from '../storage/git.js';
+import { REPO_NAME_PATTERN } from './git-clone.js';
+/** Root directory for all uploaded repositories. Targets must resolve inside this. */
+export const UPLOAD_ROOT = path.resolve(path.join(os.homedir(), '.gitnexus', 'uploads'));
+/** Prefix for per-upload staging directories created under UPLOAD_ROOT. */
+export const STAGING_PREFIX = '.staging-';
+/**
+ * Get the upload target directory for a repo name.
+ *
+ * Re-validates at the boundary (callers may derive the name from an untrusted
+ * manifest). Rejects `.`, `..`, the `'unknown'` sentinel that sanitizeRepoName
+ * emits for un-nameable inputs, names beginning with `.` (which would collide
+ * with the `.staging-` prefix), and anything outside the safe charset.
+ */
+export function getUploadDir(repoName) {
+    if (!repoName ||
+        repoName === '.' ||
+        repoName === '..' ||
+        repoName === 'unknown' ||
+        repoName.startsWith('.') ||
+        !REPO_NAME_PATTERN.test(repoName)) {
+        throw new Error('Invalid repository name');
+    }
+    return path.join(UPLOAD_ROOT, repoName);
+}
+/**
+ * Derive a filesystem-safe upload directory name from the manifest's
+ * top-level folder. Returns null when the name is un-nameable (so the caller
+ * rejects with 400 rather than colliding everyone on `UPLOAD_ROOT/unknown`).
+ */
+export function deriveUploadName(topLevelName) {
+    const safe = sanitizeRepoName(topLevelName);
+    if (safe === 'unknown' || safe === '.' || safe === '..' || safe.startsWith('.')) {
+        return null;
+    }
+    return safe;
+}

package/dist/server/upload-sweep.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Backstop cleanup for abandoned upload staging directories.
+ *
+ * A crashed/killed process can leave a `.staging-*` directory under
+ * UPLOAD_ROOT (the normal path removes it on success/failure/abort). This
+ * sweep, run once at server startup, removes staging dirs older than a
+ * threshold. Promoted upload dirs are persistent registered repos (like
+ * clones) and are NOT touched here — they are removed via DELETE /api/repo.
+ */
+export interface SweepOptions {
+    /** Remove staging dirs older than this (default 6h). */
+    maxAgeMs?: number;
+    /** Override the root to sweep (defaults to UPLOAD_ROOT; for tests). */
+    root?: string;
+    /** Clock injection for tests. */
+    now?: number;
+}
+export declare function sweepStaleUploads(opts?: SweepOptions): Promise<{
+    removed: string[];
+}>;

package/dist/server/upload-sweep.js

@@ -0,0 +1,57 @@
+/**
+ * Backstop cleanup for abandoned upload staging directories.
+ *
+ * A crashed/killed process can leave a `.staging-*` directory under
+ * UPLOAD_ROOT (the normal path removes it on success/failure/abort). This
+ * sweep, run once at server startup, removes staging dirs older than a
+ * threshold. Promoted upload dirs are persistent registered repos (like
+ * clones) and are NOT touched here — they are removed via DELETE /api/repo.
+ */
+import path from 'path';
+import fsp from 'fs/promises';
+import { UPLOAD_ROOT, STAGING_PREFIX } from './upload-paths.js';
+export async function sweepStaleUploads(opts = {}) {
+    const maxAgeMs = opts.maxAgeMs ?? 6 * 60 * 60 * 1000;
+    const root = opts.root ?? UPLOAD_ROOT;
+    const now = opts.now ?? Date.now();
+    const removed = [];
+    let entries;
+    try {
+        entries = await fsp.readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return { removed }; // root does not exist yet — nothing to sweep
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const full = path.join(root, entry.name);
+        try {
+            const st = await fsp.stat(full);
+            if (now - st.mtimeMs <= maxAgeMs)
+                continue; // recent — keep
+            if (entry.name.startsWith(STAGING_PREFIX)) {
+                // Transient staging dir orphaned by a crash — always removable.
+                await fsp.rm(full, { recursive: true, force: true }).catch(() => { });
+                removed.push(full);
+            }
+            else {
+                // Promoted upload dir. A successfully-analyzed (registered) repo always
+                // has a `.gitnexus` index inside it; a stale promoted dir WITHOUT one is
+                // an orphan from an analysis that failed before registering — remove it.
+                const hasIndex = await fsp
+                    .access(path.join(full, '.gitnexus'))
+                    .then(() => true)
+                    .catch(() => false);
+                if (!hasIndex) {
+                    await fsp.rm(full, { recursive: true, force: true }).catch(() => { });
+                    removed.push(full);
+                }
+            }
+        }
+        catch {
+            /* stat race — skip */
+        }
+    }
+    return { removed };
+}

package/dist/storage/branch-index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Branch-index primitives (#2106).
+ *
+ * Extracted from `repo-manager.ts` to keep the multi-branch slug/placement
+ * logic in one focused module. `getStoragePaths`, `loadMeta`, and the registry
+ * I/O stay in `repo-manager.ts`; this module imports the two it needs at
+ * call-time only (no module-load cross-calls), so the repo-manager ⇄
+ * branch-index import cycle is ESM-safe. `repo-manager.ts` re-exports these so
+ * existing import sites keep working unchanged.
+ */
+import { type RepoMeta } from './repo-manager.js';
+/**
+ * Per-branch index summary nested under a registry entry (#2106). Records
+ * non-primary branches indexed for the same repo path so `list`, `status`, and
+ * `list_repos` can surface them without a second registry entry.
+ */
+export interface BranchSummary {
+    /** Git branch name this sub-index represents. */
+    branch: string;
+    indexedAt: string;
+    lastCommit: string;
+    stats?: RepoMeta['stats'];
+}
+/** Branch-index sub-directory name, relative to the flat `.gitnexus` storage. */
+export declare const BRANCHES_DIR = "branches";
+/**
+ * Filesystem-safe slug for a git branch ref (#2106).
+ *
+ * `sanitizeRepoName` alone is lossy — it maps `/`→`_`, so `feature/x` and
+ * `feature_x` would collide into the same directory. We append a short sha256
+ * of the RAW ref (mirroring `assignRepoId`'s digest fallback) so two distinct
+ * refs can never share a branch directory, while keeping the human prefix
+ * readable.
+ */
+export declare const branchSlug: (rawRef: string) => string;
+/**
+ * Decide where a freshly-analyzed branch's index lives: the flat (primary) slot
+ * or a per-branch sub-directory (#2106 KTD2).
+ *
+ * Returns `{}` for the flat/primary placement (byte-identical layout) or
+ * `{ branch }` for a `branches/<slug>/` sub-directory. The flat slot is owned by
+ * the FIRST branch indexed, recorded as `branch` in the flat `meta.json`; a
+ * different checked-out branch then auto-routes to its own sub-directory so it
+ * never overwrites the primary index.
+ *
+ * `label` is the resolved index-branch (explicit `--branch`, else the
+ * checked-out branch, else `null`). A `null` label — detached HEAD, non-git
+ * folder, or CI checkout — always maps to the flat slot.
+ */
+export declare const resolveBranchPlacement: (repoPath: string, label: string | null) => Promise<{
+    branch?: string;
+}>;

package/dist/storage/branch-index.js

@@ -0,0 +1,65 @@
+/**
+ * Branch-index primitives (#2106).
+ *
+ * Extracted from `repo-manager.ts` to keep the multi-branch slug/placement
+ * logic in one focused module. `getStoragePaths`, `loadMeta`, and the registry
+ * I/O stay in `repo-manager.ts`; this module imports the two it needs at
+ * call-time only (no module-load cross-calls), so the repo-manager ⇄
+ * branch-index import cycle is ESM-safe. `repo-manager.ts` re-exports these so
+ * existing import sites keep working unchanged.
+ */
+import { createHash } from 'crypto';
+import { sanitizeRepoName } from './git.js';
+import { getStoragePaths, loadMeta } from './repo-manager.js';
+/** Branch-index sub-directory name, relative to the flat `.gitnexus` storage. */
+export const BRANCHES_DIR = 'branches';
+/**
+ * Filesystem-safe slug for a git branch ref (#2106).
+ *
+ * `sanitizeRepoName` alone is lossy — it maps `/`→`_`, so `feature/x` and
+ * `feature_x` would collide into the same directory. We append a short sha256
+ * of the RAW ref (mirroring `assignRepoId`'s digest fallback) so two distinct
+ * refs can never share a branch directory, while keeping the human prefix
+ * readable.
+ */
+export const branchSlug = (rawRef) => {
+    const safe = sanitizeRepoName(rawRef);
+    const hash = createHash('sha256').update(rawRef).digest('hex').slice(0, 8);
+    return `${safe}-${hash}`;
+};
+/**
+ * Decide where a freshly-analyzed branch's index lives: the flat (primary) slot
+ * or a per-branch sub-directory (#2106 KTD2).
+ *
+ * Returns `{}` for the flat/primary placement (byte-identical layout) or
+ * `{ branch }` for a `branches/<slug>/` sub-directory. The flat slot is owned by
+ * the FIRST branch indexed, recorded as `branch` in the flat `meta.json`; a
+ * different checked-out branch then auto-routes to its own sub-directory so it
+ * never overwrites the primary index.
+ *
+ * `label` is the resolved index-branch (explicit `--branch`, else the
+ * checked-out branch, else `null`). A `null` label — detached HEAD, non-git
+ * folder, or CI checkout — always maps to the flat slot.
+ */
+export const resolveBranchPlacement = async (repoPath, label) => {
+    // Detached HEAD / non-git / no label → flat (CI-safe, byte-identical).
+    if (!label)
+        return {};
+    const { storagePath } = getStoragePaths(repoPath);
+    const flatMeta = await loadMeta(storagePath);
+    // The flat slot's owner is authoritative ONLY when it is a non-empty string.
+    // A corrupt/hand-edited meta (empty string, or a non-string value that slips
+    // past JSON typing) must not be trusted to route the real primary into a
+    // sub-directory (#2106 review R5).
+    const owner = flatMeta && typeof flatMeta.branch === 'string' && flatMeta.branch.length > 0
+        ? flatMeta.branch
+        : undefined;
+    // Fresh repo (no flat index) or legacy/unstamped flat index (no recorded
+    // owner): the current label claims/adopts the flat slot. The legacy case
+    // preserves today's overwrite-in-place behavior until the slot is stamped.
+    if (!owner)
+        return {};
+    // Flat slot is owned. Same branch → flat; otherwise this branch gets its own
+    // sub-directory.
+    return owner === label ? {} : { branch: label };
+};

package/dist/storage/git.d.ts

@@ -118,6 +118,17 @@ export declare const getRemoteOriginUrl: (repoPath: string) => string | null;
  * git is unavailable, so callers can fall back to a configured/default branch.
  */
 export declare const getDefaultBranch: (repoPath: string) => string | null;
+/**
+ * Name of the currently checked-out branch, or `null` when HEAD is detached
+ * (CI checkouts, `git checkout <sha>`), the directory is not a git worktree, or
+ * git is unavailable.
+ *
+ * `git rev-parse --abbrev-ref HEAD` prints the literal `HEAD` for a detached
+ * checkout. We map that (and empty output) to `null` so callers fall back to the
+ * flat/default index rather than ever creating a branch literally named
+ * "HEAD" (#2106).
+ */
+export declare const getCurrentBranch: (repoPath: string) => string | null;
 /**
  * Sanitize a repository name to prevent argument injection and ensure
  * cross-platform filesystem compatibility.

package/dist/storage/git.js

@@ -295,6 +295,34 @@ export const getDefaultBranch = (repoPath) => {
         return null;
     }
 };
+/**
+ * Name of the currently checked-out branch, or `null` when HEAD is detached
+ * (CI checkouts, `git checkout <sha>`), the directory is not a git worktree, or
+ * git is unavailable.
+ *
+ * `git rev-parse --abbrev-ref HEAD` prints the literal `HEAD` for a detached
+ * checkout. We map that (and empty output) to `null` so callers fall back to the
+ * flat/default index rather than ever creating a branch literally named
+ * "HEAD" (#2106).
+ */
+export const getCurrentBranch = (repoPath) => {
+    try {
+        const branch = execSync('git rev-parse --abbrev-ref HEAD', {
+            cwd: repoPath,
+            // Suppress stderr -- see getCurrentCommit comment and #1172.
+            stdio: ['ignore', 'pipe', 'ignore'],
+            windowsHide: true,
+        })
+            .toString()
+            .trim();
+        if (!branch || branch === 'HEAD')
+            return null;
+        return branch;
+    }
+    catch {
+        return null;
+    }
+};
 /**
  * Sanitize a repository name to prevent argument injection and ensure
  * cross-platform filesystem compatibility.

package/dist/storage/parse-cache.d.ts

@@ -53,10 +53,31 @@ export declare const fileContentHash: (content: Buffer | string) => string;
  * in the chunk. We sort by filePath before hashing so chunks composed of
  * the same files in different order produce the same key.
  */
+/** PDG/CFG cache namespace (#2081 M1) — every input that changes the
+ *  WORKER-EMITTED `cfgSideChannel` must be folded into the chunk key, and
+ *  ONLY those. The classification test for a future option: does the worker
+ *  see it (workerData) and does it change the bytes the worker writes to the
+ *  shard? `pdgMaxEdgesPerFunction` famously fails that test — it is applied
+ *  at EMIT time on the main thread (scope-resolution run.ts), the worker
+ *  never receives it, and the cached output is byte-identical across cap
+ *  values; folding it in (as a prior review round did) only forced a
+ *  spurious full re-parse on every cap change (#2099 F3). Options that
+ *  change the PERSISTED GRAPH but not the shard belong in the RepoMeta pdg
+ *  stamp (incremental-eligibility), not here. */
+export interface PdgCacheKey {
+    readonly pdg?: boolean;
+    /** Per-function source-line cap (changes WHICH functions get a CFG —
+     *  applied in the worker, so it shapes the cached shard). Callers must
+     *  pass the RESOLVED value (the production call site in parse-impl.ts
+     *  applies the worker's default before folding) so an explicit-default
+     *  run shares the default run's keys — this function folds whatever it
+     *  is given verbatim. */
+    readonly maxFunctionLines?: number;
+}
 export declare const computeChunkHash: (entries: Array<{
     filePath: string;
     contentHash: string;
-}>) => string;
+}>, pdg?: boolean | PdgCacheKey) => string;
 export declare const mapReplacer: (_key: string, value: unknown) => unknown;
 export declare const mapReviver: (_key: string, value: unknown) => unknown;
 /**

package/dist/storage/parse-cache.js

@@ -52,7 +52,7 @@ import { fileURLToPath } from 'url';
 // the main thread (the #1983 OOM). Because the two stores share this version,
 // any future change to the `ParsedFile` serialization shape MUST bump
 // SCHEMA_BUMP so both invalidate in lockstep.
-const SCHEMA_BUMP = 4;
+const SCHEMA_BUMP = 6; // #2082 M2: cfgSideChannel gained bindings + per-block statement facts
 const GITNEXUS_PKG_VERSION = (() => {
     try {
         // package.json sits at gitnexus/package.json — two levels up from
@@ -92,17 +92,36 @@ const sha256Hex = (input) => createHash('sha256')
     .digest('hex');
 /** Stable hash of a single file's contents — used by callers to compose a chunk hash. */
 export const fileContentHash = (content) => sha256Hex(content);
-/**
- * Compute the canonical cache key for a chunk's contents.
- *
- * `entries` is the list of (filePath, file content hash) for every file
- * in the chunk. We sort by filePath before hashing so chunks composed of
- * the same files in different order produce the same key.
- */
-export const computeChunkHash = (entries) => {
+export const computeChunkHash = (entries, pdg = false) => {
     const sorted = [...entries].sort((a, b) => (a.filePath < b.filePath ? -1 : 1));
     const joined = sorted.map((e) => `${e.filePath}:${e.contentHash}`).join('\n');
-    return sha256Hex(joined);
+    const opts = typeof pdg === 'boolean' ? { pdg } : pdg;
+    // pdg-off path keeps its pre-#2081 chunk-KEY format verbatim. Note this does
+    // NOT mean caches survive the M1 upgrade: SCHEMA_BUMP 4→5 changed
+    // PARSE_CACHE_VERSION, and both loadParseCache (below) and the durable
+    // parsedfile-store index hard-invalidate on it — every user pays one full
+    // cold re-parse on upgrade regardless of --pdg. Keeping the key format
+    // stable only means no SECOND invalidation class is introduced here.
+    if (!opts.pdg)
+        return sha256Hex(joined);
+    // Fold the worker-visible --pdg configuration into the key: the boolean
+    // plus `maxFunctionLines` (decides which functions get a CFG at all, in the
+    // worker). Without it a warm chunk built under one cap is served to a run
+    // with a different cap → a stale/under-built CFG: the #2038-class
+    // option-blind-key trap. `def` marks an unset (default) value so two
+    // default-cap runs share a key. The emit-time edge cap is deliberately
+    // absent — see the PdgCacheKey doc comment.
+    //
+    // NAMESPACE VERSION (`pdg:2`): bumped when the worker-emitted
+    // `cfgSideChannel` SHAPE changes for pdg-mode runs only — pdg:1→2 in #2083
+    // M3 U1 (TsHarvester emits taint `sites` on StatementFacts). Invalidates
+    // pdg-mode chunks and their durable parsedfile-cache entries; flag-off
+    // chunk keys never reach this line and stay byte-identical, so non-pdg
+    // users pay nothing. Deliberately NOT a SCHEMA_BUMP — that gates the whole
+    // cache version and would force a full cold re-parse on EVERY user (the M1
+    // bump comment above records that cost).
+    const ns = `pdg:2;maxFn=${opts.maxFunctionLines ?? 'def'}`;
+    return sha256Hex(`${ns}\n${joined}`);
 };
 /**
  * JSON replacer that round-trips Map/Set instances through plain JSON.
@@ -149,6 +168,9 @@ export const slimParseWorkerResultsForCache = (chunkResults) => {
             assignments: [],
             constructorBindings: [],
             parsedFiles: [],
+            // #2112: a clone-safety skip list is per-run telemetry, not graph data —
+            // replay ignores it. Drop it so it doesn't bloat the cached shard.
+            skippedPaths: [],
         });
     }
     return slim;

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

@@ -5,6 +5,9 @@
  * Also maintains a global registry at ~/.gitnexus/registry.json
  * so the MCP server can discover indexed repos from any cwd.
  */
+import { branchSlug, resolveBranchPlacement, type BranchSummary } from './branch-index.js';
+export { branchSlug, resolveBranchPlacement };
+export type { BranchSummary };
 /**
  * Normalise a repo path for registry comparison across platforms
  * (#664 review feedback from @evander-wang).
@@ -71,18 +74,85 @@ export interface RepoMeta {
      */
     fileHashes?: Record<string, string>;
     /**
-     * Crash-recovery dirty flag. Written to meta.json BEFORE any
-     * destructive DB mutation in an incremental run; cleared on success
-     * by overwriting meta.json. If a run crashes between, the next run
-     * sees the flag and forces a full rebuild — the cheapest path back
-     * to a known-good index.
+     * Crash-recovery dirty flag — a generic marker written to meta.json
+     * BEFORE any destructive DB mutation by BOTH writeback branches
+     * (incremental since its introduction; full rebuilds over an existing
+     * meta since #2099 F1); cleared on success by overwriting meta.json.
+     * If a run crashes between, the next run sees the flag and forces a
+     * full rebuild — the cheapest path back to a known-good index.
      */
     incrementalInProgress?: {
-        /** When the incremental run started (epoch ms). */
+        /** When the run started (epoch ms). */
         startedAt: number;
-        /** Number of files in the writable set, for diagnostic logs. */
+        /** Number of files in the writable set, for diagnostic logs.
+         *  `0` on the full-rebuild path (no incremental write set exists). */
         toWriteCount: number;
     };
+    /**
+     * Name of the git branch this index represents (#2106). Absent for the
+     * default/legacy single-branch case so the flat `meta.json` stays
+     * byte-identical to pre-multi-branch output. When present in the FLAT
+     * `meta.json`, it records which branch "owns" the flat slot (the first
+     * branch indexed); per-branch indexes under `branches/<slug>/` always carry
+     * their own `branch`.
+     */
+    branch?: string;
+    /**
+     * The parse-cache chunk keys this branch's index needs (#2106 R6). The
+     * parse-cache and durable parsedfile store live ONCE at the repo root and are
+     * shared across branches; recording each branch's live chunk keys lets the
+     * prune step union them so re-analyzing one branch doesn't evict another
+     * branch's still-live shards. Additive/optional; absent in legacy metas.
+     */
+    cacheKeys?: string[];
+    /**
+     * The effective `--pdg` configuration this index's DB rows were built
+     * under (#2099 F1). Presence ≡ the BasicBlock/CFG layer exists in the DB;
+     * ABSENT ≡ pdg-off — which covers every legacy meta, since `--pdg`
+     * shipped opt-in. Caps are recorded RESOLVED (defaults applied) so an
+     * explicit-default run compares equal to a default run. run-analyze
+     * compares this against the requested options and forces a full
+     * writeback on any mismatch — the incremental path only persists
+     * changed-file nodes and would otherwise silently drop (or strand) the
+     * CFG layer on a mode flip. Additive/optional, no
+     * INCREMENTAL_SCHEMA_VERSION bump (a bump would force a one-time full
+     * rebuild for every user). NOTE the removal mechanism is load-bearing:
+     * the end-of-run meta is a fresh object literal, NOT a spread of the
+     * prior meta, so omitting this field on a pdg-off run is what clears
+     * the stamp after an on→off flip.
+     */
+    pdg?: {
+        /** Worker-side per-function source-line cap, resolved (0 = unlimited). */
+        maxFunctionLines: number;
+        /** Emit-side per-function CFG edge cap, resolved (0 = unlimited). */
+        maxEdgesPerFunction: number;
+        /**
+         * Emit-side per-function REACHING_DEF edge cap, resolved (0 = unlimited;
+         * #2082 M2). ABSENT on an M1-era stamp — which is exactly what makes
+         * `pdgModeMismatch` trip on the first M2 run over an M1 index and force
+         * the full writeback that populates REACHING_DEF rows. Optional in the
+         * type for that reason; resolved (always present) on every M2+ write.
+         */
+        maxReachingDefEdgesPerFunction?: number;
+        /**
+         * Per-function taint findings cap, resolved (0 = unlimited; #2083 M3).
+         * ABSENT on an M1/M2-era stamp — like `maxReachingDefEdgesPerFunction`,
+         * that absence is what trips `pdgModeMismatch` on the first M3 run and
+         * forces the full writeback that populates TAINTED/SANITIZES rows.
+         */
+        maxTaintFindingsPerFunction?: number;
+        /** Per-finding taint hop cap, resolved (0 = unlimited; #2083 M3 KTD6 —
+         *  bounds the persisted hop-encoded `reason`). Optional for the same
+         *  M2-era-stamp upgrade reason as the findings cap. */
+        maxTaintHops?: number;
+        /**
+         * Digest of the built-in taint model the persisted findings were
+         * produced under (#2083 M3 KTD7/R7). Any model-content change ships a
+         * new digest → mismatch → full writeback repopulates taint edges
+         * without `--force`. Optional: absent on pre-M3 stamps.
+         */
+        taintModelVersion?: string;
+    };
 }
 /**
  * Bumped whenever incremental-indexing invariants change incompatibly.
@@ -107,15 +177,33 @@ export interface RegistryEntry {
     /** See {@link RepoMeta.remoteUrl}. Mirrored from meta at register time. */
     remoteUrl?: string;
     stats?: RepoMeta['stats'];
+    /**
+     * Branch name owning the flat/primary index (#2106). Mirrors the flat
+     * `meta.branch`. Absent for legacy single-branch entries and non-git repos —
+     * additive and backward compatible.
+     */
+    branch?: string;
+    /**
+     * Non-primary branch indexes for this same path (#2106). Absent when only the
+     * primary branch is indexed, preserving the one-entry-per-path model and the
+     * legacy registry shape.
+     */
+    branches?: BranchSummary[];
 }
 /**
  * Get the .gitnexus storage path for a repository
  */
 export declare const getStoragePath: (repoPath: string) => string;
 /**
- * Get paths to key storage files
+ * Get paths to key storage files.
+ *
+ * `storagePath` is ALWAYS the flat `<repo>/.gitnexus` — content-addressed
+ * caches (`parse-cache/`, `parsedfile-store/`) live there and are shared
+ * across branches (#2106 KTD7). When `branch` is provided, only `lbugPath` and
+ * `metaPath` are scoped under `branches/<slug>/`; the flat call (no `branch`)
+ * returns byte-identical paths to the pre-multi-branch behavior.
  */
-export declare const getStoragePaths: (repoPath: string) => {
+export declare const getStoragePaths: (repoPath: string, branch?: string) => {
     storagePath: string;
     lbugPath: string;
     metaPath: string;
@@ -213,6 +301,14 @@ export interface RegisterRepoOptions {
      * re-run the full pipeline.
      */
     allowDuplicateName?: boolean;
+    /**
+     * Non-primary branch this run indexed (#2106). When set, the branch's
+     * summary is upserted into the entry's `branches[]` and the primary
+     * top-level fields are left untouched. When `undefined`, this is a
+     * primary/flat run that refreshes the top-level fields (and preserves any
+     * existing branch summaries).
+     */
+    branch?: string;
 }
 /**
  * Thrown by {@link registerRepo} when a requested name is already in
@@ -262,6 +358,15 @@ export declare const registerRepo: (repoPath: string, meta: RepoMeta, opts?: Reg
  * Called after `gitnexus clean`.
  */
 export declare const unregisterRepo: (repoPath: string) => Promise<void>;
+/**
+ * Remove a single non-primary branch's summary from a repo's registry entry
+ * (#2106 R7). Called by `gitnexus clean --branch`. Returns `true` when a
+ * matching `branches[]` summary was found and removed; `false` otherwise (so
+ * the CLI can report "no such indexed branch" without crashing). The top-level
+ * primary entry is left intact; an empty `branches[]` is dropped to keep the
+ * registry shape legacy-clean.
+ */
+export declare const removeBranchIndex: (repoPath: string, branch: string) => Promise<boolean>;
 /**
  * Thrown by {@link resolveRegistryEntry} when no registered repo matches
  * the caller's target string (by alias, basename, remote-inferred name,
@@ -404,7 +509,14 @@ export declare const assertSafeStoragePath: (entry: RegistryEntry) => void;
 export declare const resolveRegistryEntry: (entries: RegistryEntry[], target: string) => RegistryEntry;
 /**
  * List all registered repos from the global registry.
- * Optionally validates that each entry's .gitnexus/ still exists.
+ *
+ * With `validate: true`, prunes only entries whose index is *provably* gone
+ * (fs.access on .gitnexus/meta.json fails with ENOENT or ENOTDIR) and persists
+ * the result. Entries that are merely "not provably absent" — any other
+ * fs.access failure (EIO/EAGAIN/EBUSY/EACCES, etc.) — are KEPT, so a transient
+ * I/O storm cannot wipe the registry. A kept entry is therefore "not confirmed
+ * present," not "confirmed present"; downstream DB opens are independently and
+ * lazily guarded.
  */
 export declare const listRegisteredRepos: (opts?: {
     validate?: boolean;