claude-mpm 3.4.10__py3-none-any.whl → 5.4.55__py3-none-any.whl

claude_mpm/core/config.py

@@ -5,20 +5,31 @@ Handles loading configuration from files, environment variables,
 and default values with proper validation and type conversion.
 """
 
+import json
+import logging
 import os
+import threading
 from pathlib import Path
-from typing import Any, Dict, Optional, Union
-import logging
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+import yaml
+
+from claude_mpm.core.logging_utils import get_logger
 
 from ..utils.config_manager import ConfigurationManager
+from .exceptions import ConfigurationError, FileOperationError
+from .unified_paths import get_path_manager
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 class Config:
     """
     Configuration manager for Claude PM services.
 
+    Implements singleton pattern to ensure configuration is loaded only once
+    and shared across all services.
+
     Supports loading from:
     - Python dictionaries
     - JSON files
@@ -26,6 +37,34 @@ class Config:
     - Environment variables
     """
 
+    _instance = None
+    _initialized = False
+    _success_logged = (
+        False  # Class-level flag to track if success message was already logged
+    )
+    _lock = threading.Lock()  # Thread safety for singleton initialization
+
+    def __new__(cls, *args, **kwargs):
+        """Implement singleton pattern to ensure single configuration instance.
+
+        WHY: Configuration was being loaded 11 times during startup, once for each service.
+        This singleton pattern ensures configuration is loaded only once and reused.
+        Thread-safe implementation prevents race conditions during concurrent initialization.
+        """
+        if cls._instance is None:
+            with cls._lock:
+                # Double-check locking pattern for thread safety
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+                    logger.debug("Creating new Config singleton instance")
+                else:
+                    logger.debug(
+                        "Reusing existing Config singleton instance (concurrent init)"
+                    )
+        else:
+            logger.debug("Reusing existing Config singleton instance")
+        return cls._instance
+
     def __init__(
         self,
         config: Optional[Dict[str, Any]] = None,
@@ -40,41 +79,191 @@ class Config:
             config_file: Path to configuration file (JSON or YAML)
             env_prefix: Prefix for environment variables
         """
-        self._config: Dict[str, Any] = {}
-        self._env_prefix = env_prefix
-        self._config_mgr = ConfigurationManager(cache_enabled=True)
-
-        # Load base configuration
-        if config:
-            self._config.update(config)
-
-        # Load from file if provided
-        if config_file:
-            self.load_file(config_file)
-
-        # Load from environment variables (new and legacy prefixes)
-        self._load_env_vars()
-        self._load_legacy_env_vars()
+        # Skip initialization if already done (singleton pattern)
+        # Use thread-safe check to prevent concurrent initialization
+        if Config._initialized:
+            logger.debug("Config already initialized, skipping re-initialization")
+            # If someone tries to load a different config file after initialization,
+            # log a debug message but don't reload
+            if config_file and str(config_file) != getattr(self, "_loaded_from", None):
+                logger.debug(
+                    f"Ignoring config_file parameter '{config_file}' - "
+                    f"configuration already loaded from '{getattr(self, '_loaded_from', 'defaults')}'"
+                )
+            return
 
