netra-zen 1.0.7__py3-none-any.whl → 1.0.9__py3-none-any.whl

scripts/agent_cli.py

@@ -61,7 +61,7 @@ if not _stream_logs_active:
         logger.disabled = True
 
 from typing import Optional, Dict, Any, List
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 import aiohttp
 import websockets
@@ -159,12 +159,10 @@ class SimpleConfigReader:
 try:
     from agent_output_validator import AgentOutputValidator, ValidationReport, ValidationResult
 except ImportError:
-    # Try relative import from scripts directory
-    import sys
-    import os
-    script_dir = os.path.dirname(os.path.abspath(__file__))
-    sys.path.insert(0, script_dir)
-    from agent_output_validator import AgentOutputValidator, ValidationReport, ValidationResult
+    # Module not available - create stub classes
+    AgentOutputValidator = None
+    ValidationReport = None
+    ValidationResult = None
 
 # Import WebSocket event validation framework for Issue #2177
 try:
@@ -172,14 +170,10 @@ try:
         WebSocketEventValidationFramework, EventValidationReport, ValidationResult as EventValidationResult
     )
 except ImportError:
-    # Try relative import from scripts directory
-    import sys
-    import os
-    script_dir = os.path.dirname(os.path.abspath(__file__))
-    sys.path.insert(0, script_dir)
-    from websocket_event_validation_framework import (
-        WebSocketEventValidationFramework, EventValidationReport, ValidationResult as EventValidationResult
-    )
+    # Module not available - create stub classes
+    WebSocketEventValidationFramework = None
+    EventValidationReport = None
+    EventValidationResult = None
 
 # Import business value validator for revenue protection
 # ISSUE #2414: Delay imports that trigger configuration validation
@@ -1632,6 +1626,7 @@ class Config:
     skip_timeout_validation: bool = False  # Issue #2483: Skip timeout hierarchy validation
     json_mode: bool = False  # ISSUE #2766: JSON output mode - suppress console output
     ci_mode: bool = False  # ISSUE #2766: CI mode - suppress Rich terminal output
+    use_backend_threads: bool = True  # SSOT: Use backend for thread ID management (can disable for backward compat)
 
     def get_websocket_url(self) -> str:
         """Get WebSocket URL for compatibility with test framework"""
@@ -2606,6 +2601,11 @@ class WebSocketClient:
         # ISSUE #2417 Phase 2: Store thread_id for filtering backend logs
         self.current_thread_id: Optional[str] = None
 
+        # SSOT: Thread management cache for performance
+        self.thread_cache_file = self._get_platform_cache_path()
+        self.thread_cache: Dict[str, Dict[str, Any]] = {}
+        self._load_thread_cache()
+
         # Log forwarding configuration
         self.send_logs = send_logs
         self.logs_count = logs_count
@@ -2861,9 +2861,25 @@ class WebSocketClient:
                         DebugLevel.BASIC,
                         style="green"
                     )
-                    safe_console_print("SUCCESS: WebSocket connected successfully!", style="green")
-                    self.connected = True
-                    return True
+
+                    # SSOT: Perform handshake to get backend-provided thread_id
+                    handshake_success = await self._perform_handshake()
+                    if handshake_success:
+                        safe_console_print(f"✅ Connected with thread ID: {self.current_thread_id}", style="green")
+                        self.connected = True
+                        return True
+                    else:
+                        # Handshake failed - backend might be old version
+                        self.debug.debug_print(
+                            "WARNING: Handshake failed - backend may not support thread agreement",
+                            DebugLevel.BASIC,
+                            style="yellow"
+                        )
+
+                        # Still mark as connected for backward compatibility
+                        # Old backends might work without the handshake
+                        self.connected = True
+                        return True
             except Exception as e:
                 self.debug.log_connection_attempt(method_name, self.config.ws_url, success=False, error=str(e))
                 self.debug.debug_print(
@@ -2961,6 +2977,492 @@ class WebSocketClient:
         )
         return True
 
