@liendev/lien 0.27.0 → 0.28.1

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;
+      }
+      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();
       }
-    }, DEFAULT_DEBOUNCE_MS2);
-    this.debounceTimers.set(filepath, timer);
+    } 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.
@@ -8277,7 +8475,7 @@ var NEVER = INVALID;
 // src/mcp/schemas/search.schema.ts
 var SemanticSearchSchema = external_exports.object({
   query: external_exports.string().min(3, "Query must be at least 3 characters").max(500, "Query too long (max 500 characters)").describe(
-    "Natural language description of what you're looking for.\n\nUse full sentences describing functionality, not exact names.\n\nGood examples:\n  - 'handles user authentication'\n  - 'validates email format'\n  - 'processes payment transactions'\n\nBad examples:\n  - 'auth' (too vague)\n  - 'validateEmail' (use grep for exact names)"
+    "Natural language description of what you're looking for.\n\nUse full sentences describing functionality, not exact names.\n\nGood examples:\n  - 'How does the code handle user authentication?'\n  - 'Where are email addresses validated?'\n  - 'How are payment transactions processed?'\n\nBad examples:\n  - 'auth' (too vague)\n  - 'validateEmail' (use grep for exact names)"
   ),
   limit: external_exports.number().int().min(1, "Limit must be at least 1").max(50, "Limit cannot exceed 50").default(5).describe(
     "Number of results to return.\n\nDefault: 5\nIncrease to 10-15 for broad exploration."
@@ -8372,8 +8570,10 @@ var tools = [
     `Search codebase by MEANING, not text. Complements grep - use this for discovery and understanding, grep for exact matches.
 
 Examples:
-- "Where is authentication handled?" \u2192 semantic_search({ query: "handles user authentication" })
-- "How does payment work?" \u2192 semantic_search({ query: "processes payment transactions" })
+- "Where is authentication handled?" \u2192 semantic_search({ query: "How does the code handle user authentication?" })
+- "How does payment work?" \u2192 semantic_search({ query: "How are payment transactions processed and validated?" })
+
+IMPORTANT: Phrase queries as full questions starting with "How", "Where", "What", etc. Full questions produce significantly better relevance than keyword phrases.
 
 Use natural language describing what the code DOES, not function names. For exact string matching, use grep instead.
 
@@ -9579,6 +9779,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);
@@ -9589,6 +9917,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...");
@@ -9621,7 +9952,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) {
@@ -9635,34 +10055,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 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) {
+async function setupFileWatching(watch, rootDir, vectorDB, embeddings, verbose, log, reindexStateManager) {
   const fileWatchingEnabled = watch !== void 0 ? watch : true;
   if (!fileWatchingEnabled) {
     return null;
@@ -9670,24 +10260,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) {
@@ -9714,7 +10288,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()) {
@@ -9725,10 +10299,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 };
 }
@@ -9774,13 +10357,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);
@@ -9803,9 +10386,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