-        # Apply defaults
-        self._apply_defaults()
+        # Thread-safe initialization - acquire lock for ENTIRE initialization process
+        with Config._lock:
+            # Double-check pattern - check again inside the lock
+            if Config._initialized:
+                logger.debug(
+                    "Config already initialized (concurrent), skipping re-initialization"
+                )
+                return
+
+            Config._initialized = True
+            logger.debug("Initializing Config singleton for the first time")
+
+            # Initialize instance variables inside the lock to ensure thread safety
+            self._config: Dict[str, Any] = {}
+            self._env_prefix = env_prefix
+            self._config_mgr = ConfigurationManager(cache_enabled=True)
+
+            # Load base configuration
+            if config:
+                self._config.update(config)
+
+            # Track where configuration was loaded from
+            self._loaded_from = None
+            # Track the actual file we loaded from to prevent re-loading
+            self._actual_loaded_file = None
+
+            # Load from file if provided
+            # Note: Only ONE config file should be loaded, and success message shown only once
+            if config_file:
+                self.load_file(config_file, is_initial_load=True)
+                self._loaded_from = str(config_file)
+            else:
+                # Try to load from standard location: .claude-mpm/configuration.yaml
+                default_config = Path.cwd() / ".claude-mpm" / "configuration.yaml"
+                if default_config.exists():
+                    self.load_file(default_config, is_initial_load=True)
+                    self._loaded_from = str(default_config)
+                elif (
+                    alt_config := Path.cwd() / ".claude-mpm" / "configuration.yml"
+                ).exists():
+                    # Also try .yml extension (using walrus operator for cleaner code)
+                    self.load_file(alt_config, is_initial_load=True)
+                    self._loaded_from = str(alt_config)
+
+            # Load from environment variables (new and legacy prefixes)
+            self._load_env_vars()
+            self._load_legacy_env_vars()
+
+            # Apply defaults
+            self._apply_defaults()
+
+    def load_file(
+        self, file_path: Union[str, Path], is_initial_load: bool = True
+    ) -> None:
+        """Load configuration from file with enhanced error handling.
+
+        WHY: Configuration loading failures can cause silent issues. We need
+        to provide clear, actionable error messages to help users fix problems.
 
-    def load_file(self, file_path: Union[str, Path]) -> None:
-        """Load configuration from file."""
+        Args:
+            file_path: Path to the configuration file
+            is_initial_load: Whether this is the initial configuration load (for logging control)
+        """
         file_path = Path(file_path)
 
+        # Check if we've already loaded from this exact file to prevent duplicate messages
+        if hasattr(self, "_actual_loaded_file") and self._actual_loaded_file == str(
+            file_path
+        ):
+            logger.debug(
+                f"Configuration already loaded from {file_path}, skipping reload"
+            )
+            return
+
         if not file_path.exists():
             logger.warning(f"Configuration file not found: {file_path}")
+            logger.info(
+                f"TIP: Create a configuration file with: mkdir -p {file_path.parent} && touch {file_path}"
+            )
             return
 
         try:
+            # Check if file is readable
+            if not os.access(file_path, os.R_OK):
+                logger.error(f"Configuration file is not readable: {file_path}")
+                logger.info(f"TIP: Fix permissions with: chmod 644 {file_path}")
+                return
+
+            # Check file size (warn if too large)
+            file_size = file_path.stat().st_size
+            if file_size > 1024 * 1024:  # 1MB
+                logger.warning(
+                    f"Configuration file is large ({file_size} bytes): {file_path}"
+                )
+
+            # Try to load the configuration
             file_config = self._config_mgr.load_auto(file_path)
             if file_config:
                 self._config = self._config_mgr.merge_configs(self._config, file_config)
-                logger.info(f"Loaded configuration from {file_path}")
-
+                # Track that we've successfully loaded from this file
+                self._actual_loaded_file = str(file_path)
+
+                # Only log success message once using class-level flag to avoid duplicate messages
+                # Check if we should log success message (thread-safe for reads after initialization)
+                if is_initial_load:
+                    if not Config._success_logged:
+                        # Set flag IMMEDIATELY before logging to prevent any possibility of duplicate
+                        # messages. No lock needed here since we're already inside __init__ lock
+                        Config._success_logged = True
+                        logger.debug(
+                            f"✓ Successfully loaded configuration from {file_path}"
+                        )
+                    else:
+                        # Configuration already successfully loaded before, just debug log
+                        logger.debug(
+                            f"Configuration already loaded, skipping success message for {file_path}"
+                        )
+                else:
+                    # Not initial load (shouldn't happen in normal flow, but handle gracefully)
+                    logger.debug(f"Configuration reloaded from {file_path}")
+
+                # Log important configuration values for debugging
+                if logger.isEnabledFor(logging.DEBUG):
+                    response_logging = file_config.get("response_logging", {})
+                    if response_logging:
+                        logger.debug(
+                            f"Response logging enabled: {response_logging.get('enabled', False)}"
+                        )
+                        logger.debug(
+                            f"Response logging format: {response_logging.get('format', 'json')}"
+                        )
+
+        except yaml.YAMLError as e:
+            logger.error(f"YAML syntax error in {file_path}: {e}")
+            if hasattr(e, "problem_mark"):
+                mark = e.problem_mark
+                logger.error(f"Error at line {mark.line + 1}, column {mark.column + 1}")
+            logger.info(
+                "TIP: Validate your YAML at https://www.yamllint.com/ or run: python scripts/validate_configuration.py"
+            )
+            logger.info(
+                "TIP: Common issue - YAML requires spaces, not tabs. Fix with: sed -i '' 's/\t/    /g' "
+                + str(file_path)
+            )
+            # Store error for later retrieval
+            self._config["_load_error"] = str(e)
+
+        except json.JSONDecodeError as e:
+            logger.error(f"JSON syntax error in {file_path}: {e}")
+            logger.error(f"Error at line {e.lineno}, column {e.colno}")
+            logger.info("TIP: Validate your JSON at https://jsonlint.com/")
+            self._config["_load_error"] = str(e)
+
+        except (OSError, PermissionError) as e:
+            raise FileOperationError(
+                f"Failed to read configuration file: {e}",
+                context={
+                    "file_path": str(file_path),
+                    "operation": "read",
+                    "error_type": type(e).__name__,
+                },
+            ) from e
         except Exception as e:
