gitnexus 1.6.5-rc.2 → 1.6.5-rc.21

package/dist/storage/git.d.ts

@@ -108,13 +108,24 @@ export declare const hasGitDir: (dirPath: string) => boolean;
  */
 export declare const getRemoteOriginUrl: (repoPath: string) => string | null;
 /**
- * Parse a repository name out of a git remote URL. Handles the common
- * SSH (`git@host:owner/repo.git`), HTTPS (`https://host/owner/repo.git`),
- * `git://`, `ssh://`, and `file://` shapes. Returns `null` for empty /
- * unparseable input.
+ * Sanitize a repository name to prevent argument injection and ensure
+ * cross-platform filesystem compatibility.
  *
- * The heuristic: strip a trailing `.git` and trailing slashes, then
- * take the segment after the last `/` or `:`.
+ * 1. Strips leading dashes to prevent git command-line argument injection
+ *    (e.g., --upload-pack=evil).
+ * 2. Replaces characters that are unsafe for directory names across
+ *    platforms (Windows/macOS/Linux) with underscores.
+ * 3. Blocks path traversal segments ("." and "..") and Windows reserved
+ *    names (e.g., CON, NUL) to prevent directory escape.
+ */
+export declare const sanitizeRepoName: (name: string) => string;
+/**
+ * Parse a repository name out of a git remote URL. Handles common shapes
+ * including SSH (git@host:owner/repo.git) and HTTPS (https://host/owner/repo.git).
+ *
+ * Returns a sanitized, filesystem-safe name or null if no name could be inferred.
+ * Returning null (rather than 'unknown') allows callers to use ?? null-coalescing
+ * for fallbacks without risk of registry collisions on 'unknown'.
  */
 export declare const parseRepoNameFromUrl: (url: string | null | undefined) => string | null;
 /**

package/dist/storage/git.js

@@ -257,13 +257,36 @@ export const getRemoteOriginUrl = (repoPath) => {
     }
 };
 /**
- * Parse a repository name out of a git remote URL. Handles the common
- * SSH (`git@host:owner/repo.git`), HTTPS (`https://host/owner/repo.git`),
- * `git://`, `ssh://`, and `file://` shapes. Returns `null` for empty /
- * unparseable input.
+ * Sanitize a repository name to prevent argument injection and ensure
+ * cross-platform filesystem compatibility.
  *
- * The heuristic: strip a trailing `.git` and trailing slashes, then
- * take the segment after the last `/` or `:`.
+ * 1. Strips leading dashes to prevent git command-line argument injection
+ *    (e.g., --upload-pack=evil).
+ * 2. Replaces characters that are unsafe for directory names across
+ *    platforms (Windows/macOS/Linux) with underscores.
+ * 3. Blocks path traversal segments ("." and "..") and Windows reserved
+ *    names (e.g., CON, NUL) to prevent directory escape.
+ */
+export const sanitizeRepoName = (name) => {
+    // 1. Prevent argument injection by stripping leading dashes.
+    // 2. Remove characters that are not alphanumerics, dots, underscores, or dashes.
+    const sanitized = name.replace(/^-+/, '').replace(/[^a-zA-Z0-9._-]/g, '_');
+    // 3. Block path traversal segments and Windows reserved names.
+    // Windows reserved names like CON, PRN, AUX, NUL, COM1-9, LPT1-9 cannot
+    // be used as directory names on Windows even if they have an extension.
+    const reserved = /^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(\..*)?$/i;
+    if (!sanitized || sanitized === '.' || sanitized === '..' || reserved.test(sanitized)) {
+        return 'unknown';
+    }
+    return sanitized;
+};
+/**
+ * Parse a repository name out of a git remote URL. Handles common shapes
+ * including SSH (git@host:owner/repo.git) and HTTPS (https://host/owner/repo.git).
+ *
+ * Returns a sanitized, filesystem-safe name or null if no name could be inferred.
+ * Returning null (rather than 'unknown') allows callers to use ?? null-coalescing
+ * for fallbacks without risk of registry collisions on 'unknown'.
  */
 export const parseRepoNameFromUrl = (url) => {
     if (!url)
@@ -271,12 +294,23 @@ export const parseRepoNameFromUrl = (url) => {
     const trimmed = url.trim();
     if (!trimmed)
         return null;
-    // Strip `.git` suffix (case-insensitive) and any trailing slashes.
-    const withoutSuffix = trimmed.replace(/\.git\/*$/i, '').replace(/\/+$/, '');
-    // Last path segment, splitting on either `/` or `:` (covers SSH form).
-    const m = withoutSuffix.match(/[/:]([^/:]+)$/);
-    const candidate = m ? m[1] : withoutSuffix;
-    return candidate || null;
+    // Strip trailing slashes without a regex to avoid polynomial-ReDoS on
+    // pathological inputs like `https://x.com/y` + '/'.repeat(1e6).
+    let end = trimmed.length;
+    while (end > 0 && trimmed.charCodeAt(end - 1) === 47 /* '/' */)
+        end--;
+    let cleaned = trimmed.slice(0, end);
+    // Strip trailing .git (case-insensitive)
+    if (cleaned.toLowerCase().endsWith('.git')) {
+        cleaned = cleaned.slice(0, -4);
+    }
+    // Last path segment, handling colons for SSH URLs and path traversal.
+    // Split on both / and : to consistently extract the last part.
+    const candidate = cleaned.split(/[/:]/).pop() || '';
+    if (!candidate)
+        return null;
+    const safe = sanitizeRepoName(candidate);
+    return safe === 'unknown' ? null : safe;
 };
 /**
  * Convenience wrapper: derive a registry-friendly name from the repo's

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

@@ -0,0 +1,67 @@
+/**
+ * Chunk-level content-addressed parse cache.
+ *
+ * The pipeline always parses every file (correctness invariant: cross-file
+ * resolution and downstream phases need full graph data). What this cache
+ * does is skip the tree-sitter worker dispatch when a chunk's contents
+ * haven't changed since the last run.
+ *
+ * Granularity: chunk-level. The parse phase chunks files into ~20MB byte
+ * budgets. The cache key is `sha256(joined(filePath:contentHash for each
+ * file in the chunk, sorted))`. A change to a single file invalidates only
+ * that file's chunk — typically 1 of ~50 chunks on a 1000-file repo.
+ *
+ * Why not per-file:
+ * - Workers process sub-batches and emit aggregated `ParseWorkerResult`s.
+ *   Splitting back to per-file would require reworking the worker contract.
+ * - Chunk-level invalidation gives a useful speedup floor (98% on a single
+ *   1-of-50 invalidated chunk) without touching the worker.
+ *
+ * Survives `--force` because it's content-addressed: the same bytes always
+ * produce the same key. `--force` only matters for the LadybugDB writeback;
+ * the cache itself is always safe to reuse.
+ */
+import type { ParseWorkerResult } from '../core/ingestion/workers/parse-worker.js';
+export declare const PARSE_CACHE_VERSION: string;
+/** Runtime view: keyed Map for fast lookup; mutated in place during a run. */
+export interface ParseCache {
+    version: string;
+    entries: Map<string, ParseWorkerResult[]>;
+    /**
+     * Hashes referenced (hit OR miss-and-stored) by the current run.
+     * The parse phase populates this as it processes chunks; the orchestrator
+     * uses it as input to `pruneCache` before saving so entries that no
+     * longer correspond to any chunk in the current scan are discarded.
+     * Transient — never serialized to disk.
+     */
+    usedKeys: Set<string>;
+}
+/** Stable hash of a single file's contents — used by callers to compose a chunk hash. */
+export declare const fileContentHash: (content: Buffer | string) => string;
+/**
+ * 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 declare const computeChunkHash: (entries: Array<{
+    filePath: string;
+    contentHash: string;
+}>) => string;
+/**
+ * Load the parse cache. Returns an empty cache on any failure (missing
+ * file, corrupt JSON, version mismatch). Never throws on a normal load.
+ */
+export declare const loadParseCache: (storagePath: string) => Promise<ParseCache>;
+/**
+ * Persist the cache to disk atomically (write-and-rename) so a crash
+ * mid-write doesn't leave a corrupt file.
+ */
+export declare const saveParseCache: (storagePath: string, cache: ParseCache) => Promise<void>;
+/**
+ * Drop entries whose hashes are not in `usedHashes`. Called at the end
+ * of a run so chunks that no longer correspond to any current chunk
+ * don't keep their stale entries forever.
+ */
+export declare const pruneCache: (cache: ParseCache, usedHashes: ReadonlySet<string>) => number;

package/dist/storage/parse-cache.js

@@ -0,0 +1,182 @@
+/**
+ * Chunk-level content-addressed parse cache.
+ *
+ * The pipeline always parses every file (correctness invariant: cross-file
+ * resolution and downstream phases need full graph data). What this cache
+ * does is skip the tree-sitter worker dispatch when a chunk's contents
+ * haven't changed since the last run.
+ *
+ * Granularity: chunk-level. The parse phase chunks files into ~20MB byte
+ * budgets. The cache key is `sha256(joined(filePath:contentHash for each
+ * file in the chunk, sorted))`. A change to a single file invalidates only
+ * that file's chunk — typically 1 of ~50 chunks on a 1000-file repo.
+ *
+ * Why not per-file:
+ * - Workers process sub-batches and emit aggregated `ParseWorkerResult`s.
+ *   Splitting back to per-file would require reworking the worker contract.
+ * - Chunk-level invalidation gives a useful speedup floor (98% on a single
+ *   1-of-50 invalidated chunk) without touching the worker.
+ *
+ * Survives `--force` because it's content-addressed: the same bytes always
+ * produce the same key. `--force` only matters for the LadybugDB writeback;
+ * the cache itself is always safe to reuse.
+ */
+import { createHash } from 'crypto';
+import { createRequire } from 'module';
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+/**
+ * Cache version composed of:
+ *   - A schema bump knob (`SCHEMA_BUMP`) for hand-controlled invalidation
+ *     when ParseWorkerResult shape or upstream parse semantics change.
+ *   - The current `gitnexus` npm package version, read at module load.
+ *     Any release that ships an updated tree-sitter grammar or revised
+ *     extractor logic implies a version bump in package.json, which
+ *     automatically invalidates the on-disk cache. Without this, a user
+ *     running `npm i -g gitnexus@latest` after a parser-affecting
+ *     release would silently replay pre-upgrade ParseWorkerResults
+ *     against the new graph schema (Bugbot/Claude review on #1479).
+ *
+ * On version mismatch, `loadParseCache` returns an empty cache and the
+ * next save overwrites the on-disk file with the new version baked in.
+ */
+const SCHEMA_BUMP = 1;
+const GITNEXUS_PKG_VERSION = (() => {
+    try {
+        // package.json sits at gitnexus/package.json — two levels up from
+        // gitnexus/src/storage/parse-cache.ts (or its dist/ equivalent).
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        const candidates = [
+            path.join(here, '..', '..', 'package.json'), // src/storage → gitnexus/
+            path.join(here, '..', '..', '..', 'package.json'), // dist/storage → gitnexus/
+        ];
+        const requireCJS = createRequire(import.meta.url);
+        for (const c of candidates) {
+            try {
+                const pkg = requireCJS(c);
+                if (typeof pkg?.version === 'string')
+                    return pkg.version;
+            }
+            catch {
+                /* try next candidate */
+            }
+        }
+    }
+    catch {
+        /* fall through to fallback */
+    }
+    return '0.0.0-unknown';
+})();
+export const PARSE_CACHE_VERSION = `${SCHEMA_BUMP}+${GITNEXUS_PKG_VERSION}`;
+const CACHE_FILENAME = 'parse-cache.json';
+/** SHA-256 hex of a single string or buffer. */
+const sha256Hex = (input) => createHash('sha256')
+    .update(typeof input === 'string' ? Buffer.from(input) : input)
+    .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) => {
+    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);
+};
+/**
+ * JSON replacer that round-trips Map/Set instances through plain JSON.
+ *
+ * `ParseWorkerResult.parsedFiles[*].scopes[*].typeBindings` is a
+ * `ReadonlyMap<string, TypeRef>`; without this transform it serializes
+ * to `{}` and downstream code that iterates / `.get()`s on it crashes
+ * with "is not iterable". Applied symmetrically by `mapReviver` on
+ * load so the in-memory shape stays Map-typed.
+ */
+const MAP_TAG = '__$mapEntries$__';
+const SET_TAG = '__$setValues$__';
+const mapReplacer = (_key, value) => {
+    if (value instanceof Map)
+        return { [MAP_TAG]: Array.from(value.entries()) };
+    if (value instanceof Set)
+        return { [SET_TAG]: Array.from(value.values()) };
+    return value;
+};
+const mapReviver = (_key, value) => {
+    if (value && typeof value === 'object') {
+        const v = value;
+        if (Array.isArray(v[MAP_TAG]))
+            return new Map(v[MAP_TAG]);
+        if (Array.isArray(v[SET_TAG]))
+            return new Set(v[SET_TAG]);
+    }
+    return value;
+};
+/**
+ * Load the parse cache. Returns an empty cache on any failure (missing
+ * file, corrupt JSON, version mismatch). Never throws on a normal load.
+ */
+export const loadParseCache = async (storagePath) => {
+    const cachePath = path.join(storagePath, CACHE_FILENAME);
+    try {
+        const raw = await fs.readFile(cachePath, 'utf-8');
+        const data = JSON.parse(raw, mapReviver);
+        if (typeof data !== 'object' ||
+            data === null ||
+            data.version !== PARSE_CACHE_VERSION ||
+            typeof data.entries !== 'object' ||
+            data.entries === null) {
+            return emptyCache();
+        }
+        const entries = new Map();
+        for (const [k, v] of Object.entries(data.entries)) {
+            if (Array.isArray(v))
+                entries.set(k, v);
+        }
+        return { version: PARSE_CACHE_VERSION, entries, usedKeys: new Set() };
+    }
+    catch {
+        return emptyCache();
+    }
+};
+/**
+ * Persist the cache to disk atomically (write-and-rename) so a crash
+ * mid-write doesn't leave a corrupt file.
+ */
+export const saveParseCache = async (storagePath, cache) => {
+    await fs.mkdir(storagePath, { recursive: true });
+    const cachePath = path.join(storagePath, CACHE_FILENAME);
+    const tmpPath = `${cachePath}.tmp`;
+    const out = {
+        version: cache.version,
+        entries: Object.fromEntries(cache.entries),
+    };
+    // Compact JSON; this file can be tens of MB on a large repo and pretty-
+    // printing roughly doubles size for no value.
+    await fs.writeFile(tmpPath, JSON.stringify(out, mapReplacer), 'utf-8');
+    await fs.rename(tmpPath, cachePath);
+};
+/**
+ * Drop entries whose hashes are not in `usedHashes`. Called at the end
+ * of a run so chunks that no longer correspond to any current chunk
+ * don't keep their stale entries forever.
+ */
+export const pruneCache = (cache, usedHashes) => {
+    let removed = 0;
+    for (const k of cache.entries.keys()) {
+        if (!usedHashes.has(k)) {
+            cache.entries.delete(k);
+            removed++;
+        }
+    }
+    return removed;
+};
+const emptyCache = () => ({
+    version: PARSE_CACHE_VERSION,
+    entries: new Map(),
+    usedKeys: new Set(),
+});

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

