Drag out: download phone/network files to Finder (M2)

Implements file promises so dropping a file from an MTP or smb2-native pane onto Finder/the Desktop downloads it there, under the exact filename Finder chose.

- `native_drag/fulfillment.rs`: plain-Rust fulfillment service (no AppKit, unit-testable). `fulfill(volume_id, source, dest)` resolves the source volume, busy-registers it (eject guard), notes the dest as a Cmdr-own write, then streams to the EXACT Finder leaf: a file via `open_read_stream` → `write_from_stream`, a folder via a hand-rolled recursive walk. On ANY `Err`, removes the partial file / created tree (the local writer doesn't self-clean on a source-read error — the disconnect-mid-stream failure mode). Carries a rendered `FriendlyError`.
- `native_drag/promises.rs`: the `define_class!` `NSFilePromiseProviderDelegate`. `fileNameForType:` (main thread) returns the known leaf; `writePromiseToURL:completionHandler:` (queue thread) `block_on`s the service and calls the `block2` completion (null = ok, `NSError` in domain `com.veszelovszki.cmdr.drag-out` = fail). One shared serial `NSOperationQueue` per session. Session-scoped storage with a two-store lifetime model (Send counters decide *when* to free; the `!Send` retained delegates/providers live main-thread-confined and are freed via a main-thread dispatch only once the gesture ended AND in-flight fulfillments drained — defends the fulfillment-after-session-end ordering).
- `native_drag/source.rs`: `CmdrDragSource` moved to `define_class!` with a session-key ivar; its `draggingSession:endedAtPoint:operation:` marks the gesture ended so the session frees once fulfillments drain.
- `native_drag/uti.rs`: pure extension→UTI mapping (fallback `public.data`, folders `public.folder`).
- `native_drag/mod.rs`: virtual sessions attach one `NSFilePromiseProvider` per item as the dragging-item writer; local sessions unchanged. Threads `source_volume_id` through `start_drag` and the two drag commands.
- `write_operations`: `pub(crate)` busy-volume seam (`register_external_volume_op` / `release_external_volume_op`) so the fulfillment service marks the source busy without being a real write op.
- Main-thread invariant: the service never does sync main-thread work from the queue thread (documented). App-quit abort rides stream `Drop` semantics + the cleanup contract; no new teardown hook needed.

No new Tauri commands (bindings unchanged). Tests: fulfillment headless vs the in-memory volume + tempdir (exact-leaf happy path, read-failure cleanup, unwritable dest, missing source, recursive folder, mid-folder cleanup, busy-volume seam), UTI mapping units, delegate smoke + NSError mapping + session-lifetime state machine.

Author: vdavid

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

@@ -51,7 +51,7 @@ pub fn start_drag_paths(
         return Err("No valid files to drag".to_string());
     }
     let locality = locality_for_volume(source_volume_id.as_deref());
-    run_drag_on_main_thread(&app, path_bufs, PathBuf::from(icon_path), locality)
+    run_drag_on_main_thread(&app, path_bufs, PathBuf::from(icon_path), locality, source_volume_id)
 }
 
 /// Stub for non-macOS platforms. Returns an error since drag is not yet implemented.
@@ -90,7 +90,7 @@ pub fn start_selection_drag(
     let volume_id = crate::file_system::listing::get_listing_volume_id_and_path(&listing_id).map(|(vid, _)| vid);
     let locality = locality_for_volume(volume_id.as_deref());
 
-    run_drag_on_main_thread(&app, paths, PathBuf::from(icon_path), locality)
+    run_drag_on_main_thread(&app, paths, PathBuf::from(icon_path), locality, volume_id)
 }
 
 /// Stub for non-macOS platforms. Returns an error since drag is not yet implemented.