-            logger.error(f"Failed to load configuration from {file_path}: {e}")
+            # Catch any remaining unexpected errors and wrap them as configuration errors
+            raise ConfigurationError(
+                f"Unexpected error loading configuration from {file_path}: {e}",
+                context={
+                    "file_path": str(file_path),
+                    "error_type": type(e).__name__,
+                    "original_error": str(e),
+                },
+            ) from e
 
     def _load_env_vars(self) -> None:
         """Load configuration from environment variables."""
@@ -116,15 +305,14 @@ class Config:
         # Boolean conversion
         if value.lower() in ("true", "yes", "1", "on"):
             return True
-        elif value.lower() in ("false", "no", "0", "off"):
+        if value.lower() in ("false", "no", "0", "off"):
             return False
 
         # Numeric conversion
         try:
             if "." in value:
                 return float(value)
-            else:
-                return int(value)
+            return int(value)
         except ValueError:
             pass
 
@@ -178,7 +366,7 @@ class Config:
                 "file_descriptors": 1000,
                 "max_clients": 1000,
                 "max_error_rate": 0.1,
-                "network_timeout": 2.0
+                "network_timeout": 2.0,
             },
             # Automatic recovery configuration
             "recovery": {
@@ -189,14 +377,14 @@ class Config:
                 "circuit_breaker": {
                     "failure_threshold": 5,
                     "timeout_seconds": 300,
-                    "success_threshold": 3
+                    "success_threshold": 3,
                 },
                 "strategy": {
                     "warning_threshold": 2,
                     "critical_threshold": 1,
                     "failure_window_seconds": 300,
-                    "min_recovery_interval": 60
-                }
+                    "min_recovery_interval": 60,
+                },
             },
             # Service management
             "graceful_shutdown_timeout": 30,
@@ -218,16 +406,39 @@ class Config:
             # Task and issue tracking
             "enable_persistent_tracking": True,
             "fallback_tracking_method": "logging",  # Options: "logging", "file", "disabled"
+            # Memory management configuration
+            "memory_management": {
+                "enabled": True,
+                "claude_json_warning_threshold_kb": 500,  # Warn at 500KB
+                "claude_json_critical_threshold_kb": 1024,  # Critical at 1MB
+                "auto_archive_enabled": False,  # Don't auto-archive by default
+                "archive_retention_days": 90,  # Keep archives for 90 days
+                "session_retention_hours": 24,  # Keep active sessions for 24 hours
+                "conversation_retention_days": 30,  # Keep conversations for 30 days
+                "monitor_memory_usage": True,  # Monitor memory usage
+                "memory_usage_log_interval": 300,  # Log memory usage every 5 minutes
+                "max_memory_usage_mb": 2048,  # Warn if memory usage exceeds 2GB
+                "cleanup_on_startup": False,  # Don't auto-cleanup on startup
+                "compress_archives": True,  # Compress archived files
+            },
             # Evaluation system - Phase 2 Mirascope integration
             "enable_evaluation": True,
