refresh_listing: short-circuit on watcher-backed (M1)

- `refresh_listing` now checks the listing's volume `listing_is_watched(path)` and returns `TimedOut { timed_out: false }` immediately when the volume is keeping the cache fresh via `notify_mutation`. Eliminates the redundant post-transfer full re-read that wedged MTP (17 s + USB collision after every cancel/complete/error).
- Logs at debug under `target: "refresh_listing"` with `listing_id`, `volume_id`, and `path` when the short-circuit fires.
- New `caching::get_listing_volume_id_and_path` helper reads both fields in one lock acquisition.
- Tests: short-circuit on watched, fall-through on unwatched, fall-through on missing listing, fall-through on unregistered volume.
- Docs: extended `refresh_listing` rustdoc, updated `commands/CLAUDE.md` file map, added `refresh_listing` as the third consumer of `listing_is_watched` in `volume/CLAUDE.md`.
- Watcher-driven `handle_directory_change` callers (FSEvents debouncer, incremental fallback, full re-read fallback) are intentionally NOT gated — they're how the cache stays in sync.

Author: vdavid

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

@@ -9,7 +9,7 @@ immediately to business-logic modules. No significant logic lives here.
 |------|--------|-------|
 | `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 | `TimedOut<T>`, `IpcError`, `blocking_with_timeout`, `blocking_with_timeout_flag`, `blocking_result_with_timeout`. See "Timeout-aware return types" below. |
-| `file_system/` | File listing & writes | Directory module split by operation type. `mod.rs` has `expand_tilde()`, re-exports, and tests. `listing.rs`: streaming + virtual-scroll listing API, path queries, `find_first_fuzzy_match` (type-to-jump), benchmarking, `get_brief_column_text_widths` (per-column widest-filename text widths for Brief mode; replaces the removed `get_max_filename_width`). `write_ops.rs`: create, copy, move, delete, trash, scan preview, conflict resolution, synthetic diff helpers. `volume_copy.rs`: cross-volume copy/move/scan, `SourceItemInput`. `drag.rs`: native drag, self-drag overlay. `e2e_support.rs`: feature-gated E2E/debug commands. |
+| `file_system/` | File listing & writes | Directory module split by operation type. `mod.rs` has `expand_tilde()`, re-exports, and tests. `listing.rs`: streaming + virtual-scroll listing API, path queries, `find_first_fuzzy_match` (type-to-jump), benchmarking, `get_brief_column_text_widths` (per-column widest-filename text widths for Brief mode; replaces the removed `get_max_filename_width`). `refresh_listing` short-circuits on watcher-backed listings (`Volume::listing_is_watched(path) == true`): the cache is already kept fresh by `notify_mutation`, so a redundant full re-read after every transfer outcome (the FE's `refreshPanesAfterTransfer`) used to wedge slow volumes (MTP 17 s + USB session collision). Logs at debug `target: "refresh_listing"` when the short-circuit fires. `write_ops.rs`: create, copy, move, delete, trash, scan preview, conflict resolution, synthetic diff helpers. `volume_copy.rs`: cross-volume copy/move/scan, `SourceItemInput`. `drag.rs`: native drag, self-drag overlay. `e2e_support.rs`: feature-gated E2E/debug commands. |
 | `volumes.rs` | Volume management (macOS) | `list_volumes`, `get_default_volume_id`, `get_volume_space`, `resolve_path_volume` (statfs-based, no volume enumeration) |
 | `volumes_linux.rs` | Volume management (Linux) | Same interface as `volumes.rs`, delegates to `volumes_linux` module |
 | `mtp.rs` | MTP devices | Full MTP command surface (connect, disconnect, list, download, upload, delete, rename, move, scan) |

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

@@ -322,9 +322,42 @@ 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.
+///
+/// Short-circuits when the listing's volume reports `listing_is_watched(path) == true`.
+/// In that case the cache is already being kept fresh by the volume's `notify_mutation`
+/// pipeline (per-file `Added` / `Removed` / `Modified` events patched into `LISTING_CACHE`
+/// after every successful mutation), so a full `list_directory` re-read is redundant
+/// and costs a lot on slow backends: a 1k-entry MTP folder takes ~17 s and holds the
+/// USB session, colliding with the user's next op. Returns `TimedOut { data: (),
+/// timed_out: false }` immediately when the short-circuit fires, matching the
+/// `timed_out: false` shape the FE already handles on the fast-path.
+///
+/// Note: only this user-triggered command is gated. The FSEvents/SMB/MTP watcher
+/// callbacks call `handle_directory_change` directly and are intentionally left
+/// alone — they're how the cache stays in sync in the first place.
 #[tauri::command]
 #[specta::specta]
 pub async fn refresh_listing(listing_id: String) -> TimedOut<()> {
+    // Short-circuit on watcher-backed listings: the volume's `notify_mutation`
+    // pipeline keeps `LISTING_CACHE` fresh, so a full re-read here is pure
+    // redundancy. See the doc comment above for why this matters on MTP/SMB.
+    if let Some((volume_id, path)) = crate::file_system::listing::get_listing_volume_id_and_path(&listing_id)
+        && let Some(volume) = get_volume_manager().get(&volume_id)
+        && volume.listing_is_watched(&path)
+    {
+        log::debug!(
+            target: "refresh_listing",
+            "refresh_listing: short-circuit, watcher-backed listing (listing_id={}, volume_id={}, path={})",
+            listing_id,
+            volume_id,
+            path.display(),
+        );
+        return TimedOut {
+            data: (),
+            timed_out: false,
+        };
+    }
+
     let timed_out = tokio::time::timeout(Duration::from_secs(2), async {
         crate::file_system::watcher::handle_directory_change(&listing_id).await;
     })
@@ -368,3 +401,208 @@ pub fn benchmark_log(message: String) {
         eprintln!("{}", message);
     }
 }
+
+#[cfg(test)]
+mod refresh_listing_tests {
+    //! Tests for the `refresh_listing` short-circuit on watcher-backed listings (M1
+    //! of the cancel-settled plan). Pattern adapted from
+    //! `write_operations::delete_volume_reuse_tests` — a counter-wrapping
+    //! `InMemoryVolume` whose `listing_is_watched` is flipped per test, seeded into
+    //! `LISTING_CACHE` and `VolumeManager`, then we call `refresh_listing` and
+    //! assert `list_directory` was or wasn't invoked.
+    use super::*;
+    use crate::file_system::get_volume_manager;
+    use crate::file_system::listing::caching::{CachedListing, LISTING_CACHE};
+    use crate::file_system::listing::metadata::FileEntry;
+    use crate::file_system::listing::sorting::{DirectorySortMode, SortColumn, SortOrder};
+    use crate::file_system::volume::{InMemoryVolume, Volume, VolumeError};
+    use std::future::Future;
+    use std::path::Path;
+    use std::pin::Pin;
+    use std::sync::Arc;
+    use std::sync::atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering};
+
+    /// Wraps an `InMemoryVolume` and counts `list_directory` calls. `watched` is
+    /// flipped per test to pin both short-circuit and fall-through behaviour.
+    struct CountingVolume {
+        inner: InMemoryVolume,
+        watched: AtomicBool,
+        list_dir_calls: AtomicUsize,
+    }
+
+    impl CountingVolume {
+        fn new(name: &str, watched: bool) -> Self {
+            Self {
+                inner: InMemoryVolume::new(name),
+                watched: AtomicBool::new(watched),
+                list_dir_calls: AtomicUsize::new(0),
+            }
+        }
+
+        fn list_dir_count(&self) -> usize {
+            self.list_dir_calls.load(Ordering::Relaxed)
+        }
+    }
+
+    impl Volume for CountingVolume {
+        fn name(&self) -> &str {
+            self.inner.name()
+        }
+        fn root(&self) -> &Path {
+            self.inner.root()
+        }
+
+        fn list_directory<'a>(
+            &'a self,
+            path: &'a Path,
+            on_progress: Option<&'a (dyn Fn(usize) + Sync)>,
+        ) -> Pin<Box<dyn Future<Output = Result<Vec<FileEntry>, VolumeError>> + Send + 'a>> {
+            self.list_dir_calls.fetch_add(1, Ordering::Relaxed);
+            self.inner.list_directory(path, on_progress)
+        }
+
+        fn get_metadata<'a>(
+            &'a self,
+            path: &'a Path,
+        ) -> Pin<Box<dyn Future<Output = Result<FileEntry, VolumeError>> + Send + 'a>> {
+            self.inner.get_metadata(path)
+        }
+
+        fn exists<'a>(&'a self, path: &'a Path) -> Pin<Box<dyn Future<Output = bool> + Send + 'a>> {
+            self.inner.exists(path)
+        }
+
+        fn is_directory<'a>(
+            &'a self,
+            path: &'a Path,
+        ) -> Pin<Box<dyn Future<Output = Result<bool, VolumeError>> + Send + 'a>> {
+            self.inner.is_directory(path)
+        }
+
+        fn listing_is_watched(&self, _path: &Path) -> bool {
+            self.watched.load(Ordering::Relaxed)
+        }
+    }
+
+    fn unique(suffix: &str) -> String {
+        static N: AtomicU64 = AtomicU64::new(0);
+        format!(
+            "refresh_listing_{}_{}_{}",
+            suffix,
+            std::process::id(),
+            N.fetch_add(1, Ordering::Relaxed)
+        )
+    }
+
+    fn insert_listing(listing_id: &str, volume_id: &str, path: &str) {
+        let mut cache = LISTING_CACHE.write().unwrap();
+        cache.insert(
+            listing_id.to_string(),
+            CachedListing {
+                volume_id: volume_id.to_string(),
+                path: PathBuf::from(path),
+                entries: Vec::new(),
+                sort_by: SortColumn::Name,
+                sort_order: SortOrder::Ascending,
+                directory_sort_mode: DirectorySortMode::LikeFiles,
+                sequence: AtomicU64::new(1),
+                created_at: std::time::Instant::now(),
+            },
+        );
+    }
+
+    fn remove_listing(listing_id: &str) {
+        let _ = LISTING_CACHE.write().unwrap().remove(listing_id);
+    }
+
+    /// Watched volume: short-circuit fires, `list_directory` never called.
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn refresh_listing_short_circuits_on_watched_volume() {
+        let vid = unique("short_circuit_vid");
+        let lid = unique("short_circuit_lid");
+        let path = "/dcim";
+
+        let vol = Arc::new(CountingVolume::new("watched-vol", true));
+        get_volume_manager().register(&vid, vol.clone() as Arc<dyn Volume>);
+        insert_listing(&lid, &vid, path);
+
+        let result = refresh_listing(lid.clone()).await;
+
+        assert!(!result.timed_out, "short-circuit returns timed_out=false");
+        assert_eq!(
+            vol.list_dir_count(),
+            0,
+            "watched-backed refresh_listing must skip list_directory",
+        );
+
+        remove_listing(&lid);
+        get_volume_manager().unregister(&vid);
+    }
+
+    /// Unwatched volume: fall-through path runs (`handle_directory_change` calls
+    /// `list_directory`). The InMemoryVolume's directory exists so we get a real
+    /// listing rather than NotFound.
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn refresh_listing_falls_through_on_unwatched() {
+        let vid = unique("fallthrough_vid");
+        let lid = unique("fallthrough_lid");
+        let path = "/dcim";
+
+        let vol = Arc::new(CountingVolume::new("unwatched-vol", false));
+        // Populate one file so `list_directory` succeeds.
+        vol.inner.create_file(Path::new("/dcim/a.jpg"), b"alpha").await.unwrap();
+        get_volume_manager().register(&vid, vol.clone() as Arc<dyn Volume>);
+        insert_listing(&lid, &vid, path);
+
+        let result = refresh_listing(lid.clone()).await;
+
+        assert!(!result.timed_out, "fast InMemory list_directory shouldn't time out");
+        assert!(
+            vol.list_dir_count() >= 1,
+            "unwatched volume must fall through to list_directory (count was {})",
+            vol.list_dir_count(),
+        );
+
+        remove_listing(&lid);
+        get_volume_manager().unregister(&vid);
+    }
+
+    /// No cache entry for the listing_id: today's behaviour is a clean no-op
+    /// (`handle_directory_change` early-returns). The short-circuit must NOT
+    /// suppress that path or panic; we just assert the call completes cleanly.
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn refresh_listing_falls_through_on_missing_listing() {
+        let lid = unique("missing_lid");
+        // No insert_listing call; no register call.
+        let result = refresh_listing(lid).await;
+        assert!(
+            !result.timed_out,
+            "missing listing should resolve quickly without timeout"
+        );
+    }
+
+    /// Cache has the listing but the volume isn't registered: short-circuit
+    /// can't ask `listing_is_watched`, so we fall through to today's behaviour
+    /// (`handle_directory_change` finds no volume, falls back to local std::fs
+    /// for the path which doesn't exist, and returns cleanly without panic).
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn refresh_listing_falls_through_when_volume_not_registered() {
+        let vid = unique("unregistered_vid");
+        let lid = unique("unregistered_lid");
+        // Use a path that doesn't exist on disk so the std::fs fallback returns
+        // NotFound and the function exits cleanly.
+        let path = "/tmp/cmdr-refresh-listing-test-nonexistent-path-xyz123";
+
+        // Note: NO get_volume_manager().register() call.
+        insert_listing(&lid, &vid, path);
+
+        let result = refresh_listing(lid.clone()).await;
+
+        assert!(
+            !result.timed_out,
+            "unregistered-volume fallthrough should resolve quickly"
+        );
+
+        remove_listing(&lid);
+    }
+}

