Implement two-tiered Ctrl+C handling for graceful session navigation (#491)

Implements a two-tiered Ctrl+C handling mechanism for better UX:
- First Ctrl+C at prompt: Shows hint message
- Second Ctrl+C (within 2s): Returns to session menu
- Ctrl+C during module: Interrupts and returns to prompt
- Ctrl+C at session menu: Exits Pacu (unchanged)

Fixes #474

Co-authored-by: Son Sulung Suryahatta Asnan <Synchx00@users.noreply.github.com>

Author: Synchx00

pacu/main.py

@@ -155,6 +155,9 @@ def display_pacu_help():
         console/open_console                Generate a URL that will log the current user/role in to
                                               the AWS web console
         debug                               Display the contents of the error log file
+    Keyboard Shortcuts:
+        Ctrl+C                              Stop the currently running module and return to the prompt
+                                              Press twice at the prompt to return to session selection
     """)
 
 
@@ -194,15 +197,46 @@ class Main:
         'swap_keys', 'swap_session', 'unset_ua_suffix', 'update_regions', 'use', 'whoami', 'debug', 'clear'
     ]
 
+    # Time window (in seconds) for detecting double Ctrl+C
+    INTERRUPT_TIMEOUT = 2.0
+
     def __init__(self):
         # NOTE: self.database is the sqlalchemy session since 'session' is reserved for PacuSession objects.
         self.database: orm.session.Session = None
         self.running_module_names: List[str] = []
         self.CATEGORIES: set = load_categories()
 
+        # Keyboard interrupt handling state (Issue #474)
+        self._module_running: bool = False
+        self._interrupt_count: int = 0
+        self._last_interrupt_time: float = 0.0
+
         # Hack so we can use session names without passing around Main.
         lib.get_active_session = self.get_active_session
 
+    def _reset_interrupt_state(self) -> None:
+        """Reset the interrupt counter and timestamp."""
+        self._interrupt_count = 0
+        self._last_interrupt_time = 0.0
+
+    def _record_interrupt(self) -> int:
+        """
+        Record an interrupt and return the count within the timeout window.
+
+        Returns:
+            The number of interrupts within the timeout window.
+        """
+        current_time = time.time()
+
+        # Check if we're within the timeout window
+        if current_time - self._last_interrupt_time > self.INTERRUPT_TIMEOUT:
+            self._interrupt_count = 1
+        else:
+            self._interrupt_count += 1
+
+        self._last_interrupt_time = current_time
+        return self._interrupt_count
+
     # Utility methods
     def log_error(self, text, exception_info=None, session=None, local_data=None, global_data=None) -> None:
         """ Write an error to the file at log_file_path, or a default log file
@@ -1039,6 +1073,9 @@ def exec_module(self, command: List[str]) -> None:
                 return
 
             self.running_module_names.append(module.module_info['name'])
+            self._module_running = True
+            self._reset_interrupt_state()
+
             try:
                 summary_data = module.main(command[2:], self)
                 # If the module's return value is None, it exited early.
@@ -1054,11 +1091,13 @@ def exec_module(self, command: List[str]) -> None:
 
                     self.print('{} completed.\n'.format(module.module_info['name']))
                     self.print('MODULE SUMMARY:\n\n{}\n'.format(summary.strip('\n')))
+
             except SystemExit as exception_value:
                 exception_type, _, tb = sys.exc_info()
 
                 if 'SIGINT called' in exception_value.args:
-                    self.print('^C\nExiting the currently running module.')
+                    # Handle Ctrl+C during module execution (Issue #474)
+                    self.print('\n[!] Module {} interrupted by user (Ctrl+C). Returning to Pacu prompt...'.format(module.module_info['name']))
                 else:
                     traceback_text = '\nTraceback (most recent call last):\n{}{}: {}\n\n'.format(
                         ''.join(traceback.format_tb(tb)), str(exception_type), str(exception_value)
@@ -1072,6 +1111,7 @@ def exec_module(self, command: List[str]) -> None:
                         global_data=global_data
                     )
             finally:
+                self._module_running = False
                 self.running_module_names.pop()
         elif module_name in self.COMMANDS:
             print('Error: "{}" is the name of a Pacu command, not a module. Try using it without "run" or "exec" in front.'.format(module_name))
@@ -1739,21 +1779,52 @@ def complete(completer, text, state):
             pass
 
     def exit(self) -> None:
-        sys.exit('SIGINT called')
-
-    def idle(self) -> None:
+        sys.exit('Pacu exit')
+
+    def idle(self) -> bool:
+        """
+        The main command input loop.
+        Returns:
+            True if should return to session selection menu
+            False if should exit Pacu entirely
+        """
         session = self.get_active_session()
 
-        if session.key_alias:
-            alias = session.key_alias
-        else:
-            alias = 'No Keys Set'
+        while True:
+            try:
+                if session.key_alias:
+                    alias = session.key_alias
+                else:
+                    alias = 'No Keys Set'
 
-        command = input('Pacu ({}:{}) > '.format(session.name, alias))
+                command = input('Pacu ({}:{}) > '.format(session.name, alias))
+                self.parse_command(command)
+
+                # Reset interrupt state only AFTER successful command
+                self._reset_interrupt_state()
+
+            except (KeyboardInterrupt, SystemExit) as e:
+                # Handle Ctrl+C at the prompt (Issue #474)
+                if isinstance(e, SystemExit):
+                    # 'Pacu exit' = exit command, 'SIGINT called' = Ctrl+C
+                    if e.args and 'SIGINT called' in str(e.args):
+                        # This is Ctrl+C, handle as interrupt
+                        pass
+                    else:
+                        # This is exit command or other SystemExit, re-raise
+                        raise
 
-        self.parse_command(command)
+                interrupt_count = self._record_interrupt()
+                if interrupt_count >= 2:
+                    print('\n[*] Returning to session selection menu...')
+                    return True
+                else:
+                    print('\n[*] Press Ctrl+C again within 2 seconds to return to session menu.')
+                    continue
 
-        self.idle()
+            except EOFError:
+                print('\n[*] EOF detected. Returning to session selection...')
+                return True
 
     def run_cli(self, *args) -> None:
         self.database = get_database_connection(settings.DATABASE_CONNECTION_PATH)
@@ -1897,13 +1968,20 @@ def run_gui(self, quiet=False) -> None:
                     idle_ready = True
 
                 self.check_user_agent()
-                self.idle()
+
+                # Session command loop with interrupt handling (Issue #474)
+                should_return_to_session_menu = self.idle()
+
+                if should_return_to_session_menu:
+                    # User pressed Ctrl+C twice, go back to session selection
+                    idle_ready = False
+                    continue
 
             except (Exception, SystemExit) as exception_value:
                 exception_type, _, tb = sys.exc_info()
 
                 if exception_type == SystemExit:
-                    if 'SIGINT called' in exception_value.args:
+                    if 'SIGINT called' in exception_value.args or 'Pacu exit' in exception_value.args:
                         print('\nBye!')
                         return
                     else: