feat: add desktop notifications for task interactions and status updates

- Introduced `notify-rust` dependency for desktop notifications.
- Updated configuration to include `desktop_notifications` option.
- Implemented `NotificationManager` for handling various notifications:
  - Interactive input detection
  - Task timeout alerts
  - Task failure notifications
  - Sudo password prompts
  - Completion notifications for all tasks
- Enhanced `TaskExecutor` to utilize notifications during task execution.
- Updated README and example configuration to reflect new notification features.

Author: BreathCodeFlow

Cargo.lock

@@ -26,3 +26,4 @@ tokio = { version = "1.47.1", features = ["full"] }
 futures = "0.3.31"
 chrono = "0.4.42"
 reqwest = { version = "0.12.24", features = ["blocking"] }
+notify-rust = "4.11.3"

Cargo.toml

@@ -10,10 +10,36 @@ show_progress = true           # Show progress bars for tasks
 parallel_execution = false     # Enable parallel execution globally
 parallel_limit = 4             # Max number of parallel tasks
 skip_optional_on_error = false # Skip optional tasks if a required task fails
-keychain_label = "tide-sudo"   # For storing sudo password in keychain
+keychain_label = "tide-sudo"   # For storing sudo password in keychain (macOS Keychain)
 use_colors = true              # Enable colored output
 verbose = false                # Show detailed output
 log_file = ""                  # Optional: Path to log file
+desktop_notifications = true   # Enable macOS desktop notifications
+
+# ============================================================================
+# IMPORTANT: Timeout and Sudo Configuration
+# ============================================================================
+# 
+# All tasks have a default timeout of 300 seconds (5 minutes) to prevent
+# hanging on password prompts or other interactive input. 
+#
+# If a command needs sudo, SET "sudo = true" in the task config!
+# This prevents the command from hanging on password prompts.
+#
+# Example of a command that would hang WITHOUT proper configuration:
+#   command = ["some-script.sh"]  # internally calls sudo
+#   # This would HANG! Solution: set "sudo = true"
+#
+# Stdin is automatically redirected to /dev/null for all non-sudo commands
+# to prevent blocking on interactive input.
+#
+# Desktop Notifications (desktop_notifications):
+# When enabled, Tide will send macOS notifications for:
+# - Tasks waiting for interactive input (detected via timeout)
+# - Sudo password required (check your terminal!)
+# - Task failures (required tasks only)
+# - All tasks completed successfully
+# ============================================================================
 
 # ============================================================================
 # SYSTEM & CORE UPDATES

example-full-config.toml

@@ -40,6 +40,14 @@ Tide coordinates macOS software updates, Homebrew cleanups, and any custom shell
 - Optional fail-fast behaviour that halts optional work after a required task fails.
 - Verbose logging for debugging plus quiet mode for automation owners.
 
+### Desktop Notifications 🔔
+
+- **Interactive Input Detection** – Get notified when a task appears to be waiting for input (timeout detected).
+- **Sudo Password Required** – Desktop alert when sudo authentication is needed (check your terminal!).
+- **Task Failures** – Instant notification when required tasks fail with error preview.
+- **Completion Summary** – Success notification when all tasks complete successfully.
+- **Configurable** – Can be disabled via `desktop_notifications = false` in config or `--quiet` flag.
+
 ## Requirements
 
 - macOS (tested on Apple Silicon; Intel should work as long as the commands you call are available).
@@ -102,6 +110,7 @@ skip_optional_on_error = false
 keychain_label = "tide-sudo"
 verbose = false
 log_file = ""                  # Optional: capture command output
+desktop_notifications = true   # Enable macOS desktop notifications
 
 [[groups]]
 name = "System Updates"
@@ -136,10 +145,63 @@ parallel = false
 - `sudo` – Tide handles authentication and optional Keychain storage.
 - `enabled` – Toggle tasks on/off without deleting them.
 - `check_command` / `check_path` – Skip tasks automatically when prerequisites are missing.
-- `timeout` – Abort long-running commands (seconds).
+- `timeout` – Abort long-running commands (seconds). Default: 300 seconds (5 minutes).
 - `env` – Command-specific environment overrides.
 - `working_dir` – Set the working directory (supports `~`).
 