apps/desktop/src-tauri/src/file_system/listing/caching.rs

@@ -188,6 +188,17 @@ pub fn get_listing_path(listing_id: &str) -> Option<PathBuf> {
     cache.get(listing_id).map(|listing| listing.path.clone())
 }
 
+/// Returns `(volume_id, path)` for a cached listing in one read-lock acquisition.
+///
+/// Used by `refresh_listing` so the short-circuit check can ask the volume
+/// `listing_is_watched(path)` without two separate cache reads.
+pub fn get_listing_volume_id_and_path(listing_id: &str) -> Option<(String, PathBuf)> {
+    let cache = LISTING_CACHE.read().ok()?;
+    cache
+        .get(listing_id)
+        .map(|listing| (listing.volume_id.clone(), listing.path.clone()))
+}
+
 /// Removes an entry by its path from the cached listing.
 ///
 /// Returns `(old_index, removed_entry)` or `None` if the listing or entry wasn't found.

apps/desktop/src-tauri/src/file_system/listing/mod.rs

@@ -29,8 +29,8 @@ pub use operations::{get_files_at_indices, get_paths_at_indices};
 
 // Internal re-exports for file_system module internals (pub(crate) for crate-internal use)
 pub(crate) use caching::{
-    ModifyResult, find_listings_for_path, get_listing_path, has_entry, increment_sequence, insert_entry_sorted,
-    remove_entry_by_path, update_entry_sorted,
+    ModifyResult, find_listings_for_path, get_listing_path, get_listing_volume_id_and_path, has_entry,
+    increment_sequence, insert_entry_sorted, remove_entry_by_path, update_entry_sorted,
 };
 // Notification API for volume mutations
 #[cfg(any(target_os = "macos", target_os = "linux"))]