+    async def _perform_handshake(self) -> bool:
+        """
+        SSOT: Perform handshake protocol to get backend-provided thread_id.
+        This ensures both CLI and backend agree on the thread_id for proper event routing.
+
+        Protocol (tries both approaches):
+        A. New protocol: Backend sends connection_established immediately
+        B. Legacy protocol: CLI sends initial message to trigger backend response
+        """
+        try:
+            import asyncio
+
+            self.debug.debug_print(
+                "Starting handshake...",
+                DebugLevel.VERBOSE,
+                style="cyan"
+            )
+
+            # Try to receive immediately (new protocol where backend sends first)
+            try:
+                # Non-blocking check if backend sent connection_established
+                response_msg = await asyncio.wait_for(self.ws.recv(), timeout=2.0)
+                response = json.loads(response_msg)
+
+                # Process if we got a connection_established immediately
+                if response.get('type') == 'connection_established':
+                    self.debug.debug_print(
+                        "Received thread ID from backend",
+                        DebugLevel.VERBOSE,
+                        style="green"
+                    )
+                    return await self._process_connection_established(response)
+                else:
+                    # Got a different message type - log it
+                    self.debug.debug_print(
+                        f"Got {response.get('type')} instead of connection_established",
+                        DebugLevel.VERBOSE,
+                        style="yellow"
+                    )
+            except asyncio.TimeoutError:
+                # Backend didn't send immediately, try sending a trigger message
+                pass  # Silent - this is normal for backends that wait for trigger
+
+            # If we didn't get connection_established immediately, send a trigger
+            # This handles backends that wait for an initial message
+            trigger_message = {
+                "type": "handshake_request",
+                "client_type": "cli",
+                "client_version": "2.0.0",
+                "timestamp": datetime.now(timezone.utc).isoformat()
+            }
+
+            self.debug.debug_print(
+                "Sending handshake_request...",
+                DebugLevel.VERBOSE,
+                style="cyan"
+            )
+
+            await self.ws.send(json.dumps(trigger_message))
+
+            # Now wait for the response
+            try:
+                response_msg = await asyncio.wait_for(self.ws.recv(), timeout=10.0)
+                response = json.loads(response_msg)
+
+                if response.get('type') == 'connection_established':
+                    return await self._process_connection_established(response)
+                else:
+                    # Not a connection_established message - show actual response
+                    response_type = response.get('type', 'unknown')
+                    self.debug.debug_print(
+                        f"ERROR: Unexpected response type: '{response_type}'",
+                        DebugLevel.BASIC,
+                        style="red"
+                    )
+
+                    # CRITICAL: Show the actual response data for debugging
+                    self.debug.debug_print(
+                        "ACTUAL RESPONSE DATA:",
+                        DebugLevel.BASIC,
+                        style="yellow"
+                    )
+                    self.debug.debug_print(
+                        json.dumps(response, indent=2),
+                        DebugLevel.BASIC,
+                        style="cyan"
+                    )
+                    return False
+
+            except asyncio.TimeoutError:
+                # Timeout - log error concisely
+                self.debug.debug_print(
+                    "ERROR: Handshake timeout - no response from backend",
+                    DebugLevel.BASIC,
+                    style="red"
+                )
+                return False
+
+        except Exception as e:
+            # Handshake error - log but don't completely fail
+            error_msg = f"WARNING: Handshake error: {e}"
+            self.debug.log_error(e, "handshake protocol")
+            self.debug.debug_print(error_msg, DebugLevel.BASIC, style="yellow")
+            safe_console_print(error_msg, style="yellow")
+            return False
+
+    async def _process_connection_established(self, response: Dict[str, Any]) -> bool:
+        """
+        Process a connection_established message from backend.
+
+        Args:
+            response: The connection_established message from backend
+
+        Returns:
+            True if thread_id was successfully extracted and acknowledged
+        """
+        # Extract all IDs from backend response
+        backend_thread_id = response.get('thread_id')
+        backend_run_id = response.get('run_id')
+        backend_request_id = response.get('request_id')
+        backend_session_token = response.get('session_token')
+
+        if not backend_thread_id:
+            # Backend didn't provide thread_id
+            self.debug.debug_print(
+                "ERROR: Backend connection_established missing thread_id",
+                DebugLevel.BASIC,
+                style="red"
+            )
+            return False
+
+        # CRITICAL: Accept backend's thread_id as single source of truth
+        self.current_thread_id = backend_thread_id
+        self.run_id = backend_run_id  # Store run_id if provided
+        self._update_thread_cache(backend_thread_id)
+
+        self.debug.debug_print(
+            f"Thread ID: {backend_thread_id}",
+            DebugLevel.VERBOSE,
+            style="green"
+        )
+
+        # CRITICAL: Send acknowledgment with the SAME thread_id
+        ack_message = {
+            "type": "session_acknowledged",
+            "thread_id": backend_thread_id,  # Echo back the same ID
+            "timestamp": datetime.now(timezone.utc).isoformat()
+        }
+
+        await self.ws.send(json.dumps(ack_message))
+
+        return True
+
+    def _get_platform_cache_path(self) -> Path:
+        """
+        Get platform-appropriate cache directory path.
+
+        Windows: %LOCALAPPDATA%/Netra/CLI/thread_cache.json
+        macOS: ~/Library/Application Support/Netra/CLI/thread_cache.json
+        Linux: ~/.local/share/netra/cli/thread_cache.json or ~/.netra/thread_cache.json
+        """
+        import platform as stdlib_platform
+
+        system = stdlib_platform.system()
+
+        if system == "Windows":
+            # Use Windows AppData/Local directory
+            app_data = os.environ.get('LOCALAPPDATA')
+            if app_data:
+                cache_dir = Path(app_data) / "Netra" / "CLI"
+            else:
+                # Fallback to user home
+                cache_dir = Path.home() / "AppData" / "Local" / "Netra" / "CLI"
+        elif system == "Darwin":  # macOS
+            # Use macOS Application Support directory
+            cache_dir = Path.home() / "Library" / "Application Support" / "Netra" / "CLI"
+        else:  # Linux and other Unix-like systems
+            # Follow XDG Base Directory Specification
+            xdg_data_home = os.environ.get('XDG_DATA_HOME')
+            if xdg_data_home:
+                cache_dir = Path(xdg_data_home) / "netra" / "cli"
+            else:
+                # Fallback to ~/.local/share or ~/.netra for compatibility
+                local_share = Path.home() / ".local" / "share" / "netra" / "cli"
+                if local_share.parent.exists():
+                    cache_dir = local_share
+                else:
+                    # Legacy path for backward compatibility
+                    cache_dir = Path.home() / ".netra"
+
+        return cache_dir / "thread_cache.json"
+
+    def _load_thread_cache(self) -> None:
+        """
+        Load thread cache from disk for SSOT thread management.
+
+        Cache structure:
+        {
+            "user_id": {
+                "thread_id": "backend_thread_123",
+                "created_at": "2024-01-01T00:00:00",
+                "last_used": "2024-01-01T00:00:00",
+                "environment": "staging"
+            }
+        }
+        """
+        try:
+            if self.thread_cache_file.exists():
+                with open(self.thread_cache_file, 'r') as f:
+                    self.thread_cache = json.load(f)
+                    self.debug.debug_print(
+                        f"SSOT: Loaded thread cache with {len(self.thread_cache)} entries",
+                        DebugLevel.VERBOSE
+                    )
+        except Exception as e:
+            self.debug.debug_print(
+                f"SSOT: Could not load thread cache: {e}",
+                DebugLevel.TRACE
+            )
+            self.thread_cache = {}
+
+    def _save_thread_cache(self) -> None:
+        """Save thread cache to disk for persistence."""
+        try:
+            # Ensure directory exists
+            self.thread_cache_file.parent.mkdir(parents=True, exist_ok=True)
+
+            # Save cache
+            with open(self.thread_cache_file, 'w') as f:
+                json.dump(self.thread_cache, f, indent=2)
+
+            self.debug.debug_print(
+                "SSOT: Thread cache saved successfully",
+                DebugLevel.TRACE
+            )
+        except Exception as e:
+            self.debug.debug_print(
+                f"SSOT: Could not save thread cache: {e}",
+                DebugLevel.TRACE
+            )
+
+    def _get_cached_thread_id(self) -> Optional[str]:
+        """
+        Get cached thread ID for current user and environment.
+
+        SSOT: Uses cached thread but validates with backend.
+        """
+        try:
+            # Get user identifier from token
+            if not self.token:
+                return None
+
+            # Decode token to get user_id
+            payload = jwt.decode(self.token, options={"verify_signature": False})
+            user_id = payload.get('user_id') or payload.get('sub') or payload.get('email')
+
+            if not user_id:
+                return None
+
+            # Check cache for this user
+            if user_id in self.thread_cache:
+                cached_data = self.thread_cache[user_id]
+
+                # Check if cache is for same environment
+                cached_env = cached_data.get('environment')
+                current_env = self.config.environment.value if hasattr(self.config, 'environment') else None
+
+                if cached_env == current_env:
+                    thread_id = cached_data.get('thread_id')
+                    last_used = cached_data.get('last_used')
+
+                    # Check if cache is recent (within 24 hours)
+                    if last_used:
+                        last_used_dt = datetime.fromisoformat(last_used)
+                        if datetime.now() - last_used_dt < timedelta(hours=24):
+                            self.debug.debug_print(
+                                f"SSOT: Found cached thread_id: {thread_id}",
+                                DebugLevel.VERBOSE
+                            )
+                            return thread_id
+
+        except Exception as e:
+            self.debug.debug_print(
+                f"SSOT: Error accessing thread cache: {e}",
+                DebugLevel.TRACE
+            )
+
+        return None
+
+    def _update_thread_cache(self, thread_id: str) -> None:
+        """Update thread cache with new or validated thread ID."""
+        try:
+            # Get user identifier
+            payload = jwt.decode(self.token, options={"verify_signature": False})
+            user_id = payload.get('user_id') or payload.get('sub') or payload.get('email')
+
+            if user_id:
+                # Update cache entry
+                self.thread_cache[user_id] = {
+                    'thread_id': thread_id,
+                    'created_at': self.thread_cache.get(user_id, {}).get('created_at', datetime.now().isoformat()),
+                    'last_used': datetime.now().isoformat(),
+                    'environment': self.config.environment.value if hasattr(self.config, 'environment') else "unknown"
+                }
+
+                # Save to disk
+                self._save_thread_cache()
+
+                self.debug.debug_print(
+                    f"SSOT: Updated thread cache for user {user_id[:10]}...",
+                    DebugLevel.TRACE
+                )
+
+        except Exception as e:
+            self.debug.debug_print(
+                f"SSOT: Could not update thread cache: {e}",
+                DebugLevel.TRACE
+            )
+
+    async def get_or_create_thread_from_backend(self) -> Optional[str]:
+        """
+        SSOT: Get or create a thread ID from the backend.
+
+        This ensures thread IDs are managed by the backend as the single source of truth,
+        not generated locally by the client.
+
+        Returns:
+            Thread ID from backend, or None if creation fails
+        """
+        # Check if backend thread management is disabled
+        if not self.config.use_backend_threads:
+            self.debug.debug_print(
+                "SSOT: Backend thread management disabled by configuration",
+                DebugLevel.VERBOSE
+            )
+            return None
+
+        try:
+            # First check if we have a cached thread_id for this session
+            if self.current_thread_id and await self._validate_thread_with_backend(self.current_thread_id):
+                self.debug.debug_print(
+                    f"SSOT: Using existing validated thread_id: {self.current_thread_id}",
+                    DebugLevel.VERBOSE
+                )
+                self._update_thread_cache(self.current_thread_id)
+                return self.current_thread_id
+
+            # Check persistent cache for thread ID
+            cached_thread_id = self._get_cached_thread_id()
+            if cached_thread_id and await self._validate_thread_with_backend(cached_thread_id):
+                self.current_thread_id = cached_thread_id
+                self.debug.debug_print(
+                    f"SSOT: Using cached and validated thread_id: {cached_thread_id}",
+                    DebugLevel.VERBOSE
+                )
+                self._update_thread_cache(cached_thread_id)
+                return cached_thread_id
+
+            # Create a new thread via backend API
+            thread_id = await self._create_thread_on_backend()
+            if thread_id:
+                self.current_thread_id = thread_id
+                self._update_thread_cache(thread_id)
+                self.debug.debug_print(
+                    f"SSOT: Created new thread_id from backend: {thread_id}",
+                    DebugLevel.BASIC,
+                    style="green"
+                )
+                return thread_id
+
+            # Fallback: Use local generation with warning (backward compatibility)
+            self.debug.debug_print(
+                "SSOT WARNING: Backend thread creation failed, falling back to local generation",
+                DebugLevel.BASIC,
+                style="yellow"
+            )
+            return None
+
+        except Exception as e:
+            self.debug.debug_print(
+                f"SSOT ERROR: Thread management failed: {e}",
+                DebugLevel.BASIC,
+                style="red"
+            )
+            return None
+
+    async def _create_thread_on_backend(self) -> Optional[str]:
+        """
+        Create a new thread on the backend and return its ID.
+
+        SSOT: Backend is the authoritative source for thread IDs.
+        """
+        try:
+            # Construct the thread creation endpoint
+            thread_url = f"{self.config.backend_url}/api/threads/create"
+
+            headers = {
+                "Authorization": f"Bearer {self.token}",
+                "Content-Type": "application/json"
+            }
+
+            # Thread creation payload with metadata
+            payload = {
+                "source": "agent_cli",
+                "environment": self.config.environment.value if hasattr(self.config, 'environment') else "unknown",
+                "client_version": "1.0.0",  # Could be made configurable
+                "timestamp": datetime.now().isoformat()
+            }
+
+            # Use aiohttp session if available, otherwise create one
+            import aiohttp
+            async with aiohttp.ClientSession() as session:
+                async with session.post(thread_url, json=payload, headers=headers) as response:
+                    if response.status == 200 or response.status == 201:
+                        data = await response.json()
+                        thread_id = data.get("thread_id") or data.get("id")
+                        if thread_id:
+                            self.debug.debug_print(
+                                f"SSOT: Backend created thread with ID: {thread_id}",
+                                DebugLevel.VERBOSE
+                            )
+                            return thread_id
+                    else:
+                        error_text = await response.text()
+                        self.debug.debug_print(
+                            f"SSOT: Backend thread creation failed with status {response.status}: {error_text}",
+                            DebugLevel.BASIC,
+                            style="yellow"
+                        )
+
+        except aiohttp.ClientError as e:
+            # Network or connection errors - expected in some environments
+            self.debug.debug_print(
+                f"SSOT: Backend thread API not available (network error): {e}",
+                DebugLevel.VERBOSE
+            )
+        except Exception as e:
+            self.debug.debug_print(
+                f"SSOT: Unexpected error creating backend thread: {e}",
+                DebugLevel.VERBOSE
+            )
+
+        return None
+
+    async def _validate_thread_with_backend(self, thread_id: str) -> bool:
+        """
+        Validate that a thread ID exists and is valid on the backend.
+
+        SSOT: Backend validates thread existence and status.
+        """
+        try:
+            # Quick validation - check if thread exists on backend
+            validate_url = f"{self.config.backend_url}/api/threads/{thread_id}/validate"
+
+            headers = {
+                "Authorization": f"Bearer {self.token}"
+            }
+
+            import aiohttp
+            async with aiohttp.ClientSession() as session:
+                async with session.get(validate_url, headers=headers) as response:
+                    if response.status == 200:
+                        data = await response.json()
+                        is_valid = data.get("valid", False)
+                        if is_valid:
+                            self.debug.debug_print(
+                                f"SSOT: Thread {thread_id} validated successfully",
+                                DebugLevel.TRACE
+                            )
+                        return is_valid
+                    elif response.status == 404:
+                        self.debug.debug_print(
+                            f"SSOT: Thread {thread_id} not found on backend",
+                            DebugLevel.VERBOSE
+                        )
+                        return False
+
+        except Exception as e:
+            # If validation fails, assume thread is invalid
+            self.debug.debug_print(
+                f"SSOT: Thread validation failed for {thread_id}: {e}",
+                DebugLevel.TRACE
+            )
+
+        return False
+
     async def send_message(self, message: str) -> str:
         """Send a message and return the run_id"""
         if not self.ws:
@@ -2971,12 +3473,73 @@ class WebSocketClient:
 
         # Create message payload
         # ISSUE #1671 FIX: Add thread_id for proper WebSocket event routing
-        # The WebSocket manager expects both user_id and thread_id to route events correctly
-        # ISSUE #2782: Simple UUID generation - no backend dependency
-        thread_id = f"cli_thread_{uuid.uuid4().hex[:12]}"
+        # SSOT: Thread ID from backend is REQUIRED
+        if not self.current_thread_id:
+            # Detailed error diagnostics
+            self.debug.debug_print(
+                "CRITICAL ERROR: Cannot send message - no thread ID available",
+                DebugLevel.BASIC,
+                style="red"
+            )
+            self.debug.debug_print(
+                "CAUSE: Backend handshake did not complete successfully",
+                DebugLevel.BASIC,
+                style="yellow"
+            )
 
-        # ISSUE #2417 Phase 2: Store thread_id for filtering backend logs
-        self.current_thread_id = thread_id
+            # User-facing error with actionable guidance
+            safe_console_print(
+                "\n❌ ERROR: Cannot send message - thread ID not established",
+                style="red"
+            )
+            safe_console_print(
+                "\n🔍 TROUBLESHOOTING STEPS:",
+                style="yellow"
+            )
+            safe_console_print(
+                "   1. Check if backend is running the latest version",
+                style="dim"
+            )
+            safe_console_print(
+                "   2. Verify backend has CLIHandshakeProtocol implemented",
+                style="dim"
+            )
+            safe_console_print(
+                "   3. Check backend logs for WebSocket connection errors",
+                style="dim"
+            )
+            safe_console_print(
+                "   4. Try running with --debug-level=verbose for more details",
+                style="dim"
+            )
+            safe_console_print(
+                "\n📝 WHAT HAPPENED:",
+                style="cyan"
+            )
+            safe_console_print(
+                "   • CLI connected to WebSocket successfully",
+                style="dim"
+            )
+            safe_console_print(
+                "   • Backend did not provide a thread ID during handshake",
+                style="dim"
+            )
+            safe_console_print(
+                "   • Without thread ID, events cannot be properly routed",
+                style="dim"
+            )
+
+            raise RuntimeError(
+                "Thread ID not established with backend. "
+                "See troubleshooting steps above."
+            )
+
+        thread_id = self.current_thread_id
+        self.debug.debug_print(
+            f"SSOT: Using backend-provided thread_id: {thread_id}",
+            DebugLevel.VERBOSE,
+            style="green"
+        )
 
         # ISSUE #1673 FIX: Backend expects payload structure with nested data
         # The backend AgentServiceCore._parse_message expects:
