fix: reopen DB when its file is replaced at the same path (#925)

After a project dir is removed and recreated at the same path (a
`git worktree remove`+`add`, or a fresh `codegraph init`), a long-lived
MCP server kept reading the old, now-unlinked inode while init/sync wrote
to the new one — serving a stale snapshot for the life of the daemon, with
`codegraph sync` unable to refresh it.

DatabaseConnection records its DB file's (dev, ino) at open and exposes
isFileReplaced(); CodeGraph surfaces it as isDbReplaced(). Detection runs at
the per-tool-call chokepoint, ToolHandler.getCodeGraph:
  - cross-project (projectPath) cache hits evict + close a replaced entry so
    the next query reopens against the new inode;
  - the default project is reopened via a hook the MCPEngine registers (it
    owns the default instance's watcher + catch-up), driven from the
    default-serving path rather than the cold init methods, which a loaded
    daemon never re-enters.

A missing file (mid-recreate) is ignored so a transient gap never churns the
connection.

Author: Sway-Chan

__tests__/mcp-db-reopen.test.ts

@@ -0,0 +1,134 @@
+/**
+ * Reopen a DB connection when its file is replaced under us (same path, new
+ * inode). Regression for issue #925.
+ *
+ * Scenario: the project dir is removed and recreated at the same path (a
+ * `git worktree remove` + `git worktree add`, or a fresh `codegraph init`).
+ * A long-lived SQLite handle keeps reading the old, now-unlinked inode while
+ * `init`/`sync` write to the new inode at the same path — so the MCP server
+ * served a stale snapshot for the life of the daemon. Four layers are covered:
+ *   1. `DatabaseConnection.isFileReplaced()` — the inode-identity primitive.
+ *   2. `CodeGraph.isDbReplaced()` — a live instance reports its DB was swapped.
+ *   3. `ToolHandler.liveCachedGraph()` — a cross-project (`projectPath`) cache
+ *      hit on a replaced DB is evicted + closed, so the caller reopens against
+ *      the new inode (the existing open path) instead of serving the stale one.
+ *   4. `ToolHandler.getCodeGraph()` default path — a swapped default project is
+ *      reopened via the engine reload hook (the steady-state tool-call path,
+ *      which the cold init methods never re-enter — issue #925's headline case).
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import CodeGraph from '../src/index';
+import { DatabaseConnection } from '../src/db';
+import { ToolHandler } from '../src/mcp/tools';
+
+const rmDb = (dbPath: string) => {
+  for (const p of [dbPath, `${dbPath}-wal`, `${dbPath}-shm`]) fs.rmSync(p, { force: true });
+};
+
+describe('DatabaseConnection.isFileReplaced (issue #925)', () => {
+  let dir: string;
+  beforeEach(() => { dir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-dbid-')); });
+  afterEach(() => { fs.rmSync(dir, { recursive: true, force: true }); });
+
+  it('false while the same file; true after the file at the path is swapped; false while missing', () => {
+    const dbPath = path.join(dir, 'graph.db');
+    const conn = DatabaseConnection.initialize(dbPath); // records inode A
+    expect(conn.isFileReplaced()).toBe(false);
+
+    // Replace the file at the same path with a brand-new inode (the recreate).
+    rmDb(dbPath);
+    DatabaseConnection.initialize(dbPath).close(); // creates inode B at the same path
+    expect(conn.isFileReplaced()).toBe(true);
+
+    // Mid-recreate gap (file absent) must NOT count — don't churn on a transient.
+    rmDb(dbPath);
+    expect(conn.isFileReplaced()).toBe(false);
+
+    conn.close();
+  });
+});
+
+describe('Reopen on replaced project DB (issue #925)', () => {
+  let dir: string;
+
+  const buildProject = async (fnName: string) => {
+    fs.mkdirSync(path.join(dir, 'src'), { recursive: true });
+    fs.writeFileSync(path.join(dir, 'src', 'probe.ts'), `export function ${fnName}() { return 1; }\n`);
+    const cg = CodeGraph.initSync(dir, { config: { include: ['**/*.ts'], exclude: [] } });
+    await cg.indexAll();
+    cg.close();
+  };
+  const replaceProjectDb = async (fnName: string) => {
+    fs.rmSync(path.join(dir, '.codegraph'), { recursive: true, force: true });
+    await buildProject(fnName);
+  };
+
+  beforeEach(() => { dir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-db-reopen-')); });
+  afterEach(() => { fs.rmSync(dir, { recursive: true, force: true }); });
+
+  it('CodeGraph.isDbReplaced flips after the DB file is recreated at the same path', async () => {
+    await buildProject('probeAlpha');
+    const cg = CodeGraph.openSync(dir);
+    try {
+      expect(cg.isDbReplaced()).toBe(false);
+      await replaceProjectDb('probeBeta'); // new .codegraph/codegraph.db = new inode
+      expect(cg.isDbReplaced()).toBe(true);
+    } finally {
+      cg.close();
+    }
+  });
+
+  it('ToolHandler.liveCachedGraph evicts + closes a cached project whose DB file was replaced', async () => {
+    await buildProject('probeAlpha');
+    const cg = CodeGraph.openSync(dir);
+    const closeSpy = vi.spyOn(cg, 'close');
+    const handler = new ToolHandler(null);
+    // Seed the cross-project cache the way getCodeGraph would (private field).
+    (handler as unknown as { projectCache: Map<string, CodeGraph> }).projectCache.set(dir, cg);
+    const live = (k: string) => (handler as unknown as { liveCachedGraph(k: string): CodeGraph | null }).liveCachedGraph(k);
+    const cached = () => (handler as unknown as { projectCache: Map<string, CodeGraph> }).projectCache;
+
+    // Fresh → returned as-is, not evicted/closed.
+    expect(live(dir)).toBe(cg);
+    expect(closeSpy).not.toHaveBeenCalled();
+
+    // Replace the DB file at the same path → next lookup evicts + closes it,
+    // returning null so the caller falls through to reopen against the new DB.
+    await replaceProjectDb('probeBeta');
+    expect(live(dir)).toBeNull();
+    expect(cached().has(dir)).toBe(false);
+    expect(closeSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('getCodeGraph reopens the DEFAULT project via the reload hook when its DB file was replaced', async () => {
+    await buildProject('probeAlpha');
+    const stale = CodeGraph.openSync(dir);
+    const handler = new ToolHandler(stale);
+    // Mirror the engine's reload hook: open the fresh DB and install it as default.
+    let hookCalls = 0;
+    handler.setDefaultReloadHook(() => {
+      hookCalls++;
+      handler.setDefaultCodeGraph(CodeGraph.openSync(dir));
+    });
+    const getDefault = () =>
+      (handler as unknown as { getCodeGraph(p?: string): CodeGraph }).getCodeGraph();
+
+    // Fresh default → served as-is on the steady-state (no-projectPath) path; hook not fired.
+    expect(getDefault()).toBe(stale);
+    expect(hookCalls).toBe(0);
+
+    // Replace the DB at the same path → the default-serving path detects it and
+    // fires the hook, which installs a fresh default; the call returns the new one.
+    await replaceProjectDb('probeBeta');
+    const reopened = getDefault();
+    expect(hookCalls).toBe(1);
+    expect(reopened).not.toBe(stale);
+    expect(reopened.isDbReplaced()).toBe(false); // fresh handle on the new inode
+
+    stale.close();
+    reopened.close();
+  });
+});

src/db/index.ts

@@ -37,18 +37,38 @@ function configureConnection(db: SqliteDatabase): void {
   db.pragma('mmap_size = 268435456');    // 256 MB memory-mapped I/O
 }
 
+/**
+ * Identity of a DB file as `dev:ino`, or null if it does not exist. Lets a
+ * long-lived connection notice when the file at its fixed path was swapped for
+ * a different inode — e.g. the project dir was removed and recreated at the
+ * same path (`git worktree remove`+`add`, or a fresh `codegraph init`), which
+ * leaves the open handle pinned to the old, now-unlinked inode. See #925.
+ */
+function dbFileIdentity(dbPath: string): string | null {
+  try {
+    const st = fs.statSync(dbPath);
+    return `${st.dev}:${st.ino}`;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Database connection wrapper with lifecycle management
  */
 export class DatabaseConnection {
   private db: SqliteDatabase;
   private dbPath: string;
   private backend: SqliteBackend;
+  // Identity (`dev:ino`) of the DB file when this connection opened it, so a
+  // replaced file at the same path (#925) is detectable via isFileReplaced().
+  private dbFileId: string | null;
 
   private constructor(db: SqliteDatabase, dbPath: string, backend: SqliteBackend) {
     this.db = db;
     this.dbPath = dbPath;
     this.backend = backend;
+    this.dbFileId = dbFileIdentity(dbPath);
   }
 
   /**
@@ -128,6 +148,18 @@ export class DatabaseConnection {
     return this.dbPath;
   }
 
+  /**
+   * Whether the DB file at this connection's path has been replaced by a
+   * different inode since we opened it — i.e. the open handle is now pinned to
+   * a deleted file while reads/writes at the path land on a new one. A missing
+   * file (mid-recreate) reports false, so a transient gap doesn't churn the
+   * connection; only a concrete swap to a new inode counts. See #925.
+   */
+  isFileReplaced(): boolean {
+    const current = dbFileIdentity(this.dbPath);
+    return current !== null && current !== this.dbFileId;
+  }
+
   /**
    * The journal mode actually in effect (e.g. 'wal', 'delete').
    *

src/index.ts

@@ -317,6 +317,17 @@ export class CodeGraph {
     this.db.close();
   }
 
+  /**
+   * Whether the underlying DB file was replaced on disk since this instance
+   * opened it (same path, new inode — e.g. a `git worktree remove`+`add` or a
+   * fresh `codegraph init` at the same path). Callers that hold a long-lived
+   * instance use this to reopen instead of serving the stale, now-unlinked
+   * snapshot. See #925.
+   */
+  isDbReplaced(): boolean {
+    return this.db.isFileReplaced();
+  }
+
   /**
    * Get the project root directory
    */

src/mcp/engine.ts

@@ -55,6 +55,11 @@ export class MCPEngine {
   constructor(opts: MCPEngineOptions = {}) {
     this.opts = { watch: opts.watch ?? true };
     this.toolHandler = new ToolHandler(null);
+    // Reopen the default project's stale handle from the per-tool-call chokepoint
+    // (ToolHandler.getCodeGraph), not just the cold init paths — a loaded daemon
+    // never re-enters those, so without this the default-project swap (#925) would
+    // never be detected at runtime.
+    this.toolHandler.setDefaultReloadHook(() => this.reloadDefaultIfDbReplaced());
   }
 
   /**
@@ -138,6 +143,44 @@ export class MCPEngine {
     }
   }
 
+  /**
+   * Reopen the default project's CodeGraph if its on-disk DB file was replaced
+   * (same path, different inode) since we opened it — e.g. the project dir was
+   * removed and recreated at the same path (`git worktree remove` + `add`, or a
+   * fresh `codegraph init`). The long-lived SQLite handle would otherwise keep
+   * reading the old, now-unlinked inode while every `init`/`sync` writes to the
+   * new one, serving a stale snapshot for the life of the daemon. See #925.
+   *
+   * Invoked via the ToolHandler default-reload hook from `getCodeGraph`, i.e. on
+   * the per-tool-call path that serves the default project — not the cold init
+   * methods, which a loaded daemon never re-enters. Fully synchronous and run
+   * between requests, so the close+reopen never races an in-flight query. Opens
+   * the replacement before closing the stale handle, so a failed reopen leaves
+   * the (still-functional, if stale) current connection in place rather than
+   * tearing it down to nothing.
+   */
+  private reloadDefaultIfDbReplaced(): void {
+    if (this.closed || !this.cg || !this.projectPath || !this.cg.isDbReplaced()) return;
+
+    const root = this.projectPath;
+    let next: CodeGraph;
+    try {
+      next = loadCodeGraph().openSync(root);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`[CodeGraph MCP] DB for ${root} was replaced but reopening failed: ${msg}\n`);
+      return;
+    }
+    process.stderr.write(`[CodeGraph MCP] Database file for ${root} was replaced (inode changed); reopened.\n`);
+    const old = this.cg;
+    this.cg = next;
+    this.watcherStarted = false;
+    this.toolHandler.setDefaultCodeGraph(next);
+    try { old?.close(); } catch { /* ignore */ }
+    this.startWatching();
+    this.catchUpSync();
+  }
+
   /**
    * Close everything. Used on graceful daemon shutdown (SIGTERM/idle timeout)
    * and on direct-mode stop. Idempotent.

src/mcp/tools.ts

@@ -681,6 +681,11 @@ export class ToolHandler {
   // populated by the watcher, not by catch-up. Cleared on first await so
   // subsequent calls don't pay any cost.
   private catchUpGate: Promise<void> | null = null;
+  // Hook the MCP engine registers so getCodeGraph can reopen the default
+  // project when its DB file was replaced on disk (#925). The engine owns the
+  // default instance's watcher/catch-up, so the reopen is delegated to it.
+  // Null when the handler has no engine (e.g. unit tests).
+  private onDefaultStale: (() => void) | null = null;
 
   constructor(private cg: CodeGraph | null) {}
 
@@ -702,6 +707,14 @@ export class ToolHandler {
     this.catchUpGate = p;
   }
 
+  /**
+   * Register the engine's hook to reopen the default project if its DB file was
+   * replaced on disk. Called from getCodeGraph on the default-serving path. See #925.
+   */
+  setDefaultReloadHook(fn: (() => void) | null): void {
+    this.onDefaultStale = fn;
+  }
+
   /**
    * Record the directory the server tried to resolve the default project from.
    * Used only to make the "no default project" error actionable.
@@ -806,6 +819,38 @@ export class ToolHandler {
     }
   }
 
+  /**
+   * If the default project's DB file was replaced on disk (#925), ask the engine
+   * (via its registered hook) to reopen it before we serve `this.cg`; the engine
+   * owns the default instance's watcher/catch-up, so the reopen is delegated.
+   * After the hook runs, `this.cg` points at the fresh instance. No-op without a
+   * registered hook or an open default.
+   */
+  private refreshDefaultIfReplaced(): void {
+    if (this.onDefaultStale && this.cg?.isDbReplaced()) this.onDefaultStale();
+  }
+
+  /**
+   * Return the cached CodeGraph for `key` if its DB file is still the one it
+   * opened. If the file was replaced on disk (same path, new inode — a
+   * `git worktree remove`+`add`, or a fresh `codegraph init`), evict and close
+   * the stale instance and return null so the caller reopens against the new
+   * inode instead of serving the now-unlinked snapshot for the daemon's life.
+   * The default instance is never cached here, so closing a cached one is safe.
+   * See #925.
+   */
+  private liveCachedGraph(key: string): CodeGraph | null {
+    const cg = this.projectCache.get(key);
+    if (!cg) return null;
+    if (!cg.isDbReplaced()) return cg;
+    // Drop every key that points at this replaced instance, then close it once.
+    for (const [k, v] of this.projectCache) {
+      if (v === cg) this.projectCache.delete(k);
+    }
+    try { cg.close(); } catch { /* ignore */ }
+    return null;
+  }
+
   /**
    * Get CodeGraph instance for a project
    *
@@ -817,6 +862,7 @@ export class ToolHandler {
    */
   private getCodeGraph(projectPath?: string): CodeGraph {
     if (!projectPath) {
+      this.refreshDefaultIfReplaced();
       if (!this.cg) {
         const searched = this.defaultProjectHint ?? process.cwd();
         throw new NotIndexedError(
@@ -834,10 +880,10 @@ export class ToolHandler {
       return this.cg;
     }
 
-    // Check cache first (using original path as key)
-    if (this.projectCache.has(projectPath)) {
-      return this.projectCache.get(projectPath)!;
-    }
+    // Check cache first (using original path as key). Reopen instead of serving
+    // a cached instance whose DB file was replaced on disk under us (#925).
+    const cached = this.liveCachedGraph(projectPath);
+    if (cached) return cached;
 
     // Reject sensitive system directories before opening. Only validate a
     // path that actually exists — a nested or not-yet-created sub-path of a
@@ -871,15 +917,16 @@ export class ToolHandler {
     // not cached under projectPath — the server owns and closes the default
     // instance, so routing it through projectCache.closeAll() would double-close it.
     if (this.cg && this.cg.getProjectRoot() === resolvedRoot) {
+      this.refreshDefaultIfReplaced();
       return this.cg;
     }
 
     // Check if we already have this resolved root cached (different path, same project)
-    if (this.projectCache.has(resolvedRoot)) {
-      const cg = this.projectCache.get(resolvedRoot)!;
+    const hit = this.liveCachedGraph(resolvedRoot);
+    if (hit) {
       // Cache under original path too for faster future lookups
-      this.projectCache.set(projectPath, cg);
-      return cg;
+      this.projectCache.set(projectPath, hit);
+      return hit;
     }
 
     // Open and cache under both paths