-            "evaluation_storage_path": str(Path.home() / ".claude-pm" / "training"),
+            "evaluation_storage_path": str(
+                get_path_manager().get_user_config_dir() / "training"
+            ),
             "correction_capture_enabled": True,
             "correction_storage_rotation_days": 30,
             "evaluation_logging_enabled": True,
             "auto_prompt_improvement": False,  # Disabled by default for Phase 1
             # Mirascope evaluation settings
             "evaluation_provider": "auto",  # auto, openai, anthropic
-            "evaluation_criteria": ["correctness", "relevance", "completeness", "clarity", "helpfulness"],
+            "evaluation_criteria": [
+                "correctness",
+                "relevance",
+                "completeness",
+                "clarity",
+                "helpfulness",
+            ],
             "evaluation_caching_enabled": True,
             "evaluation_cache_ttl_hours": 24,
             "evaluation_cache_max_size": 1000,
@@ -259,23 +470,23 @@ class Config:
             "correction_compression_enabled": True,
             # Agent Memory System configuration
             "memory": {
-                "enabled": True,                    # Master switch for memory system
-                "auto_learning": True,              # Automatic learning extraction (changed default to True)
+                "enabled": True,  # Master switch for memory system
+                "auto_learning": True,  # Automatic learning extraction (changed default to True)
                 "limits": {
-                    "default_size_kb": 8,           # Default file size limit
-                    "max_sections": 10,             # Maximum sections per file
-                    "max_items_per_section": 15,    # Maximum items per section
-                    "max_line_length": 120          # Maximum line length
+                    "default_size_kb": 80,  # Default file size limit (80KB ~20k tokens)
+                    "max_sections": 10,  # Maximum sections per file
+                    "max_items_per_section": 15,  # Maximum items per section
+                    "max_line_length": 120,  # Maximum line length
                 },
                 "agent_overrides": {
-                    "research": {                   # Research agent override
-                        "size_kb": 16,              # Can have larger memory
-                        "auto_learning": True       # Enable auto learning
+                    "research": {  # Research agent override
+                        "size_kb": 120,  # Can have larger memory (120KB ~30k tokens)
+                        "auto_learning": True,  # Enable auto learning
                     },
-                    "qa": {                         # QA agent override
-                        "auto_learning": True       # Enable auto learning
-                    }
-                }
+                    "qa": {
+                        "auto_learning": True
+                    },  # QA agent override  # Enable auto learning
+                },
             },
             # Socket.IO server health and recovery configuration
             "socketio_server": {
@@ -292,8 +503,8 @@ class Config:
                         "memory_mb": 500,
                         "file_descriptors": 1000,
                         "max_clients": 1000,
-                        "max_error_rate": 0.1
-                    }
+                        "max_error_rate": 0.1,
+                    },
                 },
                 "recovery": {
                     "enabled": True,
@@ -302,32 +513,111 @@ class Config:
                     "circuit_breaker": {
                         "failure_threshold": 5,
                         "timeout_seconds": 300,
-                        "success_threshold": 3
+                        "success_threshold": 3,
                     },
                     "strategy": {
                         "warning_threshold": 2,
                         "critical_threshold": 1,
                         "failure_window_seconds": 300,
-                        "min_recovery_interval": 60
+                        "min_recovery_interval": 60,
                     },
                     "actions": {
                         "log_warning": True,
                         "clear_connections": True,
                         "restart_service": True,
-                        "emergency_stop": True
+                        "emergency_stop": True,
+                    },
+                },
+            },
+            # Monitor server configuration (decoupled from dashboard)
+            "monitor_server": {
+                "host": "localhost",
+                "port": 8765,  # Default monitor port (shared with dashboard)
+                "enable_health_monitoring": True,
+                "auto_start": False,  # Don't auto-start with dashboard by default
+                "event_buffer_size": 2000,  # Larger buffer for monitor server
+                "client_timeout": 60,  # Timeout for inactive clients
+            },
+            # Dashboard server configuration (connects to monitor)
+            "dashboard_server": {
+                "host": "localhost",
+                "port": 8765,  # Dashboard UI port
+                "monitor_host": "localhost",  # Monitor server host to connect to
+                "monitor_port": 8765,  # Monitor server port to connect to
+                "auto_connect_monitor": True,  # Automatically connect to monitor
+                "monitor_reconnect": True,  # Auto-reconnect to monitor if disconnected
+                "fallback_standalone": True,  # Run in standalone mode if monitor unavailable
+            },
+            # Agent deployment configuration
+            "agent_deployment": {
+                "excluded_agents": [],  # List of agent IDs to exclude from deployment
+                "exclude_dependencies": False,  # Whether to exclude agent dependencies too
+                "case_sensitive": False,  # Whether agent name matching is case-sensitive
+                "filter_non_mpm_agents": True,  # Filter out non-MPM agents by default
+                "mpm_author_patterns": [
+                    "claude mpm",
+                    "claude-mpm",
+                    "anthropic",
+                ],  # Patterns for MPM agents
+            },
+            # Instruction reinforcement system configuration
+            "instruction_reinforcement": {
+                "enabled": True,
+                "test_mode": False,
+                "injection_interval": 5,
+                "test_messages": [
+                    "[TEST-REMINDER] This is an injected instruction reminder",
+                    "[PM-INSTRUCTION] Remember to delegate all work to agents",
+                    "[PM-INSTRUCTION] Do not use Edit, Write, or Bash tools directly",
+                    "[PM-INSTRUCTION] Your role is orchestration and coordination",
+                ],
+                "production_messages": [
+                    "[PM-REMINDER] Delegate implementation tasks to specialized agents",
+                    "[PM-REMINDER] Use Task tool for all work delegation",
+                    "[PM-REMINDER] Focus on orchestration, not implementation",
+                    "[PM-REMINDER] Your role is coordination and management",
+                ],
+            },
+            # Session management configuration
+            "session": {
+                "auto_save": True,  # Enable automatic session saving
+                "save_interval": 300,  # Auto-save interval in seconds (5 minutes)
+            },
+            # Update checking configuration
+            "updates": {
+                "check_enabled": True,  # Enable automatic update checks
+                "check_frequency": "daily",  # Options: "always", "daily", "weekly", "never"
+                "check_claude_code": True,  # Check Claude Code version compatibility
+                "auto_upgrade": False,  # Automatically upgrade without prompting (use with caution)
+                "cache_ttl": 86400,  # Cache update check results (24 hours)
+            },
+            # Agent synchronization configuration
+            "agent_sync": {
+                "enabled": True,  # Enable automatic agent sync on startup
+                "sources": [
+                    {
+                        "id": "github-remote",
+                        "url": "https://raw.githubusercontent.com/bobmatnyc/claude-mpm-agents/main/agents",
+                        "priority": 100,
+                        "enabled": True,
                     }
-                }
-            }
+                ],
+                "sync_interval": "startup",  # Options: "startup", "hourly", "daily", "manual"
+                "cache_dir": str(Path.home() / ".claude-mpm" / "cache" / "agents"),
+            },
         }
 
         # Apply defaults for missing keys
         for key, default_value in defaults.items():
             if key not in self._config:
                 self._config[key] = default_value
