IPC hardening: actually make the UX nice

Backend:
- Add TimedOut<T> and IpcError types so frontend can distinguish timeouts from real empty/none results
- Add force-timeouts Cargo feature for QA (FORCE_TIMEOUTS=1 pnpm dev)

Frontend — transparent timeout UI:
- Volume dropdown: "Some volumes may be missing" warning row + retry
- Volume space bars: dashed placeholder with spinner/shake retry cycle, auto-retry after 5s, debounced clicks, context-aware tooltips
- Tab restore: inline banner with "Retry" / "Open home folder" instead of silently falling back to default volume; warning icon on tab
- Write ops (create/rename/trash): honest "may have succeeded" message with "Refresh listing" action instead of generic error
- File viewer: retry+cancel buttons for timeout errors, visually distinct from permanent errors
- Silent auto-retry for cosmetic data (sync badges, icons) after 5s

Bug fix:
- Dir-exists poll now requires 2 consecutive "not exists" before navigating away, preventing false navigation on slow mounts

Author: vdavid

apps/desktop/coverage-allowlist.json

@@ -53,6 +53,9 @@
         "file-explorer/navigation/path-navigation.ts": { "reason": "Depends on Tauri pathExists command" },
         "file-explorer/network/NetworkLoginForm.svelte": { "reason": "Network component, needs Tauri integration" },
         "file-explorer/pane/PermissionDeniedPane.svelte": { "reason": "Simple UI component" },
+        "file-explorer/pane/VolumeUnreachableBanner.svelte": {
+            "reason": "UI banner component, depends on Tauri commands"
+        },
         "file-explorer/selection/SelectionInfo.svelte": {
             "reason": "Logic tested in selection-info-utils.ts, DOM-dependent"
         },
@@ -118,6 +121,7 @@
         "tauri-commands/mtp.ts": { "reason": "Tauri command wrappers, tested via integration" },
         "tauri-commands/networking.ts": { "reason": "Tauri command wrappers, tested via integration" },
         "tauri-commands/settings.ts": { "reason": "Tauri command wrappers, tested via integration" },
+        "tauri-commands/ipc-types.ts": { "reason": "Type definitions and small helpers, tested via consuming modules" },
         "tauri-commands/storage.ts": { "reason": "Tauri command wrappers, tested via integration" },
         "tauri-commands/write-operations.ts": { "reason": "Tauri command wrappers, tested via integration" },
         "utils/confirm-dialog.ts": { "reason": "Thin wrapper over Tauri dialog API" },

apps/desktop/src-tauri/src/commands/CLAUDE.md

@@ -8,7 +8,7 @@ immediately to business-logic modules. No significant logic lives here.
 | File | Domain | Notes |
 |------|--------|-------|
 | `mod.rs` | Re-exports | `mtp`, `network` gated behind `#[cfg(any(target_os = "macos", target_os = "linux"))]`; `volumes` behind `#[cfg(target_os = "macos")]`; `volumes_linux` behind `#[cfg(target_os = "linux")]` |
-| `util.rs` | Shared helpers | `blocking_with_timeout` — runs a blocking closure on the blocking thread pool with a timeout, returning a fallback value on timeout. Used by all filesystem-touching commands. |
+| `util.rs` | Shared helpers | `TimedOut<T>`, `IpcError`, `blocking_with_timeout`, `blocking_with_timeout_flag`, `blocking_result_with_timeout`. See "Timeout-aware return types" below. |
 | `file_system.rs` | File listing & writes | Largest file. Streaming + virtual-scroll listing API, write ops (copy, move, delete, trash), scan preview, conflict resolution, volume copy, native drag, self-drag overlay. Contains `expand_tilde()`. |
 | `volumes.rs` | Volume management (macOS) | `list_volumes`, `get_default_volume_id`, `find_containing_volume`, `get_volume_space` |
 | `volumes_linux.rs` | Volume management (Linux) | Same interface as `volumes.rs`, delegates to `volumes_linux` module |
@@ -35,14 +35,24 @@ immediately to business-logic modules. No significant logic lives here.
 **Decision**: `blocking_with_timeout` for all filesystem-touching commands, not just read-only ones.
 **Why**: `spawn_blocking` alone doesn't protect against hung NFS/SMB mounts where even a simple `path.exists()` can block indefinitely. The timeout wrapper (2s for reads, 5s for writes, 15s for trash, 30s for recursive scans) returns a fallback value (or error for `Result`-returning commands) instead of freezing the IPC thread or exhausting the blocking pool. The helper lives in `util.rs` so all command files can share it. Commands that already use `spawn_blocking` (P2 commands like `rename_file`, `move_to_trash`) wrap the existing `spawn_blocking` with `tokio::time::timeout` instead.
 
