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

docs/03-special-guides/scala_setup_guide_for_serena.md

@@ -63,5 +63,41 @@ These instructions cover the setup for projects that use sbt as the build tool,
 Notes:
 - Ensure you completed the manual or auto‑import steps so that the build is compiled and indexed; otherwise, code navigation and references may be incomplete until the first successful compile.
 
+---
+## Running Multiple Metals Instances
+
+Serena can run alongside other Metals instances (e.g., VS Code with Metals extension) on the same project. This is **fully supported** by Metals via H2 AUTO_SERVER mode.
+
+### How It Works
+
+Metals uses an H2 database (`.metals/metals.mv.db`) to cache semantic information. When multiple Metals instances run on the same project:
+
+- **H2 AUTO_SERVER**: The first instance becomes the TCP server; subsequent instances connect as clients
+- **Bloop Build Server**: All instances share a single Bloop process (port 8212)
+- **Compilation Results**: Shared via Bloop — no duplicate compilation
+
+### Stale Lock Detection
+
+If a Metals process crashes without proper cleanup, it may leave a stale lock file (`.metals/metals.mv.db.lock.db`). This can prevent proper AUTO_SERVER coordination, causing new instances to fall back to in-memory database mode (degraded experience).
+
+Serena automatically detects and handles stale locks based on your configuration:
+
+```yaml
+# ~/.serena/serena_config.yml or .serena/project.yml
+ls_specific_settings:
+  scala:
+    on_stale_lock: "auto-clean"      # auto-clean | warn | fail
+    log_multi_instance_notice: true  # Log info when another Metals detected
+```
+
+#### Stale Lock Modes
+
+| Mode | Behavior |
+|------|----------|
+| `auto-clean` | **(Default, Recommended)** Automatically removes stale lock files and proceeds normally. |
+| `warn` | Logs a warning but proceeds. Metals may use in-memory database (slower). |
+| `fail` | Raises an error and refuses to start. Useful for debugging lock issues. |
+
+---
 ## Reference 
-- Metals + sbt: [https://scalameta.org/metals/docs/build-tools/sbt](https://scalameta.org/metals/docs/build-tools/sbt)
+- Metals + sbt: [https://scalameta.org/metals/docs/build-tools/sbt](https://scalameta.org/metals/docs/build-tools/sbt)