-        
+
         # Validate health and recovery configuration
         self._validate_health_recovery_config()
 
+        # Validate session configuration
+        self._validate_session_config()
+
     def get(self, key: str, default: Any = None) -> Any:
         """Get configuration value."""
         # Support nested keys with dot notation
@@ -372,13 +662,38 @@ class Config:
             elif format.lower() in ["yaml", "yml"]:
                 self._config_mgr.save_yaml(self._config, file_path)
             else:
-                raise ValueError(f"Unsupported format: {format}")
+                raise ConfigurationError(
+                    f"Unsupported configuration format: {format}",
+                    context={
+                        "format": format,
+                        "supported_formats": ["json", "yaml", "yml"],
+                    },
+                )
 
             logger.info(f"Configuration saved to {file_path}")
 
+        except (OSError, PermissionError) as e:
+            raise FileOperationError(
+                f"Failed to write configuration file: {e}",
+                context={
+                    "file_path": str(file_path),
+                    "operation": "write",
+                    "format": format,
+                    "error_type": type(e).__name__,
+                },
+            ) from e
         except Exception as e:
-            logger.error(f"Failed to save configuration to {file_path}: {e}")
-            raise
+            # Re-raise ConfigurationError as-is, wrap others
+            if isinstance(e, ConfigurationError):
+                raise
+            raise ConfigurationError(
+                f"Unexpected error saving configuration: {e}",
+                context={
+                    "file_path": str(file_path),
+                    "format": format,
+                    "error_type": type(e).__name__,
+                },
+            ) from e
 
     def validate(self, schema: Dict[str, Any]) -> bool:
         """
@@ -407,7 +722,10 @@ class Config:
             return True
 
         except Exception as e:
-            logger.error(f"Configuration validation error: {e}")
+            # Validation errors should be logged but not raise exceptions
+            # since this method returns a boolean result
+            logger.error(f"Unexpected error during configuration validation: {e}")
+            logger.debug(f"Validation error details: {type(e).__name__}: {e}")
             return False
 
     def __getitem__(self, key: str) -> Any:
@@ -426,89 +744,262 @@ class Config:
         """Validate health monitoring and recovery configuration."""
         try:
             # Validate health thresholds
-            thresholds = self.get('health_thresholds', {})
-            if thresholds.get('cpu_percent', 0) < 0 or thresholds.get('cpu_percent', 0) > 100:
-                logger.warning("CPU threshold should be between 0-100, using default 80")
-                self.set('health_thresholds.cpu_percent', 80.0)
-            
-            if thresholds.get('memory_mb', 0) <= 0:
-                logger.warning("Memory threshold should be positive, using default 500MB")
-                self.set('health_thresholds.memory_mb', 500)
-            
-            if thresholds.get('max_error_rate', 0) < 0 or thresholds.get('max_error_rate', 0) > 1:
-                logger.warning("Error rate threshold should be between 0-1, using default 0.1")
-                self.set('health_thresholds.max_error_rate', 0.1)
-            
+            thresholds = self.get("health_thresholds", {})
+            if (
+                thresholds.get("cpu_percent", 0) < 0
+                or thresholds.get("cpu_percent", 0) > 100
+            ):
+                logger.warning(
+                    "CPU threshold should be between 0-100, using default 80"
+                )
+                self.set("health_thresholds.cpu_percent", 80.0)
+
+            if thresholds.get("memory_mb", 0) <= 0:
+                logger.warning(
+                    "Memory threshold should be positive, using default 500MB"
+                )
+                self.set("health_thresholds.memory_mb", 500)
+
+            if (
+                thresholds.get("max_error_rate", 0) < 0
+                or thresholds.get("max_error_rate", 0) > 1
+            ):
+                logger.warning(
+                    "Error rate threshold should be between 0-1, using default 0.1"
+                )
+                self.set("health_thresholds.max_error_rate", 0.1)
+
             # Validate recovery configuration
-            recovery_config = self.get('recovery', {})
-            if recovery_config.get('max_recovery_attempts', 0) <= 0:
-                logger.warning("Max recovery attempts should be positive, using default 5")
-                self.set('recovery.max_recovery_attempts', 5)
-            
+            recovery_config = self.get("recovery", {})
+            if recovery_config.get("max_recovery_attempts", 0) <= 0:
+                logger.warning(
+                    "Max recovery attempts should be positive, using default 5"
+                )
+                self.set("recovery.max_recovery_attempts", 5)
+
             # Validate circuit breaker configuration
-            cb_config = recovery_config.get('circuit_breaker', {})
-            if cb_config.get('failure_threshold', 0) <= 0:
-                logger.warning("Circuit breaker failure threshold should be positive, using default 5")
-                self.set('recovery.circuit_breaker.failure_threshold', 5)
-            
-            if cb_config.get('timeout_seconds', 0) <= 0:
-                logger.warning("Circuit breaker timeout should be positive, using default 300")
-                self.set('recovery.circuit_breaker.timeout_seconds', 300)
-            
+            cb_config = recovery_config.get("circuit_breaker", {})
+            if cb_config.get("failure_threshold", 0) <= 0:
+                logger.warning(
+                    "Circuit breaker failure threshold should be positive, using default 5"
+                )
+                self.set("recovery.circuit_breaker.failure_threshold", 5)
+
+            if cb_config.get("timeout_seconds", 0) <= 0:
+                logger.warning(
+                    "Circuit breaker timeout should be positive, using default 300"
+                )
+                self.set("recovery.circuit_breaker.timeout_seconds", 300)
+
         except Exception as e:
             logger.error(f"Error validating health/recovery configuration: {e}")
-    
+
+    def _validate_session_config(self) -> None:
+        """Validate session management configuration."""
+        try:
+            session_config = self.get("session", {})
+
+            # Validate save_interval range (60-1800 seconds)
+            save_interval = session_config.get("save_interval", 300)
+            if not isinstance(save_interval, int):
+                logger.warning(
+                    f"Session save_interval must be integer, got {type(save_interval).__name__}, using default 300"
+                )
+                self.set("session.save_interval", 300)
+            elif save_interval < 60:
+                logger.warning(
+                    f"Session save_interval must be at least 60 seconds, got {save_interval}, using 60"
+                )
+                self.set("session.save_interval", 60)
+            elif save_interval > 1800:
+                logger.warning(
+                    f"Session save_interval must be at most 1800 seconds (30 min), got {save_interval}, using 1800"
+                )
+                self.set("session.save_interval", 1800)
+
+            # Validate auto_save is boolean
+            auto_save = session_config.get("auto_save", True)
+            if not isinstance(auto_save, bool):
+                logger.warning(
+                    f"Session auto_save must be boolean, got {type(auto_save).__name__}, using True"
+                )
+                self.set("session.auto_save", True)
+
+        except Exception as e:
+            logger.error(f"Error validating session configuration: {e}")
+
     def get_health_monitoring_config(self) -> Dict[str, Any]:
         """Get health monitoring configuration with defaults."""
         base_config = {
-            'enabled': self.get('enable_health_monitoring', True),
-            'check_interval': self.get('health_check_interval', 30),
-            'history_size': self.get('health_history_size', 100),
-            'aggregation_window': self.get('health_aggregation_window', 300),
-            'thresholds': self.get('health_thresholds', {
-                'cpu_percent': 80.0,
-                'memory_mb': 500,
-                'file_descriptors': 1000,
-                'max_clients': 1000,
-                'max_error_rate': 0.1,
-                'network_timeout': 2.0
-            })
+            "enabled": self.get("enable_health_monitoring", True),
+            "check_interval": self.get("health_check_interval", 30),
+            "history_size": self.get("health_history_size", 100),
+            "aggregation_window": self.get("health_aggregation_window", 300),
+            "thresholds": self.get(
+                "health_thresholds",
+                {
+                    "cpu_percent": 80.0,
+                    "memory_mb": 500,
+                    "file_descriptors": 1000,
+                    "max_clients": 1000,
+                    "max_error_rate": 0.1,
+                    "network_timeout": 2.0,
+                },
+            ),
         }
-        
+
         # Merge with socketio-specific config if available
-        socketio_config = self.get('socketio_server.health_monitoring', {})
+        socketio_config = self.get("socketio_server.health_monitoring", {})
         if socketio_config:
             base_config.update(socketio_config)
-        
+
         return base_config
-    
+
     def get_recovery_config(self) -> Dict[str, Any]:
         """Get recovery configuration with defaults."""
-        base_config = self.get('recovery', {
-            'enabled': True,
-            'check_interval': 60,
-            'max_recovery_attempts': 5,
-            'recovery_timeout': 30,
-            'circuit_breaker': {
-                'failure_threshold': 5,
-                'timeout_seconds': 300,
-                'success_threshold': 3
+        base_config = self.get(
+            "recovery",
+            {
+                "enabled": True,
+                "check_interval": 60,
+                "max_recovery_attempts": 5,
+                "recovery_timeout": 30,
+                "circuit_breaker": {
+                    "failure_threshold": 5,
+                    "timeout_seconds": 300,
+                    "success_threshold": 3,
+                },
+                "strategy": {
+                    "warning_threshold": 2,
+                    "critical_threshold": 1,
+                    "failure_window_seconds": 300,
+                    "min_recovery_interval": 60,
+                },
             },
-            'strategy': {
-                'warning_threshold': 2,
-                'critical_threshold': 1,
-                'failure_window_seconds': 300,
-                'min_recovery_interval': 60
-            }
-        })
-        
+        )
+
         # Merge with socketio-specific config if available
-        socketio_config = self.get('socketio_server.recovery', {})
+        socketio_config = self.get("socketio_server.recovery", {})
         if socketio_config:
             base_config = self._config_mgr.merge_configs(base_config, socketio_config)
-        
+
         return base_config
 
+    def validate_configuration(self) -> Tuple[bool, List[str], List[str]]:
+        """Validate the loaded configuration programmatically.
+
+        WHY: Provide a programmatic way to validate configuration that can be
+        used by other components to check configuration health.
+
+        Returns:
+            Tuple of (is_valid, errors, warnings)
+        """
+        errors = []
+        warnings = []
+
+        # Check if there was a load error
+        if "_load_error" in self._config:
+            errors.append(f"Configuration load error: {self._config['_load_error']}")
+
+        # Validate response_logging configuration
+        response_logging = self.get("response_logging", {})
+        if response_logging:
+            # Check enabled field
+            if "enabled" in response_logging and not isinstance(
+                response_logging["enabled"], bool
+            ):
+                errors.append(
+                    f"response_logging.enabled must be boolean, got {type(response_logging['enabled']).__name__}"
+                )
+
+            # Check format field
+            if "format" in response_logging:
+                valid_formats = ["json", "syslog", "journald"]
+                if response_logging["format"] not in valid_formats:
+                    errors.append(
+                        f"response_logging.format must be one of {valid_formats}, "
+                        f"got '{response_logging['format']}'"
+                    )
+
+            # Check session_directory
+            if "session_directory" in response_logging:
+                session_dir = Path(response_logging["session_directory"])
+                if session_dir.is_absolute() and not session_dir.parent.exists():
+                    warnings.append(
+                        f"Parent directory for session_directory does not exist: {session_dir.parent}"
+                    )
+
+        # Validate memory configuration
+        memory_config = self.get("memory", {})
+        if memory_config:
+            if "enabled" in memory_config and not isinstance(
+                memory_config["enabled"], bool
+            ):
+                errors.append("memory.enabled must be boolean")
+
+            # Check limits
+            limits = memory_config.get("limits", {})
+            for field in ["default_size_kb", "max_sections", "max_items_per_section"]:
+                if field in limits:
+                    value = limits[field]
+                    if not isinstance(value, int) or value <= 0:
+                        errors.append(
+                            f"memory.limits.{field} must be positive integer, got {value}"
+                        )
+
+        # Validate health thresholds
+        health_thresholds = self.get("health_thresholds", {})
+        if health_thresholds:
+            cpu = health_thresholds.get("cpu_percent")
+            if cpu is not None and (
+                not isinstance(cpu, (int, float)) or cpu < 0 or cpu > 100
+            ):
+                errors.append(f"health_thresholds.cpu_percent must be 0-100, got {cpu}")
+
+            mem = health_thresholds.get("memory_mb")
+            if mem is not None and (not isinstance(mem, (int, float)) or mem <= 0):
+                errors.append(
+                    f"health_thresholds.memory_mb must be positive, got {mem}"
+                )
+
+        is_valid = len(errors) == 0
+        return is_valid, errors, warnings
+
+    def get_configuration_status(self) -> Dict[str, Any]:
+        """Get detailed configuration status for debugging.
+
+        WHY: Provide a comprehensive view of configuration state for
+        troubleshooting and health checks.
+
+        Returns:
+            Dictionary with configuration status information
+        """
+        is_valid, errors, warnings = self.validate_configuration()
+
+        return {
+            "valid": is_valid,
+            "errors": errors,
+            "warnings": warnings,
+            "loaded_from": getattr(self, "_loaded_from", "defaults"),
+            "key_count": len(self._config),
+            "has_response_logging": "response_logging" in self._config,
+            "has_memory_config": "memory" in self._config,
+            "response_logging_enabled": self.get("response_logging.enabled", False),
+            "memory_enabled": self.get("memory.enabled", False),
+        }
+
     def __repr__(self) -> str:
         """String representation of configuration."""
         return f"<Config({len(self._config)} keys)>"
+
+    @classmethod
+    def reset_singleton(cls):
+        """Reset the singleton instance (mainly for testing purposes).
+
+        WHY: During testing, we may need to reset the singleton to test different
+        configurations. This method allows controlled reset of the singleton state.
+        """
+        cls._instance = None
+        cls._initialized = False
+        cls._success_logged = False
+        logger.debug("Config singleton reset")