+**Decision**: Timeout-aware return types (`TimedOut<T>` and `IpcError`) for all timeout-protected commands.
+**Why**: The original `blocking_with_timeout` returned a fallback value indistinguishable from a real empty/none result. The frontend couldn't tell "no volumes mounted" from "timed out before listing volumes." Two wrapper types solve this:
+- `TimedOut<T>` (`{ data: T, timedOut: bool }`) — for commands that don't return `Result` (collections, `Option`, `()`). Use `blocking_with_timeout_flag` to produce these.
+- `IpcError` (`{ message: String, timedOut: bool }`) — for commands returning `Result<T, _>`. Use `blocking_result_with_timeout` or map `tokio::time::timeout` errors to `IpcError::timeout()`.
+The frontend has matching TypeScript types in `$lib/tauri-commands/ipc-types.ts` (`TimedOut<T>`, `IpcError`, `isIpcError`, `getIpcErrorMessage`). The old `blocking_with_timeout` is kept for `path_exists` and other commands where timeout distinction isn't needed.
+
 **Decision**: No `commands/ai.rs` file -- AI commands register directly from `ai::manager` and `ai::suggestions`.
 **Why**: The AI subsystem has its own complex lifecycle (model loading, suggestion pipelines). Adding a thin wrapper in `commands/` would just be boilerplate forwarding. Registering directly keeps the AI command surface co-located with its implementation, which changes frequently.
 
 ## Key patterns and gotchas
 
 - **No business logic here.** If you find yourself adding branching or data transformation, move it to the relevant subsystem module.
 - **`spawn_blocking` for filesystem I/O.** All blocking operations in async commands are wrapped in `tokio::task::spawn_blocking`.
-- **`blocking_with_timeout` for potentially slow I/O.** All filesystem-touching commands use either `blocking_with_timeout` (from `util.rs`) or `tokio::time::timeout` around `spawn_blocking`. Timeouts: 2s for reads, 5s for writes (`create_directory`, `rename_file`), 15s for trash (`move_to_trash` — macOS NSFileManager is slow on cold start), 30s for recursive scans (`scan_volume_for_copy`, `scan_volume_for_conflicts`). The helper returns a fallback value on timeout or `JoinError`.
+- **Timeout-protected I/O with distinguishable results.** All filesystem-touching commands use timeout wrappers from `util.rs`. Timeouts: 2s for reads, 5s for writes (`create_directory`, `rename_file`), 15s for trash (`move_to_trash`), 30s for recursive scans. Three helpers:
+  - `blocking_with_timeout(duration, fallback, closure)` — returns raw `T`, timeout indistinguishable from fallback. Used only where distinction isn't needed (like `path_exists`).
+  - `blocking_with_timeout_flag(duration, fallback, closure)` → `TimedOut<T>` — for commands returning `Vec`, `HashMap`, `Option`, or `()`. Frontend unwraps `.data` and can check `.timedOut`.
+  - `blocking_result_with_timeout(duration, closure)` → `Result<T, IpcError>` — for commands that already return `Result`. Timeout becomes `Err(IpcError { message, timedOut: true })`.
+  - For P2 commands using raw `tokio::time::timeout`, map the `Elapsed` error to `IpcError::timeout()` and other errors to `IpcError::from_err(msg)`.
 - **`expand_tilde`** is applied conditionally: for `list_directory` it's gated on `volume_id == "root"`, but for write operations (copy, move, delete, scan preview) it's always applied. MTP and network volume paths must never be tilde-expanded.
 - **AI commands** are registered directly from `ai::manager` and `ai::suggestions` — there is no `commands/ai.rs` file.
 - **Platform gates.** `volumes` is macOS-only; `mtp` and `network` are macOS+Linux; `volumes_linux` is Linux-only. Individual functions also use `#[cfg]` where behaviour differs (e.g., `sync_status`).

apps/desktop/src-tauri/src/commands/file_system.rs

@@ -29,7 +29,9 @@ use std::sync::mpsc::channel;
 use tauri::Manager;
 use tokio::time::Duration;
 
-use super::util::blocking_with_timeout;
+use super::util::{
+    IpcError, TimedOut, blocking_result_with_timeout, blocking_with_timeout, blocking_with_timeout_flag,
+};
 
 const PATH_EXISTS_TIMEOUT: Duration = Duration::from_secs(2);
 