@@ -2998,18 +3561,79 @@ class WebSocketClient:
             try:
                 from scripts.agent_logs import collect_recent_logs
 
-                logs = collect_recent_logs(
+                result = collect_recent_logs(
                     limit=self.logs_count,
                     project_name=self.logs_project,
                     base_path=self.logs_path,
                     username=self.logs_user
                 )
 
-                if logs:
+                if result:
+                    logs, files_read, file_info = result
                     payload["payload"]["jsonl_logs"] = logs
+
+                    # Calculate payload size for transmission proof
+                    import logging
+                    import sys
+
+                    # Get size of logs in payload
+                    logs_json = json.dumps(logs)
+                    logs_size_bytes = len(logs_json.encode('utf-8'))
+                    logs_size_kb = logs_size_bytes / 1024
+                    logs_size_mb = logs_size_kb / 1024
+
+                    # Format size appropriately
+                    if logs_size_mb >= 1:
+                        size_str = f"{logs_size_mb:.2f} MB"
+                    elif logs_size_kb >= 1:
+                        size_str = f"{logs_size_kb:.2f} KB"
+                    else:
+                        size_str = f"{logs_size_bytes} bytes"
+
+                    # Create prominent, formatted log message
+                    separator = "=" * 60
+                    log_msg_parts = [
+                        "",
+                        separator,
+                        f"📤 SENDING LOGS TO OPTIMIZER",
+                        separator,
+                        f"  Total Entries: {len(logs)}",
+                        f"  Files Read: {files_read}",
+                        f"  Payload Size: {size_str}",
+                    ]
+
+                    if self.logs_project:
+                        log_msg_parts.append(f"  Project: {self.logs_project}")
+
+                    log_msg_parts.append("")
+                    log_msg_parts.append("  Files:")
+
+                    # Add file details with hashes
+                    for info in file_info:
+                        log_msg_parts.append(
+                            f"    • {info['name']} (hash: {info['hash']}, {info['entries']} entries)"
+                        )
+
+                    # Add payload proof
+                    log_msg_parts.append("")
+                    log_msg_parts.append("  Payload Confirmation:")
+                    log_msg_parts.append(f"    ✓ 'jsonl_logs' key added to payload")
+                    log_msg_parts.append(f"    ✓ First log entry timestamp: {logs[0].get('timestamp', 'N/A') if logs else 'N/A'}")
+                    log_msg_parts.append(f"    ✓ Last log entry timestamp: {logs[-1].get('timestamp', 'N/A') if logs else 'N/A'}")
+
+                    log_msg_parts.append(separator)
+                    log_msg_parts.append("")
+
+                    log_msg = "\n".join(log_msg_parts)
+
+                    # Log at INFO level
+                    logging.info(log_msg)
+
+                    # Also print via debug system for consistency
                     self.debug.debug_print(
-                        f"Attached {len(logs)} log entries to message payload",
-                        DebugLevel.BASIC
+                        log_msg,
+                        DebugLevel.BASIC,
+                        style="cyan"
                     )
                 else:
                     self.debug.debug_print(
@@ -3031,6 +3655,51 @@ class WebSocketClient:
             style="yellow"
         )
 
+        # Proof of logs in transmission
+        if "jsonl_logs" in payload["payload"]:
+            log_count = len(payload["payload"]["jsonl_logs"])
+            self.debug.debug_print(
+                f"✓ TRANSMISSION PROOF: Payload contains {log_count} JSONL log entries in 'jsonl_logs' key",
+                DebugLevel.BASIC,
+                style="green"
+            )
+
+            # Optional: Save payload proof to file for verification
+            if os.environ.get('ZEN_SAVE_PAYLOAD_PROOF'):
+                try:
+                    import tempfile
+                    proof_file = tempfile.NamedTemporaryFile(
+                        mode='w',
+                        prefix='zen_payload_proof_',
+                        suffix='.json',
+                        delete=False
+                    )
+
+                    # Save payload structure (with truncated logs for readability)
+                    proof_payload = {
+                        "run_id": payload.get("run_id"),
+                        "payload": {
+                            "message": payload["payload"].get("message"),
+                            "jsonl_logs": {
+                                "count": len(payload["payload"]["jsonl_logs"]),
+                                "sample_first": payload["payload"]["jsonl_logs"][0] if payload["payload"]["jsonl_logs"] else None,
+                                "sample_last": payload["payload"]["jsonl_logs"][-1] if payload["payload"]["jsonl_logs"] else None,
+                            }
+                        }
+                    }
+
+                    json.dump(proof_payload, proof_file, indent=2)
+                    proof_file.close()
+
+                    self.debug.debug_print(
+                        f"📝 Payload proof saved to: {proof_file.name}",
+                        DebugLevel.BASIC,
+                        style="cyan"
+                    )
+                except Exception as e:
+                    # Don't fail transmission if proof saving fails
+                    pass
+
         # ISSUE #1603 FIX: Add critical logging for message sending (only in diagnostic mode)
         if self.debug.debug_level >= DebugLevel.DIAGNOSTIC:
             self.debug.debug_print(f"SENDING WEBSOCKET MESSAGE: {json.dumps(payload, indent=2)}", DebugLevel.DIAGNOSTIC)
@@ -3064,6 +3733,15 @@ class WebSocketClient:
                 )
                 self.events.append(event)
 