apps/desktop/src-tauri/src/file_system/volume/CLAUDE.md

@@ -49,7 +49,11 @@ Optional methods default to `Err(VolumeError::NotSupported)` or `false`, so new
 - `on_unmount()`: lifecycle hook called before unregistration. `SmbVolume` uses it to disconnect its smb2 session. Default is no-op.
 - `scanner()` / `watcher()`: drive indexing hooks; `None` by default.
 - `space_poll_interval()`: recommended interval for the live disk-space poller (`space_poller.rs`). Default 2 s (local volumes). `SmbVolume` and `MtpVolume` override to 5 s. `InMemoryVolume` returns `None` (no polling). The poller uses this to tick each volume at its own cadence.
-- `listing_is_watched(path)`: returns `true` when this volume's cached listing for `path` is being kept in sync by a live watcher. Used by `file_system::listing::caching::try_get_watched_listing` (the "fresh-listing oracle") to decide whether write-op pre-flight scans can reuse a cached listing instead of re-reading. Default `false` so a new backend without a real watcher won't accidentally claim freshness. **Freshness contract**: a `true` result does NOT mean the cache is byte-perfect with the device right now. Every backend has a debounce or settling window between a real change and the cache reflecting it: local FS ≈ 10 ms (FSEvents coalesce), SMB 200 ms (watcher debounce; > 50 events/dir triggers a `FullRefresh`), MTP 500 ms (event debouncer plus per-device polling; many cameras emit no events at all, so on those `true` means only "the device is reachable"). Callers must treat the result as "fresh as our most recent observation" — the same guarantee a `list_directory` call gives. The MTP and SMB checks are volume-level, not path-level: when the gate flips true, every path on that volume becomes oracle-eligible.
+- `listing_is_watched(path)`: returns `true` when this volume's cached listing for `path` is being kept in sync by a live watcher. Three consumers today:
+    1. `file_system::listing::caching::try_get_watched_listing` (the "fresh-listing oracle") — write-op pre-flight scans reuse a cached listing instead of re-reading.
+    2. `write_operations::delete::scan_volume_recursive` (the oracle-aware delete walker) — same idea, per-recursion-level.
+    3. The `refresh_listing` Tauri command (`commands/file_system/listing.rs`) — short-circuits the post-transfer redundant `list_directory` re-read entirely when the volume is keeping the cache fresh via `notify_mutation`. Without this, a 1k-entry MTP folder paid ~17 s + USB session collision after every transfer outcome, wedging the next user op.
+  Default `false` so a new backend without a real watcher won't accidentally claim freshness. **Freshness contract**: a `true` result does NOT mean the cache is byte-perfect with the device right now. Every backend has a debounce or settling window between a real change and the cache reflecting it: local FS ≈ 10 ms (FSEvents coalesce), SMB 200 ms (watcher debounce; > 50 events/dir triggers a `FullRefresh`), MTP 500 ms (event debouncer plus per-device polling; many cameras emit no events at all, so on those `true` means only "the device is reachable"). Callers must treat the result as "fresh as our most recent observation" — the same guarantee a `list_directory` call gives. The MTP and SMB checks are volume-level, not path-level: when the gate flips true, every path on that volume becomes oracle-eligible.
 
 ## Building a new volume