gitnexus 1.6.10-rc.21 → 1.6.10-rc.211

package/dist/types/pipeline.d.ts

@@ -2,7 +2,9 @@ import type { KnowledgeGraph } from '../core/graph/types.js';
 import { CommunityDetectionResult } from '../core/ingestion/community-processor.js';
 import { ProcessDetectionResult } from '../core/ingestion/process-processor.js';
 import type { ResolutionOutcome } from '../core/ingestion/scope-resolution/resolution-outcome.js';
+import type { UndecidedSatisfaction } from '../core/ingestion/scope-resolution/contract/scope-resolver.js';
 import type { PdgEmitManifest } from '../core/lbug/pdg-emit-sink.js';
+import type { GraphEmitManifest } from '../core/lbug/graph-emit-sink.js';
 export interface PipelineResult {
     graph: KnowledgeGraph;
     /** Absolute path to the repo root — used for lazy file reads during LadybugDB loading */
@@ -17,6 +19,16 @@ export interface PipelineResult {
      * produced; graph edge semantics are unchanged.
      */
     resolutionOutcomes: readonly ResolutionOutcome[];
+    /**
+     * Interfaces whose structural-satisfaction check could not be completed
+     * (#2873). Empty for languages with no structural detection.
+     *
+     * ABSENT means scope resolution never ran, which is not the same claim as an
+     * empty array — that one says the analyzer looked and decided everything.
+     * The writer needs the difference: it carries a prior record forward across a
+     * run that could not measure, and CLEARS it on a run that measured clean.
+     */
+    undecidedSatisfaction?: readonly UndecidedSatisfaction[];
     /**
      * True if a worker pool was actually constructed for this run. The worker
      * pool is the sole parse path (sequential parsing was removed). False means
@@ -34,4 +46,29 @@ export interface PipelineResult {
      * layer (if any) is resident in `graph` and persists via the whole-graph emit.
      */
     pdgEmitManifest?: PdgEmitManifest;
+    /**
+     * Streamed structural-emit COPY manifest (#2680). Present only when
+     * `streamGraphEmit` was active (full rebuild + enabled): the per-pair CSVs of
+     * relationships that never entered the in-memory graph, for `loadGraphToLbug`
+     * to COPY ALONGSIDE the whole-graph CSVs (their pair keys overlap, so they are
+     * additional COPY jobs, not map entries).
+     */
+    graphEmitManifest?: GraphEmitManifest;
+    /**
+     * Property-inference facts from scope resolution (R3-1). Present so a caller
+     * — a test, the CLI, or a future MCP surface — can tell WHY a field has no
+     * ACCESSES rows: genuinely unread, ambiguous between candidates, or anchored
+     * only in a language the per-language inference may not cross. Those are
+     * three different situations with three different remedies, and without this
+     * they produce byte-identical empty results.
+     */
+    propertyInference?: {
+        readonly ambiguous: number;
+        readonly ambiguousNames: readonly string[];
+        readonly crossLanguage: number;
+        readonly crossLanguageNames: readonly {
+            readonly name: string;
+            readonly languages: string[];
+        }[];
+    };
 }

package/hooks/antigravity/gitnexus-antigravity-hook.cjs

@@ -503,7 +503,7 @@ function buildStaleIndexHint(gitNexusDir, cwd) {
 
   if (currentHead === lastCommit) return '';
 
-  const analyzeCmd = formatAnalyzeCommand({ embeddings: hadEmbeddings });
+  const analyzeCmd = formatAnalyzeCommand({ embeddings: hadEmbeddings, indexOnly: true });
   return (
     `[GitNexus] index is stale (last indexed: ${lastCommit ? lastCommit.slice(0, 7) : 'never'}). ` +
     `Run \`${analyzeCmd}\` to refresh the knowledge graph.`

package/hooks/claude/gitnexus-hook.cjs

@@ -523,7 +523,7 @@ function handlePostToolUse(input) {
   // If HEAD matches last indexed commit, no reindex needed
   if (currentHead && currentHead === lastCommit) return;
 
-  const analyzeCmd = formatAnalyzeCommand({ embeddings: hadEmbeddings });
+  const analyzeCmd = formatAnalyzeCommand({ embeddings: hadEmbeddings, indexOnly: true });
   sendHookResponse(
     'PostToolUse',
     `GitNexus index is stale (last indexed: ${lastCommit ? lastCommit.slice(0, 7) : 'never'}). ` +

package/hooks/claude/resolve-analyze-cmd.cjs

@@ -5,9 +5,19 @@
  * 1. Global `gitnexus` on PATH (best — no install step)
  * 2. npm 11+ with pnpm on PATH → `pnpm --allow-build=… dlx` (avoids the npx
  *    arborist crash *and* pnpm 10+ ignored-build-script failures, #1939)
- * 3. npm < 11 with npm on PATH → `npx` (works; simpler than pnpm dlx)
- * 4. pnpm-only → `pnpm --allow-build=… dlx`
- * 5. Last resort → `npx` (warned on npm 11+ from analyze.ts)
+ * 3. npm 11+ without pnpm but with bunx → `bunx` (dodges the same crash)
+ * 4. npm < 11 with npm on PATH → `npx` (works; simpler than pnpm dlx)
+ * 5. pnpm-only → `pnpm --allow-build=… dlx`
+ * 6. bun-only → `bunx`
+ * 7. Last resort → `npx` (warned on npm 11+ from analyze.ts)
+ *
+ * The bun branches exist because a Node toolchain is no longer implied: on a
+ * bun-only machine npm, npx and pnpm are all absent, so every rung above
+ * resolved to `npx` and the emitted command could not run at all. `bunx` is
+ * bun's install-free one-shot runner and needs no allow-build equivalent — bun
+ * skips lifecycle scripts unconditionally for a `bunx` fetch, which the native
+ * loader recovers from directly (see core/lbug/native-check.ts). Both bun rungs
+ * gate on `bunx` actually running, not merely existing on PATH — see `hasBun`.
  *
  * The `--allow-build` flags MUST precede the `dlx` token. pnpm < 10.14 keeps
  * `dlx` in its argv escape list, so flags placed *after* `dlx` are parsed as
@@ -42,7 +52,12 @@ const PNPM_ALLOW_BUILD_EMBEDDINGS = ['onnxruntime-node'];
 // hook first runs `git rev-parse --git-common-dir` (~2s) and `git rev-parse HEAD`
 // (~3s); the pnpm path then adds up to two 1s `--version` probes (npm, pnpm), so
 // the worst case is ~7s — within budget. A healthy `--version` returns in well
-// under a second, so the realistic cost is far lower.
+// under a second, so the realistic cost is far lower. The bun rungs add at most
+// one more 1s probe (`bunx --version`), reached only when pnpm is unusable and
+// npm is 11+ or unreadable, for a ~8s theoretical cap. That cap needs an absent
+// pnpm to burn its full second, which only Windows can do (`shell: true` spawns
+// cmd.exe); on POSIX an absent pnpm ENOENTs in ~1ms, so the real ceiling is
+// unmoved.
 const PROBE_TIMEOUT_MS = 1000;
 
 /**
@@ -104,9 +119,17 @@ function resolveOnPath(
   return weakHit;
 }
 
-// One spawn of `<command> --version` → { major, minor } (each null when
+// One spawn of `<command> --version` → { ran, major, minor } (versions null when
 // unreadable). Version injection happens at the resolver seam (getNpmMajorVersion
 // / formatPnpmAllowBuildArgs), so this stays a pure real-process probe.
+//
+// `ran` is liveness, kept separate from the version because a PATH hit proves a
+// file exists, not that it works, and the two answers differ: a banner-printing
+// or oddly-versioned tool is alive with `major: null`, while a stale shim left by
+// a partial uninstall is neither. Only the bun rung consults `ran` today (see
+// hasBun) — it is the one runner with no version to read, so a dedicated probe is
+// its only liveness signal; pnpm gets the same evidence for free from the version
+// spawn it must make anyway, and deliberately forgives an unreadable one (#1939).
 function probeVersion(command) {
   try {
     const output = execFileSync(command, ['--version'], {
@@ -131,11 +154,13 @@ function probeVersion(command) {
       .find((l) => /^v?\d+\.\d+/.test(l));
     const match = versionLine ? versionLine.match(/^v?(\d+)\.(\d+)/) : null;
     return {
+      ran: true,
       major: match ? Number(match[1]) : null,
       minor: match ? Number(match[2]) : null,
     };
   } catch {
-    return { major: null, minor: null };
+    // Spawn failure, non-zero exit, or the timeout — the command did not run.
+    return { ran: false, major: null, minor: null };
   }
 }
 
@@ -176,14 +201,14 @@ function formatDocumentationDlxCommand(gitnexusArgs, options = {}) {
 }
 
 /**
- * Resolve `gitnexus` | `pnpm` | `npx`. `GITNEXUS_INVOCATION` forces a mode
- * (test/escape hatch). `probe` is injectable so the preference order can be
+ * Resolve `gitnexus` | `pnpm` | `bun` | `npx`. `GITNEXUS_INVOCATION` forces a
+ * mode (test/escape hatch). `probe` is injectable so the preference order can be
  * unit-tested without spawning; it defaults to the real PATH probe. `deps` can
- * inject `{ npmMajor, pnpmMajor }` for tests.
+ * inject `{ npmMajor, pnpmMajor, bunPresent, bunRuns }` for tests.
  */
 function resolveInvocationMode(probe = resolveOnPath, deps = {}) {
   const forced = process.env.GITNEXUS_INVOCATION?.trim().toLowerCase();
-  if (forced === 'gitnexus' || forced === 'pnpm' || forced === 'npx') {
+  if (forced === 'gitnexus' || forced === 'pnpm' || forced === 'npx' || forced === 'bun') {
     return forced;
   }
   if (probe('gitnexus', true)) return 'gitnexus';
@@ -202,12 +227,33 @@ function resolveInvocationMode(probe = resolveOnPath, deps = {}) {
         ? deps.pnpmMajor !== null
         : Boolean(probe('pnpm'));
 
+  // bun usability is resolved lazily: only the two branches below can select it,
+  // so a machine with pnpm, or with npm < 11, never pays the PATH scan or the
+  // spawn. `bunx` (not `bun`) is probed because `bunx` is what the resolved
+  // command actually runs. Two gates, `&&`-ordered cheapest first: a spawn-free
+  // PATH scan, then liveness — a PATH hit alone would route a present-but-broken
+  // shim to a command that can only fail at execution time.
+  let bunCache;
+  const hasBun = () => {
+    if (bunCache === undefined) {
+      const present = 'bunPresent' in deps ? Boolean(deps.bunPresent) : Boolean(probe('bunx'));
+      bunCache = present && ('bunRuns' in deps ? Boolean(deps.bunRuns) : probeVersion('bunx').ran);
+    }
+    return bunCache;
+  };
+
   // npm 11+ npx install crash (#1939) — prefer pnpm dlx when available.
   if (hasPnpm && npmMajor !== null && npmMajor >= 11) return 'pnpm';
+  // Same crash, no pnpm to fall back on: bunx is install-free and unaffected.
+  if (npmMajor !== null && npmMajor >= 11 && hasBun()) return 'bun';
   // npm 10 and earlier: npx works; prefer it over pnpm dlx when npm is present.
   if (npmMajor !== null && npmMajor < 11) return 'npx';
   // npm absent or unreadable — use pnpm if present (with allow-build flags).
   if (hasPnpm) return 'pnpm';
+  // Neither npm nor pnpm — bunx is the only install-free runner left. Without
+  // this rung a bun-only machine fell through to `npx`, which is not installed
+  // there, so the emitted command failed with "npx: command not found".
+  if (hasBun()) return 'bun';
 
   return 'npx';
 }
@@ -218,8 +264,25 @@ function formatPnpmDlxCommand(gitnexusArgs, options = {}, deps = {}) {
   return `pnpm ${prefix}dlx ${NPX_REF} ${gitnexusArgs}`;
 }
 
+/**
+ * bun's install-free one-shot runner. Deliberately flag-free: bun has no
+ * per-invocation `--allow-build` equivalent (`--trust` is a `bun add`/`bun
+ * install` flag that writes trustedDependencies into a project package.json,
+ * which a one-shot `bunx` has nowhere to put), so the skipped lifecycle copy is
+ * recovered by the native loader instead of by the invocation.
+ */
+function formatBunxCommand(gitnexusArgs) {
+  return `bunx ${NPX_REF} ${gitnexusArgs}`;
+}
+
 function formatAnalyzeCommand(options = {}, deps = {}) {
-  const suffix = options.embeddings ? ' --embeddings' : '';
+  // `--index-only` is what a routine "your index is stale" nudge wants: it
+  // reindexes without rewriting AGENTS.md / CLAUDE.md / skills, so an agent
+  // following the nudge on every commit cannot churn the tracked agent guides
+  // (#2907). Callers that actually want the docs refreshed omit it.
+  const suffix = `${options.indexOnly ? ' --index-only' : ''}${
+    options.embeddings ? ' --embeddings' : ''
+  }`;
   // Keep the stale-index hook budget tight by querying each tool at most once.
   // The memoized `probe` is a spawn-free PATH scan (resolveOnPath) shared with
   // resolveInvocationMode, so `gitnexus` is scanned only once and no subprocess
@@ -238,7 +301,8 @@ function formatAnalyzeCommand(options = {}, deps = {}) {
     const forced = process.env.GITNEXUS_INVOCATION?.trim().toLowerCase();
     // pnpm is only consulted when no non-pnpm mode is already certain: forced
     // gitnexus/npx never use pnpm, and a present global gitnexus wins outright.
-    const mightUsePnpm = forced === 'pnpm' || (forced !== 'gitnexus' && forced !== 'npx');
+    const mightUsePnpm =
+      forced === 'pnpm' || (forced !== 'gitnexus' && forced !== 'npx' && forced !== 'bun');
     if (mightUsePnpm && (forced === 'pnpm' || !probe('gitnexus', true))) {
       const { major, minor } = probeVersion('pnpm');
       // Carry presence separately from version: when the version probe fails
@@ -252,6 +316,7 @@ function formatAnalyzeCommand(options = {}, deps = {}) {
   const mode = resolveInvocationMode(probe, resolved);
   if (mode === 'gitnexus') return `gitnexus analyze${suffix}`;
   if (mode === 'pnpm') return `${formatPnpmDlxCommand(`analyze${suffix}`, options, resolved)}`;
+  if (mode === 'bun') return formatBunxCommand(`analyze${suffix}`);
   return `npx ${NPX_REF} analyze${suffix}`;
 }
 
@@ -268,6 +333,7 @@ function buildRunnerArgv(mode, gitnexusArgs, deps = {}) {
     (a) => a === '--embeddings' || a.startsWith('--embeddings='),
   );
   if (mode === 'gitnexus') return { program: 'gitnexus', args: [...gitnexusArgs] };
+  if (mode === 'bun') return { program: 'bunx', args: [NPX_REF, ...gitnexusArgs] };
   if (mode === 'pnpm') {
     return {
       program: 'pnpm',
@@ -279,6 +345,7 @@ function buildRunnerArgv(mode, gitnexusArgs, deps = {}) {
 
 module.exports = {
   formatAnalyzeCommand,
+  formatBunxCommand,
   formatDocumentationDlxCommand,
   formatPnpmAllowBuildArgs,
   formatPnpmDlxCommand,
@@ -291,7 +358,7 @@ module.exports = {
 };
 
 // Direct-exec entrypoint (#1945): `node run.cjs <gitnexus args…>` resolves the
-// best available runner (global `gitnexus` → `pnpm dlx` → `npx`) at call time and
+// best available runner (global `gitnexus` → `pnpm dlx` → `bunx` → `npx`) at call time and
 // runs it, inheriting stdio and propagating the child's exit code. This lets the
 // committed skills and generated AGENTS.md/CLAUDE.md reference ONE stable,
 // CLI-neutral command without baking in a package-manager assumption. `gitnexus

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.10-rc.21",
+  "version": "1.6.10-rc.211",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",
@@ -52,10 +52,11 @@
     "postinstall": "node scripts/build-tree-sitter-grammars.cjs",
     "assert-publish-coverage": "node scripts/assert-publish-grammar-coverage.cjs",
     "prepare": "node scripts/build.js",
-    "prepack": "node scripts/assert-publish-grammar-coverage.cjs && node scripts/build.js"
+    "prepack": "node scripts/assert-publish-grammar-coverage.cjs && node scripts/build.js",
+    "version": "node scripts/sync-plugin-manifests.mjs"
   },
   "dependencies": {
-    "@ladybugdb/core": "^0.18.0",
+    "@ladybugdb/core": "^0.19.0",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@scarf/scarf": "^1.4.0",
     "busboy": "^1.6.0",
@@ -69,7 +70,7 @@
     "graphology-indices": "^0.17.0",
     "graphology-utils": "^2.3.0",
     "ignore": "^7.0.5",
-    "js-yaml": "^4.1.1",
+    "js-yaml": "^5.0.0",
     "jsonc-parser": "^3.3.1",
     "mnemonist": "^0.40.3",
     "node-addon-api": "^8.0.0",
@@ -78,6 +79,7 @@
     "pandemonium": "^2.4.0",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
+    "proxy-addr": "^2.0.7",
     "tree-sitter": "0.21.1",
     "tree-sitter-c-sharp": "0.23.1",
     "tree-sitter-cpp": "0.23.2",
@@ -95,18 +97,22 @@
     "@huggingface/transformers": "^4.1.0",
     "onnxruntime-node": "^1.24.0"
   },
+  "trustedDependencies": [
+    "@ladybugdb/core",
+    "gitnexus",
+    "tree-sitter"
+  ],
   "devDependencies": {
-    "@babel/generator": "^7.29.7",
-    "@babel/parser": "^7.29.7",
-    "@babel/traverse": "^7.29.7",
-    "@babel/types": "^7.29.7",
+    "@babel/generator": "^8.0.0",
+    "@babel/parser": "^8.0.0",
+    "@babel/traverse": "^8.0.0",
+    "@babel/types": "^8.0.0",
     "@types/busboy": "^1.5.4",
     "@types/cli-progress": "^3.11.6",
     "@types/cors": "^2.8.17",
     "@types/express": "^5.0.6",
-    "@types/js-yaml": "^4.0.9",
-    "@types/node": "^25.6.0",
-    "@types/uuid": "^11.0.0",
+    "@types/node": "^26.0.0",
+    "@types/proxy-addr": "^2.0.3",
     "@vitest/coverage-v8": "^4.0.18",
     "gitnexus-shared": "file:../gitnexus-shared",
     "tsx": "^4.0.0",
@@ -114,11 +120,13 @@
     "vitest": "^4.0.18"
   },
   "overrides": {
+    "adm-zip": ">=0.6.0",
+    "sharp": ">=0.35.0",
     "@huggingface/transformers": {
       "onnxruntime-node": "$onnxruntime-node"
     }
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": "^22.18.0 || >=24.11.0"
   }
 }

package/scripts/cross-platform-shard.ts

@@ -0,0 +1,143 @@
+/**
+ * Weight-aware partitioning for the cross-platform test matrix.
+ *
+ * WHY THIS EXISTS. `run-cross-platform.ts` used to hand vitest the whole file
+ * list plus `--shard=i/n`, and vitest partitions by file COUNT. Runtime on this
+ * suite is wildly uneven — measured on the Windows runner, `cli-e2e` is 361 s
+ * and `worker-pool` 221 s, while most files are under a second — so a
+ * count-split routinely put several of the heaviest suites on one shard. That
+ * is #2449, and this file's sibling header has documented the symptom ("the
+ * heaviest spawn suites can cluster on one shard") since the watchdog was first
+ * raised from 15 to 20 minutes.
+ *
+ * It went from a latent hazard to a red matrix when three CHEAP files (the
+ * `dist/` module-load closure guards: 448 ms, 53 ms, sub-second) were added to
+ * `SPAWN_CLI`. They cost nothing to run, but a count-split re-partitions on
+ * every insertion, and the reshuffle happened to land `cli-e2e` + `cli-limit-e2e`
+ * + `analyze-heap-oom-e2e` together on shard 1/3 — 32 files against 26 and 29 —
+ * which blew the 20-minute budget with four files still queued. Nothing about
+ * the added files caused it; they were simply the perturbation.
+ *
+ * So the split is done HERE, by weight, and only the chosen shard's files are
+ * handed to vitest. Two properties follow, and both are pinned in
+ * `test/unit/cross-platform-shard.test.ts`:
+ *
+ *  - the heaviest suites are spread across shards by construction, so the
+ *    busiest shard tracks the ideal rather than the luck of the sort order;
+ *  - adding or removing a CHEAP file cannot move a heavy one, so registering a
+ *    new platform-sensitive test is no longer a CI-stability gamble. That is the
+ *    property whose absence caused this.
+ */
+
+/**
+ * Measured wall-clock on the WINDOWS runner (the slowest platform, so it is the
+ * one that decides the budget), in seconds, from the last fully-green matrix run
+ * plus the timed files of the run that failed.
+ *
+ * Only files heavy enough to matter are listed; everything else is carried by
+ * {@link PER_FILE_OVERHEAD_SEC} alone. These are load-balancing hints, NOT
+ * assertions — no
+ * test asserts a runtime, and drift only makes the split slightly less even, so
+ * a stale entry is harmless and refreshing them is optional. Deliberately not
+ * auto-generated: a committed table is reviewable and works offline, and the
+ * alternative (timing files at CI runtime to decide the split) would make the
+ * partition depend on the very machine load it is trying to protect against.
+ */
+export const WINDOWS_WEIGHTS_SEC: Readonly<Record<string, number>> = {
+  'test/integration/cli-e2e.test.ts': 361,
+  'test/integration/worker-pool.test.ts': 222,
+  'test/unit/incremental-vector-extension-ordering.test.ts': 87,
+  // ESTIMATE, not a measurement (#2841): this suite drives more full
+  // `runFullAnalysis` cycles than the VECTOR sibling above, so the 8 s
+  // PER_FILE_OVERHEAD floor would badly under-charge it and skew the Windows
+  // split — the failure mode that produced the job timeouts this table exists
+  // to prevent. Scaled from the sibling's measured 87 s by analyze-run count.
+  // Replace with a real figure after the first green Windows matrix run.
+  'test/unit/incremental-index-extension-dml-gate.test.ts': 180,
+  'test/integration/cli-limit-e2e.test.ts': 75,
+  'test/unit/hooks.test.ts': 26,
+  'test/integration/analyze-heap-oom-e2e.test.ts': 23,
+  'test/unit/git-utils.test.ts': 18,
+  'test/integration/hooks-e2e.test.ts': 15,
+  'test/integration/tree-sitter-languages.test.ts': 9,
+  'test/unit/repo-manager.test.ts': 9,
+  'test/unit/detect-changes-worktree.test.ts': 9,
+  'test/integration/antigravity-hook-e2e.test.ts': 7,
+  'test/unit/index-lock.test.ts': 5,
+  'test/unit/setup.test.ts': 5,
+};
+
+/**
+ * Fixed cost every file pays regardless of what it asserts: a pool worker start,
+ * module graph evaluation, and (for most of this list) a native addon load.
+ *
+ * Added to EVERY file's weight, not just unmeasured ones, and that is the point.
+ * Calibrated against the last green Windows matrix: its busiest shard ran 736 s
+ * of wall clock over ~511 s of measured file time, so roughly 8 s per file is
+ * unattributed setup. Without this term the balancer treats a light file as
+ * nearly free and, having isolated the two monsters, piles every remaining file
+ * onto the other shards — trading a runtime imbalance for a file-count one that
+ * costs just as much. With it, the split balances runtime AND count together.
+ */
+const PER_FILE_OVERHEAD_SEC = 8;
+
+/**
+ * Scheduling weight for `file`: its measured runtime (0 if it was fast enough
+ * that vitest printed no duration) plus the per-file floor above.
+ */
+export function weightOf(file: string): number {
+  return (WINDOWS_WEIGHTS_SEC[file] ?? 0) + PER_FILE_OVERHEAD_SEC;
+}
+
+/**
+ * Partition `files` into `total` shards and return the 1-based `index` one.
+ *
+ * Longest-processing-time first: sort by weight descending, then repeatedly give
+ * the next file to the lightest shard so far. LPT is the standard greedy for
+ * multiprocessor scheduling and is guaranteed within 4/3 of optimal — far more
+ * than enough here, where the goal is only "no shard gets two monsters".
+ *
+ * Ties break on the file path so the partition is DETERMINISTIC: every shard
+ * computes the same split independently, on a different machine, with no
+ * coordination — which is what lets each runner select its own slice.
+ *
+ * Returns files in the input list's original order, not weight order, so failure
+ * output and reruns stay readable.
+ */
+export function shardFiles(
+  files: readonly string[],
+  index: number,
+  total: number,
+): readonly string[] {
+  if (!Number.isInteger(total) || total < 1) {
+    throw new Error(`shard total must be a positive integer, got ${total}`);
+  }
+  if (!Number.isInteger(index) || index < 1 || index > total) {
+    throw new Error(`shard index must be in 1..${total}, got ${index}`);
+  }
+  if (total === 1) return [...files];
+
+  const byWeightDesc = [...files].sort((a, b) => {
+    const diff = weightOf(b) - weightOf(a);
+    return diff !== 0 ? diff : a.localeCompare(b);
+  });
+
+  const loads = Array.from({ length: total }, () => 0);
+  const assigned = Array.from({ length: total }, () => new Set<string>());
+  for (const file of byWeightDesc) {
+    let lightest = 0;
+    for (let i = 1; i < total; i++) {
+      if (loads[i]! < loads[lightest]!) lightest = i;
+    }
+    assigned[lightest]!.add(file);
+    loads[lightest]! += weightOf(file);
+  }
+
+  const mine = assigned[index - 1]!;
+  return files.filter((f) => mine.has(f));
+}
+
+/** Total weight of a file set — the shard cost this balancer is minimising. */
+export function shardWeight(files: readonly string[]): number {
+  return files.reduce((sum, f) => sum + weightOf(f), 0);
+}

package/scripts/cross-platform-tests.ts

@@ -36,12 +36,46 @@ const PLATFORM_LOGIC = [
   // must exercise the Windows backslash branch, so run it on the OS matrix (#2394).
   'test/unit/cli-entry.test.ts',
   'test/unit/platform-capabilities.test.ts',
+  // The gitnexus-plan safe writer resolves every name through a per-platform
+  // backend: Linux anchors through /proc/self/fd, macOS resolves lexically and
+  // verifies each step against descriptors it holds open. Publication is link(2)
+  // on both. #2905 shipped the Darwin backend after the suite had silently
+  // skipped on every non-Linux runner, so this file must run on the OS matrix or
+  // the macOS half is unverified by construction — and the flag, trailing-
+  // separator and hard-link fixtures assert kernel behaviour that only a real
+  // Darwin kernel can confirm. Windows is refused by the capability gate; the
+  // suite asserts that refusal rather than skipping it.
+  'test/unit/evidence-provenance-helper.test.ts',
+  // Windows drive-letter case variance in the analyzer runner-identity path
+  // fields (#2668): normalizeAnalyzerRootPath is a POSIX no-op, so the
+  // "identity path fields are normalizer-stable" fixpoint guard only bites on
+  // the windows-latest matrix — it must run there, not just in the Ubuntu
+  // full-suite where it's trivially green. Deliberately the split-out
+  // normalization file, NOT analyzer-identity.test.ts: the latter's fixture
+  // tests compare identity fields against raw temp-dir paths and fail on macOS,
+  // where /var/... realpaths to /private/var/....
+  'test/unit/analyzer-identity-path-normalization.test.ts',
+  // `isInside` containment guard vs Windows cross-drive paths: path.relative
+  // returns the absolute target across drives, so the guard needs isAbsolute.
+  // Fixture-free and pathApi-injectable, so it is portable to every runner.
+  'test/unit/analyzer-identity-is-inside.test.ts',
+  // `\\?\` extended-length prefix normalization (#2667): fixture-free and
+  // platform-injectable (every assertion passes an explicit 'win32'), so like the
+  // is-inside guard above it is portable to every runner and its assertions run
+  // identically here and on Ubuntu. Registered alongside its two siblings so the
+  // Windows path-handling guards stay discoverable as one group. Same
+  // mixed-prefix relativize hazard as is-inside, reached through a
+  // caller-supplied path.
+  'test/unit/windows-long-path-prefix.test.ts',
   // getconf page-size probe: explicit process.platform gate (win32 short-circuit)
   // plus a live-probe test whose only real non-4K coverage is macos-arm64's
   // 16 KiB pages — the exact hardware class #1231 targets (#2424 review).
   'test/unit/lbug-config-pagesize.test.ts',
   'test/unit/worker-pool-windows-quarantine.test.ts',
   'test/unit/lbug-pool-fts-load.test.ts',
+  // Global registry writes use the platform-specific index-lock backend
+  // (Windows named pipe, Linux socket, or macOS file lock). This includes the
+  // overlapping-registration regression from #2716 on every OS matrix.
   'test/unit/repo-manager.test.ts',
   'test/unit/repo-manager-finalize-invariant.test.ts',
   'test/unit/git-utils.test.ts',
@@ -79,6 +113,13 @@ const PLATFORM_LOGIC = [
   // POSIX and Windows — the fail-closed path-claim semantics must hold on the
   // real windows-latest path implementation (#2419/#2420).
   'test/unit/server-api-repo-resolution.test.ts',
+  // The index write-lock (#2658) selects its backend by process.platform — the
+  // OS socket lock (Windows named pipe / Linux abstract socket) vs the file
+  // fallback — and its socket-backend describe block is gated to linux/win32.
+  // The Ubuntu suite only proves the Linux abstract-socket path, so run it here
+  // to exercise the Windows named-pipe backend and the macOS file fallback on
+  // their real platforms (#2658 review H3).
+  'test/unit/index-lock.test.ts',
 ];
 
 // Native LadybugDB integration tests — exercise the @ladybugdb/core
@@ -117,6 +158,24 @@ const LBUG_NATIVE = [
   // to a live native DB, rm-then-rename over an existing parked copy) before
   // any open — rename semantics are exactly what differs on Windows.
   'test/unit/incremental-dirty-recovery.test.ts',
+  // #2623: the incremental writeback must load VECTOR before the CodeEmbedding
+  // join-delete, and the blocked path must escalate instead of crashing. The
+  // win32 VECTOR gate was removed in the same PR, so this ordering must be
+  // proven on the windows-latest native addon, not just Ubuntu. Budget: ~25s
+  // on Linux → expect ~2min on the slowest Windows shard.
+  'test/unit/incremental-vector-extension-ordering.test.ts',
+  // #2841: the FTS half of that same gate, plus the both-extensions-blocked
+  // case — and it needs this matrix for two reasons the VECTOR sibling above
+  // does not cover. The reported failure environment is a machine where the
+  // extension stopped LOADING, which is the #2374 class and Windows-reported
+  // (the same reason fts-extension-e2e.test.ts is registered below), so the
+  // FTS-unavailable branch has to run on a real Windows/macOS runner rather
+  // than only on Ubuntu where FTS always loads. And its both-blocked case is
+  // gated on GITNEXUS_REQUIRE_VECTOR=1, which ci-tests.yml sets ONLY on this
+  // job — everywhere else an unavailable VECTOR extension skips instead of
+  // failing. Budget: four real analyze runs, so expect it to sit alongside the
+  // VECTOR sibling's ~87s Windows measurement.
+  'test/unit/incremental-index-extension-dml-gate.test.ts',
 ];
 
 // Process spawning and CLI tests — exercise child_process with real
@@ -141,6 +200,41 @@ const SPAWN_CLI = [
   'test/integration/antigravity-hook-e2e.test.ts',
   'test/unit/local-cli-subprocess.test.ts',
   'test/unit/runner-exec-tail.test.ts',
+  // Real cross-process single-writer lock coordination (#2658): child processes
+  // contend for the lock and race to reclaim a dead holder. Process spawning,
+  // kernel socket auto-release (Win named pipe / Linux abstract socket), and the
+  // FILE-backend rename-steal reclaim (macOS/BSD default) all vary across OSes —
+  // the exact behaviors the Windows/macOS matrix must prove. macOS timing first
+  // exposed a file-backend double-admit race here (#2658 review); the reclaim is
+  // now judgment-verified so a live holder is never displaced.
+  'test/integration/analyze-index-lock-concurrency.test.ts',
+  // The three `dist/` module-load closure guards, all built on the shared
+  // child-process probe in `test/helpers/module-load-probe.ts`. That probe IS
+  // the platform-varying part: it spawns `process.execPath` in array form,
+  // clears NODE_OPTIONS, addresses its target via `pathToFileURL` (Windows needs
+  // the `file:///C:/...` form — a bare absolute path is not a valid ESM
+  // specifier there), and renders every result through a `path.sep`→POSIX
+  // normalisation the anchors and offender regexes depend on. None of that is
+  // proven anywhere else.
+  //
+  // Cheap: measured on the Windows runner at 448 ms, 53 ms and sub-second. An
+  // earlier attempt to register them still turned the matrix red — not from
+  // their own cost, but because vitest sharded by file COUNT, so inserting any
+  // file re-partitioned the list and happened to cluster `cli-e2e` (361 s) with
+  // `cli-limit-e2e` (75 s) on one shard. The split is weight-aware now
+  // (`scripts/cross-platform-shard.ts`), so a cheap file can no longer move a
+  // heavy one.
+  //
+  // #2802: MCP startup must not eagerly load the analyze-only language
+  // provider registry or the group contract extractors.
+  'test/integration/mcp/startup-language-closure.test.ts',
+  // PR #1383: `cli/mcp.js`'s static-import closure must stay leaf-only so no
+  // native binding initialises before the stdout sentinel installs.
+  'test/integration/mcp/import-closure.test.ts',
+  // #2091/#2093/#2116: the scope-resolution registry must not load the optional
+  // tree-sitter grammars at import time. The offender regexes match grammar
+  // paths with either separator, which only the Windows runner proves.
+  'test/integration/optional-grammars/registry-import-closure.test.ts',
 ];
 
 // Worker threads tests — exercise real worker_threads which have

package/scripts/ensure-fts.ts

@@ -1,6 +1,6 @@
 /**
- * Install the LadybugDB FTS extension into the shared home (~/.lbdb) up front, so
- * every test in a sharded CI run finds it regardless of which shard it lands in.
+ * Install the LadybugDB FTS and VECTOR extensions into the shared home (~/.lbdb)
+ * up front, so every test in a sharded CI run finds them regardless of shard.
  *
  * FTS-dependent tests split two ways: the LOAD-path gate (skipUnlessFtsAvailable)
  * self-installs on miss, but the FILE-path gate (requireFtsResourceOrSkip, e.g.
@@ -17,13 +17,24 @@
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { initLbug, loadFTSExtension, closeLbug } from '../src/core/lbug/lbug-adapter.js';
+import {
+  initLbug,
+  loadFTSExtension,
+  loadVectorExtension,
+  closeLbug,
+} from '../src/core/lbug/lbug-adapter.js';
 
 const dir = mkdtempSync(join(tmpdir(), 'gn-ensure-fts-'));
 try {
   await initLbug(join(dir, 'ensure-fts.lbug'));
   const ok = await loadFTSExtension(undefined, { policy: 'auto' });
   console.log(ok ? 'FTS extension ready.' : 'FTS extension unavailable (continuing).');
+  // VECTOR rides the same pre-install (#2623): the win32 gate is gone, so the
+  // vector suites genuinely run on Windows/macOS — installing once here means
+  // every sharded test process LOADs from ~/.lbdb instead of racing its own
+  // out-of-process INSTALL (bounded 15s each when the server is unreachable).
+  const vec = await loadVectorExtension(undefined, { policy: 'auto' });
+  console.log(vec ? 'VECTOR extension ready.' : 'VECTOR extension unavailable (continuing).');
 } catch (err) {
   console.warn(`ensure-fts: skipped (${err instanceof Error ? err.message : String(err)})`);
 } finally {