feat: implement background cleanup for orphaned attachments

Provides an automated way to manage storage by removing attachment directories associated with deleted or missing sessions.

- Initialize a background thread on startup to prune orphaned attachments.
- Update `AttachmentManager.cleanup_orphaned_attachments` with CPU yielding and a startup delay to minimize impact on performance.
- Implement a 60-second age threshold safety check to prevent race conditions during new session creation.
- Add logic to track removed session IDs in `session_manager.py` to facilitate cleanup.

Author: zaxx-q

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [4.3.2] - 2026-02-15
+
+### Improvements
+
+- **Attachments**: Implemented a background cleanup process to automatically remove orphaned attachment directories from deleted or missing sessions.
+
+### Fixes
+
+- **Console**: Bugfixes and adjustments to make console work reliably.
+
 ## [4.3.1] - 2026-02-14
 
 ### Fixes

main.py

@@ -29,6 +29,7 @@
 from src.version import __version__
 from src.key_manager import KeyManager
 from src.session_manager import load_sessions, list_sessions
+from src.attachment_manager import AttachmentManager
 from src.terminal import terminal_session_manager, print_commands_box
 from src.gui.core import HAVE_GUI, show_settings_window_blocking
 from src import web_server
@@ -178,6 +179,11 @@ def initialize():
     # ─── Sessions ─────────────────────────────────────────────────────────
     load_sessions()
     sessions = list_sessions()
+    
+    # Cleanup orphaned attachments from deleted sessions
+    # (Runs in background to avoid slowing down startup)
+    threading.Thread(target=AttachmentManager.cleanup_orphaned_attachments, daemon=True).start()
+
     if HAVE_RICH:
         console.print(f"[bold]📂 Sessions[/bold]  {len(sessions)} loaded")
         console.print()

src/attachment_manager.py

@@ -508,28 +508,67 @@ def cleanup_orphaned_attachments(cls) -> int:
         Compares attachment directories against existing sessions and
         removes any orphaned directories.
         
+        Built with CPU usage optimization:
+        - Checks file age before deleting (skips very new files to avoid race conditions)
+        - Yields CPU during heavy deletion operations
+        - Runs once and exits (designed for background thread usage)
+        
         Returns:
             Number of orphaned directories removed
         """
         attachments_path = Path(ATTACHMENTS_DIR)
         if not attachments_path.exists():
             return 0
+            
+        # Startup delay to ensure session manager is fully loaded and stable
+        # and to degrade priority effectively
+        time.sleep(2.0)
 
         removed = 0
 
         try:
             # Get existing session IDs
             from .session_manager import CHAT_SESSIONS
+            
+            # Create a localized set of valid IDs to minimize lock contention
+            # We assume session deletions during this millisecond window are acceptable handling edge cases
             existing_ids = set(str(sid) for sid in CHAT_SESSIONS.keys())
 
-            # Check each attachment directory
+            # Iterate through directories
             for item in attachments_path.iterdir():
-                if item.is_dir() and item.name not in existing_ids:
+                # Yield CPU between directory checks to keep background usage low
+                time.sleep(0.05)
+                
+                if item.is_dir():
+                    # Check if folder name is numeric (session ID)
+                    # We only manage numeric session IDs
+                    if not item.name.isdigit():
+                        continue
+                        
+                    # Skip if session exists
+                    if item.name in existing_ids:
+                        continue
+                        
+                    # SAFETY CHECK: Only delete folders older than 60 seconds
+                    # This prevents deleting attachments for a session that is currently being created
+                    # (where the folder might exist before it's registered in CHAT_SESSIONS)
+                    try:
+                        stat = item.stat()
+                        if time.time() - stat.st_mtime < 60:
+                            continue
+                    except OSError:
+                        pass
+                        
+                    # Force delete orphaned folder
                     try:
                         with _FILE_LOCK:
                             shutil.rmtree(item)
                         logging.info(f"[AttachmentManager] Removed orphaned: {item.name}")
                         removed += 1
+                        
+                        # Longer sleep after actual deletion work as it's I/O heavy
+                        time.sleep(0.2)
+                        
                     except Exception as e:
                         logging.warning(f"[AttachmentManager] Failed to remove {item.name}: {e}")
 

src/session_manager.py

@@ -214,13 +214,41 @@ def load_sessions():
 
 def add_session(session, max_sessions=50):
     """Add a session and manage max limit"""
+    removed_ids = []
     with SESSION_LOCK:
         while len(CHAT_SESSIONS) >= max_sessions:
             oldest_id = next(iter(CHAT_SESSIONS))
             del CHAT_SESSIONS[oldest_id]
+            removed_ids.append(oldest_id)
         CHAT_SESSIONS[session.session_id] = session
+    
     threading.Thread(target=save_sessions, daemon=True).start()
 
+    # Cleanup attachments for removed sessions
+    # (Only runs if items were actually removed)
+    if removed_ids:
+        def cleanup():
+            import time
+            from .attachment_manager import delete_session_attachments
+            
+            # Initial delay to let the main operation finish
+            time.sleep(2.0)
+            
+            for sid in removed_ids:
+                try:
+                    # Clean up attachments - handle string/int IDs
+                    numeric_id = int(sid) if isinstance(sid, str) and sid.isdigit() else sid
+                    if isinstance(numeric_id, int):
+                        delete_session_attachments(numeric_id)
+                        # Yield CPU after each deletion
+                        time.sleep(0.1)
+                except Exception as e:
+                    print(f"[Warning] Failed to cleanup session {sid}: {e}")
+        
+        # Start cleanup in background
+        t = threading.Thread(target=cleanup, daemon=True)
+        t.start()
+
 
 def get_session(session_id):
     """Get a session by ID (handles both string and int IDs)"""