feat: Add NOT_INITIALIZED status for lazy-loaded databases

Add graceful fallback for lazy-loaded databases that don't exist yet.

Changes:
- Add DatabaseHealthStatus.NOT_INITIALIZED status for optional databases
- Identify search_config.db and file_content_limits.db as lazy-loaded
- Update health service to not treat missing lazy-loaded DBs as errors
- Add UI styling and display for NOT_INITIALIZED state
- Add comprehensive tests for lazy-loaded database handling

Database files using singleton pattern (get_instance()) are only created
when their features are first accessed. Health checks now properly handle
these optional databases with NOT_INITIALIZED status instead of ERROR.

Author: Josh Bendson

src/code_indexer/server/services/database_health_service.py

@@ -28,6 +28,9 @@ class DatabaseHealthStatus(str, Enum):
     HEALTHY = "healthy"  # Green - All 5 checks pass
     WARNING = "warning"  # Yellow - Some checks pass, some fail
     ERROR = "error"  # Red - Critical checks fail
+    NOT_INITIALIZED = (
+        "not_initialized"  # Blue/Gray - Lazy-loaded database not yet created
+    )
 
 
 @dataclass
@@ -54,13 +57,18 @@ def get_tooltip(self) -> str:
 
         Always shows display name and path.
         Unhealthy databases also show the failed condition.
+        NOT_INITIALIZED databases show they're optional and not yet created.
         """
         # Always include path in tooltip
         base_tooltip = f"{self.display_name}\n{self.db_path}"
 
         if self.status == DatabaseHealthStatus.HEALTHY:
             return base_tooltip
 
+        # NOT_INITIALIZED databases get special message
+        if self.status == DatabaseHealthStatus.NOT_INITIALIZED:
+            return f"{base_tooltip}\nNot initialized (optional)"
+
         # Find first failed check to include in tooltip
         for check_name, result in self.checks.items():
             if not result.passed:
@@ -83,6 +91,10 @@ def get_tooltip(self) -> str:
     "payload_cache.db": "Payload Cache",
 }
 
+# Lazy-loaded databases (singleton pattern with get_instance())
+# These databases are only created when their features are first accessed
+LAZY_LOADED_DATABASES = {"search_config.db", "file_content_limits.db"}
+
 
 class DatabaseHealthService:
     """
@@ -203,6 +215,12 @@ def _check_connect(db_path: str) -> CheckResult:
         try:
             # Check if file exists first
             if not Path(db_path).exists():
+                # Check if this is a lazy-loaded database
+                file_name = Path(db_path).name
+                if file_name in LAZY_LOADED_DATABASES:
+                    return CheckResult(
+                        passed=False, error_message="Not initialized (optional)"
+                    )
                 return CheckResult(
                     passed=False, error_message="Connection failed: file not found"
                 )
@@ -314,7 +332,13 @@ def _determine_status(checks: Dict[str, CheckResult]) -> DatabaseHealthStatus:
         - GREEN (HEALTHY): All 5 checks pass
         - YELLOW (WARNING): Some checks pass, some fail (degraded but operational)
         - RED (ERROR): Critical checks fail (connect/read)
