codebrain 0.3.3__tar.gz → 0.3.5__tar.gz

{codebrain-0.3.3 → codebrain-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codebrain
-Version: 0.3.3
+Version: 0.3.5
 Summary: Know what breaks before you break it. Structural knowledge graph for codebases — impact analysis, dead code detection, health scores. No LLM required.
 Author: CodeBrain Contributors
 License: MIT License

{codebrain-0.3.3 → codebrain-0.3.5}/codebrain/__init__.py

@@ -7,4 +7,4 @@ try:
 except PackageNotFoundError:
     # Source checkout without installation (e.g. running from a worktree).
     # Keep in sync with [project.version] in pyproject.toml.
-    __version__ = "0.3.3"
+    __version__ = "0.3.5"

{codebrain-0.3.3 → codebrain-0.3.5}/codebrain/cli.py

@@ -375,7 +375,7 @@ def setup(ctx: click.Context, force: bool) -> None:
     project_name = repo_root.name
 
     # 1. Index if needed
-    db_path = _get_db(repo_root)
+    db_path = _db_path(repo_root)
     if not db_path.exists():
         files = discover_files(repo_root)
         click.echo(f"Indexing {repo_root} ({len(files)} files) ...")

{codebrain-0.3.3 → codebrain-0.3.5}/codebrain/graph/store.py

@@ -113,6 +113,11 @@ class GraphStore:
         ).fetchone()
         return row["content_hash"] if row else None
 
+    def all_file_paths(self) -> list[str]:
+        """Return every file path currently in the index."""
+        rows = self.conn.execute("SELECT path FROM files").fetchall()
+        return [row["path"] for row in rows]
+
     # ------------------------------------------------------------------
     # Node operations
     # ------------------------------------------------------------------

{codebrain-0.3.3 → codebrain-0.3.5}/codebrain/mcp_lifecycle.py

@@ -167,7 +167,7 @@ def _remove_pid_file(pid_file: Path) -> None:
         pass
 
 
-def _find_watch_target(start_pid: int) -> tuple[int, float | None]:
+def _find_watch_target(start_pid: int) -> tuple[int, float | None, bool]:
     """Pick the PID whose death should kill the MCP.
 
     Walks up the ancestor chain (up to ANCESTOR_WALK_DEPTH levels) looking
@@ -175,6 +175,10 @@ def _find_watch_target(start_pid: int) -> tuple[int, float | None]:
     real IDE host. Falls back to ``start_pid`` if no hint matches, psutil
     is unavailable, or ``CODEBRAIN_MCP_DISABLE_ANCESTOR_WALK=1`` is set.
 
+    Returns ``(pid, create_time, host_anchored)``. ``host_anchored`` is True
+    only when an actual IDE host process was found — callers use it to decide
+    whether the idle-timeout backstop is needed at all.
+
     Why: on Windows, Claude Code spawns the MCP via a transient launcher
     (cmd.exe wrapper or Electron worker shell). The launcher exits soon
     after the python child starts, so watching ``os.getppid()`` directly
@@ -183,16 +187,16 @@ def _find_watch_target(start_pid: int) -> tuple[int, float | None]:
     try:
         import psutil
     except ImportError:
-        return start_pid, None
+        return start_pid, None, False
 
     fallback_create_time: float | None = None
     try:
         fallback_create_time = psutil.Process(start_pid).create_time()
     except (psutil.NoSuchProcess, psutil.AccessDenied):
-        return start_pid, None
+        return start_pid, None, False
 
     if os.environ.get("CODEBRAIN_MCP_DISABLE_ANCESTOR_WALK") == "1":
-        return start_pid, fallback_create_time
+        return start_pid, fallback_create_time, False
 
     try:
         proc = psutil.Process(start_pid)
@@ -202,7 +206,7 @@ def _find_watch_target(start_pid: int) -> tuple[int, float | None]:
             except (psutil.NoSuchProcess, psutil.AccessDenied):
                 break
             if any(hint in name for hint in HOST_PROCESS_NAME_HINTS):
-                return proc.pid, proc.create_time()
+                return proc.pid, proc.create_time(), True
             try:
                 parent = proc.parent()
             except (psutil.NoSuchProcess, psutil.AccessDenied):
@@ -212,7 +216,7 @@ def _find_watch_target(start_pid: int) -> tuple[int, float | None]:
             proc = parent
     except (psutil.NoSuchProcess, psutil.AccessDenied):
         pass
-    return start_pid, fallback_create_time
+    return start_pid, fallback_create_time, False
 
 
 def _parent_watchdog(initial_ppid: int, initial_create_time: float | None) -> None:
@@ -241,16 +245,35 @@ def _parent_watchdog(initial_ppid: int, initial_create_time: float | None) -> No
             _log.debug("parent watchdog tick error: %s", exc)
 
 
-def _idle_watchdog() -> None:
-    if IDLE_TIMEOUT_SECONDS <= 0:
+def _effective_idle_timeout(host_anchored: bool) -> int:
+    """Resolve the idle timeout in seconds (0 disables the idle watchdog).
+
+    The idle watchdog is a *backstop* for when the parent watchdog has no
+    reliable IDE host to watch. When we are anchored to a real host
+    (claude/cursor/vscode), the parent watchdog deterministically tears the
+    server down at session end — an idle timeout on top of that only kills
+    the file watcher mid-session and leaves the index stale. So:
+
+    - explicit ``CODEBRAIN_MCP_IDLE_TIMEOUT`` env var always wins
+    - otherwise: disabled when host-anchored, 30-min backstop when not
+    """
+    if "CODEBRAIN_MCP_IDLE_TIMEOUT" in os.environ:
+        return IDLE_TIMEOUT_SECONDS
+    if host_anchored:
+        return 0
+    return IDLE_TIMEOUT_SECONDS
+
+
+def _idle_watchdog(timeout: int) -> None:
+    if timeout <= 0:
         return
-    poll = max(5, min(60, IDLE_TIMEOUT_SECONDS // 4))
+    poll = max(5, min(60, timeout // 4))
     while True:
         time.sleep(poll)
         with _last_activity_lock:
             idle = time.time() - _last_activity
-        if idle > IDLE_TIMEOUT_SECONDS:
-            _exit(f"idle for {idle:.0f}s (limit {IDLE_TIMEOUT_SECONDS}s)")
+        if idle > timeout:
+            _exit(f"idle for {idle:.0f}s (limit {timeout}s)")
 
 
 def _lifetime_watchdog(start: float) -> None:
@@ -285,13 +308,16 @@ def install_watchdogs(repo_root: Path | None = None) -> None:
         atexit.register(_remove_pid_file, pid_file)
 
     immediate_ppid = os.getppid()
-    initial_ppid, initial_create_time = _find_watch_target(immediate_ppid)
+    initial_ppid, initial_create_time, host_anchored = _find_watch_target(immediate_ppid)
+    idle_timeout = _effective_idle_timeout(host_anchored)
 
     _log.info(
-        "MCP watchdogs installed (ppid=%d via=%d, idle_timeout=%ds, max_lifetime=%ds)",
+        "MCP watchdogs installed (ppid=%d via=%d, host_anchored=%s, "
+        "idle_timeout=%ds, max_lifetime=%ds)",
         initial_ppid,
         immediate_ppid,
-        IDLE_TIMEOUT_SECONDS,
+        host_anchored,
+        idle_timeout,
         MAX_LIFETIME_SECONDS,
     )
 
@@ -303,6 +329,7 @@ def install_watchdogs(repo_root: Path | None = None) -> None:
     ).start()
     threading.Thread(
         target=_idle_watchdog,
+        args=(idle_timeout,),
         name="cb-idle-watchdog",
         daemon=True,
     ).start()

{codebrain-0.3.3 → codebrain-0.3.5}/codebrain/watcher/file_watcher.py

@@ -11,9 +11,10 @@ from watchdog.observers import Observer
 
 from codebrain.config import INDEXABLE_EXTENSIONS, WATCHER_DEBOUNCE_SECONDS
 from codebrain.graph.store import GraphStore
-from codebrain.indexer import incremental_update
+from codebrain.indexer import discover_files, incremental_update
+from codebrain.utils import normalize_path
 from codebrain.logging import get_logger
-from codebrain.settings import load_settings
+from codebrain.settings import Settings, load_settings
 
 _log = get_logger("watcher")
 
@@ -37,6 +38,8 @@ class _DebouncedHandler(FileSystemEventHandler):
         self._changed: set[Path] = set()
         self._deleted: set[Path] = set()
         self._lock = threading.Lock()
+        # Serializes DB writes between flush timer threads and the catch-up thread.
+        self.db_lock = threading.Lock()
         self._timer: threading.Timer | None = None
         self._last_validation: dict[str, object] = {}  # rel_path -> ValidationReport
 
@@ -57,6 +60,14 @@ class _DebouncedHandler(FileSystemEventHandler):
         if not changed and not deleted:
             return
 
+        # Live file edits count as activity — without this the idle watchdog
+        # kills the MCP (and this watcher with it) mid-editing-session.
+        try:
+            from codebrain.mcp_lifecycle import mark_activity
+            mark_activity()
+        except Exception:
+            pass
+
         # Redirect stdout to stderr to prevent MCP stdio protocol corruption
         # when running inside the MCP server process.
         import sys
@@ -67,7 +78,8 @@ class _DebouncedHandler(FileSystemEventHandler):
             if changed:
                 self._validate_changed(changed)
 
-            result = incremental_update(self.repo_root, changed, deleted, self.store)
+            with self.db_lock:
+                result = incremental_update(self.repo_root, changed, deleted, self.store)
             total = result["files_updated"] + result["files_removed"]
             if total:
                 _log.info(
@@ -147,6 +159,59 @@ class _DebouncedHandler(FileSystemEventHandler):
         self._schedule_flush()
 
 
+def catch_up_sync(
+    repo_root: Path,
+    store: GraphStore,
+    settings: Settings | None = None,
+    db_lock: threading.Lock | None = None,
+) -> dict:
+    """Bring the index up to date with changes made while no watcher was alive.
+
+    The file watcher only sees events that happen while its process is
+    running. Edits made between sessions (or after a lifecycle watchdog
+    killed the MCP server) are otherwise missed forever, leaving the index
+    stale until a manual `brain reindex`. This diffs disk vs. index:
+
+    - changed/new files: detected by content hash inside incremental_update
+    - deleted files: indexed paths that no longer exist on disk
+
+    Returns the incremental_update summary dict.
+    """
+    on_disk = discover_files(repo_root, settings)
+    disk_rels = {normalize_path(p, repo_root) for p in on_disk}
+    deleted = [
+        repo_root / rel
+        for rel in store.all_file_paths()
+        if rel not in disk_rels
+    ]
+    lock = db_lock if db_lock is not None else threading.Lock()
+    with lock:
+        result = incremental_update(repo_root, on_disk, deleted, store)
+    if result["files_updated"] or result["files_removed"]:
+        _log.info(
+            "Catch-up sync: updated %d, removed %d (%.3fs)",
+            result["files_updated"],
+            result["files_removed"],
+            result["elapsed_seconds"],
+        )
+    else:
+        _log.info("Catch-up sync: index already current")
+    return result
+
+
+def _catch_up_in_background(
+    repo_root: Path, store: GraphStore, settings: Settings, handler: _DebouncedHandler,
+) -> None:
+    # NOTE: deliberately no sys.stdout redirect here — this thread runs
+    # concurrently with the MCP initialize handshake on the real stdout;
+    # swapping the global stdout would corrupt the JSON-RPC stream.
+    # Parsers do not print, so there is nothing to redirect anyway.
+    try:
+        catch_up_sync(repo_root, store, settings, db_lock=handler.db_lock)
+    except Exception as exc:
+        _log.warning("Catch-up sync failed: %s", exc)
+
+
 def start_watching_background(
     repo_root: Path, db_path: Path,
 ) -> tuple[Observer, GraphStore, _DebouncedHandler]:
@@ -166,7 +231,15 @@ def start_watching_background(
     observer = Observer()
     observer.daemon = True
     observer.schedule(handler, str(repo_root), recursive=True)
+    # Observer starts BEFORE the catch-up scan so no event falls in the gap;
+    # the hash check in incremental_update makes any overlap harmless.
     observer.start()
+    threading.Thread(
+        target=_catch_up_in_background,
+        args=(repo_root, store, settings, handler),
+        name="cb-catchup-sync",
+        daemon=True,
+    ).start()
     _log.info("Background watcher started for %s", repo_root)
     return observer, store, handler
 

{codebrain-0.3.3 → codebrain-0.3.5}/codebrain.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codebrain
-Version: 0.3.3
+Version: 0.3.5
 Summary: Know what breaks before you break it. Structural knowledge graph for codebases — impact analysis, dead code detection, health scores. No LLM required.
 Author: CodeBrain Contributors
 License: MIT License

{codebrain-0.3.3 → codebrain-0.3.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codebrain"
-version = "0.3.3"
+version = "0.3.5"
 description = "Know what breaks before you break it. Structural knowledge graph for codebases — impact analysis, dead code detection, health scores. No LLM required."
 readme = "README.md"
 license = {file = "LICENSE"}

{codebrain-0.3.3 → codebrain-0.3.5}/tests/test_cli.py

@@ -39,6 +39,36 @@ class TestInit:
         assert "Edges:" in result.output
 
 
+class TestSetup:
+    def test_setup_cold(self, simple_project):
+        runner = CliRunner()
+        result = _invoke(runner, ["setup"], str(simple_project))
+        assert result.exit_code == 0, result.output
+        assert (simple_project / "CLAUDE.md").exists()
+        config = json.loads((simple_project / ".mcp.json").read_text())
+        assert "codebrain" in config["mcpServers"]
+        assert config["mcpServers"]["codebrain"]["args"] == ["-m", "codebrain.mcp_server"]
+
+    def test_setup_preserves_existing_mcp_servers(self, simple_project):
+        existing = {"mcpServers": {"other": {"command": "node", "args": ["server.js"]}}}
+        (simple_project / ".mcp.json").write_text(json.dumps(existing))
+        runner = CliRunner()
+        result = _invoke(runner, ["setup"], str(simple_project))
+        assert result.exit_code == 0, result.output
+        config = json.loads((simple_project / ".mcp.json").read_text())
+        assert "other" in config["mcpServers"]
+        assert "codebrain" in config["mcpServers"]
+
+    def test_setup_idempotent_without_force(self, simple_project):
+        runner = CliRunner()
+        first = _invoke(runner, ["setup"], str(simple_project))
+        assert first.exit_code == 0
+        (simple_project / "CLAUDE.md").write_text("custom user content")
+        second = _invoke(runner, ["setup"], str(simple_project))
+        assert second.exit_code == 0
+        assert (simple_project / "CLAUDE.md").read_text() == "custom user content"
+
+
 class TestStatus:
     def test_status_text(self, indexed_project):
         repo_root, store = indexed_project

{codebrain-0.3.3 → codebrain-0.3.5}/tests/test_mcp_lifecycle.py

@@ -131,9 +131,10 @@ def test_find_watch_target_falls_back_when_no_host_match(monkeypatch):
         return {10: great, 11: grand, 12: parent}[pid]
 
     monkeypatch.setattr(psutil, "Process", fake_process)
-    pid, ctime = ml._find_watch_target(12)
+    pid, ctime, anchored = ml._find_watch_target(12)
     assert pid == 12
     assert ctime == 300.0
+    assert anchored is False
 
 
 def test_find_watch_target_walks_to_claude(monkeypatch):
@@ -155,9 +156,10 @@ def test_find_watch_target_walks_to_claude(monkeypatch):
     py = _Proc(300, "python.exe", parent=launcher, ctime=3000.0)
 
     monkeypatch.setattr(psutil, "Process", lambda pid: {100: claude, 200: launcher, 300: py}[pid])
-    pid, ctime = ml._find_watch_target(300)
+    pid, ctime, anchored = ml._find_watch_target(300)
     assert pid == 100
     assert ctime == 1000.0
+    assert anchored is True
 
 
 def test_find_watch_target_handles_no_psutil(monkeypatch):
@@ -171,9 +173,32 @@ def test_find_watch_target_handles_no_psutil(monkeypatch):
         return real_import(name, *a, **k)
 
     monkeypatch.setattr(builtins, "__import__", blocked)
-    pid, ctime = ml._find_watch_target(42)
+    pid, ctime, anchored = ml._find_watch_target(42)
     assert pid == 42
     assert ctime is None
+    assert anchored is False
+
+
+def test_effective_idle_timeout_disabled_when_host_anchored(monkeypatch):
+    """Anchored to a real IDE host → parent watchdog owns the lifecycle;
+    the idle backstop must NOT kill the server (and its file watcher)."""
+    monkeypatch.delenv("CODEBRAIN_MCP_IDLE_TIMEOUT", raising=False)
+    assert ml._effective_idle_timeout(True) == 0
+
+
+def test_effective_idle_timeout_backstop_when_not_anchored(monkeypatch):
+    """No host found (psutil missing / odd process tree) → keep the 30-min
+    backstop so a truly orphaned server cannot hold the DB forever."""
+    monkeypatch.delenv("CODEBRAIN_MCP_IDLE_TIMEOUT", raising=False)
+    assert ml._effective_idle_timeout(False) == ml.IDLE_TIMEOUT_SECONDS
+
+
+def test_effective_idle_timeout_env_override_wins(monkeypatch):
+    """An explicit CODEBRAIN_MCP_IDLE_TIMEOUT always applies, even anchored."""
+    monkeypatch.setenv("CODEBRAIN_MCP_IDLE_TIMEOUT", "120")
+    monkeypatch.setattr(ml, "IDLE_TIMEOUT_SECONDS", 120)
+    assert ml._effective_idle_timeout(True) == 120
+    assert ml._effective_idle_timeout(False) == 120
 
 
 def test_install_watchdogs_is_idempotent(tmp_path, monkeypatch):

codebrain-0.3.5/tests/test_watcher.py

@@ -0,0 +1,244 @@
+"""Tests for the file watcher debounced handler."""
+
+from __future__ import annotations
+
+import threading
+import time
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+class MockEvent:
+    """Minimal stand-in for watchdog FileSystemEvent."""
+
+    def __init__(self, src_path: str, is_directory: bool = False, dest_path: str = ""):
+        self.src_path = src_path
+        self.dest_path = dest_path
+        self.is_directory = is_directory
+
+
+class TestDebouncedHandler:
+    def _make_handler(self, repo_root, store, debounce=0.05):
+        from codebrain.watcher.file_watcher import _DebouncedHandler
+        return _DebouncedHandler(
+            repo_root=repo_root,
+            store=store,
+            debounce=debounce,
+            extensions=frozenset({".py", ".ts"}),
+        )
+
+    def test_on_modified_collects_path(self, tmp_path):
+        store = MagicMock()
+        handler = self._make_handler(tmp_path, store)
+        event = MockEvent(str(tmp_path / "foo.py"))
+        handler.on_modified(event)
+        assert Path(event.src_path) in handler._changed
+
+    def test_ignores_irrelevant_extensions(self, tmp_path):
+        store = MagicMock()
+        handler = self._make_handler(tmp_path, store)
+        event = MockEvent(str(tmp_path / "readme.md"))
+        handler.on_modified(event)
+        assert len(handler._changed) == 0
+
+    def test_ignores_directories(self, tmp_path):
+        store = MagicMock()
+        handler = self._make_handler(tmp_path, store)
+        event = MockEvent(str(tmp_path / "subdir"), is_directory=True)
+        handler.on_modified(event)
+        assert len(handler._changed) == 0
+
+    def test_on_created_collects_path(self, tmp_path):
+        store = MagicMock()
+        handler = self._make_handler(tmp_path, store)
+        event = MockEvent(str(tmp_path / "new.py"))
+        handler.on_created(event)
+        assert Path(event.src_path) in handler._changed
+
+    def test_on_deleted_collects_path(self, tmp_path):
+        store = MagicMock()
+        handler = self._make_handler(tmp_path, store)
+        event = MockEvent(str(tmp_path / "old.py"))
+        handler.on_deleted(event)
+        assert Path(event.src_path) in handler._deleted
+
+    def test_deleted_removes_from_changed(self, tmp_path):
+        store = MagicMock()
+        handler = self._make_handler(tmp_path, store)
+        path = str(tmp_path / "old.py")
+        handler.on_modified(MockEvent(path))
+        assert Path(path) in handler._changed
+        handler.on_deleted(MockEvent(path))
+        assert Path(path) not in handler._changed
+        assert Path(path) in handler._deleted
+
+    def test_on_moved_tracks_both(self, tmp_path):
+        store = MagicMock()
+        handler = self._make_handler(tmp_path, store)
+        event = MockEvent(
+            str(tmp_path / "old.py"),
+            dest_path=str(tmp_path / "new.py"),
+        )
+        handler.on_moved(event)
+        assert Path(event.src_path) in handler._deleted
+        assert Path(event.dest_path) in handler._changed
+
+    @patch("codebrain.watcher.file_watcher.incremental_update")
+    def test_flush_calls_incremental_update(self, mock_update, tmp_path):
+        mock_update.return_value = {
+            "files_updated": 1,
+            "files_removed": 0,
+            "errors": [],
+            "elapsed_seconds": 0.001,
+        }
+        store = MagicMock()
+        handler = self._make_handler(tmp_path, store, debounce=0.01)
+        handler.on_modified(MockEvent(str(tmp_path / "foo.py")))
+        # Wait for debounce to fire
+        time.sleep(0.1)
+        assert mock_update.called
+
+    @patch("codebrain.watcher.file_watcher.incremental_update")
+    def test_debounce_collapses_events(self, mock_update, tmp_path):
+        mock_update.return_value = {
+            "files_updated": 1,
+            "files_removed": 0,
+            "errors": [],
+            "elapsed_seconds": 0.001,
+        }
+        store = MagicMock()
+        # Deterministic version: a huge debounce so no timer ever fires on
+        # its own, then flush manually. Timing-based variants flake on a
+        # loaded machine — Timer.cancel() loses the race against a timer
+        # that already started, producing a legitimate second flush.
+        handler = self._make_handler(tmp_path, store, debounce=300)
+        # Rapid-fire multiple events
+        for i in range(5):
+            handler.on_modified(MockEvent(str(tmp_path / "foo.py")))
+        # All 5 events collapsed into a single pending change
+        assert handler._changed == {Path(str(tmp_path / "foo.py"))}
+        handler._timer.cancel()
+        handler._flush()
+        # Should only flush once
+        assert mock_update.call_count == 1
+        # Sets drained — a follow-up flush with nothing pending is a no-op
+        handler._flush()
+        assert mock_update.call_count == 1
+
+    @patch("codebrain.watcher.file_watcher.incremental_update")
+    def test_flush_clears_sets(self, mock_update, tmp_path):
+        mock_update.return_value = {
+            "files_updated": 1,
+            "files_removed": 0,
+            "errors": [],
+            "elapsed_seconds": 0.001,
+        }
+        store = MagicMock()
+        handler = self._make_handler(tmp_path, store, debounce=0.01)
+        handler.on_modified(MockEvent(str(tmp_path / "foo.py")))
+        handler.on_deleted(MockEvent(str(tmp_path / "bar.py")))
+        time.sleep(0.1)
+        assert len(handler._changed) == 0
+        assert len(handler._deleted) == 0
+
+    @patch("codebrain.watcher.file_watcher.incremental_update")
+    def test_flush_marks_idle_activity(self, mock_update, tmp_path):
+        """A watcher flush must reset the MCP idle clock — otherwise the
+        idle watchdog kills the server while the user is actively editing."""
+        mock_update.return_value = {
+            "files_updated": 1,
+            "files_removed": 0,
+            "errors": [],
+            "elapsed_seconds": 0.001,
+        }
+        import codebrain.mcp_lifecycle as ml
+        before = ml._last_activity
+        time.sleep(0.02)
+        store = MagicMock()
+        handler = self._make_handler(tmp_path, store, debounce=0.01)
+        handler.on_modified(MockEvent(str(tmp_path / "foo.py")))
+        time.sleep(0.1)
+        assert ml._last_activity > before
+
+
+class TestCatchUpSync:
+    """Changes made while no watcher was alive must be picked up at startup."""
+
+    def _make_repo(self, tmp_path):
+        repo = tmp_path / "repo"
+        repo.mkdir()
+        (repo / "alpha.py").write_text("def alpha():\n    return 1\n")
+        (repo / "beta.py").write_text("def beta():\n    return 2\n")
+        from codebrain.indexer import full_index
+        full_index(repo)
+        return repo, repo / ".codebrain" / "graph.db"
+
+    def _function_names(self, store):
+        rows = store.conn.execute(
+            "SELECT name FROM nodes WHERE type = 'function'"
+        ).fetchall()
+        return {row["name"] for row in rows}
+
+    def test_picks_up_offline_modification(self, tmp_path):
+        from codebrain.graph.store import GraphStore
+        from codebrain.watcher.file_watcher import catch_up_sync
+        repo, db = self._make_repo(tmp_path)
+        # Simulate an edit while no watcher process was running
+        (repo / "alpha.py").write_text("def alpha_renamed():\n    return 1\n")
+        with GraphStore(db) as store:
+            result = catch_up_sync(repo, store)
+            assert result["files_updated"] == 1
+            names = self._function_names(store)
+            assert "alpha_renamed" in names
+            assert "alpha" not in names
+
+    def test_picks_up_offline_new_file(self, tmp_path):
+        from codebrain.graph.store import GraphStore
+        from codebrain.watcher.file_watcher import catch_up_sync
+        repo, db = self._make_repo(tmp_path)
+        (repo / "gamma.py").write_text("def gamma():\n    return 3\n")
+        with GraphStore(db) as store:
+            result = catch_up_sync(repo, store)
+            assert result["files_updated"] == 1
+            assert "gamma" in self._function_names(store)
+
+    def test_picks_up_offline_deletion(self, tmp_path):
+        from codebrain.graph.store import GraphStore
+        from codebrain.watcher.file_watcher import catch_up_sync
+        repo, db = self._make_repo(tmp_path)
+        (repo / "beta.py").unlink()
+        with GraphStore(db) as store:
+            result = catch_up_sync(repo, store)
+            assert result["files_removed"] == 1
+            assert "beta" not in self._function_names(store)
+            assert "beta.py" not in store.all_file_paths()
+
+    def test_noop_when_index_current(self, tmp_path):
+        from codebrain.graph.store import GraphStore
+        from codebrain.watcher.file_watcher import catch_up_sync
+        repo, db = self._make_repo(tmp_path)
+        with GraphStore(db) as store:
+            result = catch_up_sync(repo, store)
+            assert result["files_updated"] == 0
+            assert result["files_removed"] == 0
+
+    def test_start_watching_background_runs_catch_up(self, tmp_path):
+        """The MCP startup path must self-heal a stale index automatically."""
+        from codebrain.watcher.file_watcher import start_watching_background
+        repo, db = self._make_repo(tmp_path)
+        # Offline edit: rename a symbol while no watcher exists
+        (repo / "alpha.py").write_text("def alpha_v2():\n    return 1\n")
+        observer, store, _handler = start_watching_background(repo, db)
+        try:
+            deadline = time.time() + 10
+            while time.time() < deadline:
+                if "alpha_v2" in self._function_names(store):
+                    break
+                time.sleep(0.1)
+            assert "alpha_v2" in self._function_names(store)
+        finally:
+            observer.stop()
+            observer.join(timeout=5)
+            store.close()