+### Protection Against Hanging Commands
+
+Tide includes built-in protections to prevent tasks from hanging:
+
+1. **Stdin Redirection**: All regular commands have stdin redirected to `/dev/null`, preventing them from blocking on password prompts or other interactive input.
+
+2. **Default Timeout**: Commands without an explicit `timeout` value will be automatically terminated after 5 minutes to prevent indefinite hanging.
+
+3. **Proactive Sudo Pre-Authentication**: Tide **always** attempts to pre-authenticate sudo at startup (unless in dry-run mode). This protects against scripts that internally call sudo without being marked with `sudo: true`.
+
+   ```bash
+   # At startup, you'll see:
+   🔐 Some tasks may require sudo privileges.
+   Enter sudo password (or press Ctrl+C to skip):
+   ```
+
+   - If you have the password in keychain, it's used automatically
+   - You can skip authentication (Ctrl+C or empty password)
+   - Password can be saved to macOS Keychain for future runs
+
+4. **Heuristic Warnings**: In verbose mode, Tide warns if a command contains "sudo" but isn't marked with `sudo: true`.
+
+5. **Helpful Error Messages**: If a command times out, Tide provides actionable error messages suggesting to set `sudo: true` or adjust the `timeout` value.
+
+**Important Use Cases:**
+
+✅ **Script with internal sudo** - Works even without `sudo: true` thanks to proactive auth:
+
+```toml
+[[groups.tasks]]
+name = "Maintenance Script"
+command = ["./scripts/cleanup.sh"]  # internally calls sudo
+# Works because sudo is pre-authenticated!
+```
+
+✅ **Explicit sudo task** - Best practice for clarity:
+
+```toml
+[[groups.tasks]]
+name = "System Update"
+command = ["brew", "upgrade"]
+sudo = true  # Clear and explicit
+```
+
+❌ **Interactive command** - Will timeout:
+
+```toml
+[[groups.tasks]]
+name = "Bad Example"
+command = ["./interactive-tool"]  # asks questions
+# Will hang and timeout after 5 minutes!
+```
+
 ## Examples
 
 Parallel developer tooling refresh:

readme.md

@@ -39,6 +39,8 @@ pub struct Settings {
     pub verbose: bool,
     #[serde(default)]
     pub log_file: Option<String>,
+    #[serde(default = "default_true")]
+    pub desktop_notifications: bool,
 }
 
 impl Default for Settings {
@@ -55,6 +57,7 @@ impl Default for Settings {
             use_colors: true,
             verbose: false,
             log_file: None,
+            desktop_notifications: true,
         }
     }
 }

src/config.rs

@@ -10,6 +10,7 @@ use std::time::{Duration, Instant};
 
 use crate::config::TaskConfig;
 use crate::keychain;
+use crate::notifications::NotificationManager;
 
 /// Task execution result
 #[derive(Debug)]