+                # Skip connection_established - already handled in handshake
+                # This prevents duplicate processing since handshake now waits for it first
+                if event.type == 'connection_established' and self.current_thread_id:
+                    self.debug.debug_print(
+                        f"SSOT: Ignoring duplicate connection_established (thread already set: {self.current_thread_id})",
+                        DebugLevel.VERBOSE,
+                        style="dim"
+                    )
+
                 self.debug.debug_print(
                     f"GOLDEN PATH TRACE: Parsed WebSocket event type={event.type}",
                     DebugLevel.BASIC,
@@ -3762,7 +4440,7 @@ class AgentCLI:
         # Issue #1822: Agent output validation
         self.validate_outputs = validate_outputs
         self.output_validator: Optional[AgentOutputValidator] = None
-        if self.validate_outputs:
+        if self.validate_outputs and AgentOutputValidator is not None:
             self.output_validator = AgentOutputValidator(debug=config.debug_level.value >= 3)
 
         # Business value validation
@@ -3918,11 +4596,37 @@ class AgentCLI:
 
     async def _receive_events(self):
         """Background task to receive and display events"""
+        thinking_spinner = None
+        thinking_live = None
+
         async def handle_event(event: WebSocketEvent):
+            nonlocal thinking_spinner, thinking_live
+
+            # Stop spinner if it's running and we get any non-thinking event
+            if thinking_live and event.type != "agent_thinking":
+                thinking_live.stop()
+                thinking_live = None
+                thinking_spinner = None
+
             # Display event with enhanced formatting
             formatted_event = event.format_for_display(self.debug)
             safe_console_print(f"[{event.timestamp.strftime('%H:%M:%S')}] {formatted_event}")
 
+            # Start spinner for agent_thinking events (20-60 second wait indicator)
+            if event.type == "agent_thinking" and not thinking_live:
+                thought = event.data.get('thought', event.data.get('reasoning', ''))
+                spinner_text = truncate_with_ellipsis(thought, 60) if thought else "Processing..."
+
+                thinking_spinner = Progress(
+                    SpinnerColumn(spinner_name="dots"),
+                    TextColumn("[cyan]{task.description}"),
+                    console=Console(file=sys.stderr),
+                    transient=True
+                )
+                thinking_live = Live(thinking_spinner, console=Console(file=sys.stderr), refresh_per_second=10)
+                thinking_live.start()
+                thinking_spinner.add_task(f"💭 {spinner_text}", total=None)
+
             # Display raw data in verbose mode
             if self.debug.debug_level >= DebugLevel.DIAGNOSTIC:
                 safe_console_print(Panel(
@@ -3931,16 +4635,47 @@ class AgentCLI:
                     border_style="dim"
                 ))
 
-        await self.ws_client.receive_events(callback=handle_event)
+        try:
+            await self.ws_client.receive_events(callback=handle_event)
+        finally:
+            # Clean up spinner if it's still running
+            if thinking_live:
+                thinking_live.stop()
 
     async def _receive_events_with_display(self):
         """ISSUE #1603 FIX: Enhanced event receiver with better display for single message mode"""
+        thinking_spinner = None
+        thinking_live = None
+
         async def handle_event_with_display(event: WebSocketEvent):
+            nonlocal thinking_spinner, thinking_live
+
+            # Stop spinner if it's running and we get any non-thinking event
+            if thinking_live and event.type != "agent_thinking":
+                thinking_live.stop()
+                thinking_live = None
+                thinking_spinner = None
+
             # Display event with enhanced formatting and emojis
             formatted_event = event.format_for_display(self.debug)
             timestamp = event.timestamp.strftime('%H:%M:%S')
             safe_console_print(f"[{timestamp}] {formatted_event}")
 
+            # Start spinner for agent_thinking events (20-60 second wait indicator)
+            if event.type == "agent_thinking" and not thinking_live:
+                thought = event.data.get('thought', event.data.get('reasoning', ''))
+                spinner_text = truncate_with_ellipsis(thought, 60) if thought else "Processing..."
+
+                thinking_spinner = Progress(
+                    SpinnerColumn(spinner_name="dots"),
+                    TextColumn("[cyan]{task.description}"),
+                    console=Console(file=sys.stderr),
+                    transient=True
+                )
+                thinking_live = Live(thinking_spinner, console=Console(file=sys.stderr), refresh_per_second=10)
+                thinking_live.start()
+                thinking_spinner.add_task(f"💭 {spinner_text}", total=None)
+
             # Issue #2177: WebSocket event validation
             if self.validate_events and self.event_validator:
                 try:
@@ -4016,7 +4751,12 @@ class AgentCLI:
                     border_style="dim"
                 ))
 