@@ -55,12 +57,16 @@ pub async fn path_exists(volume_id: Option<String>, path: String) -> bool {
 }
 
 #[tauri::command]
-pub async fn create_directory(volume_id: Option<String>, parent_path: String, name: String) -> Result<String, String> {
+pub async fn create_directory(
+    volume_id: Option<String>,
+    parent_path: String,
+    name: String,
+) -> Result<String, IpcError> {
     if name.is_empty() {
-        return Err("Folder name cannot be empty".to_string());
+        return Err(IpcError::from_err("Folder name cannot be empty"));
     }
     if name.contains('/') || name.contains('\0') {
-        return Err("Folder name contains invalid characters".to_string());
+        return Err(IpcError::from_err("Folder name contains invalid characters"));
     }
 
     let volume_id = volume_id.unwrap_or_else(|| "root".to_string());
@@ -85,7 +91,9 @@ pub async fn create_directory(volume_id: Option<String>, parent_path: String, na
             Duration::from_secs(5),
             tokio::task::spawn_blocking(move || {
                 volume.create_directory(&new_path_clone).map_err(|e| match e {
-                    crate::file_system::VolumeError::AlreadyExists(_) => format!("'{}' already exists", name_clone),
+                    crate::file_system::VolumeError::AlreadyExists(_) => {
+                        format!("'{}' already exists", name_clone)
+                    }
                     crate::file_system::VolumeError::PermissionDenied(_) => {
                         format!(
                             "Permission denied: cannot create '{}' in '{}'",
@@ -97,22 +105,25 @@ pub async fn create_directory(volume_id: Option<String>, parent_path: String, na
             }),
         )
         .await
-        .map_err(|_| "Operation timed out (network mount may be unresponsive)".to_string())?
-        .map_err(|e| format!("Task failed: {}", e))??;
+        .map_err(|_| IpcError::timeout())?
+        .map_err(|e| IpcError::from_err(format!("Task failed: {}", e)))?
+        .map_err(IpcError::from_err)?;
 
         return Ok(new_path.to_string_lossy().to_string());
     }
 
     // Fallback for unknown volumes (shouldn't happen in practice)
     let mut new_path = PathBuf::from(&expanded_path);
     new_path.push(&name);
-    std::fs::create_dir(&new_path).map_err(|e| match e.kind() {
-        std::io::ErrorKind::AlreadyExists => format!("'{}' already exists", name),
-        std::io::ErrorKind::PermissionDenied => {
-            format!("Permission denied: cannot create '{}' in '{}'", name, parent_path)
-        }
-        _ => format!("Failed to create folder: {}", e),
-    })?;
+    std::fs::create_dir(&new_path)
+        .map_err(|e| match e.kind() {
+            std::io::ErrorKind::AlreadyExists => format!("'{}' already exists", name),
+            std::io::ErrorKind::PermissionDenied => {
+                format!("Permission denied: cannot create '{}' in '{}'", name, parent_path)
+            }
+            _ => format!("Failed to create folder: {}", e),
+        })
+        .map_err(IpcError::from_err)?;
     Ok(new_path.to_string_lossy().to_string())
 }
 
@@ -128,18 +139,14 @@ pub async fn list_directory_start(
     sort_by: SortColumn,
     sort_order: SortOrder,
     directory_sort_mode: Option<DirectorySortMode>,
-) -> Result<ListingStartResult, String> {
+) -> Result<ListingStartResult, IpcError> {
     let expanded_path = expand_tilde(&path);
     let path_buf = PathBuf::from(&expanded_path);
     let dir_sort_mode = directory_sort_mode.unwrap_or_default();
-    blocking_with_timeout(
-        Duration::from_secs(2),
-        Err("Operation timed out (network mount may be unresponsive)".to_string()),
-        move || {
-            ops_list_directory_start_with_volume("root", &path_buf, include_hidden, sort_by, sort_order, dir_sort_mode)
-                .map_err(|e| format!("Failed to start directory listing '{}': {}", path, e))
-        },
-    )
+    blocking_result_with_timeout(Duration::from_secs(2), move || {
+        ops_list_directory_start_with_volume("root", &path_buf, include_hidden, sort_by, sort_order, dir_sort_mode)
+            .map_err(|e| format!("Failed to start directory listing '{}': {}", path, e))
+    })
     .await
 }
 
@@ -247,11 +254,11 @@ pub fn list_directory_end(listing_id: String) {
 /// Force a re-read of a watched directory listing, emitting any diff.
 /// Used after write operations (move) when the file watcher may not fire promptly.
 #[tauri::command]
-pub async fn refresh_listing(listing_id: String) {
-    blocking_with_timeout(Duration::from_secs(2), (), move || {
+pub async fn refresh_listing(listing_id: String) -> TimedOut<()> {
+    blocking_with_timeout_flag(Duration::from_secs(2), (), move || {
         crate::file_system::watcher::handle_directory_change(&listing_id);
     })
-    .await;
+    .await
 }
 
 /// Returns total file/dir counts and sizes, plus selection stats if `selected_indices` is given.
@@ -524,14 +531,14 @@ pub async fn scan_volume_for_copy(
     dest_volume_id: String,
     dest_path: String,
     max_conflicts: Option<usize>,
-) -> Result<VolumeCopyScanResult, String> {
+) -> Result<VolumeCopyScanResult, IpcError> {
     let source_volume = get_volume_manager()
         .get(&source_volume_id)
-        .ok_or_else(|| format!("Source volume '{}' not found", source_volume_id))?;
+        .ok_or_else(|| IpcError::from_err(format!("Source volume '{}' not found", source_volume_id)))?;
 
     let dest_volume = get_volume_manager()
         .get(&dest_volume_id)
-        .ok_or_else(|| format!("Destination volume '{}' not found", dest_volume_id))?;
+        .ok_or_else(|| IpcError::from_err(format!("Destination volume '{}' not found", dest_volume_id)))?;
 
     let source_paths: Vec<PathBuf> = source_paths.iter().map(PathBuf::from).collect();
     let dest_path = PathBuf::from(dest_path);
@@ -546,8 +553,9 @@ pub async fn scan_volume_for_copy(
         }),
     )
     .await
-    .map_err(|_| "Operation timed out (network mount may be unresponsive)".to_string())?
-    .map_err(|e| format!("Scan task failed: {}", e))?
+    .map_err(|_| IpcError::timeout())?
+    .map_err(|e| IpcError::from_err(format!("Scan task failed: {}", e)))?
+    .map_err(IpcError::from_err)
 }
 
 /// Checks which source items already exist at the destination. Returns conflict details for UI.
@@ -556,10 +564,10 @@ pub async fn scan_volume_for_conflicts(
     volume_id: String,
     source_items: Vec<SourceItemInput>,
     dest_path: String,
-) -> Result<Vec<ScanConflict>, String> {
+) -> Result<Vec<ScanConflict>, IpcError> {
     let volume = get_volume_manager()
         .get(&volume_id)
-        .ok_or_else(|| format!("Volume '{}' not found", volume_id))?;
+        .ok_or_else(|| IpcError::from_err(format!("Volume '{}' not found", volume_id)))?;
 
     let source_items: Vec<crate::file_system::SourceItemInfo> = source_items
         .into_iter()
@@ -581,8 +589,9 @@ pub async fn scan_volume_for_conflicts(
         }),
     )
     .await
-    .map_err(|_| "Operation timed out (network mount may be unresponsive)".to_string())?
-    .map_err(|e| format!("Conflict scan task failed: {}", e))?
+    .map_err(|_| IpcError::timeout())?
+    .map_err(|e| IpcError::from_err(format!("Conflict scan task failed: {}", e)))?
+    .map_err(IpcError::from_err)
 }
 
 /// Input type for source item information (used by scan_volume_for_conflicts).
@@ -693,7 +702,7 @@ mod tests {
         fs::create_dir(tmp.join("existing")).unwrap();
         let result = create_directory(None, parent, "existing".to_string()).await;
         assert!(result.is_err());
-        assert!(result.unwrap_err().contains("already exists"));
+        assert!(result.unwrap_err().message.contains("already exists"));
         cleanup_test_dir(&tmp);
     }
 
@@ -703,7 +712,7 @@ mod tests {
         let parent = tmp.to_string_lossy().to_string();
         let result = create_directory(None, parent, "".to_string()).await;
         assert!(result.is_err());
-        assert!(result.unwrap_err().contains("cannot be empty"));
+        assert!(result.unwrap_err().message.contains("cannot be empty"));
         cleanup_test_dir(&tmp);
     }
 
@@ -713,11 +722,11 @@ mod tests {
         let parent = tmp.to_string_lossy().to_string();
         let result = create_directory(None, parent.clone(), "foo/bar".to_string()).await;
         assert!(result.is_err());
-        assert!(result.unwrap_err().contains("invalid characters"));
+        assert!(result.unwrap_err().message.contains("invalid characters"));
 
         let result = create_directory(None, parent, "foo\0bar".to_string()).await;
         assert!(result.is_err());
-        assert!(result.unwrap_err().contains("invalid characters"));
+        assert!(result.unwrap_err().message.contains("invalid characters"));
         cleanup_test_dir(&tmp);
     }
 

apps/desktop/src-tauri/src/commands/file_viewer.rs

@@ -2,7 +2,7 @@
 
 use tokio::time::Duration;
 
-use super::util::blocking_with_timeout;
+use super::util::{IpcError, blocking_result_with_timeout};
 use crate::file_viewer::{self, LineChunk, SearchPollResult, SeekTarget, ViewerOpenResult, ViewerSessionStatus};
 use log::debug;
 use tauri::Manager;
@@ -13,12 +13,10 @@ const VIEWER_TIMEOUT: Duration = Duration::from_secs(2);
 /// Opens a viewer session for the given file.
 /// Returns session metadata + initial lines from the start of the file.
 #[tauri::command]
-pub async fn viewer_open(path: String) -> Result<ViewerOpenResult, String> {
-    blocking_with_timeout(
-        VIEWER_TIMEOUT,
-        Err("Operation timed out (network mount may be unresponsive)".to_string()),
-        move || file_viewer::open_session(&path).map_err(|e| e.to_string()),
-    )
+pub async fn viewer_open(path: String) -> Result<ViewerOpenResult, IpcError> {
+    blocking_result_with_timeout(VIEWER_TIMEOUT, move || {
+        file_viewer::open_session(&path).map_err(|e| e.to_string())
+    })
     .await
 }
 
@@ -35,16 +33,16 @@ pub async fn viewer_get_lines(
     target_type: String,
     target_value: f64,
     count: usize,
-) -> Result<LineChunk, String> {
+) -> Result<LineChunk, IpcError> {
     let target = match target_type.as_str() {
         "line" => SeekTarget::Line(target_value as usize),
         "byte" => SeekTarget::ByteOffset(target_value as u64),
         "fraction" => SeekTarget::Fraction(target_value),
         other => {
-            return Err(format!(
+            return Err(IpcError::from_err(format!(
                 "Unknown target type: {}. Use 'line', 'byte', or 'fraction'.",
                 other
-            ));
+            )));
         }
     };
 
@@ -53,11 +51,9 @@ pub async fn viewer_get_lines(
         session_id, target_type, target_value, count
     );
 
-    let result = blocking_with_timeout(
-        VIEWER_TIMEOUT,
-        Err("Operation timed out (network mount may be unresponsive)".to_string()),
-        move || file_viewer::get_lines(&session_id, target, count).map_err(|e| e.to_string()),
-    )
+    let result = blocking_result_with_timeout(VIEWER_TIMEOUT, move || {
+        file_viewer::get_lines(&session_id, target, count).map_err(|e| e.to_string())
+    })
     .await?;
 
     debug!(

apps/desktop/src-tauri/src/commands/icons.rs

@@ -3,7 +3,7 @@
 use std::collections::HashMap;
 use tokio::time::Duration;
 
-use super::util::blocking_with_timeout;
+use super::util::{TimedOut, blocking_with_timeout_flag};
 use crate::icons;
 
 const ICONS_TIMEOUT: Duration = Duration::from_secs(2);
@@ -16,8 +16,8 @@ const ICONS_TIMEOUT: Duration = Duration::from_secs(2);
 /// are fetched from app bundles (showing the app's icon as fallback). When false,
 /// the system's default document icons are used (Finder-style with app badge).
 #[tauri::command]
-pub async fn get_icons(icon_ids: Vec<String>, use_app_icons_for_documents: bool) -> HashMap<String, String> {
-    blocking_with_timeout(ICONS_TIMEOUT, HashMap::new(), move || {
+pub async fn get_icons(icon_ids: Vec<String>, use_app_icons_for_documents: bool) -> TimedOut<HashMap<String, String>> {
+    blocking_with_timeout_flag(ICONS_TIMEOUT, HashMap::new(), move || {
         icons::get_icons(icon_ids, use_app_icons_for_documents)
     })
     .await
@@ -34,8 +34,8 @@ pub async fn refresh_directory_icons(
     directory_paths: Vec<String>,
     extensions: Vec<String>,
     use_app_icons_for_documents: bool,
-) -> HashMap<String, String> {
-    blocking_with_timeout(ICONS_TIMEOUT, HashMap::new(), move || {
+) -> TimedOut<HashMap<String, String>> {
+    blocking_with_timeout_flag(ICONS_TIMEOUT, HashMap::new(), move || {
         icons::refresh_icons_for_directory(directory_paths, extensions, use_app_icons_for_documents)
     })
     .await