gitnexus 1.6.9-rc.44 → 1.6.9-rc.45

package/README.md

@@ -40,14 +40,14 @@ To configure MCP for your editor, run `npx gitnexus setup` once — or set it up
 
 | Editor                   | MCP | Skills | Hooks (auto-augment)                                                                       | Support      |
 | ------------------------ | --- | ------ | ------------------------------------------------------------------------------------------ | ------------ |
-| **Claude Code**          | Yes | Yes    | Yes (PreToolUse)                                                                           | **Full**     |
+| **Claude Code**          | Yes | Yes    | Yes (PreToolUse + PostToolUse)                                                             | **Full**     |
 | **Cursor**               | Yes | Yes    | Yes (postToolUse, [manual install](../gitnexus-cursor-integration/README.md#hook-install)) | **Full**     |
 | **Antigravity** (Google) | Yes | Yes    | Yes (AfterTool, [Gemini CLI hooks schema](https://geminicli.com/docs/hooks/reference/))    | **Full**     |
 | **Codex**                | Yes | Yes    | —                                                                                          | MCP + Skills |
-| **Windsurf**             | Yes | —      | —                                                                                          | MCP          |
 | **OpenCode**             | Yes | Yes    | —                                                                                          | MCP + Skills |
+| **Windsurf**             | Yes | —      | —                                                                                          | MCP          |
 
-> **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that automatically enrich grep/glob/bash calls with knowledge graph context.
+> **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that automatically enrich grep/glob/bash calls with knowledge graph context + PostToolUse hooks that detect a stale index after commits and prompt the agent to reindex.
 
 ### Community Integrations
 
@@ -122,31 +122,44 @@ The result is a **LadybugDB graph database** stored locally in `.gitnexus/` with
 
 ## MCP Tools
 
-Your AI agent gets these tools automatically:
-
-| Tool             | What It Does                                                     | `repo` Param |
-| ---------------- | ---------------------------------------------------------------- | ------------ |
-| `list_repos`     | Discover all indexed repositories (paginated — `limit`/`offset`) | —            |
-| `query`          | Process-grouped hybrid search (BM25 + semantic + RRF)            | Optional     |
-| `context`        | 360-degree symbol view — categorized refs, process participation | Optional     |
-| `impact`         | Blast radius analysis with depth grouping and confidence         | Optional     |
-| `detect_changes` | Git-diff impact — maps changed lines to affected processes       | Optional     |
-| `rename`         | Multi-file coordinated rename with graph + text search           | Optional     |
-| `cypher`         | Raw Cypher graph queries                                         | Optional     |
-
-> With one indexed repo, the `repo` param is optional. With multiple, specify which: `query({search_query: "auth", repo: "my-app"})`.
+Your AI agent gets **17 tools** (15 per-repo + 2 group) automatically:
+
+| Tool             | What It Does                                                           |
+| ---------------- | ----------------------------------------------------------------------- |
+| `list_repos`     | Discover all indexed repositories (paginated — `limit`/`offset`)        |
+| `query`          | Process-grouped hybrid search (BM25 + semantic + RRF)                   |
+| `context`        | 360-degree symbol view — categorized refs, process participation        |
+| `impact`         | Blast radius analysis with depth grouping and confidence                |
+| `trace`          | Shortest directed path between two symbols (call + class-member edges)  |
+| `detect_changes` | Git-diff impact — maps changed lines to affected processes              |
+| `check`          | Read-only structural checks against the indexed graph                   |
+| `rename`         | Multi-file coordinated rename with graph + text search                  |
+| `cypher`         | Raw Cypher graph queries                                                |
+| `route_map`      | API route map — which components fetch which endpoints, and handlers    |
+| `tool_map`       | MCP/RPC tool definitions — where they're defined and handled            |
+| `shape_check`    | Validate API response shapes against consumers' property accesses       |
+| `api_impact`     | Pre-change impact report for an API route handler                       |
+| `explain`        | Explain persisted taint findings (source→sink flows, `--pdg` indexes)   |
+| `pdg_query`      | Query control/data dependence at statement level (`--pdg` indexes)      |
+| `group_list`     | List configured repository groups                                       |
+| `group_sync`     | Rebuild a group's Contract Registry and cross-repo links                |
+
+> With one indexed repo, the `repo` param is optional. With multiple, specify which: `query({search_query: "auth", repo: "my-app"})`. Per-repo tools also take an optional `branch` for multi-branch indexes. `explain` and `pdg_query` need an index built with `gitnexus analyze --pdg`.
 
 ## MCP Resources
 
 | Resource                                | Purpose                                              |
 | --------------------------------------- | ---------------------------------------------------- |
 | `gitnexus://repos`                      | List all indexed repositories (read first)           |
+| `gitnexus://setup`                      | Setup and usage guidance for agents                  |
 | `gitnexus://repo/{name}/context`        | Codebase stats, staleness check, and available tools |
 | `gitnexus://repo/{name}/clusters`       | All functional clusters with cohesion scores         |
 | `gitnexus://repo/{name}/cluster/{name}` | Cluster members and details                          |
 | `gitnexus://repo/{name}/processes`      | All execution flows                                  |
 | `gitnexus://repo/{name}/process/{name}` | Full process trace with steps                        |
 | `gitnexus://repo/{name}/schema`         | Graph schema for Cypher queries                      |
+| `gitnexus://group/{name}/contracts`     | A group's extracted contracts and cross-links        |
+| `gitnexus://group/{name}/status`        | Staleness of repos in a group                        |
 
 ## MCP Prompts
 
@@ -164,7 +177,11 @@ gitnexus analyze [path]          # Index a repository (or update stale index)
 gitnexus analyze --repair-fts    # Fast path: rebuild/verify only FTS indexes on existing index data
 gitnexus analyze --force         # Full rebuild: re-parse + graph rebuild + FTS rebuild
 gitnexus analyze --embeddings    # Enable embedding generation (slower, better search)
+gitnexus analyze --skills        # Generate repo-specific skill files from detected communities
 gitnexus analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md gitnexus section edits
+gitnexus analyze --skip-skills   # Skip installing .claude/skills/gitnexus/ skill files
+gitnexus analyze --skip-git      # Index folders that are not Git repositories
+gitnexus analyze --workers <n>   # Parse worker pool size (>=1; default: cores-1, capped at 16)
 gitnexus analyze --verbose       # Log skipped files when parsers are unavailable
 gitnexus analyze --max-file-size 1024  # Skip files larger than N KB (default: 512, cap: 32768)
 gitnexus analyze --worker-timeout 60  # Increase worker idle timeout for slow parses
@@ -177,13 +194,16 @@ gitnexus status                  # Show index status for current repo
 gitnexus clean                   # Delete index for current repo
 gitnexus clean --all --force     # Delete all indexes
 gitnexus wiki [path]             # Generate LLM-powered docs from knowledge graph
-gitnexus wiki --model <model>    # Wiki with custom LLM model (default: gpt-4o-mini)
+gitnexus wiki --model <model>    # Wiki with custom LLM model (default: minimax/minimax-m2.5)
+gitnexus doctor                  # Show runtime platform capabilities and embedding configuration
 
 # Direct graph queries — the same tools the MCP server exposes, no MCP daemon needed
 gitnexus query "<concept>"                                    # Process-grouped hybrid search
 gitnexus context <symbol> [--uid <uid> | --file <path>]       # 360° symbol view; flags disambiguate a shared name
 gitnexus impact <symbol> [--uid <uid> | --file <path> | --kind <kind>]  # Blast radius; flags disambiguate a shared name
+gitnexus trace <from> <to>       # Shortest directed path between two symbols
 gitnexus detect-changes          # Map the working-tree diff to affected symbols and execution flows
+gitnexus check                   # Read-only structural checks against the indexed graph
 gitnexus cypher "<query>"        # Run a raw Cypher query against the knowledge graph
 
 # Repository groups (multi-repo / monorepo service tracking)
@@ -195,6 +215,7 @@ gitnexus group sync <name>                                     # Extract contrac
 gitnexus group contracts <name>  # Inspect extracted contracts and cross-links
 gitnexus group query <name> <q>  # Search execution flows across all repos in a group
 gitnexus group status <name>     # Check staleness of repos in a group
+gitnexus group impact <name> --target <symbol> --repo <groupPath>  # Cross-repo blast radius
 ```
 
 > **`gitnexus uninstall`** reverses `gitnexus setup` — it removes the GitNexus MCP entries, hooks, and skill directories it added to each detected editor. Skill directories are identified **by bundled gitnexus skill name** (e.g. `gitnexus-cli/`), so if you customized files inside an installed skill directory, back them up first. It is a dry-run preview by default and prints the exact paths it would remove; pass `--force` to apply. Per-repo indexes (`gitnexus clean --all`) and the global npm package (`npm uninstall -g gitnexus`) are left for you to remove.
@@ -219,7 +240,7 @@ GitNexus supports indexing multiple repositories. Each `gitnexus analyze` regist
 
 ## Supported Languages
 
-TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust, PHP, Kotlin, Swift, Ruby
+TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust, PHP, Kotlin, Swift, Ruby, Dart
 
 ### Language Feature Matrix
 
@@ -238,6 +259,7 @@ TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust, PHP, Kotlin, Swift,
 | Swift      | —       | —              | ✓       | ✓        | ✓                | ✓                     | ✓      | ✓          | ✓            |
 | C          | —       | —              | ✓       | —        | ✓                | ✓                     | —      | ✓          | ✓            |
 | C++        | —       | —              | ✓       | ✓        | ✓                | ✓                     | —      | ✓          | ✓            |
+| Dart       | ✓       | —              | ✓       | ✓        | ✓                | ✓                     | —      | ✓          | ✓            |
 
 **Imports** — cross-file import resolution · **Named Bindings** — `import { X as Y }` / re-export tracking · **Exports** — public/exported symbol detection · **Heritage** — class inheritance, interfaces, mixins · **Type Annotations** — explicit type extraction for receiver resolution · **Constructor Inference** — infer receiver type from constructor calls (`self`/`this` resolution included for all languages) · **Config** — language toolchain config parsing (tsconfig, go.mod, etc.) · **Frameworks** — AST-based framework pattern detection · **Entry Points** — entry point scoring heuristics
 
@@ -249,12 +271,14 @@ GitNexus ships with skill files that teach AI agents how to use the tools effect
 - **Debugging** — Trace bugs through call chains
 - **Impact Analysis** — Analyze blast radius before changes
 - **Refactoring** — Plan safe refactors using dependency mapping
+- **Guide** — GitNexus tool/resource/schema reference for the agent
+- **CLI** — Run analyze/status/clean/wiki commands on request
 
-Installed automatically by both `gitnexus analyze` (per-repo) and `gitnexus setup` (global).
+Installed automatically by both `gitnexus analyze` (per-repo) and `gitnexus setup` (global). Run `gitnexus analyze --skills` to additionally generate repo-specific skills for each detected functional area under `.claude/skills/generated/`.
 
 ## Requirements
 
-- Node.js >= 18
+- Node.js >= 22
 - Git repository (uses git for commit tracking)
 
 ## Release candidates
@@ -340,7 +364,7 @@ gitnexus serve
 
 ### Installation fails with native module errors
 
-Some optional language grammars (Dart, Kotlin, Swift) require native compilation. If they fail, GitNexus still works — those languages will be skipped.
+Some optional language grammars (Dart, Proto, Swift, Kotlin) require native compilation. If they fail, GitNexus still works — those languages will be skipped. To skip them intentionally (no C++ toolchain needed), set `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1` before installing.
 
 If `npm install -g gitnexus` fails on native modules:
 

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

@@ -162,7 +162,7 @@ export declare const en: {
     readonly 'help.option.analyze.embeddingBatchSize': "Number of nodes per embedding batch";
     readonly 'help.option.analyze.embeddingSubBatchSize': "Number of chunks per embedding model call";
     readonly 'help.option.analyze.embeddingDevice': "Embedding device: auto, cpu, dml, cuda, or wasm";
-    readonly 'help.option.index.force': "Register even if meta.json is missing (stats will be empty)";
+    readonly 'help.option.index.force': "Register even if index metadata is missing (stats will be empty)";
     readonly 'help.option.index.allowNonGit': "Allow registering folders that are not Git repositories";
     readonly 'help.option.port': "Port number";
     readonly 'help.option.serve.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 for remote access)";

package/dist/cli/i18n/en.js

@@ -162,7 +162,7 @@ export const en = {
     'help.option.analyze.embeddingBatchSize': 'Number of nodes per embedding batch',
     'help.option.analyze.embeddingSubBatchSize': 'Number of chunks per embedding model call',
     'help.option.analyze.embeddingDevice': 'Embedding device: auto, cpu, dml, cuda, or wasm',
-    'help.option.index.force': 'Register even if meta.json is missing (stats will be empty)',
+    'help.option.index.force': 'Register even if index metadata is missing (stats will be empty)',
     'help.option.index.allowNonGit': 'Allow registering folders that are not Git repositories',
     'help.option.port': 'Port number',
     'help.option.serve.host': 'Bind address (default: 127.0.0.1, use 0.0.0.0 for remote access)',

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

@@ -163,7 +163,7 @@ export declare const cliResources: {
         readonly 'help.option.analyze.embeddingBatchSize': "Number of nodes per embedding batch";
         readonly 'help.option.analyze.embeddingSubBatchSize': "Number of chunks per embedding model call";
         readonly 'help.option.analyze.embeddingDevice': "Embedding device: auto, cpu, dml, cuda, or wasm";
-        readonly 'help.option.index.force': "Register even if meta.json is missing (stats will be empty)";
+        readonly 'help.option.index.force': "Register even if index metadata is missing (stats will be empty)";
         readonly 'help.option.index.allowNonGit': "Allow registering folders that are not Git repositories";
         readonly 'help.option.port': "Port number";
         readonly 'help.option.serve.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 for remote access)";

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

@@ -162,7 +162,7 @@ export const zhCN = {
     'help.option.analyze.embeddingBatchSize': '每个嵌入批次的节点数',
     'help.option.analyze.embeddingSubBatchSize': '每次嵌入模型调用的分块数',
     'help.option.analyze.embeddingDevice': '嵌入设备：auto、cpu、dml、cuda 或 wasm',
-    'help.option.index.force': '即使缺少 meta.json 也注册（统计为空）',
+    'help.option.index.force': '即使缺少索引元数据也注册（统计为空）',
     'help.option.index.allowNonGit': '允许注册非 Git 仓库文件夹',
     'help.option.port': '端口号',
     'help.option.serve.host': '绑定地址（默认：127.0.0.1；远程访问可用 0.0.0.0）',

package/dist/cli/index-repo.d.ts

@@ -1,10 +1,14 @@
 /**
  * Index Command
  *
- * Registers an existing .gitnexus/ folder into the global registry so the
+ * Registers an existing GitNexus index into the global registry so the
  * MCP server can discover the repo without running a full `gitnexus analyze`.
  *
- * Useful when a pre-built .gitnexus/ directory is already present (e.g. after
+ * The index can be either:
+ * - A per-worktree gitnexus.json file under .gitnexus/ (new format, worktree-compatible)
+ * - A legacy .gitnexus/meta.json file (auto-migrated on analyze)
+ *
+ * Useful when a pre-built index is already present (e.g. after
  * cloning a repo that ships its index, restoring from backup, or using a
  * shared team index).
  */

package/dist/cli/index-repo.js

@@ -1,16 +1,20 @@
 /**
  * Index Command
  *
- * Registers an existing .gitnexus/ folder into the global registry so the
+ * Registers an existing GitNexus index into the global registry so the
  * MCP server can discover the repo without running a full `gitnexus analyze`.
  *
- * Useful when a pre-built .gitnexus/ directory is already present (e.g. after
+ * The index can be either:
+ * - A per-worktree gitnexus.json file under .gitnexus/ (new format, worktree-compatible)
+ * - A legacy .gitnexus/meta.json file (auto-migrated on analyze)
+ *
+ * Useful when a pre-built index is already present (e.g. after
  * cloning a repo that ships its index, restoring from backup, or using a
  * shared team index).
  */
 import path from 'path';
 import fs from 'fs/promises';
-import { getStoragePaths, loadMeta, ensureGitNexusIgnored, registerRepo, } from '../storage/repo-manager.js';
+import { getStoragePaths, INDEX_METADATA_FILE, loadMeta, ensureGitNexusIgnored, registerRepo, } from '../storage/repo-manager.js';
 import { getGitRoot, getRemoteUrl, isGitRepo } from '../storage/git.js';
 export const indexCommand = async (inputPathParts, options) => {
     console.log('\n  GitNexus Index\n');
@@ -50,22 +54,35 @@ export const indexCommand = async (inputPathParts, options) => {
         return;
     }
     const { storagePath, lbugPath } = getStoragePaths(repoPath);
-    // ── Verify .gitnexus/ exists ──────────────────────────────────────
+    // ── Verify index exists (metadata file, legacy metadata, or restorable DB) ─
+    let hasMetadataIndex = false;
+    let hasLegacyIndex = false;
+    let hasLbugIndex = false;
+    try {
+        await fs.access(path.join(storagePath, INDEX_METADATA_FILE));
+        hasMetadataIndex = true;
+    }
+    catch { }
     try {
-        await fs.access(storagePath);
+        await fs.access(path.join(storagePath, 'meta.json'));
+        hasLegacyIndex = true;
     }
-    catch {
-        console.log(`  No .gitnexus/ folder found at: ${storagePath}`);
+    catch { }
+    try {
+        await fs.access(lbugPath);
+        hasLbugIndex = true;
+    }
+    catch { }
+    if (!hasMetadataIndex && !hasLegacyIndex && !hasLbugIndex) {
+        console.log(`  No GitNexus index found.`);
+        console.log(`  Expected gitnexus.json, .gitnexus/meta.json, or LadybugDB at: ${storagePath}`);
         console.log('  Run `gitnexus analyze` to build the index first.\n');
         process.exitCode = 1;
         return;
     }
     // ── Verify lbug database exists ───────────────────────────────────
-    try {
-        await fs.access(lbugPath);
-    }
-    catch {
-        console.log(`  .gitnexus/ folder exists but contains no LadybugDB index.`);
+    if (!hasLbugIndex) {
+        console.log(`  Index exists but contains no LadybugDB database.`);
         console.log('  Run `gitnexus analyze` to build the index.\n');
         process.exitCode = 1;
         return;
@@ -74,7 +91,7 @@ export const indexCommand = async (inputPathParts, options) => {
     let meta = await loadMeta(storagePath);
     if (!meta) {
         if (!options?.force) {
-            console.log(`  .gitnexus/ exists but meta.json is missing.`);
+            console.log(`  gitnexus.json or .gitnexus/meta.json is missing.`);
             console.log('  Use --force to register anyway (stats will be empty),');
             console.log('  or run `gitnexus analyze` to rebuild properly.\n');
             process.exitCode = 1;

package/dist/cli/index.js

@@ -123,7 +123,7 @@ program
 program
     .command('index [path...]')
     .description('Register an existing .gitnexus/ folder into the global registry (no re-analysis needed)')
-    .option('-f, --force', 'Register even if meta.json is missing (stats will be empty)')
+    .option('-f, --force', 'Register even if index metadata is missing (stats will be empty)')
     .option('--allow-non-git', 'Allow registering folders that are not Git repositories')
     .action(createLazyAction(() => import('./index-repo.js'), 'indexCommand'));
 program

package/dist/cli/remove.d.ts

@@ -1,9 +1,12 @@
 /**
  * Remove Command (#664)
  *
- * Delete the `.gitnexus/` index for a registered repo and unregister it
- * from the global registry (~/.gitnexus/registry.json). The target is
- * identified by alias / basename-derived name / remote-inferred name /
+ * Delete the `.gitnexus/` index directory for a registered repo (including
+ * both metadata filenames — gitnexus.json and its legacy meta.json mirror —
+ * which live inside it) and unregister it from the global registry
+ * (~/.gitnexus/registry.json).
+ *
+ * The target is identified by alias / basename-derived name / remote-inferred name /
  * absolute path — no `--repo` flag, just a positional argument so the
  * destructive-command ergonomics match `clean` (which is also
  * destructive but scoped to `process.cwd()`).

package/dist/cli/remove.js

@@ -1,9 +1,12 @@
 /**
  * Remove Command (#664)
  *
- * Delete the `.gitnexus/` index for a registered repo and unregister it
- * from the global registry (~/.gitnexus/registry.json). The target is
- * identified by alias / basename-derived name / remote-inferred name /
+ * Delete the `.gitnexus/` index directory for a registered repo (including
+ * both metadata filenames — gitnexus.json and its legacy meta.json mirror —
+ * which live inside it) and unregister it from the global registry
+ * (~/.gitnexus/registry.json).
+ *
+ * The target is identified by alias / basename-derived name / remote-inferred name /
  * absolute path — no `--repo` flag, just a positional argument so the
  * destructive-command ergonomics match `clean` (which is also
  * destructive but scoped to `process.cwd()`).

package/dist/core/group/bridge-db.d.ts

@@ -110,7 +110,6 @@ export declare function queryBridge<T>(handle: BridgeHandle, cypher: string, par
  * is a lease release, so the file may stay open under other readers.
  */
 export declare function closeBridgeDb(handle: BridgeHandle): Promise<void>;
-export declare function retryRename(src: string, dst: string, attempts?: number): Promise<void>;
 export declare function writeBridgeMeta(groupDir: string, meta: BridgeMeta): Promise<void>;
 export declare function readBridgeMeta(groupDir: string): Promise<BridgeMeta>;
 export interface WriteBridgeInput {

package/dist/core/group/bridge-db.js

@@ -6,6 +6,7 @@ import { BRIDGE_SCHEMA_QUERIES, BRIDGE_SCHEMA_VERSION } from './bridge-schema.js
 import { closeLbugConnection, openLbugConnection, } from '../lbug/lbug-config.js';
 import { dedupeContracts, dedupeCrossLinks } from './normalization.js';
 import { createLogger } from '../logger.js';
+import { retryRename } from '../../storage/fs-atomic.js';
 const bridgeLogger = createLogger('bridge-db', {
     debugEnvVar: 'GITNEXUS_DEBUG_BRIDGE',
 });
@@ -512,24 +513,6 @@ export async function closeBridgeDb(handle) {
 // The read-only CHECKPOINT skip above remains the load-bearing fix on
 // Linux/macOS.
 /* ------------------------------------------------------------------ */
-/*  retryRename — handles transient EBUSY/EPERM/EACCES on Windows    */
-/* ------------------------------------------------------------------ */
-const RETRY_CODES = new Set(['EBUSY', 'EPERM', 'EACCES']);
-export async function retryRename(src, dst, attempts = 3) {
-    for (let i = 1; i <= attempts; i++) {
-        try {
-            await fsp.rename(src, dst);
-            return;
-        }
-        catch (err) {
-            const code = err.code;
-            if (!code || !RETRY_CODES.has(code) || i === attempts)
-                throw err;
-            await new Promise((r) => setTimeout(r, 100 * Math.pow(2, i - 1)));
-        }
-    }
-}
-/* ------------------------------------------------------------------ */
 /*  writeBridgeMeta / readBridgeMeta                                  */
 /* ------------------------------------------------------------------ */
 export async function writeBridgeMeta(groupDir, meta) {

package/dist/core/group/service.js

@@ -5,6 +5,7 @@
 import fsp from 'node:fs/promises';
 import path from 'node:path';
 import { checkStaleness } from '../git-staleness.js';
+import { loadMeta } from '../../storage/repo-manager.js';
 import { GroupNotFoundError, loadGroupConfig } from './config-parser.js';
 import { fileMatchesServicePrefix, normalizeServicePrefix, repoInSubgroup, } from './group-path-utils.js';
 import { getDefaultGitnexusDir, getGroupDir, listGroups, readContractRegistry } from './storage.js';
@@ -370,9 +371,7 @@ export class GroupService {
         for (const [repoPath, registryName] of Object.entries(config.repos)) {
             try {
                 const repoObj = await this.port.resolveRepo(registryName);
-                const metaPath = path.join(repoObj.storagePath, 'meta.json');
-                const metaRaw = await fsp.readFile(metaPath, 'utf-8').catch(() => '{}');
-                const meta = JSON.parse(metaRaw);
+                const meta = (await loadMeta(repoObj.storagePath)) ?? {};
                 const staleness = meta.lastCommit
                     ? checkStaleness(repoObj.repoPath, meta.lastCommit)
                     : { isStale: true, commitsBehind: -1 };

package/dist/core/group/storage.js

@@ -3,7 +3,7 @@ import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import { randomBytes } from 'node:crypto';
-import { retryRename } from './bridge-db.js';
+import { retryRename } from '../../storage/fs-atomic.js';
 /**
  * Build an unpredictable suffix for atomic-write tmp files. Replaces the
  * previous `Date.now()` pattern which CodeQL flagged as

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

@@ -207,11 +207,14 @@ export declare const PHASE_LABELS: Record<string, string>;
 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
+ * metadata directory 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 — the byte-identity claim
+ * is about the PRUNE result; the metadata FILENAME read here changed with
+ * PR #2363's rename, checking `gitnexus.json` first then the legacy
+ * `meta.json` mirror). `complete` is false when a sibling metadata file exists
+ * but fails to read or 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<{

package/dist/core/run-analyze.js

@@ -18,7 +18,7 @@ import { createSearchFTSIndexes, initialiseSearchFTSStemmer, verifySearchFTSInde
 import { cjkSegmentationModeMismatch, getSearchFTSCjkSegmentation, initialiseSearchFTSCjkSegmentation, } from './search/cjk-segmentation.js';
 import { resolveAnalyzeInstallPolicy } from './lbug/extension-loader.js';
 import { startWalCheckpointDriver, } from './lbug/wal-checkpoint-driver.js';
-import { getStoragePaths, resolveBranchPlacement, saveMeta, loadMeta, ensureGitNexusIgnored, registerRepo, isRepoRegistered, cleanupOldKuzuFiles, INCREMENTAL_SCHEMA_VERSION, } from '../storage/repo-manager.js';
+import { getStoragePaths, resolveBranchPlacement, saveMeta, loadMeta, ensureGitNexusIgnored, registerRepo, isRepoRegistered, cleanupOldKuzuFiles, reconcileMetadataFiles, isMissingFilesystemError, INDEX_METADATA_FILE, 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, DEFAULT_PDG_MAX_CDG_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';
@@ -97,11 +97,14 @@ export const primaryInversionWarning = (defaultBranch, flatOwner) => {
 };
 /**
  * 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
+ * metadata directory 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 — the byte-identity claim
+ * is about the PRUNE result; the metadata FILENAME read here changed with
+ * PR #2363's rename, checking `gitnexus.json` first then the legacy
+ * `meta.json` mirror). `complete` is false when a sibling metadata file exists
+ * but fails to read or 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) => {
@@ -117,10 +120,21 @@ export const collectBranchCacheKeys = async (storagePath, excludeDir) => {
             continue;
         let raw;
         try {
-            raw = await fs.readFile(path.join(dir, 'meta.json'), 'utf-8');
+            raw = await fs.readFile(path.join(dir, INDEX_METADATA_FILE), 'utf-8');
         }
-        catch {
-            continue; // no meta here — not a branch index, not a failure
+        catch (newErr) {
+            if (!isMissingFilesystemError(newErr)) {
+                complete = false;
+                continue;
+            }
+            try {
+                raw = await fs.readFile(path.join(dir, 'meta.json'), 'utf-8');
+            }
+            catch (legacyErr) {
+                if (!isMissingFilesystemError(legacyErr))
+                    complete = false;
+                continue; // no metadata here — not a branch index, not a failure
+            }
         }
         try {
             const parsed = JSON.parse(raw);
@@ -306,10 +320,21 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     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.
+    // metaPath now points to the metadata file (gitnexus.json) in a branch-specific directory.
+    // metaDir is the directory containing the metadata file (and branch-specific DBs).
     const metaDir = path.dirname(metaPath);
+    // Keep gitnexus.json and the legacy meta.json mirror in sync (fresher
+    // indexedAt wins; nothing is deleted). Best-effort: loadMeta has its own
+    // legacy fallback, so a reconciliation failure (read-only mount, full disk)
+    // must never abort the analyze run — a repo that indexed fine read-only
+    // before the rename must keep doing so.
+    try {
+        await reconcileMetadataFiles(repoPath);
+    }
+    catch (err) {
+        const code = err?.code;
+        log(`Metadata reconciliation failed (non-critical${code ? `, ${code}` : ''}); continuing.`);
+    }
     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

package/dist/mcp/local/local-backend.js

@@ -968,14 +968,15 @@ export class LocalBackend {
                 return; // Checked recently — skip
             this.lastStalenessCheck.set(poolKey, now);
             try {
-                // Read the meta.json that sits next to THIS handle's lbug. For the
-                // flat/primary handle this is `<storagePath>/meta.json` (unchanged);
-                // for a branch handle it is `<storagePath>/branches/<slug>/meta.json`.
+                // Read the metadata that sits next to THIS handle's lbug. For the
+                // flat/primary handle this is `<storagePath>/gitnexus.json`; for a
+                // branch handle it is `<storagePath>/branches/<slug>/gitnexus.json`.
+                // loadMeta falls back to legacy meta.json during migration.
                 // Reading the flat meta for a branch handle would compare the branch
                 // index's indexedAt against the primary's and thrash the pool (#2106).
-                const metaPath = path.join(path.dirname(repo.lbugPath), 'meta.json');
-                const metaRaw = await fs.readFile(metaPath, 'utf-8');
-                const meta = JSON.parse(metaRaw);
+                const meta = await loadMeta(path.dirname(repo.lbugPath));
+                if (!meta)
+                    return;
                 // Compare against the last indexedAt OBSERVED for this pool (keyed by
                 // lbugPath), not the handle's — branch handles are fresh spreads so a
                 // handle mutation would not persist and would reinit on every check.

package/dist/storage/fs-atomic.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Rename with retry on transient EBUSY/EPERM/EACCES (observed on Windows
+ * when a concurrent reader holds the target file open).
+ */
+export declare function retryRename(src: string, dst: string, attempts?: number): Promise<void>;

package/dist/storage/fs-atomic.js

@@ -0,0 +1,28 @@
+/**
+ * Atomic file-write primitives shared across storage/ and core/group/.
+ *
+ * `retryRename` originated in core/group/bridge-db.ts; it lives here so
+ * storage/repo-manager.ts can use it without introducing a storage/ ->
+ * core/group/ import (the established direction is core/group/ -> storage/,
+ * e.g. core/group/service.ts already imports loadMeta from here).
+ */
+import fsp from 'fs/promises';
+const RETRY_CODES = new Set(['EBUSY', 'EPERM', 'EACCES']);
+/**
+ * Rename with retry on transient EBUSY/EPERM/EACCES (observed on Windows
+ * when a concurrent reader holds the target file open).
+ */
+export async function retryRename(src, dst, attempts = 3) {
+    for (let i = 1; i <= attempts; i++) {
+        try {
+            await fsp.rename(src, dst);
+            return;
+        }
+        catch (err) {
+            const code = err.code;
+            if (!code || !RETRY_CODES.has(code) || i === attempts)
+                throw err;
+            await new Promise((r) => setTimeout(r, 100 * Math.pow(2, i - 1)));
+        }
+    }
+}