@@ -56,7 +56,38 @@ export interface RepoMeta {
         processes?: number;
         embeddings?: number;
     };
+    /**
+     * Bumped whenever incremental-indexing invariants change in an
+     * incompatible way (delete-and-rewrite logic, subgraph extraction,
+     * graph-wide node handling). On mismatch, runFullAnalysis forces a
+     * full rebuild rather than risk an inconsistent incremental update.
+     */
+    schemaVersion?: number;
+    /**
+     * SHA-256 of every file's content at the time of the last successful
+     * indexing run. The next run computes current hashes and diffs against
+     * this map to determine which files' DB rows must be replaced.
+     * Map keys are repo-relative paths.
+     */
+    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.
+     */
+    incrementalInProgress?: {
+        /** When the incremental run started (epoch ms). */
+        startedAt: number;
+        /** Number of files in the writable set, for diagnostic logs. */
+        toWriteCount: number;
+    };
 }
+/**
+ * Bumped whenever incremental-indexing invariants change incompatibly.
+ */
+export declare const INCREMENTAL_SCHEMA_VERSION = 1;
 export interface IndexedRepo {
     repoPath: string;
     storagePath: string;
@@ -112,7 +143,16 @@ export declare const cleanupOldKuzuFiles: (storagePath: string) => Promise<{
  */
 export declare const loadMeta: (storagePath: string) => Promise<RepoMeta | null>;
 /**
- * Save metadata to storage
+ * Save metadata to storage.
+ *
+ * Atomic via tmp-file + rename (matches `saveParseCache`'s pattern). The
+ * `incrementalInProgress` dirty flag travels through this file — a crash
+ * mid-write would leave a corrupt `meta.json` that the next run's
+ * `loadMeta` would silently treat as "no prior index", losing the dirty
+ * flag and skipping the recovery full-rebuild. Write-and-rename rules
+ * that out: the rename is atomic on POSIX and on Windows (`fs.rename`
+ * on `node:fs/promises` uses `MoveFileEx(REPLACE_EXISTING)`), so either
+ * the old or the new file is observed at every moment.
  */
 export declare const saveMeta: (storagePath: string, meta: RepoMeta) => Promise<void>;
 /**

package/dist/storage/repo-manager.js

@@ -49,6 +49,10 @@ export const canonicalizePath = (p) => {
         return resolved;
     }
 };
+/**
+ * Bumped whenever incremental-indexing invariants change incompatibly.
+ */
+export const INCREMENTAL_SCHEMA_VERSION = 1;
 const GITNEXUS_DIR = '.gitnexus';
 const GITNEXUS_EXCLUDE_ENTRY = `${GITNEXUS_DIR}/`;
 // ─── Local Storage Helpers ─────────────────────────────────────────────
@@ -137,12 +141,23 @@ export const loadMeta = async (storagePath) => {
     }
 };
 /**
- * Save metadata to storage
+ * Save metadata to storage.
+ *
+ * Atomic via tmp-file + rename (matches `saveParseCache`'s pattern). The
+ * `incrementalInProgress` dirty flag travels through this file — a crash
+ * mid-write would leave a corrupt `meta.json` that the next run's
+ * `loadMeta` would silently treat as "no prior index", losing the dirty
+ * flag and skipping the recovery full-rebuild. Write-and-rename rules
+ * that out: the rename is atomic on POSIX and on Windows (`fs.rename`
+ * on `node:fs/promises` uses `MoveFileEx(REPLACE_EXISTING)`), so either
+ * the old or the new file is observed at every moment.
  */
 export const saveMeta = async (storagePath, meta) => {
     await fs.mkdir(storagePath, { recursive: true });
     const metaPath = path.join(storagePath, 'meta.json');
-    await fs.writeFile(metaPath, JSON.stringify(meta, null, 2), 'utf-8');
+    const tmpPath = `${metaPath}.tmp`;
+    await fs.writeFile(tmpPath, JSON.stringify(meta, null, 2), 'utf-8');
+    await fs.rename(tmpPath, metaPath);
 };
 /**
  * Check if a path has a GitNexus index

package/hooks/claude/gitnexus-hook.cjs

@@ -14,6 +14,7 @@
 const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
+const { acquireHookSlot } = require('./hook-lock.cjs');
 
 /**
  * Read JSON input from stdin synchronously.
@@ -207,7 +208,8 @@ function runGitNexusCli(cliPath, args, cwd, timeout) {
 function handlePreToolUse(input) {
   const cwd = input.cwd || process.cwd();
   if (!path.isAbsolute(cwd)) return;
-  if (!findGitNexusDir(cwd)) return;
+  const gitNexusDir = findGitNexusDir(cwd);
+  if (!gitNexusDir) return;
 
   const toolName = input.tool_name || '';
   const toolInput = input.tool_input || {};
@@ -217,6 +219,9 @@ function handlePreToolUse(input) {
   const pattern = extractPattern(toolName, toolInput);
   if (!pattern || pattern.length < 3) return;
 
+  const release = acquireHookSlot(gitNexusDir);
+  if (!release) return;
+
   const cliPath = resolveCliPath();
   let result = '';
   try {
@@ -226,6 +231,8 @@ function handlePreToolUse(input) {
     }
   } catch {
     /* graceful failure */
+  } finally {
+    release();
   }
 
   if (result && result.trim()) {

package/hooks/claude/hook-lock.cjs

@@ -0,0 +1,119 @@
+const fs = require('fs');
+const path = require('path');
+
+const HOOK_LOCK_SUBDIR = '.hook-locks';
+const HOOK_LOCK_MAX_INFLIGHT = 3;
+const HOOK_LOCK_STALE_MS = 30000;
+
+function acquireHookSlot(gitNexusDir) {
+  const lockDir = path.join(gitNexusDir, HOOK_LOCK_SUBDIR);
+  try {
+    fs.mkdirSync(lockDir, { recursive: true });
+  } catch {
+    // Cannot create lock dir (read-only fs, cross-user perm denial, out of
+    // inodes, etc.) — fail closed by returning null. Caller skips augment.
+    // Fail-open here would let N concurrent hooks all proceed unguarded and
+    // reintroduce the #1486 fan-out the guard exists to prevent.
+    return null;
+  }
+
+  const myPidStr = String(process.pid);
+
+  for (let slot = 0; slot < HOOK_LOCK_MAX_INFLIGHT; slot++) {
+    const slotPath = path.join(lockDir, `slot-${slot}.lock`);
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        fs.writeFileSync(slotPath, myPidStr, { flag: 'wx' });
+        let released = false;
+        const release = () => {
+          if (released) return;
+          released = true;
+          try {
+            // Only unlink if we still own the slot. If we appeared stale and
+            // another hook took over, the file now belongs to it — leave alone.
+            const content = fs.readFileSync(slotPath, 'utf-8').trim();
+            if (content === myPidStr) fs.unlinkSync(slotPath);
+          } catch {
+            /* already removed or unreadable */
+          }
+        };
+        process.on('exit', release);
+        return release;
+      } catch {
+        // Slot exists. Decide whether to take it over.
+        // Open once and inspect mtime + content via the same fd so there's
+        // no TOCTOU between the metadata check and the content read
+        // (codeql js/file-system-race).
+        let fd;
+        try {
+          fd = fs.openSync(slotPath, 'r');
+        } catch {
+          continue; // Vanished between EEXIST and open — retry this slot.
+        }
+        let isLive = false;
+        let mtimeMs = Date.now();
+        try {
+          mtimeMs = fs.fstatSync(fd).mtimeMs;
+          const buf = Buffer.alloc(32);
+          const n = fs.readSync(fd, buf, 0, 32, 0);
+          const ownerStr = buf.slice(0, n).toString('utf-8').trim();
+          if (ownerStr === '') {
+            // Owner created the file but hasn't written its PID yet. The
+            // wx open+write window is microseconds; give it the benefit
+            // of the doubt and treat as live.
+            isLive = true;
+          } else {
+            const owner = Number.parseInt(ownerStr, 10);
+            if (Number.isFinite(owner) && owner > 0) {
+              try {
+                process.kill(owner, 0);
+                isLive = true;
+              } catch (e) {
+                // ESRCH = process gone → treat as dead. EPERM = process exists
+                // but owned by another user (cross-user lock dir) → still alive,
+                // keep the slot. Anything else: be conservative, assume alive.
+                if (e && e.code === 'ESRCH') {
+                  isLive = false;
+                } else {
+                  isLive = true;
+                }
+              }
+            }
+          }
+        } catch {
+          /* unreadable — treat as dead */
+        } finally {
+          try {
+            fs.closeSync(fd);
+          } catch {
+            /* already closed */
+          }
+        }
+        // For slots younger than HOOK_LOCK_STALE_MS, PID-liveness wins —
+        // a slow-but-alive hook is never wrongly evicted. For older slots,
+        // age is the final arbiter as a defense against PID reuse on long-
+        // abandoned slots. 30s >> the 7s augment timeout, so a healthy run
+        // never crosses this threshold.
+        if (isLive && Date.now() - mtimeMs > HOOK_LOCK_STALE_MS) {
+          isLive = false;
+        }
+        if (isLive) break; // Try the next slot.
+        try {
+          fs.unlinkSync(slotPath);
+        } catch {
+          /* another hook beat us to it — retry will hit EEXIST */
+        }
+        // Loop and retry this slot.
+      }
+    }
+  }
+
+  return null;
+}
+
+module.exports = {
+  HOOK_LOCK_SUBDIR,
+  HOOK_LOCK_MAX_INFLIGHT,
+  HOOK_LOCK_STALE_MS,
+  acquireHookSlot,
+};

package/package.json

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