-        await self.ws_client.receive_events(callback=handle_event_with_display)
+        try:
+            await self.ws_client.receive_events(callback=handle_event_with_display)
+        finally:
+            # Clean up spinner if it's still running
+            if thinking_live:
+                thinking_live.stop()
 
     def _get_event_summary(self, event: WebSocketEvent) -> str:
         """ISSUE #1603 FIX: Get a concise summary of an event for display"""
@@ -5313,6 +6053,26 @@ def main(argv=None):
         help="Disable WebSocket error diagnostics (opt-out)"
     )
 
+    # SSOT Thread Management Arguments
+    parser.add_argument(
+        "--handshake-timeout",
+        type=float,
+        default=5.0,
+        help="Timeout for handshake with backend (seconds, default: 5.0)"
+    )
+
+    parser.add_argument(
+        "--disable-backend-threads",
+        action="store_true",
+        help="SSOT: Disable backend thread ID management and use local generation (backward compatibility)"
+    )
+
+    parser.add_argument(
+        "--clear-thread-cache",
+        action="store_true",
+        help="SSOT: Clear cached thread IDs and force new thread creation"
+    )
+
     parser.add_argument(
         "--health-check",
         action="store_true",
@@ -5497,9 +6257,9 @@ def main(argv=None):
     parser.add_argument(
         "--logs-count",
         type=int,
-        default=5,
+        default=3,
         metavar="N",
-        help="Number of recent log files to collect (default: 5, must be positive)"
+        help="Number of recent log files to collect (default: 3, must be positive)"
     )
 
     parser.add_argument(
@@ -5680,7 +6440,8 @@ def main(argv=None):
         enable_websocket_diagnostics=enable_diagnostics,  # Issue #2484 Phase 2: Default enabled with opt-out
         skip_timeout_validation=args.skip_timeout_validation,  # Issue #2483: Skip timeout hierarchy validation
         json_mode=json_mode,  # ISSUE #2766: Pass json_mode to config for output suppression
-        ci_mode=ci_mode  # ISSUE #2766: Pass ci_mode to config for output suppression
+        ci_mode=ci_mode,  # ISSUE #2766: Pass ci_mode to config for output suppression
+        use_backend_threads=not args.disable_backend_threads  # SSOT: Backend thread management (enabled by default)
     )
 
     # ISSUE #2839: Load validation framework imports when validation is explicitly requested
@@ -5728,6 +6489,31 @@ def main(argv=None):
             safe_console_print("SUCCESS: Cleared cached authentication token", style="green",
                              json_mode=json_mode, ci_mode=ci_mode)
 
+    # SSOT: Clear thread cache if requested
+    if args.clear_thread_cache:
+        # Use platform-aware cache path
+        from pathlib import Path
+        import platform as stdlib_platform
+
+        system = stdlib_platform.system()
+        if system == "Windows":
+            app_data = os.environ.get('LOCALAPPDATA', str(Path.home() / "AppData" / "Local"))
+            thread_cache_file = Path(app_data) / "Netra" / "CLI" / "thread_cache.json"
+        elif system == "Darwin":
+            thread_cache_file = Path.home() / "Library" / "Application Support" / "Netra" / "CLI" / "thread_cache.json"
+        else:
+            xdg_data = os.environ.get('XDG_DATA_HOME', str(Path.home() / ".local" / "share"))
+            thread_cache_file = Path(xdg_data) / "netra" / "cli" / "thread_cache.json"
+            # Also check legacy location
+            legacy_cache = Path.home() / ".netra" / "thread_cache.json"
+            if legacy_cache.exists():
+                legacy_cache.unlink()
+
+        if thread_cache_file.exists():
+            thread_cache_file.unlink()
+            safe_console_print("SUCCESS: Cleared cached thread IDs", style="green",
+                             json_mode=json_mode, ci_mode=ci_mode)
+
     # ISSUE #2766: json_mode and ci_mode already determined at top of main()
     json_output_file = args.json_output
 
@@ -6121,6 +6907,25 @@ def main(argv=None):
                 elif args.validate_outputs and result is False:
                     # Validation failed, exit with code 1 (fallback)
                     sys.exit(1)
+            elif args.send_logs:
+                # Handle --send-logs without --message: use default message
+                # the jsonl logs are attached in payload
+                #   {
+                #    "type": "user_message",
+                #    "payload": { 
+                #           ...
+                #   *** "jsonl_logs": [... actual logs here ...] ***
+                #    }
+                #}
+
+                default_message = "claude-code optimizer default message"
+                result = await cli.run_single_message(default_message, args.wait)
+                # ISSUE #2766: Use structured exit code from ExitCodeGenerator
+                if hasattr(cli, 'exit_code'):
+                    sys.exit(cli.exit_code)
+                elif args.validate_outputs and result is False:
+                    # Validation failed, exit with code 1 (fallback)
+                    sys.exit(1)
             else:
                 await cli.run_interactive()
         except Exception as e: