Write ops: per-op settle event for honest cancel UX (M4)

- New `write-settled` Tauri event, emitted exactly once per op after the spawned background task fully returns. Implemented via a `WriteSettledGuard` RAII struct whose `Drop` fires the event — runs even on handler panic, so the FE never hangs waiting for a settle that never comes.
- Wired into all five spawn-task entry points: `start_write_operation` (local copy/move/delete/trash), the volume-delete branch in `delete_files_start`, `copy_between_volumes`, `move_between_volumes`, and `move_within_same_volume`. Cache cleanup happens before the guard drops; ordering guarantee: terminal event (`write-cancelled` / `write-complete` / `write-error`) → cache cleanup → `write-settled`.
- FE `TransferProgressDialog` gates the cancel close on BOTH `write-cancelled` AND `write-settled`. The dialog stays in "Cancelling…" until settle lands, then applies the existing 400 ms display floor and closes. Defensive against out-of-order delivery. Complete / error paths are unchanged.
- After 200 ms of waiting for settle, the label gains "(finishing USB transfers)" so users see real work, not a generic spinner.
- 4 backend tests pin the guard invariants (single fire, panic safety, ordering). 3 backend integration tests pin volume-delete cancel / complete / error each emit settle. 4 Vitest tests pin the FE dialog's two-condition close, out-of-order ordering protection, and operationId filtering. 1 Playwright spec covers the full MTP cancel-then-F8-again flow.
- Docs: new "Settle contract" section in `write_operations/CLAUDE.md`; "Cancel close is two-condition" gotcha added in `file-operations/CLAUDE.md`.

Author: vdavid

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

@@ -209,13 +209,41 @@ exits, partial files or staging directories may remain on disk. These use the `.
 | `write-complete` | Operation finished successfully |
 | `write-cancelled` | Operation cancelled (includes `rolled_back` flag) |
 | `write-error` | Operation failed. Carries `error: WriteOperationError` (typed) plus `friendly: FriendlyError` (rendered title/explanation/suggestion + category) populated by `WriteErrorEvent::new` via `friendly_from_write_error`. The FE renders the `friendly` payload directly in `TransferErrorDialog` and applies category-based colors. |
+| `write-settled` | Emitted once per op after the spawned background task fully returns. See [Settle contract](#settle-contract). |
 | `write-source-item-done` | All files for a top-level source item processed (for gradual deselection) |
 | `dry-run-complete` | `config.dry_run == true` (returns `DryRunResult`) |
 | `scan-preview-progress` | During `start_scan_preview` |
 | `scan-preview-complete` | Preview scan finished |
 | `scan-preview-error` | Preview scan failed |
 | `scan-preview-cancelled` | Preview scan cancelled |
 
+## Settle contract
+
+`write-settled` fires exactly once per operation, after the spawned background task has fully torn down — including
+in-flight USB / network teardown that may briefly outlive the `write-cancelled` emit. The FE uses it to gate the
+"Cancelling…" dialog close so the user can't dispatch a new op against a still-tearing-down volume (the wedge mode
+the M2 cancel propagation already shortens but doesn't eliminate).
+
+**Ordering**: `write-settled` always fires AFTER the terminal outcome event (`write-complete` / `write-cancelled` /
+`write-error`) for the same `operation_id`. The BE guarantees this by placing the settle emit in a `WriteSettledGuard`
+RAII struct whose `Drop` runs at the very end of the spawn-task scope, AFTER all the conditional terminal-event emits.
+
+**Guard pattern**: every spawn-task entry point (`start_write_operation` in `mod.rs`, the volume-delete branch in
+`delete_files_start`, `copy_between_volumes`, `move_between_volumes`, `move_within_same_volume`) constructs a
+`WriteSettledGuard` at the top of the spawned task. The guard's `Drop` impl emits the event. This makes the emit
+panic-safe: even if the handler closure panics and the task exits via `JoinError`, the guard still drops as part of
+stack unwinding, so the FE never hangs waiting for a settle that never comes. See
+`settle_event_tests.rs::settled_fires_on_panic_unwind` for the safety-net pin.
+
+**Payload**: `{ operationId: String, operationType, volumeId: Option<String> }`. The `volume_id` is best-effort: filled
+with the source volume's display name for volume-aware ops (copy/move between volumes, volume delete), `None` for pure
+local-FS operations. The FE currently filters only by `operationId`; `volume_id` is for diagnostics and forward
+compatibility.
+
+**Tests**: `settle_event_tests.rs` pins the guard's invariants (single fire, panic safety, ordering relative to the
+terminal event). `volume_cancel_tests::volume_*_emits_write_settled_event` pin the integration shape against the
+volume-delete handler.
+
 ## Key decisions
 
 **Decision**: `walk_dir_recursive` dedupes hardlinks by inode when summing `total_bytes`.

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

@@ -53,7 +53,7 @@ use helpers::{
 use move_op::move_files_with_progress;
 #[cfg(not(test))]
 use state::WriteOperationState;
-use state::{WRITE_OPERATION_STATE, register_operation_status, unregister_operation_status};
+use state::{WRITE_OPERATION_STATE, WriteSettledGuard, register_operation_status, unregister_operation_status};
 use trash::trash_files_with_progress;
 
 // Re-export public types
@@ -68,7 +68,7 @@ pub use types::{
     ScanPreviewCompleteEvent, ScanPreviewErrorEvent, ScanPreviewProgressEvent, ScanPreviewStartResult,
     ScanProgressEvent, SortColumn, SortOrder, WriteCancelledEvent, WriteCompleteEvent, WriteConflictEvent,
     WriteErrorEvent, WriteOperationConfig, WriteOperationError, WriteOperationPhase, WriteOperationStartResult,
-    WriteOperationType, WriteProgressEvent,
+    WriteOperationType, WriteProgressEvent, WriteSettledEvent,
 };
 
 // Re-export for tests (these are pub(crate) in helpers.rs and state.rs)
@@ -128,14 +128,19 @@ where
     tokio::spawn(async move {
         let operation_id_for_cleanup = operation_id_for_spawn.clone();
         let app_for_error = app.clone();
+        // RAII guard: emits `write-settled` when this task exits, no matter
+        // how (handler success, error, cancel, or panic via JoinError). FE
+        // gates the "Cancelling…" dialog close on this event so the user
+        // can't dispatch a new op against a still-tearing-down volume.
+        let _settled_guard = WriteSettledGuard::new(
+            app_for_error.clone(),
+            operation_id_for_cleanup.clone(),
+            operation_type,
+            None,
+        );
 
         let result = tokio::task::spawn_blocking(move || handler(app, operation_id_for_spawn, state)).await;
 
-        if let Ok(mut cache) = WRITE_OPERATION_STATE.write() {
-            cache.remove(&operation_id_for_cleanup);
-        }
-        unregister_operation_status(&operation_id_for_cleanup);
-
         use tauri::Emitter;
         match result {
             Ok(Ok(())) => {} // Handler already emitted write-complete or write-cancelled
@@ -146,15 +151,15 @@ where
                 // Handler error (validation, I/O, etc.): emit write-error as safety net
                 let _ = app_for_error.emit(
                     "write-error",
-                    WriteErrorEvent::new(operation_id_for_cleanup, operation_type, e),
+                    WriteErrorEvent::new(operation_id_for_cleanup.clone(), operation_type, e),
                 );
             }
             Err(join_error) => {
                 // Panic/abort in spawn_blocking
                 let _ = app_for_error.emit(
                     "write-error",
                     WriteErrorEvent::new(
-                        operation_id_for_cleanup,
+                        operation_id_for_cleanup.clone(),
                         operation_type,
                         WriteOperationError::IoError {
                             path: String::new(),
@@ -164,6 +169,14 @@ where
                 );
             }
         }
+
+        // Cache cleanup happens AFTER terminal events are emitted, BEFORE the
+        // settle guard drops (the guard is the very last thing in scope).
+        // Order: terminal event → cache removal → `write-settled` via Drop.
+        if let Ok(mut cache) = WRITE_OPERATION_STATE.write() {
+            cache.remove(&operation_id_for_cleanup);
+        }
+        unregister_operation_status(&operation_id_for_cleanup);
     });
 
     Ok(WriteOperationStartResult {
@@ -272,6 +285,16 @@ pub async fn delete_files_start(
         tokio::spawn(async move {
             let operation_id_for_cleanup = operation_id_for_spawn.clone();
             let app_for_error = app.clone();
+            // RAII settle guard: fires `write-settled` when the task exits.
+            // Drop runs last in scope so the FE sees the terminal event
+            // (write-cancelled / write-error / write-complete) first, then
+            // settle, then is free to clear the dialog.
+            let _settled_guard = WriteSettledGuard::new(
+                app_for_error.clone(),
+                operation_id_for_cleanup.clone(),
+                WriteOperationType::Delete,
+                Some(volume_id_str.clone()),
+            );
 
             let volume = match crate::file_system::get_volume_manager().get(&volume_id_str) {
                 Some(v) => v,
@@ -307,22 +330,22 @@ pub async fn delete_files_start(
             )
             .await;
 
-            if let Ok(mut cache) = WRITE_OPERATION_STATE.write() {
-                cache.remove(&operation_id_for_cleanup);
-            }
-            unregister_operation_status(&operation_id_for_cleanup);
-
             use tauri::Emitter;
             match result {
                 Ok(()) => {}
                 Err(ref e) if matches!(e, WriteOperationError::Cancelled { .. }) => {}
                 Err(e) => {
                     let _ = app_for_error.emit(
                         "write-error",
-                        WriteErrorEvent::new(operation_id_for_cleanup, WriteOperationType::Delete, e),
+                        WriteErrorEvent::new(operation_id_for_cleanup.clone(), WriteOperationType::Delete, e),
                     );
                 }
             }
+
+            if let Ok(mut cache) = WRITE_OPERATION_STATE.write() {
+                cache.remove(&operation_id_for_cleanup);
+            }
+            unregister_operation_status(&operation_id_for_cleanup);
         });
 
         Ok(WriteOperationStartResult {
@@ -379,6 +402,8 @@ mod move_integration_test;
 #[cfg(test)]
 mod scan_preview_oracle_tests;
 #[cfg(test)]
+mod settle_event_tests;
+#[cfg(test)]
 mod tests;
 #[cfg(test)]
 mod transaction_integration_test;

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

@@ -0,0 +1,184 @@
+//! Tests for the `write-settled` per-op event (M4 of `cancel-settled-plan.md`).
+//!
+//! The `WriteSettledGuard` RAII pattern emits exactly one `write-settled`
+//! event when the spawned task fully returns — happy path, error path,
+//! cancellation, or panic. These tests pin the contract.
+//!
+//! Production code emits via `app.emit("write-settled", ...)` from inside
+//! the guard's `Drop`. Tests use the alternate `new_with_sink` constructor to
+//! redirect into a `CollectorEventSink`, so the full lifecycle runs without
+//! a Tauri runtime.
+
+use std::sync::Arc;
+
+use super::state::WriteSettledGuard;
+use super::types::{CollectorEventSink, OperationEventSink, WriteOperationType, WriteSettledEvent};
+
+/// Bridge sink that keeps a direct handle to the underlying `CollectorEventSink`
+/// for inspection. Needed because the guard takes `Arc<dyn OperationEventSink>`,
+/// and `dyn OperationEventSink` isn't downcastable.
+struct Bridge {
+    inner: Arc<CollectorEventSink>,
+}
+
+impl OperationEventSink for Bridge {
+    fn emit_progress(&self, e: super::types::WriteProgressEvent) {
+        self.inner.emit_progress(e);
+    }
+    fn emit_complete(&self, e: super::types::WriteCompleteEvent) {
+        self.inner.emit_complete(e);
+    }
+    fn emit_cancelled(&self, e: super::types::WriteCancelledEvent) {
+        self.inner.emit_cancelled(e);
+    }
+    fn emit_error(&self, e: super::types::WriteErrorEvent) {
+        self.inner.emit_error(e);
+    }
+    fn emit_conflict(&self, e: super::types::WriteConflictEvent) {
+        self.inner.emit_conflict(e);
+    }
+    fn emit_source_item_done(&self, e: super::types::WriteSourceItemDoneEvent) {
+        self.inner.emit_source_item_done(e);
+    }
+    fn emit_scan_progress(&self, e: super::types::ScanProgressEvent) {
+        self.inner.emit_scan_progress(e);
+    }
+    fn emit_scan_conflict(&self, c: super::types::ConflictInfo) {
+        self.inner.emit_scan_conflict(c);
+    }
+    fn emit_dry_run_complete(&self, r: super::types::DryRunResult) {
+        self.inner.emit_dry_run_complete(r);
+    }
+    fn emit_settled(&self, e: WriteSettledEvent) {
+        self.inner.emit_settled(e);
+    }
+}
+
+fn pair() -> (Arc<dyn OperationEventSink>, Arc<CollectorEventSink>) {
+    let inner = Arc::new(CollectorEventSink::new());
+    let bridge: Arc<dyn OperationEventSink> = Arc::new(Bridge {
+        inner: Arc::clone(&inner),
+    });
+    (bridge, inner)
+}
+
+#[test]
+fn settled_fires_once_on_normal_drop() {
+    let (sink, collector) = pair();
+
+    {
+        let _guard =
+            WriteSettledGuard::new_with_sink(sink, "op-happy", WriteOperationType::Copy, Some("test-vol".to_string()));
+        // Guard drops at end of scope.
+    }
+
+    let settled = collector.settled.lock().unwrap();
+    assert_eq!(settled.len(), 1, "guard must fire exactly one write-settled event");
+    assert_eq!(settled[0].operation_id, "op-happy");
+    assert_eq!(settled[0].operation_type, WriteOperationType::Copy);
+    assert_eq!(settled[0].volume_id.as_deref(), Some("test-vol"));
+}
+
+#[test]
+fn settled_fires_with_none_volume_for_local_ops() {
+    let (sink, collector) = pair();
+
+    drop(WriteSettledGuard::new_with_sink(
+        sink,
+        "op-local",
+        WriteOperationType::Delete,
+        None,
+    ));
+
+    let settled = collector.settled.lock().unwrap();
+    assert_eq!(settled.len(), 1);
+    assert!(
+        settled[0].volume_id.is_none(),
+        "local-FS settle event must carry volume_id=None"
+    );
+}
+
+#[test]
+fn settled_fires_on_panic_unwind() {
+    // The guard is in scope when the closure panics. `catch_unwind` swallows
+    // the panic, but the guard's Drop still runs as part of stack unwinding.
+    // This is the panic-safety property the FE relies on so the dialog can
+    // always clear, even on a backend bug.
+    let (sink, collector) = pair();
+
+    let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(move || {
+        let _guard =
+            WriteSettledGuard::new_with_sink(sink, "op-panic", WriteOperationType::Move, Some("v".to_string()));
+        panic!("simulated handler panic");
+    }));
+
+    assert!(result.is_err(), "the closure must have panicked");
+    let settled = collector.settled.lock().unwrap();
+    assert_eq!(
+        settled.len(),
+        1,
+        "settle event must fire even when the spawned task panicked: the FE would hang otherwise"
+    );
+    assert_eq!(settled[0].operation_id, "op-panic");
+}
+
+#[test]
+fn settled_event_order_is_after_terminal_outcome_event() {
+    // The FE depends on this ordering: it sees the terminal event
+    // (write-cancelled / write-complete / write-error) first, knows the
+    // outcome, then sees write-settled and knows the volume is ready.
+    // Reversing would race: the dialog could try to close on settle before
+    // it knows the outcome.
+    //
+    // Mirrors how production spawn tasks emit: handler emits the terminal
+    // event, then state cleanup runs, then the guard's Drop emits settled.
+    let (sink, collector) = pair();
+    let op_id = "op-order".to_string();
+
+    {
+        let _guard = WriteSettledGuard::new_with_sink(
+            Arc::clone(&sink),
+            op_id.clone(),
+            WriteOperationType::Delete,
+            Some("v1".to_string()),
+        );
+        // Simulate the handler's terminal emit.
+        sink.emit_cancelled(super::types::WriteCancelledEvent {
+            operation_id: op_id.clone(),
+            operation_type: WriteOperationType::Delete,
+            files_processed: 7,
+            rolled_back: false,
+        });
+        // Guard's Drop runs at end of scope, AFTER the cancelled emit above.
+    }
+
+    let cancelled = collector.cancelled.lock().unwrap();
+    let settled = collector.settled.lock().unwrap();
+    assert_eq!(cancelled.len(), 1, "cancelled should fire first");
+    assert_eq!(settled.len(), 1, "settled should fire second");
+    assert_eq!(settled[0].operation_id, op_id);
+}
+
+#[test]
+fn settled_fires_for_every_operation_type() {
+    // Trivial coverage: each op-type variant flows through the same path,
+    // but we pin it so a future refactor that branches on type won't
+    // accidentally drop one.
+    for op_type in [
+        WriteOperationType::Copy,
+        WriteOperationType::Move,
+        WriteOperationType::Delete,
+        WriteOperationType::Trash,
+    ] {
+        let (sink, collector) = pair();
+        drop(WriteSettledGuard::new_with_sink(
+            sink,
+            format!("op-{:?}", op_type),
+            op_type,
+            None,
+        ));
+        let settled = collector.settled.lock().unwrap();
+        assert_eq!(settled.len(), 1, "settle must fire once per op_type={:?}", op_type);
+        assert_eq!(settled[0].operation_type, op_type);
+    }
+}