@@ -36,18 +37,110 @@ pub struct TaskExecutor {
     pub multi_progress: Arc<MultiProgress>,
     pub dry_run: bool,
     pub verbose: bool,
+    pub notifier: Arc<NotificationManager>,
 }
 
 impl TaskExecutor {
     /// Create a new task executor
-    pub fn new(dry_run: bool, verbose: bool) -> Self {
+    pub fn new(dry_run: bool, verbose: bool, notifications_enabled: bool) -> Self {
         Self {
             multi_progress: Arc::new(MultiProgress::new()),
             dry_run,
             verbose,
+            notifier: Arc::new(NotificationManager::new(notifications_enabled)),
         }
     }
 
+    /// Ensure sudo authentication is valid before executing tasks
+    /// This prevents tasks from hanging on password prompts
+    /// Returns Ok if auth succeeded or was already valid
+    /// Returns Err only if user provided wrong password
+    pub async fn ensure_sudo_auth(&self, keychain_label: &str) -> Result<()> {
+        // Check if sudo timestamp is already cached
+        if Command::new("sudo")
+            .arg("-n")
+            .arg("true")
+            .stdout(Stdio::null())
+            .stderr(Stdio::null())
+            .status()
+            .map(|s| s.success())
+            .unwrap_or(false)
+        {
+            if self.verbose {
+                println!("{}", "✓ Sudo timestamp already valid".green());
+            }
+            return Ok(());
+        }
+
+        // Try keychain password to refresh sudo timestamp
+        if let Ok(password) = keychain::get_password(keychain_label) {
+            if authenticate_sudo(&password).await? {
+                if self.verbose {
+                    println!("{}", "✓ Sudo authenticated via keychain".green());
+                }
+                return Ok(());
+            } else {
+                // Keychain password is wrong/outdated - we'll prompt
+                if self.verbose {
+                    println!(
+                        "{}",
+                        "⚠️  Keychain password is outdated, prompting for new password".yellow()
+                    );
+                }
+            }
+        }
+
+        // Prompt user for password
+        println!(
+            "{}",
+            "🔐 Some tasks may require sudo privileges.".bright_blue()
+        );
+
+        // Send desktop notification
+        let _ = self.notifier.notify_sudo_required();
+
+        let password = match Password::with_theme(&ColorfulTheme::default())
+            .with_prompt("Enter sudo password (or press Ctrl+C to skip)")
+            .allow_empty_password(true)
+            .interact()
+        {
+            Ok(pwd) if pwd.is_empty() => {
+                println!("{}", "Skipping sudo authentication.".yellow());
+                return Err(anyhow::anyhow!("User skipped sudo authentication"));
+            }
+            Ok(pwd) => pwd,
+            Err(_) => {
+                println!("{}", "Sudo authentication cancelled.".yellow());
+                return Err(anyhow::anyhow!("User cancelled sudo authentication"));
+            }
+        };
+
+        if !authenticate_sudo(&password).await? {
+            return Err(anyhow::anyhow!("Invalid sudo password"));
+        }
+
+        if self.verbose {
+            println!("{}", "✓ Sudo authenticated successfully".green());
+        }
+
+        // Optionally save password into keychain
+        if !keychain::entry_exists(keychain_label) {
+            if Confirm::with_theme(&ColorfulTheme::default())
+                .with_prompt("Save password to keychain for future use?")
+                .default(true)
+                .interact()?
+            {
+                keychain::save_password(keychain_label, &password)?;
+                println!(
+                    "{}",
+                    "✓ Password saved to keychain (service: tide-sudo)".green()
+                );
+            }
+        }
+
+        Ok(())
+    }
+
     /// Create a configured spinner progress bar
     pub fn new_spinner(&self) -> ProgressBar {
         let pb = self.multi_progress.add(ProgressBar::new_spinner());
@@ -144,16 +237,37 @@ impl TaskExecutor {
             cmd.insert(0, "sudo".to_string());
         }
 
+        // Warn if command might internally call sudo (heuristic check)
+        if !task.sudo && self.verbose && !cmd.is_empty() {
+            let cmd_str = cmd.join(" ").to_lowercase();
+            if cmd_str.contains("sudo") {
+                pb.println(format!(
+                    "{}",
+                    format!(
+                        "⚠️  Task '{}' may call sudo internally. Consider setting 'sudo: true'",
+                        task_name
+                    )
+                    .yellow()
+                ));
+            }
+        }
+
         // Execute command
         let result = if cmd.get(0).map(|s| s.as_str()) == Some("sudo") {
             self.run_sudo_command(&cmd[1..], keychain_label).await
         } else {
-            self.run_command(&cmd, &task).await
+            self.run_command(&cmd, &task, &task_name, &group_name).await
         };
 
         let (status, output) = match result {
             Ok(output) => (TaskStatus::Success, Some(output)),
-            Err(e) if task.required => (TaskStatus::Failed, Some(e.to_string())),
+            Err(e) if task.required => {
+                // Send notification for failed required task
+                let _ = self
+                    .notifier
+                    .notify_task_failed(&task_name, &group_name, &e.to_string());
+                (TaskStatus::Failed, Some(e.to_string()))
+            }
             Err(e) => (TaskStatus::Skipped, Some(e.to_string())),
         };
 
@@ -182,7 +296,13 @@ impl TaskExecutor {
     }
 
     /// Run a regular command
-    async fn run_command(&self, cmd: &[String], task: &TaskConfig) -> Result<String> {
+    async fn run_command(
+        &self,
+        cmd: &[String],
+        task: &TaskConfig,
+        task_name: &str,
+        group_name: &str,
+    ) -> Result<String> {
         if cmd.is_empty() {
             return Err(anyhow::anyhow!("Empty command"));
         }
@@ -201,11 +321,38 @@ impl TaskExecutor {
             command.env(key, value);
         }
 
+        // CRITICAL: Redirect stdin to /dev/null to prevent blocking on password prompts
+        // This prevents commands from hanging if they internally require interactive input
+        command.stdin(Stdio::null());
+
         if !self.verbose {
             command.stdout(Stdio::piped()).stderr(Stdio::piped());
         }
 
-        let output = command.output()?;
+        // Apply timeout if specified in task config
+        let command_future = tokio::task::spawn_blocking(move || command.output());
+        let timeout_secs = task.timeout.unwrap_or(300);
+
+        let output = match tokio::time::timeout(Duration::from_secs(timeout_secs), command_future)
+            .await
+        {
+            Ok(Ok(result)) => result?,
+            Ok(Err(e)) => return Err(anyhow::anyhow!("Command execution error: {}", e)),
+            Err(_) => {
+                // Send notification that task timed out (likely waiting for input)
+                let _ = self
+                    .notifier
+                    .notify_interactive_input_detected(task_name, group_name);
+                let _ = self
+                    .notifier
+                    .notify_task_timeout(task_name, group_name, timeout_secs);
+
+                return Err(anyhow::anyhow!(
+                    "Command timed out after {} seconds. This may indicate the command is waiting for input (like sudo password). Consider setting 'sudo: true' or 'timeout: <seconds>' in the task config.",
+                    timeout_secs
+                ));
+            }
+        };
 
         if output.status.success() {
             Ok(String::from_utf8_lossy(&output.stdout).to_string())