shotgun-sh 0.2.11.dev3__py3-none-any.whl → 0.2.19__py3-none-any.whl

shotgun/sentry_telemetry.py

@@ -1,5 +1,8 @@
 """Sentry observability setup for Shotgun."""
 
+from pathlib import Path
+from typing import Any
+
 from shotgun import __version__
 from shotgun.logging_config import get_early_logger
 from shotgun.settings import settings
@@ -8,6 +11,122 @@ from shotgun.settings import settings
 logger = get_early_logger(__name__)
 
 
+def _scrub_path(path: str) -> str:
+    """Scrub sensitive information from file paths.
+
+    Removes home directory and current working directory prefixes to prevent
+    leaking usernames that might be part of the path.
+
+    Args:
+        path: The file path to scrub
+
+    Returns:
+        The scrubbed path with sensitive prefixes removed
+    """
+    if not path:
+        return path
+
+    try:
+        # Get home and cwd as Path objects for comparison
+        home = Path.home()
+        cwd = Path.cwd()
+
+        # Convert path to Path object
+        path_obj = Path(path)
+
+        # Try to make path relative to cwd first (most common case)
+        try:
+            relative_to_cwd = path_obj.relative_to(cwd)
+            return str(relative_to_cwd)
+        except ValueError:
+            pass
+
+        # Try to replace home directory with ~
+        try:
+            relative_to_home = path_obj.relative_to(home)
+            return f"~/{relative_to_home}"
+        except ValueError:
+            pass
+
+        # If path is absolute but not under cwd or home, just return filename
+        if path_obj.is_absolute():
+            return path_obj.name
+
+        # Return as-is if already relative
+        return path
+
+    except Exception:
+        # If anything goes wrong, return the original path
+        # Better to leak a path than break error reporting
+        return path
+
+
+def _scrub_sensitive_paths(event: dict[str, Any]) -> None:
+    """Scrub sensitive paths from Sentry event data.
+
+    Modifies the event in-place to remove:
+    - Home directory paths (might contain usernames)
+    - Current working directory paths (might contain usernames)
+    - Server name/hostname
+    - Paths in sys.argv
+
+    Args:
+        event: The Sentry event dictionary to scrub
+    """
+    extra = event.get("extra", {})
+    if "sys.argv" in extra:
+        argv = extra["sys.argv"]
+        if isinstance(argv, list):
+            extra["sys.argv"] = [
+                _scrub_path(arg) if isinstance(arg, str) else arg for arg in argv
+            ]
+
+    # Scrub server name if present
+    if "server_name" in event:
+        event["server_name"] = ""
+
+    # Scrub contexts that might contain paths
+    if "contexts" in event:
+        contexts = event["contexts"]
+        # Remove runtime context if it has CWD
+        if "runtime" in contexts:
+            if "cwd" in contexts["runtime"]:
+                del contexts["runtime"]["cwd"]
+            # Scrub sys.argv to remove paths
+            if "sys.argv" in contexts["runtime"]:
+                argv = contexts["runtime"]["sys.argv"]
+                if isinstance(argv, list):
+                    contexts["runtime"]["sys.argv"] = [
+                        _scrub_path(arg) if isinstance(arg, str) else arg
+                        for arg in argv
+                    ]
+
+    # Scrub exception stack traces
+    if "exception" in event and "values" in event["exception"]:
+        for exception in event["exception"]["values"]:
+            if "stacktrace" in exception and "frames" in exception["stacktrace"]:
+                for frame in exception["stacktrace"]["frames"]:
+                    # Scrub file paths
+                    if "abs_path" in frame:
+                        frame["abs_path"] = _scrub_path(frame["abs_path"])
+                    if "filename" in frame:
+                        frame["filename"] = _scrub_path(frame["filename"])
+
+                    # Scrub local variables that might contain paths
+                    if "vars" in frame:
+                        for var_name, var_value in frame["vars"].items():
+                            if isinstance(var_value, str):
+                                frame["vars"][var_name] = _scrub_path(var_value)
+
+    # Scrub breadcrumbs that might contain paths
+    if "breadcrumbs" in event and "values" in event["breadcrumbs"]:
+        for breadcrumb in event["breadcrumbs"]["values"]:
+            if "data" in breadcrumb:
+                for key, value in breadcrumb["data"].items():
+                    if isinstance(value, str):
+                        breadcrumb["data"][key] = _scrub_path(value)
+
+
 def setup_sentry_observability() -> bool:
     """Set up Sentry observability for error tracking.
 
@@ -32,20 +151,57 @@ def setup_sentry_observability() -> bool:
         logger.debug("Using Sentry DSN from settings, proceeding with setup")
 
         # Determine environment based on version
-        # Dev versions contain "dev", "rc", "alpha", or "beta"
+        # Dev versions contain "dev", "rc", "alpha", "beta"
         if any(marker in __version__ for marker in ["dev", "rc", "alpha", "beta"]):
             environment = "development"
         else:
             environment = "production"
 
+        def before_send(event: Any, hint: dict[str, Any]) -> Any:
+            """Filter out user-actionable errors and scrub sensitive paths.
+
+            User-actionable errors (like context size limits) are expected conditions
+            that users need to resolve, not bugs that need tracking.
+
+            Also scrubs sensitive information like usernames from file paths and
+            working directories to protect user privacy.
+            """
+
+            log_record = hint.get("log_record")
+            if log_record:
+                # Scrub pathname using the helper function
+                log_record.pathname = _scrub_path(log_record.pathname)
+
+                # Scrub traceback text if it exists
+                if hasattr(log_record, "exc_text") and isinstance(
+                    log_record.exc_text, str
+                ):
+                    # Replace home directory in traceback text
+                    home = Path.home()
+                    log_record.exc_text = log_record.exc_text.replace(str(home), "~")
+
+            if "exc_info" in hint:
+                _, exc_value, _ = hint["exc_info"]
+                from shotgun.exceptions import ErrorNotPickedUpBySentry
+
+                if isinstance(exc_value, ErrorNotPickedUpBySentry):
+                    # Don't send to Sentry - this is user-actionable, not a bug
+                    return None
+
+            # Scrub sensitive paths from the event
+            _scrub_sensitive_paths(event)
+            return event
+
         # Initialize Sentry
         sentry_sdk.init(
             dsn=dsn,
             release=f"shotgun-sh@{__version__}",
             environment=environment,
             send_default_pii=False,  # Privacy-first: never send PII
+            server_name="",  # Privacy: don't send hostname (may contain username)
             traces_sample_rate=0.1 if environment == "production" else 1.0,
             profiles_sample_rate=0.1 if environment == "production" else 1.0,
+            before_send=before_send,
         )
 
         # Set user context with anonymous shotgun instance ID from config

shotgun/settings.py

@@ -108,6 +108,11 @@ class LoggingSettings(BaseSettings):
         default=True,
         description="Enable file logging output",
     )
+    max_log_files: int = Field(
+        default=10,
+        description="Maximum number of log files to keep (older files are deleted)",
+        ge=1,
+    )
 
     model_config = SettingsConfigDict(
         env_prefix="SHOTGUN_",

shotgun/tui/app.py

@@ -6,7 +6,10 @@ from textual.binding import Binding
 from textual.screen import Screen
 
 from shotgun.agents.agent_manager import AgentManager
-from shotgun.agents.config import ConfigManager, get_config_manager
+from shotgun.agents.config import (
+    ConfigManager,
+    get_config_manager,
+)
 from shotgun.agents.models import AgentType
 from shotgun.logging_config import get_logger
 from shotgun.tui.containers import TUIContainer
@@ -19,7 +22,7 @@ from shotgun.utils.update_checker import (
 
 from .screens.chat import ChatScreen
 from .screens.directory_setup import DirectorySetupScreen
-from .screens.feedback import FeedbackScreen
+from .screens.github_issue import GitHubIssueScreen
 from .screens.model_picker import ModelPickerScreen
 from .screens.pipx_migration import PipxMigrationScreen
 from .screens.provider_config import ProviderConfigScreen
@@ -35,7 +38,7 @@ class ShotgunApp(App[None]):
         "provider_config": ProviderConfigScreen,
         "model_picker": ModelPickerScreen,
         "directory_setup": DirectorySetupScreen,
-        "feedback": FeedbackScreen,
+        "github_issue": GitHubIssueScreen,
     }
     BINDINGS = [
         Binding("ctrl+c", "quit", "Quit the app"),
@@ -99,7 +102,10 @@ class ShotgunApp(App[None]):
         # Run async config loading in worker
         async def _check_config() -> None:
             # Show welcome screen if no providers are configured OR if user hasn't seen it yet
+            # Note: If config migration fails, ConfigManager will auto-create fresh config
+            # and set migration_failed flag, which WelcomeScreen will display
             config = await self.config_manager.load()
+
             has_any_key = await self.config_manager.has_any_provider_key()
             if not has_any_key or not config.shown_welcome_screen:
                 if isinstance(self.screen, WelcomeScreen):
@@ -181,20 +187,15 @@ class ShotgunApp(App[None]):
     def get_system_commands(self, screen: Screen[Any]) -> Iterable[SystemCommand]:
         return [
             SystemCommand(
-                "Feedback", "Send us feedback or report a bug", self.action_feedback
+                "New Issue",
+                "Report a bug or request a feature on GitHub",
+                self.action_new_issue,
             )
-        ]  # we don't want any system commands
-
-    def action_feedback(self) -> None:
-        """Open feedback screen and submit feedback."""
-        from shotgun.posthog_telemetry import Feedback, submit_feedback_survey
-
-        def handle_feedback(feedback: Feedback | None) -> None:
-            if feedback is not None:
-                submit_feedback_survey(feedback)
-                self.notify("Feedback sent. Thank you!")
+        ]
 
-        self.push_screen(FeedbackScreen(), callback=handle_feedback)
+    def action_new_issue(self) -> None:
+        """Open GitHub issue screen to guide users to create an issue."""
+        self.push_screen(GitHubIssueScreen())
 
 
 def run(

shotgun/tui/screens/chat/chat_screen.py

@@ -2,6 +2,8 @@
 
 import asyncio
 import logging
+import time
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import cast
 
@@ -10,6 +12,7 @@ from pydantic_ai.messages import (
     ModelRequest,
     ModelResponse,
     TextPart,
+    ToolCallPart,
     ToolReturnPart,
     UserPromptPart,
 )
@@ -31,6 +34,7 @@ from shotgun.agents.agent_manager import (
     ModelConfigUpdated,
     PartialResponseMessage,
 )
+from shotgun.agents.config import get_config_manager
 from shotgun.agents.config.models import MODEL_SPECS
 from shotgun.agents.conversation_manager import ConversationManager
 from shotgun.agents.history.compaction import apply_persistent_compaction
@@ -45,6 +49,7 @@ from shotgun.codebase.core.manager import (
     CodebaseGraphManager,
 )
 from shotgun.codebase.models import IndexProgress, ProgressPhase
+from shotgun.exceptions import ContextSizeLimitExceeded
 from shotgun.posthog_telemetry import track_event
 from shotgun.sdk.codebase import CodebaseSDK
 from shotgun.sdk.exceptions import CodebaseNotFoundError, InvalidPathError
@@ -70,6 +75,7 @@ from shotgun.tui.screens.chat_screen.command_providers import (
 from shotgun.tui.screens.chat_screen.hint_message import HintMessage
 from shotgun.tui.screens.chat_screen.history import ChatHistory
 from shotgun.tui.screens.confirmation_dialog import ConfirmationDialog
+from shotgun.tui.screens.onboarding import OnboardingModal
 from shotgun.tui.services.conversation_service import ConversationService
 from shotgun.tui.state.processing_state import ProcessingStateManager
 from shotgun.tui.utils.mode_progress import PlaceholderHints
@@ -98,7 +104,6 @@ class ChatScreen(Screen[None]):
     history: PromptHistory = PromptHistory()
     messages = reactive(list[ModelMessage | HintMessage]())
     indexing_job: reactive[CodebaseIndexSelection | None] = reactive(None)
-    partial_message: reactive[ModelMessage | None] = reactive(None)
 
     # Q&A mode state (for structured output clarifying questions)
     qa_mode = reactive(False)
@@ -109,6 +114,10 @@ class ChatScreen(Screen[None]):
     # Working state - keep reactive for Textual watchers
     working = reactive(False)
 
+    # Throttle context indicator updates (in seconds)
+    _last_context_update: float = 0.0
+    _context_update_throttle: float = 5.0  # 5 seconds
+
     def __init__(
         self,
         agent_manager: AgentManager,
@@ -166,13 +175,17 @@ class ChatScreen(Screen[None]):
         self.processing_state.bind_spinner(self.query_one("#spinner", Spinner))
 
         # Load conversation history if --continue flag was provided
-        if self.continue_session and self.conversation_manager.exists():
-            self._load_conversation()
+        # Use call_later to handle async exists() check
+        if self.continue_session:
+            self.call_later(self._check_and_load_conversation)
 
         self.call_later(self.check_if_codebase_is_indexed)
         # Initial update of context indicator
         self.update_context_indicator()
 
+        # Show onboarding popup if not shown before
+        self.call_later(self._check_and_show_onboarding)
+
     async def on_key(self, event: events.Key) -> None:
         """Handle key presses for cancellation."""
         # If escape is pressed during Q&A mode, exit Q&A
@@ -271,10 +284,8 @@ class ChatScreen(Screen[None]):
     def action_toggle_mode(self) -> None:
         # Prevent mode switching during Q&A
         if self.qa_mode:
-            self.notify(
-                "Cannot switch modes while answering questions",
-                severity="warning",
-                timeout=3,
+            self.agent_manager.add_hint_message(
+                HintMessage(message="⚠️ Cannot switch modes while answering questions")
             )
             return
 
@@ -296,14 +307,22 @@ class ChatScreen(Screen[None]):
         if usage_hint:
             self.mount_hint(usage_hint)
         else:
-            self.notify("No usage hint available", severity="error")
+            self.agent_manager.add_hint_message(
+                HintMessage(message="⚠️ No usage hint available")
+            )
 
     async def action_show_context(self) -> None:
         context_hint = await self.agent_manager.get_context_hint()
         if context_hint:
             self.mount_hint(context_hint)
         else:
-            self.notify("No context analysis available", severity="error")
+            self.agent_manager.add_hint_message(
+                HintMessage(message="⚠️ No context analysis available")
+            )
+
+    def action_view_onboarding(self) -> None:
+        """Show the onboarding modal."""
+        self.app.push_screen(OnboardingModal())
 
     @work
     async def action_compact_conversation(self) -> None:
@@ -424,7 +443,9 @@ class ChatScreen(Screen[None]):
 
         except Exception as e:
             logger.error(f"Failed to compact conversation: {e}", exc_info=True)
-            self.notify(f"Failed to compact: {e}", severity="error")
+            self.agent_manager.add_hint_message(
+                HintMessage(message=f"❌ Failed to compact: {e}")
+            )
         finally:
             # Hide spinner
             self.processing_state.stop_processing()
@@ -456,7 +477,7 @@ class ChatScreen(Screen[None]):
             self.agent_manager.ui_message_history = []
 
             # Use conversation service to clear conversation
-            self.conversation_service.clear_conversation()
+            await self.conversation_service.clear_conversation()
 
             # Post message history updated event to refresh UI
             self.agent_manager.post_message(
@@ -472,7 +493,9 @@ class ChatScreen(Screen[None]):
 
         except Exception as e:
             logger.error(f"Failed to clear conversation: {e}", exc_info=True)
-            self.notify(f"Failed to clear: {e}", severity="error")
+            self.agent_manager.add_hint_message(
+                HintMessage(message=f"❌ Failed to clear: {e}")
+            )
 
     @work(exclusive=False)
     async def update_context_indicator(self) -> None:
@@ -561,8 +584,6 @@ class ChatScreen(Screen[None]):
 
     @on(PartialResponseMessage)
     def handle_partial_response(self, event: PartialResponseMessage) -> None:
-        self.partial_message = event.message
-
         # Filter event.messages to exclude ModelRequest with only ToolReturnPart
         # These are intermediate tool results that would render as empty (UserQuestionWidget
         # filters out ToolReturnPart in format_prompt_parts), causing user messages to disappear
@@ -586,16 +607,33 @@ class ChatScreen(Screen[None]):
         )
 
         # Use widget coordinator to set partial response
-        self.widget_coordinator.set_partial_response(
-            self.partial_message, new_message_list
+        self.widget_coordinator.set_partial_response(event.message, new_message_list)
+
+        # Skip context updates for file write operations (they don't add to input context)
+        has_file_write = any(
+            isinstance(msg, ModelResponse)
+            and any(
+                isinstance(part, ToolCallPart)
+                and part.tool_name in ("write_file", "append_file")
+                for part in msg.parts
+            )
+            for msg in event.messages
         )
 
-        # Update context indicator with full message history including streaming messages
-        # Combine existing agent history with new streaming messages for accurate token count
-        combined_agent_history = self.agent_manager.message_history + event.messages
-        self.update_context_indicator_with_messages(
-            combined_agent_history, new_message_list
-        )
+        if has_file_write:
+            return  # Skip context update for file writes
+
+        # Throttle context indicator updates to improve performance during streaming
+        # Only update at most once per 5 seconds to avoid excessive token calculations
+        current_time = time.time()
+        if current_time - self._last_context_update >= self._context_update_throttle:
+            self._last_context_update = current_time
+            # Update context indicator with full message history including streaming messages
+            # Combine existing agent history with new streaming messages for accurate token count
+            combined_agent_history = self.agent_manager.message_history + event.messages
+            self.update_context_indicator_with_messages(
+                combined_agent_history, new_message_list
+            )
 
     def _clear_partial_response(self) -> None:
         # Use widget coordinator to clear partial response
@@ -655,32 +693,42 @@ class ChatScreen(Screen[None]):
         self.update_context_indicator()
 
         # If there are file operations, add a message showing the modified files
+        # Skip if hint was already added by agent_manager (e.g., in QA mode)
         if event.file_operations:
-            chat_history = self.query_one(ChatHistory)
-            if chat_history.vertical_tail:
-                tracker = FileOperationTracker(operations=event.file_operations)
-                display_path = tracker.get_display_path()
-
-                if display_path:
-                    # Create a simple markdown message with the file path
-                    # The terminal emulator will make this clickable automatically
-                    path_obj = Path(display_path)
-
-                    if len(event.file_operations) == 1:
-                        message = f"📝 Modified: `{display_path}`"
-                    else:
-                        num_files = len({op.file_path for op in event.file_operations})
-                        if path_obj.is_dir():
-                            message = (
-                                f"📁 Modified {num_files} files in: `{display_path}`"
-                            )
+            # Check if file operation hint already exists in recent messages
+            file_hint_exists = any(
+                isinstance(msg, HintMessage)
+                and (
+                    msg.message.startswith("📝 Modified:")
+                    or msg.message.startswith("📁 Modified")
+                )
+                for msg in event.messages[-5:]  # Check last 5 messages
+            )
+
+            if not file_hint_exists:
+                chat_history = self.query_one(ChatHistory)
+                if chat_history.vertical_tail:
+                    tracker = FileOperationTracker(operations=event.file_operations)
+                    display_path = tracker.get_display_path()
+
+                    if display_path:
+                        # Create a simple markdown message with the file path
+                        # The terminal emulator will make this clickable automatically
+                        path_obj = Path(display_path)
+
+                        if len(event.file_operations) == 1:
+                            message = f"📝 Modified: `{display_path}`"
                         else:
-                            # Common path is a file, show parent directory
-                            message = (
-                                f"📁 Modified {num_files} files in: `{path_obj.parent}`"
+                            num_files = len(
+                                {op.file_path for op in event.file_operations}
                             )
+                            if path_obj.is_dir():
+                                message = f"📁 Modified {num_files} files in: `{display_path}`"
+                            else:
+                                # Common path is a file, show parent directory
+                                message = f"📁 Modified {num_files} files in: `{path_obj.parent}`"
 
-                    self.mount_hint(message)
+                        self.mount_hint(message)
 
                     # Check and display any marketing messages
                     from shotgun.tui.app import ShotgunApp
@@ -897,11 +945,15 @@ class ChatScreen(Screen[None]):
     async def delete_codebase(self, graph_id: str) -> None:
         try:
             await self.codebase_sdk.delete_codebase(graph_id)
-            self.notify(f"Deleted codebase: {graph_id}", severity="information")
+            self.agent_manager.add_hint_message(
+                HintMessage(message=f"✓ Deleted codebase: {graph_id}")
+            )
         except CodebaseNotFoundError as exc:
-            self.notify(str(exc), severity="error")
+            self.agent_manager.add_hint_message(HintMessage(message=f"❌ {exc}"))
         except Exception as exc:  # pragma: no cover - defensive UI path
-            self.notify(f"Failed to delete codebase: {exc}", severity="error")
+            self.agent_manager.add_hint_message(
+                HintMessage(message=f"❌ Failed to delete codebase: {exc}")
+            )
 
     def _is_kuzu_corruption_error(self, exception: Exception) -> bool:
         """Check if error is related to kuzu database corruption.
@@ -1008,9 +1060,10 @@ class ChatScreen(Screen[None]):
                     )
                     cleaned = await manager.cleanup_corrupted_databases()
                     logger.info(f"Cleaned up {len(cleaned)} corrupted database(s)")
-                    self.notify(
-                        f"Retrying indexing after cleanup (attempt {attempt + 1}/{max_retries})...",
-                        severity="information",
+                    self.agent_manager.add_hint_message(
+                        HintMessage(
+                            message=f"🔄 Retrying indexing after cleanup (attempt {attempt + 1}/{max_retries})..."
+                        )
                     )
 
                 # Pass the current working directory as the indexed_from_cwd
@@ -1038,22 +1091,22 @@ class ChatScreen(Screen[None]):
                 logger.info(
                     f"Successfully indexed codebase '{result.name}' (ID: {result.graph_id})"
                 )
-                self.notify(
-                    f"Indexed codebase '{result.name}' (ID: {result.graph_id})",
-                    severity="information",
-                    timeout=8,
+                self.agent_manager.add_hint_message(
+                    HintMessage(
+                        message=f"✓ Indexed codebase '{result.name}' (ID: {result.graph_id})"
+                    )
                 )
                 break  # Success - exit retry loop
 
             except CodebaseAlreadyIndexedError as exc:
                 progress_timer.stop()
                 logger.warning(f"Codebase already indexed: {exc}")
-                self.notify(str(exc), severity="warning")
+                self.agent_manager.add_hint_message(HintMessage(message=f"⚠️ {exc}"))
                 return
             except InvalidPathError as exc:
                 progress_timer.stop()
                 logger.error(f"Invalid path error: {exc}")
-                self.notify(str(exc), severity="error")
+                self.agent_manager.add_hint_message(HintMessage(message=f"❌ {exc}"))
                 return
 
             except Exception as exc:  # pragma: no cover - defensive UI path
@@ -1072,10 +1125,10 @@ class ChatScreen(Screen[None]):
                     f"Failed to index codebase after {attempt + 1} attempts - "
                     f"repo_path: {selection.repo_path}, name: {selection.name}, error: {exc}"
                 )
-                self.notify(
-                    f"Failed to index codebase after {attempt + 1} attempts: {exc}",
-                    severity="error",
-                    timeout=30,  # Keep error visible for 30 seconds
+                self.agent_manager.add_hint_message(
+                    HintMessage(
+                        message=f"❌ Failed to index codebase after {attempt + 1} attempts: {exc}"
+                    )
                 )
                 break
 
@@ -1106,6 +1159,27 @@ class ChatScreen(Screen[None]):
         except asyncio.CancelledError:
             # Handle cancellation gracefully - DO NOT re-raise
             self.mount_hint("⚠️ Operation cancelled by user")
+        except ContextSizeLimitExceeded as e:
+            # User-friendly error with actionable options
+            hint = (
+                f"⚠️ **Context too large for {e.model_name}**\n\n"
+                f"Your conversation history exceeds this model's limit ({e.max_tokens:,} tokens).\n\n"
+                f"**Choose an action:**\n\n"
+                f"1. Switch to a larger model (`Ctrl+P` → Change Model)\n"
+                f"2. Switch to a larger model, compact (`/compact`), then switch back to {e.model_name}\n"
+                f"3. Clear conversation (`/clear`)\n"
+            )
+
+            self.mount_hint(hint)
+
+            # Log for debugging (won't send to Sentry due to ErrorNotPickedUpBySentry)
+            logger.info(
+                "Context size limit exceeded",
+                extra={
+                    "max_tokens": e.max_tokens,
+                    "model_name": e.model_name,
+                },
+            )
         except Exception as e:
             # Log with full stack trace to shotgun.log
             logger.exception(
@@ -1143,11 +1217,17 @@ class ChatScreen(Screen[None]):
     def _save_conversation(self) -> None:
         """Save the current conversation to persistent storage."""
         # Use conversation service for saving (run async in background)
+        # Use exclusive=True to prevent concurrent saves that can cause file contention
         self.run_worker(
             self.conversation_service.save_conversation(self.agent_manager),
-            exclusive=False,
+            exclusive=True,
         )
 
+    async def _check_and_load_conversation(self) -> None:
+        """Check if conversation exists and load it if it does."""
+        if await self.conversation_manager.exists():
+            self._load_conversation()
+
     def _load_conversation(self) -> None:
         """Load conversation from persistent storage."""
 
@@ -1168,3 +1248,18 @@ class ChatScreen(Screen[None]):
                 self.mode = restored_type
 
         self.run_worker(_do_load(), exclusive=False)
+
+    @work
+    async def _check_and_show_onboarding(self) -> None:
+        """Check if onboarding should be shown and display modal if needed."""
+        config_manager = get_config_manager()
+        config = await config_manager.load()
+
+        # Only show onboarding if it hasn't been shown before
+        if config.shown_onboarding_popup is None:
+            # Show the onboarding modal
+            await self.app.push_screen_wait(OnboardingModal())
+
+            # Mark as shown in config with current timestamp
+            config.shown_onboarding_popup = datetime.now(timezone.utc)
+            await config_manager.save(config)