codebrain 0.3.4__py3-none-any.whl → 0.4.0__py3-none-any.whl

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.4"
+    __version__ = "0.4.0"

codebrain/cli.py

@@ -58,9 +58,17 @@ def _require_index(repo_root: Path) -> Path:
         import gc
         gc.collect()  # Release any lingering connections
         try:
-            db.unlink(missing_ok=True)
-            for wal in db.parent.glob(f"{db.name}-*"):
-                wal.unlink(missing_ok=True)
+            # Prefer rebuilding in place — deleting the file fails on
+            # Windows while any MCP server holds it open. Only fall back
+            # to file replacement when the DB is unreadable.
+            try:
+                from codebrain.graph.store import GraphStore
+                with GraphStore(db) as _store:
+                    _store.clear_all()
+            except Exception:
+                db.unlink(missing_ok=True)
+                for wal in db.parent.glob(f"{db.name}-*"):
+                    wal.unlink(missing_ok=True)
             from codebrain.indexer import full_index
             full_index(repo_root, db)
             click.echo(click.style("Database rebuilt successfully.", fg="green"), err=True)
@@ -1618,33 +1626,37 @@ def reindex(ctx: click.Context, yes: bool, as_json: bool) -> None:
     db = _db_path(repo_root)
 
     if not yes and not as_json:
-        if not click.confirm("This will delete and rebuild the entire index. Continue?"):
+        if not click.confirm("This will rebuild the entire index. Continue?"):
             click.echo("Aborted.")
             return
 
+    # Rebuild IN PLACE (clear tables, re-fill) rather than deleting the DB
+    # file. Deleting fails on Windows whenever any MCP server holds the DB
+    # open — and with session-long server lifetimes that is "always". WAL
+    # mode makes the in-place rebuild safe with readers attached, so reindex
+    # never needs to find, kill, or wait for other processes.
     if db.exists():
+        from codebrain.graph.store import GraphStore
         try:
-            db.unlink()
-        except PermissionError:
-            from codebrain.mcp_lifecycle import find_db_lock_holder, kill_pid
-            holder = find_db_lock_holder(repo_root)
-            if holder is None:
-                click.echo(
-                    "  Database is locked but no recorded MCP holder.\n"
-                    "  Find the holder with `Get-Process python` (Windows) or `lsof` (Unix) and stop it."
-                )
+            with GraphStore(db) as _store:
+                _store.clear_all()
+        except Exception as exc:
+            # Corrupted beyond clearing — replacing the file is the only
+            # option left. This fails if another process holds it open.
+            click.echo(click.style(
+                f"  Index unreadable ({exc}); replacing the database file.", fg="yellow",
+            ))
+            try:
+                db.unlink()
+                for wal in db.parent.glob(f"{db.name}-*"):
+                    wal.unlink(missing_ok=True)
+            except PermissionError:
+                click.echo(click.style(
+                    "  The corrupted database is held open by a running MCP server.\n"
+                    "  Close Claude Code sessions for this project (or run "
+                    "`brain doctor --kill-stale-mcps`) and retry.", fg="red",
+                ))
                 raise
-            should_kill = yes or as_json or click.confirm(
-                f"Database locked by CodeBrain MCP server PID {holder}. Terminate it and continue?"
-            )
-            if not should_kill:
-                click.echo("Aborted.")
-                return
-            status = kill_pid(holder)
-            click.echo(f"  Killed MCP PID {holder}: {status}")
-            import time as _time
-            _time.sleep(1)
-            db.unlink()
 
     files = discover_files(repo_root)
 
@@ -1847,6 +1859,13 @@ def repair(ctx: click.Context) -> None:
             break
         except PermissionError:
             _time.sleep(0.2)
+    else:
+        click.echo(click.style(
+            "Could not replace the corrupted database — a running MCP server "
+            "holds it open.\nClose Claude Code sessions for this project (or "
+            "run `brain doctor --kill-stale-mcps`) and retry.", fg="red",
+        ))
+        sys.exit(1)
     # Also clean up WAL/SHM files
     for suffix in ("-wal", "-shm"):
         wal = db.parent / (db.name + suffix)

codebrain/graph/store.py

@@ -22,11 +22,18 @@ class GraphStore:
         self.db_path.parent.mkdir(parents=True, exist_ok=True)
         _log.debug("Opening database %s", self.db_path)
         self.conn = sqlite3.connect(str(self.db_path), timeout=30, check_same_thread=False)