@@ -117,12 +117,13 @@ fn run_drag_on_main_thread(
     paths: Vec<PathBuf>,
     icon_path: PathBuf,
     locality: DragSessionLocality,
+    source_volume_id: Option<String>,
 ) -> Result<(), String> {
     let window = app.get_webview_window("main").ok_or("Main window not found")?;
     let (tx, rx) = channel();
 
     app.run_on_main_thread(move || {
-        let result = native_drag::start_drag(&window, paths, &icon_path, locality);
+        let result = native_drag::start_drag(&window, paths, &icon_path, locality, source_volume_id.as_deref());
         let _ = tx.send(result);
     })
     .map_err(|e| format!("Failed to run on main thread: {}", e))?;

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

@@ -175,6 +175,7 @@ Drives "disable Eject while an op reads from / writes to this device" so a disco
 - The busy set is the union of every active op's `volume_ids`, minus `root` (never ejectable). `recompute_and_emit_busy_volumes` fires `volumes-busy-changed` only when membership changes — progress ticks don't churn it. Membership-by-union means two concurrent transfers to one device keep it busy until both finish, with no manual refcount.
 - **Where `volume_ids` come from**: the cross-volume transfer entry points (`copy_between_volumes`, `move_between_volumes`, `move_within_same_volume`) and the volume-aware `delete_files_start` carry the IDs; `copy_files_start` / `move_files_start` take a `volume_ids` param so the both-local branch of `copy_between_volumes` (which is how a local→USB / DMG copy lands) still marks the ejectable destination. The plain `copy_files` / `move_files` / `trash` commands pass `vec![]` — the unified transfer dialog only routes through them for same-`root` ops, where no ejectable volume is involved.
 - **Consumers**: `busy_volume_ids()` backs the `get_busy_volume_ids` bootstrap command, the `eject_volume` server-side guard (refuses a busy volume — the real safety net, since the picker's disable is only UX), and the native breadcrumb-menu builder (renders the Eject item disabled with a ` (busy)` suffix). The frontend `volume-busy-store.svelte.ts` subscribes to `volumes-busy-changed` and exposes `isVolumeBusy(id)` to disable the picker's eject controls. `init_busy_volume_emitter(app)` wires the emitter at startup (`lib.rs`).
+- **External (non-write-op) seam**: the drag-out file-promise fulfillment service (`native_drag::fulfillment`) marks the source volume busy while it streams a promise to a Finder destination, but it isn't a real write op (no `WRITE_OPERATION_STATE`, no progress events, no settle). The `pub(crate)` `register_external_volume_op(op_id, volume_ids)` / `release_external_volume_op(op_id)` pair (in `state.rs`, re-exported from `mod.rs`) is the seam: it touches only the `OPERATION_STATUS_CACHE` half that `recompute_and_emit_busy_volumes` reads, registering under `WriteOperationType::Copy` (the type only affects `list_active_operations` diagnostics; the busy set is type-agnostic). The fulfillment side wraps it in an RAII guard so release fires on every exit path.
 
 ## Settle contract
 

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

@@ -65,6 +65,10 @@ pub use state::{
     busy_volume_ids, cancel_all_write_operations, cancel_write_operation, get_operation_status,
     init_busy_volume_emitter, list_active_operations, resolve_write_conflict,
 };
+// External busy-volume seam for the drag-out fulfillment service (see
+// `state.rs` § "External busy-volume seam"). `pub(crate)` so only in-crate
+// callers (`native_drag::fulfillment`) reach it.
+pub(crate) use state::{register_external_volume_op, release_external_volume_op};
 #[allow(unused_imports, reason = "Public API re-exports for consumers of this module")]
 pub use types::{
     ConflictInfo, ConflictResolution, DryRunResult, OperationStatus, OperationSummary, ScanPreviewCancelledEvent,

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

@@ -352,6 +352,41 @@ pub(super) fn unregister_operation_status(operation_id: &str) {
     recompute_and_emit_busy_volumes();
 }
 
+// ============================================================================
+// External busy-volume seam (drag-out file promises)
+// ============================================================================
+//
+// `register_operation_status` / `unregister_operation_status` are `pub(super)`,
+// reachable only inside `write_operations`. The drag-out fulfillment service
+// (`crate::native_drag::fulfillment`) lives outside this module but needs the
+// same eject guard: while it streams bytes off an MTP/SMB device into a
+// Finder-chosen destination, the source volume must register as busy so the
+// user can't eject the phone mid-download (the server-side `eject_volume` guard
+// reads `busy_volume_ids()`). It is NOT a real write operation — no
+// `WRITE_OPERATION_STATE` entry, no progress events, no settle — so it can't go
+// through `start_write_operation`. This thin `pub(crate)` pair is the smallest
+// honest seam: it touches only the `OPERATION_STATUS_CACHE` half (which is what
+// `recompute_and_emit_busy_volumes` reads), keeping the busy set and the
+// `volumes-busy-changed` event firing exactly as a real op would.
+
+/// Marks `volume_ids` busy for the duration of an external (non-write-op)
+/// operation, keyed by `op_id`. Used by the drag-out fulfillment service to
+/// guard the source volume against eject while a promise is streaming. Pair
+/// every call with [`release_external_volume_op`] (the fulfillment service uses
+/// an RAII guard so release fires on every exit path).
+///
+/// Registers under `WriteOperationType::Copy` because a drag-out download IS a
+/// copy from the device to local disk — the type only affects diagnostics
+/// (`list_active_operations`), and the busy set itself is type-agnostic.
+pub(crate) fn register_external_volume_op(op_id: &str, volume_ids: Vec<String>) {
+    register_operation_status(op_id, WriteOperationType::Copy, volume_ids);
+}
+
+/// Clears the busy mark registered by [`register_external_volume_op`].
+pub(crate) fn release_external_volume_op(op_id: &str) {
+    unregister_operation_status(op_id);
+}
+
 // ============================================================================
 // Busy-volumes set (drives "disable Eject while an op touches this device")
 // ============================================================================

apps/desktop/src-tauri/src/lib.rs

@@ -397,6 +397,12 @@ pub fn run() {
             #[cfg(any(target_os = "macos", target_os = "linux"))]
             file_system::volume::smb::set_app_handle(app.handle().clone());
 
+            // Stash the AppHandle so the drag-out file-promise machinery can
+            // dispatch session cleanup (freeing the retained promise delegates)
+            // back to the AppKit main thread once a fulfillment drains.
+            #[cfg(target_os = "macos")]
+            native_drag::set_app_handle(app.handle().clone());
+
             // Network discovery (mDNS) startup is deferred. See the post-`load_settings`
             // block below. Starting mDNS here would trigger macOS's "Cmdr wants to find devices
             // on local networks" prompt at app launch even on first install before the user has

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

@@ -0,0 +1,145 @@
+# Native drag (macOS)
+
+macOS-only native drag-and-drop OUT of Cmdr. Builds the `NSDraggingSession` that carries dragged
+files to other apps (Finder, terminals, editors). Driven by the `start_selection_drag` /
+`start_drag_paths` commands in `commands/file_system/drag.rs`, which hop to the AppKit main thread
+and call `start_drag`.
+
+The whole module is `#[cfg(target_os = "macos")]`.
+
+## Files
+
+| File | Role |
+|------|------|
+| `mod.rs` | `start_drag`: builds the `NSDraggingItem`s + drag image, attaches per-item pasteboard writers, begins the session. Local sessions get plain `NSPasteboardItem`s; virtual sessions get `NSFilePromiseProvider`s. |
+| `type_plan.rs` | Pure, locality-aware pasteboard composition (`plan_pasteboard_items`). Local = file-url + text + filenames; virtual = empty (the textClipping fix). Unit-tested policy. |
+| `source.rs` | `CmdrDragSource` (`define_class!`, `MainThreadOnly`): the `NSDraggingSource`. Returns the permissive operation mask and, on `draggingSession:endedAtPoint:operation:`, tells the promise machinery the gesture ended so a virtual session's objects can be freed. |
+| `promises.rs` | The file-promise providers + delegate (`CmdrPromiseDelegate`), the shared serial queue, the session-lifetime storage, and the `NSError` mapping. |
+| `fulfillment.rs` | The plain-Rust fulfillment service: downloads a virtual file to the Finder-chosen destination. NO AppKit; unit-testable. |
+| `uti.rs` | Pure filename-extension → UTI mapping for promise providers (`public.jpeg`, …, fallback `public.data`; folders `public.folder`). |
+
+## How drag-out works
+
+1. The FE starts a drag; the command resolves the session's **locality** (`locality_for_volume`,
+   keyed on `Volume::supports_local_fs_access()`) and the source volume id, and calls `start_drag`.
+2. `start_drag` (on the main thread) builds one `NSDraggingItem` per file:
+   - **Local session**: writer is an `NSPasteboardItem` filled from the pure type plan (file-url +
+     shell-escaped text + legacy filenames). Source carries `NO_PROMISE_SESSION`.
+   - **Virtual session** (MTP, direct SMB, search-results): writer is an `NSFilePromiseProvider`
+     per item, carrying NO legacy types. The providers register their delegates under a fresh
+     `session_key`; the source carries that key.
+3. Dropping on **Finder** invokes the promise delegate, which streams the real bytes off the device
+   into the Finder-chosen destination via the fulfillment service. Dropping back **into Cmdr**
+   still fires wry's drop event (empty paths, no panic) and the recorded-identity self-drag path
+   handles it. Dropping on a **terminal** from a virtual pane is a clean no-op (no text to insert).
+
+## File promises (the drag-out-to-Finder feature)
+
+When Finder accepts a promise drop, it calls the delegate per item:
+
+- `filePromiseProvider:fileNameForType:` (MAIN thread) — returns the leaf name we already know,
+  zero I/O.
+- `filePromiseProvider:writePromiseToURL:completionHandler:` (operation-queue thread) — `block_on`s
+  the async `fulfillment::fulfill` and calls the completion block with `null` (success) or a mapped
+  `NSError` (failure).
+- `operationQueueForFilePromiseProvider:` — returns ONE shared serial queue per drag session.
+
+### Fulfillment service (`fulfillment.rs`)
+
+`fulfill(source_volume_id, source_path, dest_path)`: resolve the volume → busy-register the source
+(eject guard) → `note_pending_write_for_cmdr(dest)` (suppress the downloads toast) → stream to the
+EXACT Finder leaf. A **file** goes `open_read_stream` → `write_from_stream(dest, …)`; a **folder**
+is a hand-rolled recursive walk (`create_dir` → list → mkdir → per-file stream), because the
+cross-volume copy engine derives landed names from source basenames and can't target a
+Finder-renamed root.
+
+**Cleanup contract (load-bearing)**: on ANY `Err`, the destination this fulfillment created is
+removed before returning. `LocalPosixVolume::write_from_stream` self-cleans its partial ONLY on the
+cancel branch, NOT on a propagated source-read error (device unplugged mid-stream) — exactly the
+promise failure mode. So the service removes the partial file (single file) or the whole created
+tree (`remove_dir_all`, safe because the dest is a fresh Finder-created directory) itself. Pinned by
+`read_failure_midstream_leaves_no_file_at_dest…` and `folder_error_midstream_removes_the_created_tree`.
+
+**Main-thread invariant**: the service never performs synchronous main-thread work from the queue
+thread (volume I/O + a cheap downloads-watcher mutex, no `run_on_main_thread`), so `block_on`-ing it
+on the queue thread can't deadlock against a busy main thread.
+
+### Delegate-lifetime model (the M0-spike gotcha)
+
+**`NSFilePromiseProvider.delegate` is WEAK** — the provider doesn't retain its delegate. A delegate
+that's a drag-start local would drop when `start_drag` returns, zeroing the provider's weak ref, and
+Finder would query a nil delegate and silently produce no file. So each session's delegates +
+providers live in process-global storage in `promises.rs`, freed only when BOTH the gesture has
+ended AND every in-flight fulfillment has completed.
+
+Two stores, because `Retained<…>` AppKit objects aren't `Send` but the in-flight counter is touched
+from the queue thread:
+
+- **`COUNTERS`** (`Send`, any-thread `Mutex<HashMap>`): `{ in_flight, gesture_ended }`. Decides
+  *when* cleanup fires.
+- **The retained store** (`thread_local!`, main-thread-confined): the `Retained` delegates +
+  providers. Registered on main at drag-start; freed via a main-thread dispatch (`run_on_main`) when
+  the counters say "ended and drained." The shared queue rides in the delegate's ivar as a
+  `SendQueue` (NSOperationQueue is documented thread-safe), so returning it from the queue thread
+  needs no main-thread hop.
+
+**Ordering defended**: AppKit ends the session at the DROP, but Finder pumps the fulfillment queue
+AFTER. Freeing on session-end alone would yank a delegate mid-write. Gating on "ended AND
+in_flight == 0" keeps everything alive across both. A fulfillment finishing after session-end frees
+the session itself (its `leave_fulfillment` sees the drained, ended state). Pinned by
+`session_counters_wait_for_in_flight_to_drain`.
+
+### Busy-volume seam
+
+The fulfillment service marks the source volume busy for the eject guard via the `pub(crate)`
+`write_operations::{register_external_volume_op, release_external_volume_op}` seam (an RAII
+`BusyGuard` releases on every exit). This is the smallest honest seam: a drag-out download isn't a
+real write op (no `WRITE_OPERATION_STATE`, no progress events), but it must guard the device the
+same way, so it touches only the `OPERATION_STATUS_CACHE` half that `recompute_and_emit_busy_volumes`
+reads. Pinned by `source_volume_is_busy_during_fulfillment_and_released_after`.
+
+### App-quit / device-disconnect abort
+
+There's no user-initiated cancel of an in-flight fulfillment in v1 (Finder owns the gesture, no
+progress UI). In-flight fulfillments end via stream `Drop` semantics: app quit drops the tokio
+runtime and the source `VolumeReadStream` (MTP's `Drop` cancels the USB transfer, SMB's signals its
+producer); a device disconnect surfaces as a `next_chunk` read error. Either way the cleanup contract
+removes the partial. No explicit teardown hook is needed beyond the existing runtime shutdown.
+
+## NSError mapping
+
+A `FulfillError` carries a rendered `FriendlyError`. The delegate maps it to an `NSError` in domain
+`com.veszelovszki.cmdr.drag-out` with the friendly title as `localizedDescription` (Finder shows its
+own alert). A cancelled fulfillment uses the `NSUserCancelledError` code (3072) so Finder stays
+quiet; a real failure uses code 1 and shows the title.
+
+## Testing
+
+- `fulfillment.rs`: headless against `InMemoryVolume` + tempdir. Happy path asserts the landed
+  filename EQUALS the Finder-chosen leaf (the regression guard against the rejected copy-engine
+  mismatch). Plus read-failure cleanup, unwritable dest, missing source, recursive folder, mid-folder
+  cleanup, and the busy-volume seam (drive a blocking stream, assert busy during + released after).
+- `uti.rs`: extension → UTI mapping units.
+- `promises.rs`: delegate smoke (construct a provider, `fileNameForType` returns the leaf), NSError
+  domain/title/code mapping, and the COUNTERS session-lifetime state machine. The AppKit-touching
+  tests guard on `MainThreadMarker::new()` and skip off-main (nextest runs tests on worker threads).
+- `type_plan.rs`: the pure pasteboard policy (local byte-identical, virtual empty across every item).
+
+The Finder leg itself can't be automated honestly (Finder owns the drop gesture); the manual
+protocol in `docs/specs/drag-out-file-promises-plan.md` § M4 covers it with the virtual-MTP rig.
+
+## Gotchas
+
+**Gotcha**: The promise delegate is NOT `MainThreadOnly`.
+**Why**: `writePromiseToURL:completionHandler:` runs on the operation-queue thread, so the delegate
+object must be usable off-main. The one main-thread-only method (`fileNameForType:`) gets its
+`MainThreadMarker` from the protocol signature, so the class-level marker isn't needed. The ivars are
+all `Send + Sync` (the queue via the `SendQueue` wrapper). The drag SOURCE (`source.rs`) IS
+`MainThreadOnly` because `NSDraggingSource` requires it.
+
+**Gotcha**: `session_key` is a monotonic counter, NOT the drag sequence number.
+**Why**: The promise delegates must register BEFORE the drag begins (their weak refs must be alive
+the instant Finder might query them), but `NSDraggingSession.draggingSequenceNumber` is only known
+AFTER `beginDraggingSessionWithItems:…` returns. A monotonic key generated up front and stashed on
+the source object sidesteps the chicken-and-egg, and the source reads its own key back in the end
+callback — no session→key mapping needed.