feat(scala): Add stale lock detection for Metals H2 database (#1012)

* feat(scala): Add stale lock detection for Metals H2 database

Add detection and automatic cleanup of stale Metals H2 database locks
to improve multi-instance support. When a Metals process crashes without
proper cleanup, it can leave a lock file that prevents proper AUTO_SERVER
coordination with new instances.

Changes:
- Add metals_db_utils.py with detection logic for stale locks
- Add StaleLockMode enum (auto-clean/warn/fail) for configurable behavior
- Add MetalsStaleLockError exception for fail mode
- Integrate stale lock checking into ScalaLanguageServer init
- Add configuration options: on_stale_lock, log_multi_instance_notice
- Add comprehensive unit tests for detection logic

This enhancement allows Serena's Metals to coexist with VS Code or other
editors running Metals on the same project, with proper handling of edge
cases like crashed processes.

* test(scala): Add integration tests for stale lock handling modes

Add 7 integration tests for ScalaLanguageServer stale lock detection:
- AUTO_CLEAN mode cleans stale locks and proceeds
- WARN mode logs warning without cleanup
- FAIL mode raises MetalsStaleLockError
- ACTIVE_INSTANCE logs info when notice enabled
- ACTIVE_INSTANCE silent when notice disabled
- NO_DATABASE proceeds silently
- NO_LOCK proceeds silently

Tests use mocking to avoid requiring Java/Coursier/Metals.

* docs(scala): Add multi-instance and stale lock documentation

Document Metals multi-instance support via H2 AUTO_SERVER:
- Explain how multiple Metals instances share database and Bloop
- Document memory considerations (~500MB per JVM)
- Add stale lock detection configuration options
- Document on_stale_lock modes (auto-clean, warn, fail)
- Add YAML configuration examples

* docs: Clean up docs

Removed memory considerations and additional configuration sections from the Scala setup guide.

* refactor(scala): Extract settings helper and add module-level constants

- Add DEFAULT_METALS_VERSION, DEFAULT_CLIENT_NAME, DEFAULT_ON_STALE_LOCK,
  DEFAULT_LOG_MULTI_INSTANCE_NOTICE constants to eliminate duplication
- Extract _get_scala_settings() pure function for centralized settings parsing
- Remove redundant cleanup_stale_lock import
- Add warning log when AUTO_CLEAN mode fails to remove stale lock
- Simplify lock path handling with ternary expression

This refactoring improves code maintainability by centralizing Scala
settings extraction and applying functional programming principles.

* chore(scala): fix typo in docstring and comments

src/solidlsp/ls_exceptions.py

@@ -50,3 +50,25 @@ class SolidLSPException(Exception):
                 s += " "
             s += f"(caused by {self.cause})"
         return s
+
+
+class MetalsStaleLockError(SolidLSPException):
+    """
+    Raised when a stale Metals H2 database lock is detected and the user
+    has configured fail-on-stale-lock behavior.
+
+    A stale lock occurs when a previous Metals process crashed without
+    cleaning up its lock file, which can prevent proper AUTO_SERVER
+    coordination with new instances.
+    """
+
+    def __init__(self, lock_path: str, message: str | None = None) -> None:
+        self.lock_path = lock_path
+        if message is None:
+            message = (
+                f"Stale Metals lock file detected at {lock_path}. "
+                "A previous Metals process may have crashed. "
+                "To resolve: remove the lock file manually, or set "
+                "on_stale_lock='auto-clean' in ls_specific_settings.scala."
+            )
+        super().__init__(message)