-        self.conn.row_factory = sqlite3.Row
-        self.conn.execute("PRAGMA journal_mode=WAL")
-        self.conn.execute("PRAGMA synchronous=NORMAL")
-        self.conn.execute("PRAGMA foreign_keys=OFF")
-        migrate_db(self.conn)
+        try:
+            self.conn.row_factory = sqlite3.Row
+            self.conn.execute("PRAGMA journal_mode=WAL")
+            self.conn.execute("PRAGMA synchronous=NORMAL")
+            self.conn.execute("PRAGMA foreign_keys=OFF")
+            migrate_db(self.conn)
+        except Exception:
+            # A corrupted/garbage file makes the pragmas raise AFTER the OS
+            # handle is open. Without this close, the dangling handle keeps
+            # the file locked on Windows and recovery-by-replacement fails.
+            self.conn.close()
+            raise
 
     def close(self) -> None:
         _log.debug("Closing database %s", self.db_path)
@@ -113,6 +120,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/indexer.py

@@ -490,6 +490,43 @@ def full_index(
     }
 
 
+def scan_stale(
+    repo_root: Path,
+    store: GraphStore,
+    settings: "Settings | None" = None,
+) -> tuple[list[Path], list[Path]]:
+    """Cheap staleness scan: which files changed since they were indexed?
+
+    Returns ``(changed_candidates, deleted)``. Uses an mtime-vs-last_indexed
+    prefilter so no file contents are read here — false candidates are fine
+    because :func:`incremental_update` hash-checks before re-parsing. This is
+    the fast freshness layer (milliseconds on a warm FS cache); the exhaustive
+    hash-everything pass lives in the watcher's startup catch-up sync.
+    """
+    rows = store.conn.execute("SELECT path, last_indexed FROM files").fetchall()
+    stored = {row["path"]: row["last_indexed"] for row in rows}
+
+    changed: list[Path] = []
+    seen: set[str] = set()
+    # Files modified within this window before indexing finished may have
+    # raced the indexer — treat them as candidates (hash check disambiguates).
+    slack = 2.0
+    for file_path in discover_files(repo_root, settings):
+        rel = normalize_path(file_path, repo_root)
+        seen.add(rel)
+        last_indexed = stored.get(rel)
+        if last_indexed is None:
+            changed.append(file_path)  # new file
+            continue
+        try:
+            if file_path.stat().st_mtime > last_indexed - slack:
+                changed.append(file_path)
+        except OSError:
+            continue
+    deleted = [repo_root / rel for rel in stored if rel not in seen]
+    return changed, deleted
+
+
 def incremental_update(
     repo_root: Path,
     changed_files: list[Path],
@@ -510,6 +547,12 @@ def incremental_update(
         store.remove_file(rel)
         removed += 1
 
+    # tree-sitter can hang holding the GIL on Windows — isolate those
+    # extensions in a subprocess, same as full_index. A hang here would
+    # otherwise freeze the watcher/catch-up thread while it holds the DB
+    # lock, silently stopping auto-indexing for the rest of the session.
+    _NEEDS_ISOLATION = frozenset({".ts", ".tsx", ".js", ".jsx"})
+
     for file_path in changed_files:
         rel = normalize_path(file_path, repo_root)
         try:
@@ -519,9 +562,16 @@ def incremental_update(
             if current_hash == stored_hash:
                 continue
 
-            pf = _parse_file(file_path, repo_root)
-            store.upsert_file(pf)
-            updated += 1
+            if sys.platform == "win32" and file_path.suffix in _NEEDS_ISOLATION:
+                pf, err = _parse_with_timeout(file_path, repo_root, timeout=30)
+                if err:
+                    errors.append(err)
+                    continue
+            else:
+                pf = _parse_file(file_path, repo_root)
+            if pf is not None:
+                store.upsert_file(pf)
+                updated += 1
         except Exception as exc:
             errors.append(f"{rel}: {exc}")
 

codebrain/mcp_lifecycle.py

@@ -79,39 +79,43 @@ def _read_pid_file(pid_file: Path) -> int | None:
         return None
 
 
-def _predecessor_has_live_host(pid: int) -> bool:
-    """True if ``pid``'s ancestor chain contains a live host (claude/cursor/...).
-
-    Such a predecessor belongs to a *concurrent* sibling Claude session and
-    must not be terminated — its disappearance would silently break that
-    session's MCP. Without psutil we cannot tell, so be safe and assume yes.
+def _predecessor_host_pid(pid: int) -> int | None:
+    """Return the PID of the live IDE host (claude/cursor/...) in ``pid``'s
+    ancestor chain, or None if there is none.
+
+    A predecessor with a live host belongs to *some* Claude session — but
+    whether it must be spared depends on WHICH session: a different host PID
+    means a concurrent sibling window (killing it would silently break that
+    session's MCP); the SAME host PID as ours means it is our own session's
+    orphaned predecessor left behind by a transport disconnect/reconnect,
+    and it must die or two servers fight over the SQLite DB.
     """
     try:
         import psutil
     except ImportError:
-        return True
+        return None
     try:
         proc = psutil.Process(pid)
     except (psutil.NoSuchProcess, psutil.AccessDenied):
-        return False
+        return None
     for _ in range(ANCESTOR_WALK_DEPTH):
         try:
             parent = proc.parent()
         except (psutil.NoSuchProcess, psutil.AccessDenied):
-            return False
+            return None
         if parent is None:
-            return False
+            return None
         try:
             name = (parent.name() or "").lower()
         except (psutil.NoSuchProcess, psutil.AccessDenied):
-            return False
+            return None
         if any(hint in name for hint in HOST_PROCESS_NAME_HINTS):
-            return True
+            return parent.pid
         proc = parent
-    return False
+    return None
 
 
-def _kill_stale_predecessor(pid_file: Path) -> None:
+def _kill_stale_predecessor(pid_file: Path, own_host_pid: int | None = None) -> None:
     if not pid_file.exists():
         return
     old_pid = _read_pid_file(pid_file)
@@ -128,12 +132,27 @@ def _kill_stale_predecessor(pid_file: Path) -> None:
         # PID was reused by an unrelated process. Don't touch.
         _log.debug("PID %d reused by unrelated process; leaving alone", old_pid)
         return
-    if _predecessor_has_live_host(old_pid):
-        # Concurrent sibling Claude session is still using this MCP — leave it.
-        # Without this, two Claude windows on the same repo race each other and
-        # whichever started last kills the other's MCP.
-        _log.debug("PID %d has a live IDE host; sibling MCP, leaving alone", old_pid)
+    pred_host = _predecessor_host_pid(old_pid)
+    if pred_host is not None and pred_host != own_host_pid:
+        # Live IDE host that is NOT ours → concurrent sibling Claude session
+        # is still using this MCP — leave it. Without this, two Claude
+        # windows on the same repo race each other and whichever started
+        # last kills the other's MCP.
+        _log.debug(
+            "PID %d has live IDE host %d (ours: %s); sibling MCP, leaving alone",
+            old_pid, pred_host, own_host_pid,
+        )
         return
+    if pred_host is not None:
+        # Same host as ours → our own session reconnected and left the old
+        # server behind with a dead stdio transport. It will never exit on
+        # its own (parent still alive, idle timer disabled when anchored)
+        # and holds the SQLite DB — kill it.
+        _log.warning(
+            "Predecessor PID %d shares our IDE host %d — duplicate from a "
+            "transport reconnect, terminating it",
+            old_pid, pred_host,
+        )
     try:
         proc = psutil.Process(old_pid)
         _log.warning("Killing stale CodeBrain MCP predecessor PID %d", old_pid)
@@ -167,7 +186,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 +194,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 +206,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 +225,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 +235,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 +264,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:
@@ -277,21 +319,30 @@ def install_watchdogs(repo_root: Path | None = None) -> None:
     start = time.time()
     mark_activity()
 
+    # Resolve our own IDE host FIRST — the predecessor check needs it to
+    # distinguish "our own session's orphan after a transport reconnect"
+    # (kill) from "a concurrent sibling window's server" (spare).
+    immediate_ppid = os.getppid()
+    initial_ppid, initial_create_time, host_anchored = _find_watch_target(immediate_ppid)
+    idle_timeout = _effective_idle_timeout(host_anchored)
+
     if repo_root is not None:
         from codebrain.config import CODEBRAIN_DIR
         pid_file = repo_root / CODEBRAIN_DIR / PID_FILE_NAME
-        _kill_stale_predecessor(pid_file)
+        _kill_stale_predecessor(
+            pid_file,
+            own_host_pid=initial_ppid if host_anchored else None,
+        )
         _write_pid_file(pid_file)
         atexit.register(_remove_pid_file, pid_file)
 
-    immediate_ppid = os.getppid()
-    initial_ppid, initial_create_time = _find_watch_target(immediate_ppid)
-
     _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 +354,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/mcp_server.py

@@ -110,6 +110,125 @@ def _make_store():
     return GraphStore(_find_db())
 
 
+# ---------------------------------------------------------------------------
+# Freshness-on-read
+#
+# Correctness must not depend on which background processes happen to be
+# alive. The watcher (instant) and the startup catch-up sync (thorough) are
+# optimizations; THIS is the guarantee: before serving a tool call, cheaply
+# verify the index matches the working tree and sync the difference. Even if
+# every watcher thread is dead, the answer the agent gets reflects current
+# code.
+# ---------------------------------------------------------------------------
+
+import threading as _threading
+import time as _time
+
+FRESHNESS_INTERVAL_SECONDS = float(os.environ.get("CODEBRAIN_FRESHNESS_INTERVAL", "5"))
+# Above this many stale files, sync in the background instead of inline so a
+# huge drift (e.g. branch switch on a big repo) can't eat the tool deadline.
+FRESHNESS_INLINE_LIMIT = 200
+
+_freshness_lock = _threading.Lock()
+_last_freshness_check: dict[str, float] = {}
+
+# Tools that must NOT trigger a freshness sync:
+# - validators compare new/written content against the PRE-change graph;
+#   syncing first would erase the baseline and the structural gate would
+#   silently pass everything
+# - reindex_codebase rebuilds anyway
+# - project/memory tools don't read graph data
+_FRESHNESS_EXEMPT_TOOLS = frozenset({
+    "validate_change",
+    "validate_changes",
+    "validate_after_write",
+    "propose_change",
+    "diff_impact",
+    "get_validation_status",
+    "reindex_codebase",
+    "set_project",
+    "get_project",
+    "save_memory",
+    "recall_memories",
+    "list_memories",
+    "update_memory",
+    "delete_memory",
+})
+
+
+def _ensure_fresh() -> None:
+    """Best-effort staleness sync before serving a tool call.
+
+    Throttled per database; never blocks on a concurrent sync (a slightly
+    stale answer beats a deadlocked one); never raises.
+    """
+    if FRESHNESS_INTERVAL_SECONDS <= 0:
+        return
+    try:
+        db_path = _find_db()
+    except FileNotFoundError:
+        return
+    key = str(db_path)
+    now = _time.monotonic()
+    if now - _last_freshness_check.get(key, 0.0) < FRESHNESS_INTERVAL_SECONDS:
+        return
+    if not _freshness_lock.acquire(blocking=False):
+        return  # another sync in flight — serve what we have
+    try:
+        _last_freshness_check[key] = now
+        from codebrain.graph.store import GraphStore
+        from codebrain.indexer import incremental_update, scan_stale
+
+        repo_root = db_path.parent.parent
+        with GraphStore(db_path) as store:
+            changed, deleted = scan_stale(repo_root, store)
+            if not changed and not deleted:
+                return
+            if len(changed) + len(deleted) > FRESHNESS_INLINE_LIMIT:
+                _log.info(
+                    "Freshness: %d files drifted — syncing in background",
+                    len(changed) + len(deleted),
+                )
+                _threading.Thread(
+                    target=_background_freshness_sync,
+                    args=(repo_root, db_path, changed, deleted),
+                    name="cb-freshness-sync",
+                    daemon=True,
+                ).start()
+                return
+            result = incremental_update(repo_root, changed, deleted, store)
+            if result["files_updated"] or result["files_removed"]:
+                _log.info(
+                    "Freshness: updated %d, removed %d (%.3fs)",
+                    result["files_updated"],
+                    result["files_removed"],
+                    result["elapsed_seconds"],
+                )
+    except Exception as exc:
+        _log.debug("Freshness sync skipped: %s", exc)
+    finally:
+        _freshness_lock.release()
+
+
+def _background_freshness_sync(
+    repo_root: Path, db_path: Path, changed: list, deleted: list,
+) -> None:
+    try:
+        from codebrain.graph.store import GraphStore
+        from codebrain.indexer import incremental_update
+
+        with GraphStore(db_path) as store:
+            result = incremental_update(repo_root, changed, deleted, store)
+        _log.info(
+            "Background freshness sync: updated %d, removed %d (%.3fs)",
+            result["files_updated"],
+            result["files_removed"],
+            result["elapsed_seconds"],
+        )
+    except Exception as exc:
+        _log.warning("Background freshness sync failed: %s", exc)
+
+
 def _safe_tool(fn):  # noqa: ANN001, ANN201
     """Wrap an MCP tool so it cooperates with MCP cancellation.
 
@@ -214,6 +333,10 @@ def _run_sync_protected(fn, args, kwargs):  # noqa: ANN001, ANN202
     saved_stdout = sys.stdout
     sys.stdout = sys.stderr
     try:
+        # Freshness gate: sync index drift before answering. Skip for tools
+        # that rebuild or don't read the graph state being synced.
+        if fn.__name__ not in _FRESHNESS_EXEMPT_TOOLS:
+            _ensure_fresh()
         return fn(*args, **kwargs)
     finally:
         sys.stdout = saved_stdout

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.4.dist-info → codebrain-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codebrain
-Version: 0.3.4
+Version: 0.4.0
 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.4.dist-info → codebrain-0.4.0.dist-info}/RECORD

@@ -1,11 +1,11 @@
-codebrain/__init__.py,sha256=-sDaW43PeyYkocMq06I_oQkqnC3tH_w3dnSmTgmUMuk,392
+codebrain/__init__.py,sha256=HrQ5FQd5GTjIxch8KWjHo5Q2CjcKK-ffXNRmY8Cr8ug,392
 codebrain/__main__.py,sha256=dgd9lRZovV1k1tScEW_wvPPjPEACXc-EcLtJ7AN3M48,115
 codebrain/agent_bridge.py,sha256=JDny3232R6rfFsQTWOoYygGgykx6rb8ektLRENPUcDQ,6262
 codebrain/analyzer.py,sha256=RxyajZp0E8XuB_1SkK1UEXD00gOo3e2vtBzS-US6ms8,40701
 codebrain/api.py,sha256=LmeFK3KyUKR1xz4tAoPteaRA06c09KA965Hk33VhV6I,31653
 codebrain/api_models.py,sha256=mE5sIsf8WLEWjGm2w6-baeyVoJH_65FOglHwFe3aJhs,1989
 codebrain/architecture.py,sha256=RCN_LUNTjd0fXYFIYDacwH17qEeFCxNCyF6irbs5yfE,29485
-codebrain/cli.py,sha256=UmiCV5O05-I9FdEiuXoJ96WJdBntxMud7al8sOMteOM,169015
+codebrain/cli.py,sha256=RbXLvRDMXihedsPH-CxbQjWTvFyJbsyFCdtRhMbVk2s,170135
 codebrain/comprehension.py,sha256=eAVf1abecxVo72_2p8aEgRmSeXR7VNMyJnt_DTst47E,83023
 codebrain/config.py,sha256=UvStpfDNvulMHkN7xnGjEF3EKvdf9tF3Cv4A01FdEQw,1745
 codebrain/context.py,sha256=BFZ_WWRf242cJli-TXoz5JFqcvsKkwbmuUMBX8WvM9o,10980
@@ -18,13 +18,13 @@ codebrain/export.py,sha256=A4zdzJ2MVmo-sxJQjwoZlMRkm-QXCxE14lYDm9RrQEY,11576
 codebrain/frontend.py,sha256=4kFIcWoPKS_pLaWAirmkJmYSYTlicCsi_GZgLLjunng,17675
 codebrain/hook_runner.py,sha256=1shd-lw8Rx8zNOuJfgcbUOzhsNUVIwhmuzDpTQsdnHo,5458
 codebrain/hooks.py,sha256=tT2Dx_T0iZLEQarL7QYvvVObYfelMUKVNXNz74MU-tM,3179
-codebrain/indexer.py,sha256=3xIe8m_zPTKJlq7dAlvyTWP3J2UsF4ondy8ndgm6dSQ,18900
+codebrain/indexer.py,sha256=NaMj-1ycT4cINJfgykjZC9cAs7cxVLfaojY0AKxaEZw,21083
 codebrain/kt.py,sha256=iXeHArPbSrrr2ObH4nuyXPobdBXSOR3b7JbIqXB0kj4,17199
 codebrain/kt_video.py,sha256=quaUyPUJh8xXsj52aBCPp_L8fekNC4vHmNYrUTfCqcE,29211
 codebrain/llm.py,sha256=0D5c5BJMVkLz2OoybfMxlUdJEbz16cZoNgVmm-LzFH0,25606
 codebrain/logging.py,sha256=ORR5L8REVlh4aJz9vqErmi76aqjLN2xVKoA2gSv_jas,1110
-codebrain/mcp_lifecycle.py,sha256=FzZBKk_MLUFC97TgT_M_EG0oNZgUAPZXzukm1U3LUKc,14172
-codebrain/mcp_server.py,sha256=Lb5ob3NI-S0Ln7Yp8G8HxWsKvAuzVzl123N08ZkxPyw,110648
+codebrain/mcp_lifecycle.py,sha256=xo-T1-RNCzFRKhWcKUkEF6ZahPCISp6swTfwRrKazGg,16598
+codebrain/mcp_server.py,sha256=tdSmB4w6KYcXi1lHxcxle-adR12Nm-v7mRSoxBDKiD4,115349
 codebrain/migration.py,sha256=ZMcug6OsvvK-DVdfmqhWCUx-oVj0KQD0EGlBVx6Jxvk,29489
 codebrain/modernize.py,sha256=4usRjIFONEThpYhemLIjoYXb9ohEbO7j2wzVO15Dz5A,38525
 codebrain/onboard.py,sha256=m63A0A8pJdZUiGFgAlRD1ySe7Bk_Eo_fiTPzLfkL1ig,15270
@@ -48,7 +48,7 @@ codebrain/actions/test_gen.py,sha256=PAnHfYuLp-AIF4YrQYQaBH5ADWhCqUVEI7bFDquxPjs
 codebrain/graph/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 codebrain/graph/query.py,sha256=FdkWTIKteCdAGnal01LJDuoSXzSpNp3AT9e0AH-m1eg,44131
 codebrain/graph/schema.py,sha256=5PItrNUMQt37kTsL3SUVLPB7rP2JtQXx-Y4uxX0A0H0,6521
-codebrain/graph/store.py,sha256=eFgXCor-MV-H897s8tcnNOeOiRieOoBmh70sj1Xi3NM,15717
+codebrain/graph/store.py,sha256=x8xkOrSGWQexIjEKP09CwCo8v1E1W4w34QQAUC8gvyE,16272
 codebrain/memory/__init__.py,sha256=PuFR35m1GPIbRAuUxKu4JYBDlPXJWMPbyrWiggFT2sU,158
 codebrain/memory/store.py,sha256=W31fe4aNTkdi-Woe8bZ8SZ9aUHpWrfBkb-9dQs0geyI,9394
 codebrain/parser/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -73,10 +73,10 @@ codebrain/parser/typescript_parser.py,sha256=fi0DoXLCi_L0aQzpadumDpFHaSyekfp3wmV
 codebrain/parser/typescript_treesitter.py,sha256=7RTdcA-HTgrlRhEMwSGa-63saNcjqtPiKZYrEOBmlD4,26391
 codebrain/parser/vue_parser.py,sha256=ZWtjUOyItn_SNfvD6T8j7alV4aIfcHA94WDCS5P59Ps,13054
 codebrain/watcher/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-codebrain/watcher/file_watcher.py,sha256=EUXQ5L8gutOCvGgtNZ9wMt6RL74wA6snH7vnDnxm13A,6562
-codebrain-0.3.4.dist-info/licenses/LICENSE,sha256=Dxb0L3H90lGFFik90WQXfMkM_8utGA1BDqizqdCT3UE,1079
-codebrain-0.3.4.dist-info/METADATA,sha256=zPvG0VbV4DwOg8h9au3Zsnpzr8upsFVbzYuRcYpVSRI,10129
-codebrain-0.3.4.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-codebrain-0.3.4.dist-info/entry_points.txt,sha256=FHKSyI7le7GK78HxAKQK54-yzt-yHNxX0df3VpGC5wg,44
-codebrain-0.3.4.dist-info/top_level.txt,sha256=mUxCZc80EyNOMzd2vAm22uIhnOb1Aw7ZOAUT_u-ksx4,10
-codebrain-0.3.4.dist-info/RECORD,,
+codebrain/watcher/file_watcher.py,sha256=6x-fWIP5YBuwq5BCX6HOV-Kc8EVgE4JUoeLxYJtxDf0,9454
+codebrain-0.4.0.dist-info/licenses/LICENSE,sha256=Dxb0L3H90lGFFik90WQXfMkM_8utGA1BDqizqdCT3UE,1079
+codebrain-0.4.0.dist-info/METADATA,sha256=W-Gb7JPxHu6eSD_bDmm42i9NU7TLxxls8Ylp5mTEbsw,10129
+codebrain-0.4.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+codebrain-0.4.0.dist-info/entry_points.txt,sha256=FHKSyI7le7GK78HxAKQK54-yzt-yHNxX0df3VpGC5wg,44
+codebrain-0.4.0.dist-info/top_level.txt,sha256=mUxCZc80EyNOMzd2vAm22uIhnOb1Aw7ZOAUT_u-ksx4,10
+codebrain-0.4.0.dist-info/RECORD,,