Bugfix: Use APFS-aware space check for copy validation

- `validate_disk_space` and `get_space_info_for_path` were using `statvfs` which reports only physically free blocks, ignoring purgeable space (APFS snapshots, iCloud caches)
- The status bar already used `NSURLVolumeAvailableCapacityForImportantUsageKey` (matching Finder), so the copy error dialog showed ~67 GB while the bar showed ~100 GB
- Both now call `crate::volumes::get_volume_space()` on macOS, falling back to `statvfs` on Linux
- Documented the gotcha in `write_operations/CLAUDE.md` and `volume/CLAUDE.md`

Author: vdavid

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

@@ -145,6 +145,9 @@ provides a manual upgrade path.
 **Decision**: Progress callbacks use `&dyn Fn(u64, u64) -> ControlFlow<()>`, not `FnMut`
 **Why**: The Volume trait is object-safe (`dyn Volume`), so callbacks must be `Fn` (not `FnMut`). Callers use `AtomicU64` for byte counters and `Cell<Instant>` for timestamps to mutate state inside a `Fn` closure. This avoids needing `RefCell` or `Mutex` in the hot path.
 
+**Gotcha**: On macOS, never use `statvfs` alone for disk space — use `NSURLVolumeAvailableCapacityForImportantUsageKey`
+**Why**: `statvfs` reports only physically free blocks and ignores purgeable space (APFS snapshots, iCloud caches), which can be tens of GB. This causes inconsistent numbers between the status bar (NSURL API) and copy validation (`statvfs`), and prematurely blocks copies that would succeed. `get_space_info_for_path` calls `crate::volumes::get_volume_space()` on macOS and falls back to `statvfs` on Linux.
+
 ## Testing
 
 - `in_memory_test.rs` — unit tests for `InMemoryVolume` (CRUD, sorting, concurrency, stress 50k entries)

apps/desktop/src-tauri/src/file_system/volume/local_posix.rs

@@ -319,8 +319,33 @@ fn copy_recursive(source: &Path, dest: &Path) -> Result<u64, VolumeError> {
     Ok(total_bytes)
 }
 
-/// Gets space information for a path using statvfs.
+/// Gets space information for a path.
+///
+/// On macOS, uses `NSURLVolumeAvailableCapacityForImportantUsageKey` which includes purgeable
+/// space (APFS snapshots, iCloud caches) — matching what Finder reports. Falls back to `statvfs`
+/// if the NSURL query fails. On Linux, uses `statvfs` directly (no purgeable space concept).
 fn get_space_info_for_path(path: &Path) -> Result<SpaceInfo, VolumeError> {
+    // On macOS, prefer the NSURL API that accounts for purgeable space.
+    #[cfg(target_os = "macos")]
+    {
+        if let Some(space) = crate::volumes::get_volume_space(&path.to_string_lossy()) {
+            // NSURL doesn't give us used_bytes directly, compute from total - available.
+            let used_bytes = space.total_bytes.saturating_sub(space.available_bytes);
+            return Ok(SpaceInfo {
+                total_bytes: space.total_bytes,
+                available_bytes: space.available_bytes,
+                used_bytes,
+            });
+        }
+    }
+
+    // Fallback (and Linux primary path): statvfs
+    get_space_info_statvfs(path)
+}
+
+/// Gets space information using `statvfs`. Used as the primary method on Linux and as a
+/// fallback on macOS.
+fn get_space_info_statvfs(path: &Path) -> Result<SpaceInfo, VolumeError> {
     use std::ffi::CString;
 
     let path_c = CString::new(path.to_string_lossy().as_bytes()).map_err(|e| VolumeError::IoError(e.to_string()))?;

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

@@ -188,6 +188,11 @@ permissions. The only metadata it doesn't preserve is birthtime (creation date)
 matter only on same-volume copies where we use `copyfile` anyway. Detection uses `st_dev` (device ID) for same-volume
 and `statfs.f_fstypename` for APFS. See `copy_strategy.rs` for the implementation.
 
+## Gotchas
+
+**Gotcha**: On macOS, never use `statvfs` alone for disk space checks — use `NSURLVolumeAvailableCapacityForImportantUsageKey`
+**Why**: `statvfs` reports only physically free blocks. On APFS, purgeable space (iCloud caches, APFS snapshots) can account for tens of GB that macOS will reclaim on demand. Using `statvfs` causes the "insufficient space" error to reject copies that would actually succeed, and shows a different available-space number than the status bar (which uses the NSURL API). `validate_disk_space` in `helpers.rs` calls `crate::volumes::get_volume_space()` on macOS and falls back to `statvfs` on Linux.
+
 ## Dependencies
 
 - `crate::file_system::volume` — `Volume` trait, `SpaceInfo`, `ScanConflict` (used by `volume_copy`)

apps/desktop/src-tauri/src/file_system/write_operations/helpers.rs

@@ -113,37 +113,19 @@ pub(crate) fn validate_destination_writable(_destination: &Path) -> Result<(), W
 }
 
 /// Checks available disk space on the destination volume against required bytes.