+        - BLUE/GRAY (NOT_INITIALIZED): Lazy-loaded database not yet created
         """
+        # Check for lazy-loaded database not yet initialized
+        if "connect" in checks and not checks["connect"].passed:
+            if checks["connect"].error_message == "Not initialized (optional)":
+                return DatabaseHealthStatus.NOT_INITIALIZED
+
         # Critical checks - if these fail, status is ERROR
         critical_checks = ["connect", "read"]
         for check_name in critical_checks:

src/code_indexer/server/services/health_service.py

@@ -80,7 +80,9 @@ def __init__(self):
             # CPU history for sustained threshold detection (Story #727 AC4)
             # List of (timestamp, cpu_percent) tuples for rolling 60s window
             self._cpu_history: List[Tuple[float, float]] = []
-            self._cpu_history_lock = threading.Lock()  # Thread safety for concurrent requests
+            self._cpu_history_lock = (
+                threading.Lock()
+            )  # Thread safety for concurrent requests
 
         except Exception as e:
             logger.error(
@@ -379,6 +381,9 @@ def _collect_database_failures(
                             f"{db_result.display_name} DB: {check.error_message or check_name}"
                         )
                         break
+            # NOT_INITIALIZED and HEALTHY statuses don't affect overall health
+            # NOT_INITIALIZED databases are lazy-loaded and optional (not yet created)
+            # HEALTHY databases are fully operational
 
         return has_warning, has_error, reasons
 
@@ -491,15 +496,13 @@ def _check_cpu_sustained(self, current_cpu: float) -> Tuple[bool, bool]:
         readings_60s = [c for t, c in history_snapshot]
 
         # Degraded: CPU >95% sustained for 30+ seconds
-        is_degraded = (
-            len(readings_30s) >= MIN_CPU_READINGS_FOR_DEGRADED
-            and all(c > CPU_SUSTAINED_THRESHOLD for c in readings_30s)
+        is_degraded = len(readings_30s) >= MIN_CPU_READINGS_FOR_DEGRADED and all(
+            c > CPU_SUSTAINED_THRESHOLD for c in readings_30s
         )
 
         # Unhealthy: CPU >95% sustained for 60+ seconds
-        is_unhealthy = (
-            len(readings_60s) >= MIN_CPU_READINGS_FOR_UNHEALTHY
-            and all(c > CPU_SUSTAINED_THRESHOLD for c in readings_60s)
+        is_unhealthy = len(readings_60s) >= MIN_CPU_READINGS_FOR_UNHEALTHY and all(
+            c > CPU_SUSTAINED_THRESHOLD for c in readings_60s
         )
 
         return is_degraded, is_unhealthy
@@ -532,7 +535,9 @@ def _calculate_overall_status(
         failure_reasons.extend(db_reasons)
 
         # AC2: Volume health
-        vol_warn, vol_err, vol_reasons = self._collect_volume_failures(system_info.volumes)
+        vol_warn, vol_err, vol_reasons = self._collect_volume_failures(
+            system_info.volumes
+        )
         has_warning = has_warning or vol_warn
         has_error = has_error or vol_err
         failure_reasons.extend(vol_reasons)
@@ -568,7 +573,9 @@ def _calculate_overall_status(
         # AC5: Limit to MAX_FAILURE_REASONS with "+N more" indicator
         if len(failure_reasons) > MAX_FAILURE_REASONS:
             extra_count = len(failure_reasons) - MAX_FAILURE_REASONS
-            failure_reasons = failure_reasons[:MAX_FAILURE_REASONS] + [f"+{extra_count} more"]
+            failure_reasons = failure_reasons[:MAX_FAILURE_REASONS] + [
+                f"+{extra_count} more"
+            ]
 
         return status, failure_reasons
 

src/code_indexer/server/web/static/admin.css

@@ -837,6 +837,10 @@ button.danger, .button.danger {
     fill: #ef4444;
 }
 
+.hexagon.hex-not-initialized {
+    fill: #94a3b8;
+}
+
 /* AC2/AC3: Hover effect for tooltips (title attribute provides native tooltip) */
 .honeycomb-svg polygon.hexagon:hover {
     stroke-width: 2;
@@ -887,6 +891,10 @@ button.danger, .button.danger {
     background-color: #ef4444;
 }
 
+.legend-dot.not-initialized {
+    background-color: #94a3b8;
+}
+
 /* ==========================================================================
    Story #712 AC5: Disk Metrics Complete Display
    ========================================================================== */

src/code_indexer/server/web/templates/partials/dashboard_health.html

@@ -39,7 +39,7 @@ <h3>Database Health</h3>
                 {% set col = i % 4 %}
                 {% set x = 35 + col * 55 %}
                 {% set y = 40 + row * 65 %}
-                {% set status_class = 'healthy' if db.status.value == 'healthy' else ('warning' if db.status.value == 'warning' else 'error') %}
+                {% set status_class = 'healthy' if db.status.value == 'healthy' else ('warning' if db.status.value == 'warning' else ('not-initialized' if db.status.value == 'not_initialized' else 'error')) %}
                 <g class="hexagon-group" transform="translate({{ x }}, {{ y }})">
                     <polygon class="hexagon hex-{{ status_class }}"
                              points="25,0 50,15 50,45 25,60 0,45 0,15">
@@ -55,6 +55,7 @@ <h3>Database Health</h3>
                 <span class="legend-item"><span class="legend-dot healthy"></span>Healthy</span>
                 <span class="legend-item"><span class="legend-dot warning"></span>Warning</span>
                 <span class="legend-item"><span class="legend-dot error"></span>Error</span>
+                <span class="legend-item"><span class="legend-dot not-initialized"></span>Not Initialized</span>
             </div>
             {% else %}
             <div class="status-content">

tests/server/services/test_database_health_service.py

@@ -37,7 +37,7 @@ def temp_server_dir(self) -> Generator[Path, None, None]:
                 "logs.db": "CREATE TABLE IF NOT EXISTS logs (id INTEGER PRIMARY KEY)",
                 "search_config.db": "CREATE TABLE IF NOT EXISTS config (id INTEGER PRIMARY KEY)",
                 "file_content_limits.db": "CREATE TABLE IF NOT EXISTS limits (id INTEGER PRIMARY KEY)",
-                "scip_audit.db": "CREATE TABLE IF NOT EXISTS audit (id INTEGER PRIMARY KEY)",
+                "groups.db": "CREATE TABLE IF NOT EXISTS groups (id INTEGER PRIMARY KEY)",
                 "payload_cache.db": "CREATE TABLE IF NOT EXISTS cache (id INTEGER PRIMARY KEY)",
             }
 
@@ -80,7 +80,7 @@ def test_health_service_checks_all_8_databases(self, temp_server_dir: Path):
             "logs.db",
             "search_config.db",
             "file_content_limits.db",
-            "scip_audit.db",
+            "groups.db",
             "payload_cache.db",
         }
         actual_files = {result.file_name for result in health_results}
@@ -110,7 +110,7 @@ def test_health_service_provides_display_names(self, temp_server_dir: Path):
             "logs.db": "Logs",
             "search_config.db": "Search Config",
             "file_content_limits.db": "File Limits",
-            "scip_audit.db": "SCIP Audit",
+            "groups.db": "Groups",
             "payload_cache.db": "Payload Cache",
         }
 
@@ -352,7 +352,7 @@ def healthy_db_path(self) -> Generator[Path, None, None]:
             yield db_path
 
     def test_healthy_database_tooltip_shows_only_name(self, healthy_db_path: Path):
-        """AC2: Healthy database tooltip shows only database name."""
+        """AC2: Healthy database tooltip shows database name and path."""
         from code_indexer.server.services.database_health_service import (
             DatabaseHealthService,
             DatabaseHealthStatus,
@@ -364,10 +364,15 @@ def test_healthy_database_tooltip_shows_only_name(self, healthy_db_path: Path):
 
         assert result.status == DatabaseHealthStatus.HEALTHY
         tooltip = result.get_tooltip()
-        assert tooltip == "Main Server"
+        # Tooltip should contain display name and path (no error info for healthy DB)
+        assert "Main Server" in tooltip
+        assert str(healthy_db_path) in tooltip
+        # Should not contain error information for healthy database
+        assert "Connect:" not in tooltip
+        assert "failed" not in tooltip
 
     def test_unhealthy_database_tooltip_shows_failure(self, healthy_db_path: Path):
-        """AC3: Unhealthy database tooltip shows name AND failed condition."""
+        """AC3: Unhealthy database tooltip shows name, path, AND failed condition."""
         from code_indexer.server.services.database_health_service import (
             DatabaseHealthService,
             DatabaseHealthStatus,
@@ -380,8 +385,11 @@ def test_unhealthy_database_tooltip_shows_failure(self, healthy_db_path: Path):
 
         assert result.status == DatabaseHealthStatus.ERROR
         tooltip = result.get_tooltip()
+        # Tooltip should contain display name, path, and error info
         assert "OAuth" in tooltip
-        assert " - " in tooltip
+        assert str(healthy_db_path) in tooltip
+        # Should contain error information (check name + error message)
+        assert "Connect:" in tooltip or "failed" in tooltip
 
 
 # =============================================================================
@@ -455,3 +463,130 @@ def test_get_stats_partial_passes_user_role_to_repo_counts(self):
         assert (
             "_get_repo_counts" in source and "user_role" in source
         ), "get_stats_partial must pass user_role to _get_repo_counts"
+
+
+# =============================================================================
+# Lazy-Loaded Database Tests
+# =============================================================================
+
+
+class TestLazyLoadedDatabases:
+    """Tests for graceful handling of lazy-loaded databases."""
+
+    def test_lazy_loaded_database_not_initialized_status(self):
+        """
+        Lazy-loaded database that doesn't exist yet gets NOT_INITIALIZED status.
+
+        Given a lazy-loaded database file (search_config.db or file_content_limits.db)
+        When the database file doesn't exist yet
+        Then the health check returns NOT_INITIALIZED status instead of ERROR
+        """
+        from code_indexer.server.services.database_health_service import (
+            DatabaseHealthService,
+            DatabaseHealthStatus,
+        )
+
+        with tempfile.TemporaryDirectory(prefix="cidx_lazy_test_") as tmp:
+            # Create non-existent path for lazy-loaded database
+            db_path = Path(tmp) / "search_config.db"
+
+            result = DatabaseHealthService.check_database_health(
+                str(db_path), display_name="Search Config"
+            )
+
+            assert result.status == DatabaseHealthStatus.NOT_INITIALIZED
+            assert result.checks["connect"].passed is False
+            assert (
+                result.checks["connect"].error_message == "Not initialized (optional)"
+            )
+
+    def test_lazy_loaded_database_initialized_is_healthy(self):
+        """
+        Lazy-loaded database that exists and is healthy gets HEALTHY status.
+
+        Given a lazy-loaded database file (search_config.db)
+        When the database file exists and all checks pass
+        Then the health check returns HEALTHY status
+        """
+        from code_indexer.server.services.database_health_service import (
+            DatabaseHealthService,
+            DatabaseHealthStatus,
+        )
+
+        with tempfile.TemporaryDirectory(prefix="cidx_lazy_test_") as tmp:
+            # Create lazy-loaded database
+            db_path = Path(tmp) / "search_config.db"
+            with sqlite3.connect(str(db_path)) as conn:
+                conn.execute("CREATE TABLE config (id INTEGER PRIMARY KEY)")
+                conn.commit()
+
+            result = DatabaseHealthService.check_database_health(
+                str(db_path), display_name="Search Config"
+            )
+
+            assert result.status == DatabaseHealthStatus.HEALTHY
+            assert result.checks["connect"].passed is True
+
+    def test_non_lazy_database_missing_is_error(self):
+        """
+        Non-lazy-loaded database that doesn't exist gets ERROR status.
+
+        Given a non-lazy-loaded database (e.g., oauth.db)
+        When the database file doesn't exist
+        Then the health check returns ERROR status (not NOT_INITIALIZED)
+        """
+        from code_indexer.server.services.database_health_service import (
+            DatabaseHealthService,
+            DatabaseHealthStatus,
+        )
+
+        with tempfile.TemporaryDirectory(prefix="cidx_lazy_test_") as tmp:
+            # Create non-existent path for non-lazy database
+            db_path = Path(tmp) / "oauth.db"
+
+            result = DatabaseHealthService.check_database_health(
+                str(db_path), display_name="OAuth"
+            )
+
+            assert result.status == DatabaseHealthStatus.ERROR
+            assert result.checks["connect"].passed is False
+            assert "file not found" in result.checks["connect"].error_message
+
+    def test_lazy_loaded_database_tooltip(self):
+        """
+        Lazy-loaded database tooltip shows 'Not initialized (optional)'.
+
+        Given a lazy-loaded database that doesn't exist yet
+        When get_tooltip() is called
+        Then it shows the display name, path, and 'Not initialized (optional)'
+        """
+        from code_indexer.server.services.database_health_service import (
+            DatabaseHealthService,
+        )
+
+        with tempfile.TemporaryDirectory(prefix="cidx_lazy_test_") as tmp:
+            db_path = Path(tmp) / "file_content_limits.db"
+
+            result = DatabaseHealthService.check_database_health(
+                str(db_path), display_name="File Limits"
+            )
+
+            tooltip = result.get_tooltip()
+            assert "File Limits" in tooltip
+            assert str(db_path) in tooltip
+            assert "Not initialized (optional)" in tooltip
+
+    def test_both_lazy_databases_defined(self):
+        """
+        Verify both lazy-loaded databases are defined in LAZY_LOADED_DATABASES.
+
+        This test documents which databases are lazy-loaded and ensures
+        they're properly configured in the constant.
+        """
+        from code_indexer.server.services.database_health_service import (
+            LAZY_LOADED_DATABASES,
+        )
+
+        assert "search_config.db" in LAZY_LOADED_DATABASES
+        assert "file_content_limits.db" in LAZY_LOADED_DATABASES
+        assert len(LAZY_LOADED_DATABASES) == 2