@liendev/lien 0.26.0 → 0.28.0

package/dist/index.js

@@ -3708,8 +3708,7 @@ import {
   DEFAULT_EMBEDDING_BATCH_SIZE,
   DEFAULT_CHUNK_SIZE,
   DEFAULT_CHUNK_OVERLAP,
-  DEFAULT_GIT_POLL_INTERVAL_MS,
-  DEFAULT_DEBOUNCE_MS
+  DEFAULT_GIT_POLL_INTERVAL_MS
 } from "@liendev/core";
 async function statusCommand() {
   const rootDir = process.cwd();
@@ -3766,7 +3765,7 @@ async function statusCommand() {
     console.log(chalk3.dim("Git detection:"), chalk3.yellow("Not a git repo"));
   }
   console.log(chalk3.dim("File watching:"), chalk3.green("\u2713 Enabled (default)"));
-  console.log(chalk3.dim("  Debounce:"), `${DEFAULT_DEBOUNCE_MS}ms`);
+  console.log(chalk3.dim("  Batch window:"), "500ms (collects rapid changes, force-flush after 5s)");
   console.log(chalk3.dim("  Disable with:"), chalk3.bold("lien serve --no-watch"));
   console.log(chalk3.bold("\nIndexing Settings (defaults):"));
   console.log(chalk3.dim("Concurrency:"), DEFAULT_CONCURRENCY);
@@ -3993,7 +3992,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createRequire as createRequire2 } from "module";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import { dirname as dirname2, join as join2 } from "path";
+import { dirname as dirname2, join as join2, resolve } from "path";
 import {
   LocalEmbeddings,
   GitStateTracker,
@@ -4004,18 +4003,35 @@ import {
   isGitRepo as isGitRepo2,
   VERSION_CHECK_INTERVAL_MS,
   DEFAULT_GIT_POLL_INTERVAL_MS as DEFAULT_GIT_POLL_INTERVAL_MS2,
-  createVectorDB
+  createVectorDB,
+  computeContentHash,
+  normalizeToRelativePath
 } from "@liendev/core";
 
 // src/watcher/index.ts
 import chokidar from "chokidar";
 import path3 from "path";
-import { detectAllFrameworks, getFrameworkDetector, DEFAULT_DEBOUNCE_MS as DEFAULT_DEBOUNCE_MS2 } from "@liendev/core";
+import { detectAllFrameworks, getFrameworkDetector } from "@liendev/core";
 var FileWatcher = class {
   watcher = null;
-  debounceTimers = /* @__PURE__ */ new Map();
   rootDir;
   onChangeHandler = null;
+  // Batch state for aggregating rapid changes
+  pendingChanges = /* @__PURE__ */ new Map();
+  batchTimer = null;
+  batchInProgress = false;
+  // Track if handler is currently processing a batch
+  BATCH_WINDOW_MS = 500;
+  // Collect changes for 500ms before processing
+  MAX_BATCH_WAIT_MS = 5e3;
+  // Force flush after 5s even if changes keep coming
+  firstChangeTimestamp = null;
+  // Track when batch started
+  // Git watching state
+  gitChangeTimer = null;
+  gitChangeHandler = null;
+  GIT_DEBOUNCE_MS = 1e3;
+  // Git operations touch multiple files
   constructor(rootDir) {
     this.rootDir = rootDir;
   }
@@ -4102,7 +4118,11 @@ var FileWatcher = class {
       return;
     }
     this.watcher.on("add", (filepath) => this.handleChange("add", filepath)).on("change", (filepath) => this.handleChange("change", filepath)).on("unlink", (filepath) => this.handleChange("unlink", filepath)).on("error", (error) => {
-      console.error(`[Lien] File watcher error: ${error}`);
+      try {
+        const message = "[FileWatcher] Error: " + (error instanceof Error ? error.stack || error.message : String(error)) + "\n";
+        process.stderr.write(message);
+      } catch {
+      }
     });
   }
   /**
@@ -4114,17 +4134,17 @@ var FileWatcher = class {
     }
     let readyFired = false;
     await Promise.race([
-      new Promise((resolve) => {
+      new Promise((resolve2) => {
         const readyHandler = () => {
           readyFired = true;
-          resolve();
+          resolve2();
         };
         this.watcher.once("ready", readyHandler);
       }),
-      new Promise((resolve) => {
+      new Promise((resolve2) => {
         setTimeout(() => {
           if (!readyFired) {
-            resolve();
+            resolve2();
           }
         }, 1e3);
       })
@@ -4146,34 +4166,200 @@ var FileWatcher = class {
     await this.waitForReady();
   }
   /**
-   * Handles a file change event with debouncing.
-   * Debouncing prevents rapid reindexing when files are saved multiple times quickly.
+   * Enable watching .git directory for git operations.
+   * Call this after start() to enable event-driven git detection.
+   * 
+   * @param onGitChange - Callback invoked when git operations detected
+   */
+  watchGit(onGitChange) {
+    if (!this.watcher) {
+      throw new Error("Cannot watch git - watcher not started");
+    }
+    this.gitChangeHandler = onGitChange;
+    this.watcher.add([
+      path3.join(this.rootDir, ".git/HEAD"),
+      path3.join(this.rootDir, ".git/index"),
+      path3.join(this.rootDir, ".git/refs/**"),
+      path3.join(this.rootDir, ".git/MERGE_HEAD"),
+      path3.join(this.rootDir, ".git/REBASE_HEAD"),
+      path3.join(this.rootDir, ".git/CHERRY_PICK_HEAD"),
+      path3.join(this.rootDir, ".git/logs/refs/stash")
+      // git stash operations
+    ]);
+  }
+  /**
+   * Check if a filepath is a git-related change
+   */
+  isGitChange(filepath) {
+    const normalized = filepath.replace(/\\/g, "/");
+    return normalized.includes(".git/");
+  }
+  /**
+   * Handle git-related file changes with debouncing
+   */
+  handleGitChange() {
+    if (this.gitChangeTimer) {
+      clearTimeout(this.gitChangeTimer);
+    }
+    this.gitChangeTimer = setTimeout(async () => {
+      try {
+        await this.gitChangeHandler?.();
+      } catch (error) {
+      }
+      this.gitChangeTimer = null;
+    }, this.GIT_DEBOUNCE_MS);
+  }
+  /**
+   * Handles a file change event with smart batching.
+   * Collects rapid changes across multiple files and processes them together.
+   * Forces flush after MAX_BATCH_WAIT_MS even if changes keep arriving.
+   * 
+   * If a batch is currently being processed by an async handler, waits for completion
+   * before starting a new batch to prevent race conditions.
    */
   handleChange(type, filepath) {
-    const existingTimer = this.debounceTimers.get(filepath);
-    if (existingTimer) {
-      clearTimeout(existingTimer);
-    }
-    const timer = setTimeout(() => {
-      this.debounceTimers.delete(filepath);
-      if (this.onChangeHandler) {
-        const absolutePath = path3.isAbsolute(filepath) ? filepath : path3.join(this.rootDir, filepath);
-        try {
-          const result = this.onChangeHandler({
-            type,
-            filepath: absolutePath
-          });
-          if (result instanceof Promise) {
-            result.catch((error) => {
-              console.error(`[Lien] Error handling file change: ${error}`);
-            });
-          }
-        } catch (error) {
-          console.error(`[Lien] Error handling file change: ${error}`);
-        }
+    if (this.gitChangeHandler && this.isGitChange(filepath)) {
+      this.handleGitChange();
+      return;
+    }
+    if (!this.onChangeHandler) {
+      return;
+    }
+    if (this.pendingChanges.size === 0) {
+      this.firstChangeTimestamp = Date.now();
+    }
+    this.pendingChanges.set(filepath, type);
+    const now = Date.now();
+    const elapsed = now - this.firstChangeTimestamp;
+    if (elapsed >= this.MAX_BATCH_WAIT_MS) {
+      if (this.batchTimer) {
+        clearTimeout(this.batchTimer);
+        this.batchTimer = null;
       }
-    }, DEFAULT_DEBOUNCE_MS2);
-    this.debounceTimers.set(filepath, timer);
+      this.flushBatch();
+      return;
+    }
+    if (this.batchTimer) {
+      clearTimeout(this.batchTimer);
+    }
+    if (!this.batchInProgress) {
+      this.batchTimer = setTimeout(() => {
+        this.flushBatch();
+      }, this.BATCH_WINDOW_MS);
+    }
+  }
+  /**
+   * Group pending changes by type and convert to absolute paths.
+   * Returns arrays of added, modified, and deleted files.
+   */
+  groupPendingChanges(changes) {
+    const added = [];
+    const modified = [];
+    const deleted = [];
+    for (const [filepath, type] of changes) {
+      const absolutePath = path3.isAbsolute(filepath) ? filepath : path3.join(this.rootDir, filepath);
+      switch (type) {
+        case "add":
+          added.push(absolutePath);
+          break;
+        case "change":
+          modified.push(absolutePath);
+          break;
+        case "unlink":
+          deleted.push(absolutePath);
+          break;
+      }
+    }
+    return { added, modified, deleted };
+  }
+  /**
+   * Handle completion of async batch handler.
+   * Triggers flush of accumulated changes if any.
+   */
+  handleBatchComplete() {
+    this.batchInProgress = false;
+    if (this.pendingChanges.size > 0 && !this.batchTimer) {
+      this.batchTimer = setTimeout(() => {
+        this.flushBatch();
+      }, this.BATCH_WINDOW_MS);
+    }
+  }
+  /**
+   * Dispatch batch event to handler and track async state.
+   * Caller must ensure at least one of added/modified/deleted is non-empty.
+   */
+  dispatchBatch(added, modified, deleted) {
+    if (!this.onChangeHandler) return;
+    const allFiles = [...added, ...modified];
+    const firstFile = allFiles.length > 0 ? allFiles[0] : deleted[0];
+    if (!firstFile) {
+      return;
+    }
+    try {
+      this.batchInProgress = true;
+      const result = this.onChangeHandler({
+        type: "batch",
+        filepath: firstFile,
+        added,
+        modified,
+        deleted
+      });
+      if (result instanceof Promise) {
+        result.catch(() => {
+        }).finally(() => this.handleBatchComplete());
+      } else {
+        this.handleBatchComplete();
+      }
+    } catch (error) {
+      this.handleBatchComplete();
+    }
+  }
+  /**
+   * Flush pending changes and dispatch batch event.
+   * Tracks async handler state to prevent race conditions.
+   */
+  flushBatch() {
+    if (this.batchTimer) {
+      clearTimeout(this.batchTimer);
+      this.batchTimer = null;
+    }
+    if (this.pendingChanges.size === 0) return;
+    const changes = new Map(this.pendingChanges);
+    this.pendingChanges.clear();
+    this.firstChangeTimestamp = null;
+    const { added, modified, deleted } = this.groupPendingChanges(changes);
+    if (added.length === 0 && modified.length === 0 && deleted.length === 0) {
+      return;
+    }
+    this.dispatchBatch(added, modified, deleted);
+  }
+  /**
+   * Flush final batch during shutdown.
+   * Handles edge case where watcher is stopped while batch is pending.
+   */
+  async flushFinalBatch(handler) {
+    if (this.pendingChanges.size === 0) return;
+    const changes = new Map(this.pendingChanges);
+    this.pendingChanges.clear();
+    const { added, modified, deleted } = this.groupPendingChanges(changes);
+    if (added.length === 0 && modified.length === 0 && deleted.length === 0) {
+      return;
+    }
+    try {
+      const allFiles = [...added, ...modified];
+      const firstFile = allFiles.length > 0 ? allFiles[0] : deleted[0];
+      if (!firstFile) {
+        return;
+      }
+      await handler({
+        type: "batch",
+        filepath: firstFile,
+        added,
+        modified,
+        deleted
+      });
+    } catch (error) {
+    }
   }
   /**
    * Stops the file watcher and cleans up resources.
@@ -4182,13 +4368,25 @@ var FileWatcher = class {
     if (!this.watcher) {
       return;
     }
-    for (const timer of this.debounceTimers.values()) {
-      clearTimeout(timer);
+    const handler = this.onChangeHandler;
+    this.onChangeHandler = null;
+    this.gitChangeHandler = null;
+    if (this.gitChangeTimer) {
+      clearTimeout(this.gitChangeTimer);
+      this.gitChangeTimer = null;
+    }
+    while (this.batchInProgress) {
+      await new Promise((resolve2) => setTimeout(resolve2, 50));
+    }
+    if (this.batchTimer) {
+      clearTimeout(this.batchTimer);
+      this.batchTimer = null;
+    }
+    if (handler && this.pendingChanges.size > 0) {
+      await this.flushFinalBatch(handler);
     }
-    this.debounceTimers.clear();
     await this.watcher.close();
     this.watcher = null;
-    this.onChangeHandler = null;
   }
   /**
    * Gets the list of files currently being watched.
@@ -8334,6 +8532,9 @@ var GetDependentsSchema = external_exports.object({
   filepath: external_exports.string().min(1, "Filepath cannot be empty").describe(
     "Path to file to find dependents for (relative to workspace root).\n\nExample: 'src/utils/validate.ts'\n\nReturns all files that import or depend on this file.\n\nNote: Scans up to 10,000 code chunks. For very large codebases,\nresults may be incomplete (a warning will be included if truncated)."
   ),
+  symbol: external_exports.string().min(1, "Symbol cannot be an empty string").optional().describe(
+    "Optional: specific exported symbol to find usages of.\n\nWhen provided, returns call sites instead of just importing files.\n\nExample: 'validateEmail' to find where validateEmail() is called.\n\nResponse includes 'usages' array showing which functions call this symbol."
+  ),
   depth: external_exports.number().int().min(1).max(1).default(1).describe(
     "Depth of transitive dependencies. Only depth=1 (direct dependents) is currently supported.\n\n1 = Direct dependents only"
   ),
@@ -8643,7 +8844,7 @@ async function handleFindSimilar(args, ctx) {
 // src/mcp/utils/path-matching.ts
 function normalizePath(path6, workspaceRoot) {
   let normalized = path6.replace(/['"]/g, "").trim().replace(/\\/g, "/");
-  normalized = normalized.replace(/\.(ts|tsx|js|jsx)$/, "");
+  normalized = normalized.replace(/\.(ts|tsx|js|jsx|php|py)$/, "");
   if (normalized.startsWith(workspaceRoot + "/")) {
     normalized = normalized.substring(workspaceRoot.length + 1);
   }
@@ -8671,8 +8872,56 @@ function matchesFile(normalizedImport, normalizedTarget) {
   if (matchesAtBoundary(cleanedImport, normalizedTarget) || matchesAtBoundary(normalizedTarget, cleanedImport)) {
     return true;
   }
+  if (matchesPHPNamespace(normalizedImport, normalizedTarget)) {
+    return true;
+  }
+  if (matchesPythonModule(normalizedImport, normalizedTarget)) {
+    return true;
+  }
   return false;
 }
+function matchesDirectPythonModule(moduleAsPath, targetWithoutPy) {
+  return targetWithoutPy === moduleAsPath || targetWithoutPy === moduleAsPath + "/__init__" || targetWithoutPy.replace(/\/__init__$/, "") === moduleAsPath;
+}
+function matchesParentPythonPackage(moduleAsPath, targetWithoutPy) {
+  return targetWithoutPy.startsWith(moduleAsPath + "/");
+}
+function matchesSuffixPythonModule(moduleAsPath, targetWithoutPy) {
+  return targetWithoutPy.endsWith("/" + moduleAsPath) || targetWithoutPy.endsWith("/" + moduleAsPath + "/__init__");
+}
+function matchesWithSourcePrefix(moduleAsPath, targetWithoutPy) {
+  const moduleIndex = targetWithoutPy.indexOf(moduleAsPath);
+  if (moduleIndex < 0) return false;
+  const prefix = targetWithoutPy.substring(0, moduleIndex);
+  const prefixSlashes = (prefix.match(/\//g) || []).length;
+  return prefixSlashes <= 1 && (prefix === "" || prefix.endsWith("/"));
+}
+function matchesPythonModule(importPath, targetPath) {
+  if (!importPath.includes(".")) {
+    return false;
+  }
+  const moduleAsPath = importPath.replace(/\./g, "/");
+  const targetWithoutPy = targetPath.replace(/\.py$/, "");
+  return matchesDirectPythonModule(moduleAsPath, targetWithoutPy) || matchesParentPythonPackage(moduleAsPath, targetWithoutPy) || matchesSuffixPythonModule(moduleAsPath, targetWithoutPy) || matchesWithSourcePrefix(moduleAsPath, targetWithoutPy);
+}
+function matchesPHPNamespace(importPath, targetPath) {
+  const importComponents = importPath.split("/").filter(Boolean);
+  const targetComponents = targetPath.split("/").filter(Boolean);
+  if (importComponents.length === 0 || targetComponents.length === 0) {
+    return false;
+  }
+  let matched = 0;
+  for (let i = 1; i <= importComponents.length && i <= targetComponents.length; i++) {
+    const impComp = importComponents[importComponents.length - i].toLowerCase();
+    const targetComp = targetComponents[targetComponents.length - i].toLowerCase();
+    if (impComp === targetComp) {
+      matched++;
+    } else {
+      break;
+    }
+  }
+  return matched === importComponents.length;
+}
 function getCanonicalPath(filepath, workspaceRoot) {
   let canonical = filepath.replace(/\\/g, "/");
   if (canonical.startsWith(workspaceRoot + "/")) {
@@ -8942,7 +9191,7 @@ var COMPLEXITY_THRESHOLDS = {
   MEDIUM_MAX: 15
   // Occasional branching
 };
-async function findDependents(vectorDB, filepath, crossRepo, log) {
+async function scanChunks(vectorDB, crossRepo, log) {
   let allChunks;
   if (crossRepo && vectorDB instanceof QdrantDB2) {
     allChunks = await vectorDB.scanCrossRepo({ limit: SCAN_LIMIT2 });
@@ -8956,48 +9205,105 @@ async function findDependents(vectorDB, filepath, crossRepo, log) {
   if (hitLimit) {
     log(`Scanned ${SCAN_LIMIT2} chunks (limit reached). Results may be incomplete.`, "warning");
   }
-  log(`Scanning ${allChunks.length} chunks for imports...`);
+  return { allChunks, hitLimit };
+}
+function createPathNormalizer() {
   const workspaceRoot = process.cwd().replace(/\\/g, "/");
-  const pathCache = /* @__PURE__ */ new Map();
-  const normalizePathCached = (path6) => {
-    if (!pathCache.has(path6)) pathCache.set(path6, normalizePath(path6, workspaceRoot));
-    return pathCache.get(path6);
+  const cache = /* @__PURE__ */ new Map();
+  return (path6) => {
+    if (!cache.has(path6)) {
+      cache.set(path6, normalizePath(path6, workspaceRoot));
+    }
+    return cache.get(path6);
   };
-  const importIndex = buildImportIndex(allChunks, normalizePathCached);
-  const normalizedTarget = normalizePathCached(filepath);
-  const dependentChunks = findDependentChunks(importIndex, normalizedTarget);
+}
+function groupChunksByFile(chunks) {
+  const workspaceRoot = process.cwd().replace(/\\/g, "/");
   const chunksByFile = /* @__PURE__ */ new Map();
-  for (const chunk of dependentChunks) {
+  for (const chunk of chunks) {
     const canonical = getCanonicalPath(chunk.metadata.file, workspaceRoot);
     const existing = chunksByFile.get(canonical) || [];
     existing.push(chunk);
     chunksByFile.set(canonical, existing);
   }
+  return chunksByFile;
+}
+function buildDependentsList(chunksByFile, symbol, normalizedTarget, normalizePathCached, allChunks, filepath, log) {
+  if (symbol) {
+    validateSymbolExport(allChunks, normalizedTarget, normalizePathCached, symbol, filepath, log);
+    return findSymbolUsages(chunksByFile, symbol, normalizedTarget, normalizePathCached);
+  }
+  const dependents = Array.from(chunksByFile.keys()).map((fp) => ({
+    filepath: fp,
+    isTestFile: isTestFile(fp)
+  }));
+  return { dependents, totalUsageCount: void 0 };
+}
+function validateSymbolExport(allChunks, normalizedTarget, normalizePathCached, symbol, filepath, log) {
+  const targetFileExportsSymbol = allChunks.some((chunk) => {
+    const chunkFile = normalizePathCached(chunk.metadata.file);
+    return matchesFile(chunkFile, normalizedTarget) && chunk.metadata.exports?.includes(symbol);
+  });
+  if (!targetFileExportsSymbol) {
+    log(`Warning: Symbol "${symbol}" not found in exports of ${filepath}`, "warning");
+  }
+}
+async function findDependents(vectorDB, filepath, crossRepo, log, symbol) {
+  const { allChunks, hitLimit } = await scanChunks(vectorDB, crossRepo, log);
+  log(`Scanning ${allChunks.length} chunks for imports...`);
+  const normalizePathCached = createPathNormalizer();
+  const normalizedTarget = normalizePathCached(filepath);
+  const importIndex = buildImportIndex(allChunks, normalizePathCached);
+  const dependentChunks = findDependentChunks(importIndex, normalizedTarget);
+  const chunksByFile = groupChunksByFile(dependentChunks);
   const fileComplexities = calculateFileComplexities(chunksByFile);
   const complexityMetrics = calculateOverallComplexityMetrics(fileComplexities);
-  const uniqueFiles = Array.from(chunksByFile.keys()).map((filepath2) => ({
-    filepath: filepath2,
-    isTestFile: isTestFile(filepath2)
-  }));
+  const { dependents, totalUsageCount } = buildDependentsList(
+    chunksByFile,
+    symbol,
+    normalizedTarget,
+    normalizePathCached,
+    allChunks,
+    filepath,
+    log
+  );
+  dependents.sort((a, b) => {
+    if (a.isTestFile === b.isTestFile) return 0;
+    return a.isTestFile ? 1 : -1;
+  });
+  const testDependentCount = dependents.filter((f) => f.isTestFile).length;
+  const productionDependentCount = dependents.length - testDependentCount;
   return {
-    dependents: uniqueFiles,
+    dependents,
+    productionDependentCount,
+    testDependentCount,
     chunksByFile,
     fileComplexities,
     complexityMetrics,
     hitLimit,
-    allChunks
+    allChunks,
+    totalUsageCount
   };
 }
 function buildImportIndex(allChunks, normalizePathCached) {
   const importIndex = /* @__PURE__ */ new Map();
+  const addToIndex = (importPath, chunk) => {
+    const normalizedImport = normalizePathCached(importPath);
+    if (!importIndex.has(normalizedImport)) {
+      importIndex.set(normalizedImport, []);
+    }
+    importIndex.get(normalizedImport).push(chunk);
+  };
   for (const chunk of allChunks) {
     const imports = chunk.metadata.imports || [];
     for (const imp of imports) {
-      const normalizedImport = normalizePathCached(imp);
-      if (!importIndex.has(normalizedImport)) {
-        importIndex.set(normalizedImport, []);
+      addToIndex(imp, chunk);
+    }
+    const importedSymbols = chunk.metadata.importedSymbols;
+    if (importedSymbols && typeof importedSymbols === "object") {
+      for (const modulePath of Object.keys(importedSymbols)) {
+        addToIndex(modulePath, chunk);
       }
-      importIndex.get(normalizedImport).push(chunk);
     }
   }
   return importIndex;
@@ -9079,14 +9385,15 @@ function calculateComplexityRiskBoost(avgComplexity, maxComplexity) {
   }
   return "low";
 }
-function calculateRiskLevel(dependentCount, complexityRiskBoost) {
+function calculateRiskLevel(dependentCount, complexityRiskBoost, productionDependentCount) {
   const DEPENDENT_COUNT_THRESHOLDS = {
     LOW: 5,
     MEDIUM: 15,
     HIGH: 30
   };
   const RISK_ORDER = { low: 0, medium: 1, high: 2, critical: 3 };
-  let riskLevel = dependentCount === 0 ? "low" : dependentCount <= DEPENDENT_COUNT_THRESHOLDS.LOW ? "low" : dependentCount <= DEPENDENT_COUNT_THRESHOLDS.MEDIUM ? "medium" : dependentCount <= DEPENDENT_COUNT_THRESHOLDS.HIGH ? "high" : "critical";
+  const effectiveCount = productionDependentCount ?? dependentCount;
+  let riskLevel = effectiveCount === 0 ? "low" : effectiveCount <= DEPENDENT_COUNT_THRESHOLDS.LOW ? "low" : effectiveCount <= DEPENDENT_COUNT_THRESHOLDS.MEDIUM ? "medium" : effectiveCount <= DEPENDENT_COUNT_THRESHOLDS.HIGH ? "high" : "critical";
   if (RISK_ORDER[complexityRiskBoost] > RISK_ORDER[riskLevel]) {
     riskLevel = complexityRiskBoost;
   }
@@ -9118,45 +9425,167 @@ function groupDependentsByRepo(dependents, chunks) {
   }
   return grouped;
 }
+function findSymbolUsages(chunksByFile, targetSymbol, normalizedTarget, normalizePathCached) {
+  const dependents = [];
+  let totalUsageCount = 0;
+  for (const [filepath, chunks] of chunksByFile.entries()) {
+    if (!fileImportsSymbol(chunks, targetSymbol, normalizedTarget, normalizePathCached)) {
+      continue;
+    }
+    const usages = extractSymbolUsagesFromChunks(chunks, targetSymbol);
+    dependents.push({
+      filepath,
+      isTestFile: isTestFile(filepath),
+      usages: usages.length > 0 ? usages : void 0
+    });
+    totalUsageCount += usages.length;
+  }
+  return { dependents, totalUsageCount };
+}
+function fileImportsSymbol(chunks, targetSymbol, normalizedTarget, normalizePathCached) {
+  return chunks.some((chunk) => {
+    const importedSymbols = chunk.metadata.importedSymbols;
+    if (!importedSymbols) return false;
+    for (const [importPath, symbols] of Object.entries(importedSymbols)) {
+      const normalizedImport = normalizePathCached(importPath);
+      if (matchesFile(normalizedImport, normalizedTarget)) {
+        if (symbols.includes(targetSymbol)) return true;
+        if (symbols.some((s) => s.startsWith("* as "))) return true;
+      }
+    }
+    return false;
+  });
+}
+function extractSymbolUsagesFromChunks(chunks, targetSymbol) {
+  const usages = [];
+  for (const chunk of chunks) {
+    const callSites = chunk.metadata.callSites;
+    if (!callSites) continue;
+    const lines = chunk.content.split("\n");
+    for (const call of callSites) {
+      if (call.symbol === targetSymbol) {
+        usages.push({
+          callerSymbol: chunk.metadata.symbolName || "unknown",
+          line: call.line,
+          snippet: extractSnippet(lines, call.line, chunk.metadata.startLine, targetSymbol)
+        });
+      }
+    }
+  }
+  return usages;
+}
+function extractSnippet(lines, callLine, startLine, symbolName) {
+  const lineIndex = callLine - startLine;
+  const placeholder = `${symbolName}(...)`;
+  if (lineIndex < 0 || lineIndex >= lines.length) {
+    return placeholder;
+  }
+  const directLine = lines[lineIndex].trim();
+  if (directLine) {
+    return directLine;
+  }
+  const searchRadius = 5;
+  for (let i = lineIndex - 1; i >= Math.max(0, lineIndex - searchRadius); i--) {
+    const candidate = lines[i].trim();
+    if (candidate) {
+      return candidate;
+    }
+  }
+  for (let i = lineIndex + 1; i < Math.min(lines.length, lineIndex + searchRadius + 1); i++) {
+    const candidate = lines[i].trim();
+    if (candidate) {
+      return candidate;
+    }
+  }
+  return placeholder;
+}
 
 // src/mcp/handlers/get-dependents.ts
+function checkCrossRepoFallback(crossRepo, vectorDB) {
+  return Boolean(crossRepo && !(vectorDB instanceof QdrantDB3));
+}
+function buildNotes(crossRepoFallback, hitLimit) {
+  const notes = [];
+  if (crossRepoFallback) {
+    notes.push("Cross-repo search requires Qdrant backend. Fell back to single-repo search.");
+  }
+  if (hitLimit) {
+    notes.push("Scanned 10,000 chunks (limit reached). Results may be incomplete.");
+  }
+  return notes;
+}
+function logRiskAssessment(analysis, riskLevel, symbol, log) {
+  const prodTest = `(${analysis.productionDependentCount} prod, ${analysis.testDependentCount} test)`;
+  if (symbol && analysis.totalUsageCount !== void 0) {
+    if (analysis.totalUsageCount > 0) {
+      log(
+        `Found ${analysis.totalUsageCount} tracked call sites across ${analysis.dependents.length} files ${prodTest} - risk: ${riskLevel}`
+      );
+    } else {
+      log(
+        `Found ${analysis.dependents.length} files importing '${symbol}' ${prodTest} - risk: ${riskLevel} (Note: Call site tracking unavailable for these chunks)`
+      );
+    }
+  } else {
+    log(
+      `Found ${analysis.dependents.length} dependents ${prodTest} - risk: ${riskLevel}`
+    );
+  }
+}
+function buildDependentsResponse(analysis, args, riskLevel, indexInfo, notes, crossRepo, vectorDB) {
+  const { symbol, filepath } = args;
+  const response = {
+    indexInfo,
+    filepath,
+    dependentCount: analysis.dependents.length,
+    productionDependentCount: analysis.productionDependentCount,
+    testDependentCount: analysis.testDependentCount,
+    riskLevel,
+    dependents: analysis.dependents,
+    complexityMetrics: analysis.complexityMetrics
+  };
+  if (symbol) {
+    response.symbol = symbol;
+  }
+  if (analysis.totalUsageCount !== void 0) {
+    response.totalUsageCount = analysis.totalUsageCount;
+  }
+  if (notes.length > 0) {
+    response.note = notes.join(" ");
+  }
+  if (crossRepo && vectorDB instanceof QdrantDB3) {
+    response.groupedByRepo = groupDependentsByRepo(analysis.dependents, analysis.allChunks);
+  }
+  return response;
+}
 async function handleGetDependents(args, ctx) {
   const { vectorDB, log, checkAndReconnect, getIndexMetadata } = ctx;
   return await wrapToolHandler(
     GetDependentsSchema,
     async (validatedArgs) => {
-      const { crossRepo, filepath } = validatedArgs;
-      log(`Finding dependents of: ${filepath}${crossRepo ? " (cross-repo)" : ""}`);
+      const { crossRepo, filepath, symbol } = validatedArgs;
+      const symbolSuffix = symbol ? ` (symbol: ${symbol})` : "";
+      const crossRepoSuffix = crossRepo ? " (cross-repo)" : "";
+      log(`Finding dependents of: ${filepath}${symbolSuffix}${crossRepoSuffix}`);
       await checkAndReconnect();
-      const analysis = await findDependents(vectorDB, filepath, crossRepo ?? false, log);
+      const analysis = await findDependents(vectorDB, filepath, crossRepo ?? false, log, symbol);
       const riskLevel = calculateRiskLevel(
         analysis.dependents.length,
-        analysis.complexityMetrics.complexityRiskBoost
-      );
-      log(
-        `Found ${analysis.dependents.length} dependent files (risk: ${riskLevel}${analysis.complexityMetrics.filesWithComplexityData > 0 ? ", complexity-boosted" : ""})`
+        analysis.complexityMetrics.complexityRiskBoost,
+        analysis.productionDependentCount
       );
-      const notes = [];
-      const crossRepoFallback = crossRepo && !(vectorDB instanceof QdrantDB3);
-      if (crossRepoFallback) {
-        notes.push("Cross-repo search requires Qdrant backend. Fell back to single-repo search.");
-      }
-      if (analysis.hitLimit) {
-        notes.push("Scanned 10,000 chunks (limit reached). Results may be incomplete.");
-      }
-      const response = {
-        indexInfo: getIndexMetadata(),
-        filepath: validatedArgs.filepath,
-        dependentCount: analysis.dependents.length,
+      logRiskAssessment(analysis, riskLevel, symbol, log);
+      const crossRepoFallback = checkCrossRepoFallback(crossRepo, vectorDB);
+      const notes = buildNotes(crossRepoFallback, analysis.hitLimit);
+      return buildDependentsResponse(
+        analysis,
+        validatedArgs,
         riskLevel,
-        dependents: analysis.dependents,
-        complexityMetrics: analysis.complexityMetrics,
-        ...notes.length > 0 && { note: notes.join(" ") }
-      };
-      if (crossRepo && vectorDB instanceof QdrantDB3) {
-        response.groupedByRepo = groupDependentsByRepo(analysis.dependents, analysis.allChunks);
-      }
-      return response;
+        getIndexMetadata(),
+        notes,
+        crossRepo,
+        vectorDB
+      );
     }
   )(args);
 }
@@ -9348,6 +9777,134 @@ function registerMCPHandlers(server, toolContext, log) {
   });
 }
 
+// src/mcp/reindex-state-manager.ts
+function checkForStuckState(inProgress, lastStateChangeTimestamp, activeOperations, pendingFilesCount) {
+  if (!inProgress) return;
+  const STUCK_STATE_THRESHOLD_MS = 5 * 60 * 1e3;
+  const stuckDuration = Date.now() - lastStateChangeTimestamp;
+  if (stuckDuration > STUCK_STATE_THRESHOLD_MS) {
+    console.warn(
+      `[Lien] HEALTH CHECK: Reindex stuck in progress for ${Math.round(stuckDuration / 1e3)}s. This indicates an operation crashed without cleanup. Active operations: ${activeOperations}, Pending files: ${pendingFilesCount}. Consider using resetIfStuck() to recover.`
+    );
+  }
+}
+function mergePendingFiles(pendingFiles, newFiles) {
+  const existing = new Set(pendingFiles);
+  for (const file of newFiles) {
+    if (!existing.has(file)) {
+      pendingFiles.push(file);
+    }
+  }
+}
+function createReindexStateManager() {
+  let state = {
+    inProgress: false,
+    pendingFiles: [],
+    lastReindexTimestamp: null,
+    lastReindexDurationMs: null
+  };
+  let activeOperations = 0;
+  let lastStateChangeTimestamp = Date.now();
+  return {
+    /**
+     * Get a copy of the current reindex state.
+     * Returns a deep copy to prevent external mutation of nested arrays.
+     */
+    getState: () => {
+      checkForStuckState(
+        state.inProgress,
+        lastStateChangeTimestamp,
+        activeOperations,
+        state.pendingFiles.length
+      );
+      return { ...state, pendingFiles: [...state.pendingFiles] };
+    },
+    /**
+     * Start a new reindex operation.
+     * 
+     * **Important**: Silently ignores empty or null file arrays without incrementing
+     * activeOperations. This is intentional - if there's no work to do, no operation
+     * is started. Callers should check for empty arrays before calling if they need
+     * to track "attempted" operations.
+     * 
+     * @param files - Array of file paths to reindex. Empty/null arrays are ignored.
+     */
+    startReindex: (files) => {
+      if (!files || files.length === 0) {
+        return;
+      }
+      activeOperations += 1;
+      state.inProgress = true;
+      lastStateChangeTimestamp = Date.now();
+      mergePendingFiles(state.pendingFiles, files);
+    },
+    /**
+     * Mark a reindex operation as complete.
+     * 
+     * Logs a warning if called without a matching startReindex.
+     * Only clears state when all concurrent operations finish.
+     * 
+     * @param durationMs - Duration of the reindex operation in milliseconds
+     */
+    completeReindex: (durationMs) => {
+      if (activeOperations === 0) {
+        console.warn("[Lien] completeReindex called without matching startReindex");
+        return;
+      }
+      activeOperations -= 1;
+      if (activeOperations === 0) {
+        state.inProgress = false;
+        state.pendingFiles = [];
+        state.lastReindexTimestamp = Date.now();
+        state.lastReindexDurationMs = durationMs;
+        lastStateChangeTimestamp = Date.now();
+      }
+    },
+    /**
+     * Mark a reindex operation as failed.
+     * 
+     * Logs a warning if called without a matching startReindex.
+     * Only clears state when all concurrent operations finish/fail.
+     */
+    failReindex: () => {
+      if (activeOperations === 0) {
+        console.warn("[Lien] failReindex called without matching startReindex");
+        return;
+      }
+      activeOperations -= 1;
+      if (activeOperations === 0) {
+        state.inProgress = false;
+        state.pendingFiles = [];
+        lastStateChangeTimestamp = Date.now();
+      }
+    },
+    /**
+     * Manually reset state if it's stuck.
+     * 
+     * **WARNING**: Only use this if you're certain operations have crashed without cleanup.
+     * This will forcibly clear the inProgress flag and reset activeOperations counter.
+     * 
+     * Use this when getState() health check detects stuck state and you've verified
+     * no legitimate operations are running.
+     * 
+     * @returns true if state was reset, false if state was already clean
+     */
+    resetIfStuck: () => {
+      if (state.inProgress && activeOperations > 0) {
+        console.warn(
+          `[Lien] Manually resetting stuck reindex state. Active operations: ${activeOperations}, Pending files: ${state.pendingFiles.length}`
+        );
+        activeOperations = 0;
+        state.inProgress = false;
+        state.pendingFiles = [];
+        lastStateChangeTimestamp = Date.now();
+        return true;
+      }
+      return false;
+    }
+  };
+}
+
 // src/mcp/server.ts
 var __filename2 = fileURLToPath2(import.meta.url);
 var __dirname2 = dirname2(__filename2);
@@ -9358,6 +9915,9 @@ try {
 } catch {
   packageJson2 = require3(join2(__dirname2, "../../package.json"));
 }
+function getRootDirFromDbPath(dbPath) {
+  return resolve(dbPath, "../../..");
+}
 async function initializeDatabase(rootDir, log) {
   const embeddings = new LocalEmbeddings();
   log("Creating vector database...");
@@ -9390,7 +9950,96 @@ async function handleAutoIndexing(vectorDB, rootDir, log) {
     }
   }
 }
-async function setupGitDetection(rootDir, vectorDB, embeddings, verbose, log) {
+async function handleGitStartup(gitTracker, vectorDB, embeddings, _verbose, log, reindexStateManager) {
+  log("Checking for git changes...");
+  const changedFiles = await gitTracker.initialize();
+  if (changedFiles && changedFiles.length > 0) {
+    const startTime = Date.now();
+    reindexStateManager.startReindex(changedFiles);
+    log(`\u{1F33F} Git changes detected: ${changedFiles.length} files changed`);
+    try {
+      const count = await indexMultipleFiles(changedFiles, vectorDB, embeddings, { verbose: false });
+      const duration = Date.now() - startTime;
+      reindexStateManager.completeReindex(duration);
+      log(`\u2713 Reindexed ${count} files in ${duration}ms`);
+    } catch (error) {
+      reindexStateManager.failReindex();
+      throw error;
+    }
+  } else {
+    log("\u2713 Index is up to date with git state");
+  }
+}
+function createGitPollInterval(gitTracker, vectorDB, embeddings, _verbose, log, reindexStateManager) {
+  return setInterval(async () => {
+    try {
+      const changedFiles = await gitTracker.detectChanges();
+      if (changedFiles && changedFiles.length > 0) {
+        const currentState = reindexStateManager.getState();
+        if (currentState.inProgress) {
+          log(
+            `Background reindex already in progress (${currentState.pendingFiles.length} files pending), skipping git poll cycle`,
+            "debug"
+          );
+          return;
+        }
+        const startTime = Date.now();
+        reindexStateManager.startReindex(changedFiles);
+        log(`\u{1F33F} Git change detected: ${changedFiles.length} files changed`);
+        try {
+          const count = await indexMultipleFiles(changedFiles, vectorDB, embeddings, { verbose: false });
+          const duration = Date.now() - startTime;
+          reindexStateManager.completeReindex(duration);
+          log(`\u2713 Background reindex complete: ${count} files in ${duration}ms`);
+        } catch (error) {
+          reindexStateManager.failReindex();
+          log(`Git background reindex failed: ${error}`, "warning");
+        }
+      }
+    } catch (error) {
+      log(`Git detection check failed: ${error}`, "warning");
+    }
+  }, DEFAULT_GIT_POLL_INTERVAL_MS2);
+}
+function createGitChangeHandler(gitTracker, vectorDB, embeddings, _verbose, log, reindexStateManager) {
+  let gitReindexInProgress = false;
+  let lastGitReindexTime = 0;
+  const GIT_REINDEX_COOLDOWN_MS = 5e3;
+  return async () => {
+    const { inProgress: globalInProgress } = reindexStateManager.getState();
+    if (gitReindexInProgress || globalInProgress) {
+      log("Git reindex already in progress, skipping", "debug");
+      return;
+    }
+    const timeSinceLastReindex = Date.now() - lastGitReindexTime;
+    if (timeSinceLastReindex < GIT_REINDEX_COOLDOWN_MS) {
+      log(`Git change ignored (cooldown: ${GIT_REINDEX_COOLDOWN_MS - timeSinceLastReindex}ms remaining)`, "debug");
+      return;
+    }
+    log("\u{1F33F} Git change detected (event-driven)");
+    const changedFiles = await gitTracker.detectChanges();
+    if (!changedFiles || changedFiles.length === 0) {
+      return;
+    }
+    gitReindexInProgress = true;
+    const startTime = Date.now();
+    reindexStateManager.startReindex(changedFiles);
+    log(`Reindexing ${changedFiles.length} files from git change`);
+    try {
+      const count = await indexMultipleFiles(changedFiles, vectorDB, embeddings, { verbose: false });
+      const duration = Date.now() - startTime;
+      reindexStateManager.completeReindex(duration);
+      log(`\u2713 Reindexed ${count} files in ${duration}ms`);
+      lastGitReindexTime = Date.now();
+    } catch (error) {
+      reindexStateManager.failReindex();
+      log(`Git reindex failed: ${error}`, "warning");
+    } finally {
+      gitReindexInProgress = false;
+    }
+  };
+}
+async function setupGitDetection(rootDir, vectorDB, embeddings, verbose, log, reindexStateManager, fileWatcher) {
   const gitAvailable = await isGitAvailable();
   const isRepo = await isGitRepo2(rootDir);
   if (!gitAvailable) {
@@ -9404,34 +10053,204 @@ async function setupGitDetection(rootDir, vectorDB, embeddings, verbose, log) {
   log("\u2713 Detected git repository");
   const gitTracker = new GitStateTracker(rootDir, vectorDB.dbPath);
   try {
-    log("Checking for git changes...");
-    const changedFiles = await gitTracker.initialize();
-    if (changedFiles && changedFiles.length > 0) {
-      log(`\u{1F33F} Git changes detected: ${changedFiles.length} files changed`);
-      const count = await indexMultipleFiles(changedFiles, vectorDB, embeddings, { verbose });
-      log(`\u2713 Reindexed ${count} files`);
-    } else {
-      log("\u2713 Index is up to date with git state");
-    }
+    await handleGitStartup(gitTracker, vectorDB, embeddings, verbose, log, reindexStateManager);
   } catch (error) {
     log(`Failed to check git state on startup: ${error}`, "warning");
   }
+  if (fileWatcher) {
+    const gitChangeHandler = createGitChangeHandler(
+      gitTracker,
+      vectorDB,
+      embeddings,
+      verbose,
+      log,
+      reindexStateManager
+    );
+    fileWatcher.watchGit(gitChangeHandler);
+    log("\u2713 Git detection enabled (event-driven via file watcher)");
+    return { gitTracker, gitPollInterval: null };
+  }
   const pollIntervalSeconds = DEFAULT_GIT_POLL_INTERVAL_MS2 / 1e3;
-  log(`\u2713 Git detection enabled (checking every ${pollIntervalSeconds}s)`);
-  const gitPollInterval = setInterval(async () => {
+  log(`\u2713 Git detection enabled (polling fallback every ${pollIntervalSeconds}s)`);
+  const gitPollInterval = createGitPollInterval(gitTracker, vectorDB, embeddings, verbose, log, reindexStateManager);
+  return { gitTracker, gitPollInterval };
+}
+async function handleFileDeletion(filepath, vectorDB, log) {
+  log(`\u{1F5D1}\uFE0F  File deleted: ${filepath}`);
+  const manifest = new ManifestManager(vectorDB.dbPath);
+  try {
+    await vectorDB.deleteByFile(filepath);
+    await manifest.removeFile(filepath);
+    log(`\u2713 Removed ${filepath} from index`);
+  } catch (error) {
+    log(`Failed to remove ${filepath}: ${error}`, "warning");
+    throw error;
+  }
+}
+async function handleSingleFileChange(filepath, type, vectorDB, embeddings, _verbose, log, reindexStateManager) {
+  const action = type === "add" ? "added" : "changed";
+  const rootDir = getRootDirFromDbPath(vectorDB.dbPath);
+  if (type === "change") {
+    const manifest = new ManifestManager(vectorDB.dbPath);
+    const normalizedPath = normalizeToRelativePath(filepath, rootDir);
     try {
-      const changedFiles = await gitTracker.detectChanges();
-      if (changedFiles && changedFiles.length > 0) {
-        log(`\u{1F33F} Git change detected: ${changedFiles.length} files changed`);
-        indexMultipleFiles(changedFiles, vectorDB, embeddings, { verbose }).then((count) => log(`\u2713 Background reindex complete: ${count} files`)).catch((error) => log(`Background reindex failed: ${error}`, "warning"));
+      const existingEntry = await manifest.transaction(async (manifestData) => {
+        return manifestData.files[normalizedPath];
+      });
+      const { shouldReindex, newMtime } = await shouldReindexFile(filepath, existingEntry, log);
+      if (!shouldReindex && newMtime && existingEntry) {
+        const skipReindex = await manifest.transaction(async (manifestData) => {
+          const entry = manifestData.files[normalizedPath];
+          if (entry) {
+            entry.lastModified = newMtime;
+            return true;
+          }
+          return false;
+        });
+        if (skipReindex) {
+          return;
+        }
       }
     } catch (error) {
-      log(`Git detection check failed: ${error}`, "warning");
+      log(`Content hash check failed, will reindex: ${error}`, "warning");
     }
-  }, DEFAULT_GIT_POLL_INTERVAL_MS2);
-  return { gitTracker, gitPollInterval };
+  }
+  const startTime = Date.now();
+  reindexStateManager.startReindex([filepath]);
+  log(`\u{1F4DD} File ${action}: ${filepath}`);
+  try {
+    await indexSingleFile(filepath, vectorDB, embeddings, { verbose: false, rootDir });
+    const duration = Date.now() - startTime;
+    reindexStateManager.completeReindex(duration);
+  } catch (error) {
+    reindexStateManager.failReindex();
+    log(`Failed to reindex ${filepath}: ${error}`, "warning");
+  }
 }
-async function setupFileWatching(watch, rootDir, vectorDB, embeddings, verbose, log) {
+async function shouldReindexFile(filepath, existingEntry, log) {
+  if (!existingEntry?.contentHash) {
+    return { shouldReindex: true };
+  }
+  const currentHash = await computeContentHash(filepath);
+  if (currentHash && currentHash === existingEntry.contentHash) {
+    log(`\u23ED\uFE0F  File mtime changed but content unchanged: ${filepath}`, "debug");
+    try {
+      const fs5 = await import("fs/promises");
+      const stats = await fs5.stat(filepath);
+      return { shouldReindex: false, newMtime: stats.mtimeMs };
+    } catch {
+      return { shouldReindex: true };
+    }
+  }
+  return { shouldReindex: true };
+}
+async function filterModifiedFilesByHash(modifiedFiles, vectorDB, log) {
+  if (modifiedFiles.length === 0) {
+    return [];
+  }
+  const manifest = new ManifestManager(vectorDB.dbPath);
+  const rootDir = getRootDirFromDbPath(vectorDB.dbPath);
+  const manifestData = await manifest.transaction(async (data) => data);
+  if (!manifestData) {
+    return modifiedFiles;
+  }
+  const checkResults = [];
+  for (const filepath of modifiedFiles) {
+    const normalizedPath = normalizeToRelativePath(filepath, rootDir);
+    const existingEntry = manifestData.files[normalizedPath];
+    const { shouldReindex, newMtime } = await shouldReindexFile(filepath, existingEntry, log);
+    checkResults.push({
+      filepath,
+      normalizedPath,
+      shouldReindex,
+      newMtime
+    });
+  }
+  await manifest.transaction(async (data) => {
+    for (const result of checkResults) {
+      if (!result.shouldReindex && result.newMtime) {
+        const entry = data.files[result.normalizedPath];
+        if (entry) {
+          entry.lastModified = result.newMtime;
+        }
+      }
+    }
+    return null;
+  });
+  return checkResults.filter((r) => r.shouldReindex).map((r) => r.filepath);
+}
+async function prepareFilesForReindexing(event, vectorDB, log) {
+  const addedFiles = event.added || [];
+  const modifiedFiles = event.modified || [];
+  const deletedFiles = event.deleted || [];
+  let modifiedFilesToReindex = [];
+  try {
+    modifiedFilesToReindex = await filterModifiedFilesByHash(modifiedFiles, vectorDB, log);
+  } catch (error) {
+    log(`Hash-based filtering failed, will reindex all modified files: ${error}`, "warning");
+    modifiedFilesToReindex = modifiedFiles;
+  }
+  const filesToIndex = [...addedFiles, ...modifiedFilesToReindex];
+  return { filesToIndex, deletedFiles };
+}
+async function executeReindexOperations(filesToIndex, deletedFiles, vectorDB, embeddings, log) {
+  const operations = [];
+  if (filesToIndex.length > 0) {
+    log(`\u{1F4C1} ${filesToIndex.length} file(s) changed, reindexing...`);
+    operations.push(indexMultipleFiles(filesToIndex, vectorDB, embeddings, { verbose: false }));
+  }
+  if (deletedFiles.length > 0) {
+    operations.push(
+      Promise.all(
+        deletedFiles.map((deleted) => handleFileDeletion(deleted, vectorDB, log))
+      )
+    );
+  }
+  await Promise.all(operations);
+}
+async function handleBatchEvent(event, vectorDB, embeddings, _verbose, log, reindexStateManager) {
+  const { filesToIndex, deletedFiles } = await prepareFilesForReindexing(event, vectorDB, log);
+  const allFiles = [...filesToIndex, ...deletedFiles];
+  if (allFiles.length === 0) {
+    return;
+  }
+  const startTime = Date.now();
+  reindexStateManager.startReindex(allFiles);
+  try {
+    await executeReindexOperations(filesToIndex, deletedFiles, vectorDB, embeddings, log);
+    const duration = Date.now() - startTime;
+    reindexStateManager.completeReindex(duration);
+    log(`\u2713 Processed ${filesToIndex.length} file(s) + ${deletedFiles.length} deletion(s) in ${duration}ms`);
+  } catch (error) {
+    reindexStateManager.failReindex();
+    log(`Batch reindex failed: ${error}`, "warning");
+  }
+}
+async function handleUnlinkEvent(filepath, vectorDB, log, reindexStateManager) {
+  const startTime = Date.now();
+  reindexStateManager.startReindex([filepath]);
+  try {
+    await handleFileDeletion(filepath, vectorDB, log);
+    const duration = Date.now() - startTime;
+    reindexStateManager.completeReindex(duration);
+  } catch (error) {
+    reindexStateManager.failReindex();
+    log(`Failed to process deletion for ${filepath}: ${error}`, "warning");
+  }
+}
+function createFileChangeHandler(vectorDB, embeddings, verbose, log, reindexStateManager) {
+  return async (event) => {
+    const { type } = event;
+    if (type === "batch") {
+      await handleBatchEvent(event, vectorDB, embeddings, verbose, log, reindexStateManager);
+    } else if (type === "unlink") {
+      await handleUnlinkEvent(event.filepath, vectorDB, log, reindexStateManager);
+    } else {
+      await handleSingleFileChange(event.filepath, type, vectorDB, embeddings, verbose, log, reindexStateManager);
+    }
+  };
+}
+async function setupFileWatching(watch, rootDir, vectorDB, embeddings, verbose, log, reindexStateManager) {
   const fileWatchingEnabled = watch !== void 0 ? watch : true;
   if (!fileWatchingEnabled) {
     return null;
@@ -9439,24 +10258,8 @@ async function setupFileWatching(watch, rootDir, vectorDB, embeddings, verbose,
   log("\u{1F440} Starting file watcher...");
   const fileWatcher = new FileWatcher(rootDir);
   try {
-    await fileWatcher.start(async (event) => {
-      const { type, filepath } = event;
-      if (type === "unlink") {
-        log(`\u{1F5D1}\uFE0F  File deleted: ${filepath}`);
-        try {
-          await vectorDB.deleteByFile(filepath);
-          const manifest = new ManifestManager(vectorDB.dbPath);
-          await manifest.removeFile(filepath);
-          log(`\u2713 Removed ${filepath} from index`);
-        } catch (error) {
-          log(`Failed to remove ${filepath}: ${error}`, "warning");
-        }
-      } else {
-        const action = type === "add" ? "added" : "changed";
-        log(`\u{1F4DD} File ${action}: ${filepath}`);
-        indexSingleFile(filepath, vectorDB, embeddings, { verbose }).catch((error) => log(`Failed to reindex ${filepath}: ${error}`, "warning"));
-      }
-    });
+    const handler = createFileChangeHandler(vectorDB, embeddings, verbose, log, reindexStateManager);
+    await fileWatcher.start(handler);
     log(`\u2713 File watching enabled (watching ${fileWatcher.getWatchedFiles().length} files)`);
     return fileWatcher;
   } catch (error) {
@@ -9483,7 +10286,7 @@ function setupCleanupHandlers(versionCheckInterval, gitPollInterval, fileWatcher
     process.exit(0);
   };
 }
-function setupVersionChecking(vectorDB, log) {
+function setupVersionChecking(vectorDB, log, reindexStateManager) {
   const checkAndReconnect = async () => {
     try {
       if (await vectorDB.checkVersion()) {
@@ -9494,10 +10297,19 @@ function setupVersionChecking(vectorDB, log) {
       log(`Version check failed: ${error}`, "warning");
     }
   };
-  const getIndexMetadata = () => ({
-    indexVersion: vectorDB.getCurrentVersion(),
-    indexDate: vectorDB.getVersionDate()
-  });
+  const getIndexMetadata = () => {
+    const reindex = reindexStateManager.getState();
+    return {
+      indexVersion: vectorDB.getCurrentVersion(),
+      indexDate: vectorDB.getVersionDate(),
+      reindexInProgress: reindex.inProgress,
+      pendingFileCount: reindex.pendingFiles.length,
+      lastReindexDurationMs: reindex.lastReindexDurationMs,
+      // Note: msSinceLastReindex is computed at call time, not cached.
+      // This ensures AI assistants always get current freshness info.
+      msSinceLastReindex: reindex.lastReindexTimestamp ? Date.now() - reindex.lastReindexTimestamp : null
+    };
+  };
   const interval = setInterval(checkAndReconnect, VERSION_CHECK_INTERVAL_MS);
   return { interval, checkAndReconnect, getIndexMetadata };
 }
@@ -9543,13 +10355,13 @@ function createMCPServer() {
     { capabilities: serverConfig.capabilities }
   );
 }
-async function setupAndConnectServer(server, toolContext, log, versionCheckInterval, options) {
+async function setupAndConnectServer(server, toolContext, log, versionCheckInterval, reindexStateManager, options) {
   const { rootDir, verbose, watch } = options;
   const { vectorDB, embeddings } = toolContext;
   registerMCPHandlers(server, toolContext, log);
   await handleAutoIndexing(vectorDB, rootDir, log);
-  const { gitPollInterval } = await setupGitDetection(rootDir, vectorDB, embeddings, verbose, log);
-  const fileWatcher = await setupFileWatching(watch, rootDir, vectorDB, embeddings, verbose, log);
+  const fileWatcher = await setupFileWatching(watch, rootDir, vectorDB, embeddings, verbose, log, reindexStateManager);
+  const { gitPollInterval } = await setupGitDetection(rootDir, vectorDB, embeddings, verbose, log, reindexStateManager, fileWatcher);
   const cleanup = setupCleanupHandlers(versionCheckInterval, gitPollInterval, fileWatcher, log);
   process.on("SIGINT", cleanup);
   process.on("SIGTERM", cleanup);
@@ -9572,9 +10384,18 @@ async function startMCPServer(options) {
   const { embeddings, vectorDB } = await initializeComponents(rootDir, earlyLog);
   const server = createMCPServer();
   const log = createMCPLog(server, verbose);
-  const { interval: versionCheckInterval, checkAndReconnect, getIndexMetadata } = setupVersionChecking(vectorDB, log);
-  const toolContext = { vectorDB, embeddings, rootDir, log, checkAndReconnect, getIndexMetadata };
-  await setupAndConnectServer(server, toolContext, log, versionCheckInterval, { rootDir, verbose, watch });
+  const reindexStateManager = createReindexStateManager();
+  const { interval: versionCheckInterval, checkAndReconnect, getIndexMetadata } = setupVersionChecking(vectorDB, log, reindexStateManager);
+  const toolContext = {
+    vectorDB,
+    embeddings,
+    rootDir,
+    log,
+    checkAndReconnect,
+    getIndexMetadata,
+    getReindexState: () => reindexStateManager.getState()
+  };
+  await setupAndConnectServer(server, toolContext, log, versionCheckInterval, reindexStateManager, { rootDir, verbose, watch });
 }
 
 // src/cli/serve.ts