-/// Uses statvfs on Unix to query free space.
+///
+/// On macOS, uses `NSURLVolumeAvailableCapacityForImportantUsageKey` which includes purgeable
+/// space (APFS snapshots, iCloud caches) — matching what Finder reports. Falls back to `statvfs`
+/// if the NSURL query fails. On Linux, uses `statvfs` directly (no purgeable space concept).
 #[cfg(unix)]
 pub(crate) fn validate_disk_space(destination: &Path, required_bytes: u64) -> Result<(), WriteOperationError> {
-    use std::ffi::CString;
-    use std::mem::MaybeUninit;
-    use std::os::unix::ffi::OsStrExt;
-
-    let c_path = CString::new(destination.as_os_str().as_bytes()).map_err(|_| WriteOperationError::IoError {
-        path: destination.display().to_string(),
-        message: "Invalid path".to_string(),
-    })?;
-
-    let mut stat = MaybeUninit::<libc::statvfs>::uninit();
-    // SAFETY: c_path is a valid null-terminated C string, stat is a valid pointer
-    let result = unsafe { libc::statvfs(c_path.as_ptr(), stat.as_mut_ptr()) };
-    if result != 0 {
-        // Cannot determine space — continue and let the OS report ENOSPC if it happens
-        return Ok(());
-    }
-
-    // SAFETY: statvfs succeeded, stat is initialized
-    let stat = unsafe { stat.assume_init() };
-    // These casts are needed on macOS where f_bavail/f_frsize may not be u64
-    #[allow(
-        clippy::unnecessary_cast,
-        reason = "Required for macOS where statvfs fields are not u64"
-    )]
-    let available = stat.f_bavail as u64 * stat.f_frsize as u64;
+    let available = get_available_space(destination).unwrap_or({
+        // Cannot determine space — return u64::MAX so the check passes and we let the OS
+        // report ENOSPC if it actually happens during the copy.
+        u64::MAX
+    });
 
     if required_bytes > available {
-        // Determine volume name from mount point for a friendlier message
         let volume_name = destination
             .ancestors()
             .find(|p| p.parent().is_some_and(|pp| pp == Path::new("/Volumes")))
@@ -160,6 +142,48 @@ pub(crate) fn validate_disk_space(destination: &Path, required_bytes: u64) -> Re
     Ok(())
 }
 
+/// Returns available bytes for a path, using the best API for the platform.
+///
+/// macOS: `NSURLVolumeAvailableCapacityForImportantUsageKey` (includes purgeable space).
+/// Linux: `statvfs` `f_bavail * f_frsize`.
+#[cfg(unix)]
+fn get_available_space(path: &Path) -> Option<u64> {
+    // On macOS, prefer the NSURL API that accounts for purgeable space.
+    #[cfg(target_os = "macos")]
+    {
+        if let Some(space) = crate::volumes::get_volume_space(&path.to_string_lossy()) {
+            return Some(space.available_bytes);
+        }
+    }
+
+    // Fallback (and Linux primary path): statvfs
+    get_available_space_statvfs(path)
+}
+
+/// Returns available bytes using `statvfs`. Used as the primary method on Linux and as a
+/// fallback on macOS.
+#[cfg(unix)]
+fn get_available_space_statvfs(path: &Path) -> Option<u64> {
+    use std::ffi::CString;
+    use std::mem::MaybeUninit;
+    use std::os::unix::ffi::OsStrExt;
+
+    let c_path = CString::new(path.as_os_str().as_bytes()).ok()?;
+    let mut stat = MaybeUninit::<libc::statvfs>::uninit();
+    // SAFETY: c_path is a valid null-terminated C string, stat is a valid pointer
+    let result = unsafe { libc::statvfs(c_path.as_ptr(), stat.as_mut_ptr()) };
+    if result != 0 {
+        return None;
+    }
+    // SAFETY: statvfs succeeded, stat is initialized
+    let stat = unsafe { stat.assume_init() };
+    #[allow(
+        clippy::unnecessary_cast,
+        reason = "Required for macOS where statvfs fields are not u64"
+    )]
+    Some(stat.f_bavail as u64 * stat.f_frsize as u64)
+}
+
 #[cfg(not(unix))]
 pub(crate) fn validate_disk_space(_destination: &Path, _required_bytes: u64) -> Result<(), WriteOperationError> {
     Ok(())