updated workflow

- B23: Generate synthetic StagedWrite sidecars in rescue_scratch when sidecar is corrupted
- B26: Add open_count and unlinked state fields to defer node removal and cache eviction on unlinked open files until release
- B27: Discard orphaned write revisions for local UIDs unlinked prior to upload
- B28: Add emergency_evict to ContentCache for LRU blob eviction upon ENOSPC
- B29: Implement FUSE forget handler and forget_lookup in state to prune unreferenced inodes
- B33: Quarantine failing drain ops on HTTP 40x / max retries to unblock offline sync queue
- docs: Track audit items B18-B36 in docs/BUGS.md with fix details and verification results

.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  rust:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install native dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            pkg-config \
+            libfuse3-dev \
+            libgtk-4-dev \
+            libadwaita-1-dev \
+            libwebkitgtk-6.0-dev \
+            libsecret-1-dev \
+            libdbus-1-dev
+
+      - name: Install minimum supported Rust
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: '1.96'
+          components: rustfmt, clippy
+
+      - uses: swatinem/rust-cache@v2
+
+      - name: Formatting
+        run: cargo fmt --all -- --check
+
+      - name: Lints
+        run: cargo clippy --workspace --all-targets -- -D warnings
+
+      - name: Unit tests
+        run: cargo test --workspace --locked
+
+      - name: Acceptance runner safety guard
+        run: |
+          if scripts/fuse-acceptance.sh /tmp >acceptance.out 2>&1; then
+            echo "runner unexpectedly accepted a non-FUSE path"
+            exit 1
+          fi
+          grep -q "refusing primary non-FUSE path" acceptance.out
+
+  # Real Proton credentials and /dev/fuse deliberately do not run on pull
+  # requests. Follow docs/TESTING.md on a dedicated test-account runner.

Cargo.lock

@@ -3518,7 +3518,7 @@ checksum = "35fb2e5f958ec131621fdd531e9fc186ed768cbe395337403ae56c17a74c68ec"
 
 [[package]]
 name = "pdfs-cli"
-version = "0.7.0"
+version = "0.7.1"
 dependencies = [
  "anyhow",
  "clap 4.6.2",
@@ -3533,7 +3533,7 @@ dependencies = [
 
 [[package]]
 name = "pdfs-core"
-version = "0.7.0"
+version = "0.7.1"
 dependencies = [
  "directories",
  "ignore",
@@ -3552,7 +3552,7 @@ dependencies = [
 
 [[package]]
 name = "pdfs-fuse"
-version = "0.7.0"
+version = "0.7.1"
 dependencies = [
  "fuser",
  "image",
@@ -3568,7 +3568,7 @@ dependencies = [
 
 [[package]]
 name = "pdfs-gui"
-version = "0.7.0"
+version = "0.7.1"
 dependencies = [
  "anyhow",
  "async-channel",

Cargo.toml

@@ -3,7 +3,7 @@ resolver = "2"
 members = ["crates/pdfs-core", "crates/pdfs-fuse", "crates/pdfs-cli", "crates/pdfs-gui"]
 
 [workspace.package]
-version = "0.7.0"
+version = "0.7.1"
 edition = "2024"
 license = "MIT"
 authors = ["Nils Pukropp <contact@narl.io>"]

README.md

@@ -6,7 +6,9 @@ A fast, unofficial Proton Drive client for Linux. This client features an advanc
 
 - **Files-on-Demand (FUSE)**: Mount your Proton Drive as a virtual filesystem where files are downloaded only when opened, utilizing smart block-level caching and disk-backed writes.
 - **Command-Line Interface (CLI)**: Manage your drive, authenticate, and monitor sync status directly from the terminal.
-- **Non-Blocking GTK4 Desktop App**: Browse files, manage pins, and configure options through a modern, native GUI with a fully non-blocking asynchronous main loop.
+- **Non-Blocking GTK4 Desktop App**: Browse files, manage pins, configure options, and monitor active transfers through a modern, native GUI with a fully non-blocking asynchronous main loop.
+- **Shared Links & Invites**: Browse files shared with you by other users, and view/manage your own public shared links directly in the GUI.
+- **Local Backup (Computers)**: Sync and back up local directories (like Downloads, Documents, Pictures, etc.) directly to your Proton Drive account.
 - **System Tray Integration**: Background indicator for status monitoring, quick actions, and fast sync controls.
 - **Fuzzy Search Launcher Prompt (HUD)**: A Google Drive-style search launcher (`pdfs-prompt`) for finding and opening files or folders instantly, ideal for binding to a system-wide hotkey.
 - **Secure Credential Storage**: Integrates with the system Secret Service (GNOME Keyring, KWallet, etc.) with smart in-memory credential caching to avoid UI thread blockages.
@@ -92,6 +94,11 @@ For the local metadata database and content cache:
 the database while it runs, so it is a deliberate operation rather than
 something the daemon does on a timer.
 
+Before a release, run the real-kernel acceptance suite against a dedicated test
+account and mount. See [`docs/TESTING.md`](docs/TESTING.md); it includes optional
+two-mount convergence checks and confines destructive operations to a fresh
+test directory.
+
 ## Scripting (`--json`)
 
 Query commands accept a global `--json` flag and emit machine-readable output:
@@ -136,11 +143,16 @@ The client includes several optimizations designed for high efficiency, a low me
     <td align="center" width="50%"><img src="images/files.png" alt="Files Browser" width="100%"><br><sub><b>Files Browser</b></sub></td>
   </tr>
   <tr>
-    <td align="center" width="50%"><img src="images/photos.png" alt="Photos Timeline" width="100%"><br><sub><b>Photos Timeline</b></sub></td>
-    <td align="center" width="50%"><img src="images/prompt.png" alt="Search Launcher Prompt" width="100%"><br><sub><b>Search Launcher Prompt</b></sub></td>
+    <td align="center" width="50%"><img src="images/shared.png" alt="Shared Links" width="100%"><br><sub><b>Shared Links</b></sub></td>
+    <td align="center" width="50%"><img src="images/shared_with_me.png" alt="Shared with me" width="100%"><br><sub><b>Shared with me</b></sub></td>
   </tr>
   <tr>
-    <td align="center" colspan="2"><img src="images/settings.png" alt="Settings" width="50%"><br><sub><b>Settings</b></sub></td>
+    <td align="center" width="50%"><img src="images/computers.png" alt="Local Backups (Computers)" width="100%"><br><sub><b>Local Backups (Computers)</b></sub></td>
+    <td align="center" width="50%"><img src="images/photos.png" alt="Photos Timeline" width="100%"><br><sub><b>Photos Timeline</b></sub></td>
+  </tr>
+  <tr>
+    <td align="center" width="50%"><img src="images/prompt.png" alt="Search Launcher Prompt" width="100%"><br><sub><b>Search Launcher Prompt</b></sub></td>
+    <td align="center" width="50%"><img src="images/settings.png" alt="Settings" width="100%"><br><sub><b>Settings</b></sub></td>
   </tr>
 </table>
 

crates/pdfs-cli/src/main.rs

@@ -1,7 +1,9 @@
 //! `pdfs` — command-line front-end for the Proton Drive Linux client.
 
 use std::collections::HashMap;
+use std::fs::OpenOptions;
 use std::io::Write;
+use std::os::unix::fs::FileTypeExt;
 use std::path::{Path, PathBuf};
 use std::sync::Arc;
 
@@ -1740,16 +1742,95 @@ fn cmd_cache_inspect(deep: bool) -> Result<()> {
     }
 }
 
-/// One line of the `diagnose` report.
-fn check(label: &str, ok: bool, detail: impl AsRef<str>) -> bool {
-    let mark = if ok { "ok  " } else { "FAIL" };
-    let detail = detail.as_ref();
-    if detail.is_empty() {
-        println!("[{mark}] {label}");
-    } else {
-        println!("[{mark}] {label}: {detail}");
+#[derive(Default)]
+struct DiagnoseReport {
+    warnings: usize,
+    failures: usize,
+}
+
+impl DiagnoseReport {
+    fn finding(&mut self, level: DiagnoseLevel, label: &str, detail: impl AsRef<str>) {
+        let mark = match level {
+            DiagnoseLevel::Ok => "ok  ",
+            DiagnoseLevel::Warn => {
+                self.warnings += 1;
+                "WARN"
+            }
+            DiagnoseLevel::Fail => {
+                self.failures += 1;
+                "FAIL"
+            }
+        };
+        let detail = detail.as_ref();
+        if detail.is_empty() {
+            println!("[{mark}] {label}");
+        } else {
+            println!("[{mark}] {label}: {detail}");
+        }
     }
-    ok
+
+    fn check(&mut self, label: &str, ok: bool, detail: impl AsRef<str>) {
+        self.finding(
+            if ok {
+                DiagnoseLevel::Ok
+            } else {
+                DiagnoseLevel::Fail
+            },
+            label,
+            detail,
+        );
+    }
+}
+
+#[derive(Clone, Copy)]
+enum DiagnoseLevel {
+    Ok,
+    Warn,
+    Fail,
+}
+
+fn executable_on_path(name: &str) -> bool {
+    std::env::var_os("PATH").is_some_and(|paths| {
+        std::env::split_paths(&paths)
+            .any(|dir| std::fs::metadata(dir.join(name)).is_ok_and(|m| m.is_file()))
+    })
+}
+
+fn mounted_fs_type(path: &Path) -> Option<String> {
+    let wanted = path.canonicalize().ok()?;
+    let mounts = std::fs::read_to_string("/proc/self/mountinfo").ok()?;
+    mounts
+        .lines()
+        .filter_map(|line| {
+            let fields: Vec<_> = line.split_whitespace().collect();
+            let separator = fields.iter().position(|field| *field == "-")?;
+            let encoded = *fields.get(4)?;
+            let decoded = encoded.replace("\\040", " ").replace("\\011", "\t");
+            let mountpoint = PathBuf::from(decoded);
+            if mountpoint.canonicalize().ok()? == wanted {
+                Some(fields.get(separator + 1)?.to_string())
+            } else {
+                None
+            }
+        })
+        .next()
+}
+
+/// Create, sync, and remove a new file without ever replacing an existing one.
+fn writable_probe(dir: &Path) -> std::io::Result<()> {
+    let name = format!(".pdfs-diagnose-probe-{}", std::process::id());
+    let path = dir.join(name);
+    let mut file = OpenOptions::new()
+        .write(true)
+        .create_new(true)
+        .open(&path)?;
+    let result = (|| {
+        file.write_all(b"probe")?;
+        file.sync_all()
+    })();
+    drop(file);
+    let remove = std::fs::remove_file(path);
+    result.and(remove)
 }
 
 /// Self-check the installation, reporting each finding and exiting non-zero if
@@ -1759,58 +1840,80 @@ fn check(label: &str, ok: bool, detail: impl AsRef<str>) -> bool {
 /// situation a user runs this in. A missing daemon is reported as a finding,
 /// not an error that aborts the rest of the report.
 fn cmd_diagnose() -> Result<()> {
-    let mut all_ok = true;
+    let mut report = DiagnoseReport::default();
 
     let dirs = AppDirs::new().context("resolve application directories")?;
     let config = dirs.load_config();
 
     println!("Paths");
     let state = dirs.state_dir();
-    all_ok &= check(
+    report.check(
         "  state dir",
         state.is_dir(),
         format!("{}", state.display()),
     );
     let cache_dir = dirs.cache_dir();
-    all_ok &= check(
+    report.check(
         "  cache dir",
         cache_dir.is_dir(),
         format!("{}", cache_dir.display()),
     );
     // Writability is checked by actually writing: permission bits do not
     // account for a full disk, a read-only remount, or an immutable flag.
-    let probe = state.join(".pdfs-diagnose-probe");
-    let writable = std::fs::write(&probe, b"probe").is_ok();
-    let _ = std::fs::remove_file(&probe);
-    all_ok &= check("  state dir writable", writable, "");
+    match writable_probe(&state) {
+        Ok(()) => report.finding(
+            DiagnoseLevel::Ok,
+            "  state dir writable",
+            "write and fsync succeeded",
+        ),
+        Err(e) => report.finding(DiagnoseLevel::Fail, "  state dir writable", e.to_string()),
+    }
 
     let db_path = dirs.db_path();
     let db_size = std::fs::metadata(&db_path).map(|m| m.len()).unwrap_or(0);
-    all_ok &= check(
+    report.check(
         "  database",
         db_path.is_file(),
         format!("{} ({})", db_path.display(), human_bytes(db_size)),
     );
 
+    println!("\nFUSE");
+    let fuse = Path::new("/dev/fuse");
+    report.check("  /dev/fuse", fuse.exists(), fuse.display().to_string());
+    let has_fusermount = executable_on_path("fusermount3") || executable_on_path("fusermount");
+    report.check(
+        "  unmount helper",
+        has_fusermount,
+        "fusermount3 or fusermount on PATH",
+    );
+
     println!("\nAccount");
     match pdfs_core::auth::load() {
         Ok(session) => {
-            all_ok &= check("  keyring session", true, session.username);
+            report.finding(DiagnoseLevel::Ok, "  keyring session", session.username);
         }
         Err(e) => {
             // A locked keyring and an absent login look the same from here, so
             // the detail carries the distinction rather than the verdict.
-            all_ok &= check("  keyring session", false, format!("{e}"));
+            report.finding(DiagnoseLevel::Fail, "  keyring session", format!("{e}"));
         }
     }
 
     println!("\nDaemon");
     let socket = dirs.control_socket();
     let socket_exists = socket.exists();
-    check(
+    let socket_kind_ok =
+        std::fs::symlink_metadata(&socket).is_ok_and(|m| m.file_type().is_socket());
+    report.finding(
+        if socket_exists && !socket_kind_ok {
+            DiagnoseLevel::Fail
+        } else if socket_exists {
+            DiagnoseLevel::Ok
+        } else {
+            DiagnoseLevel::Warn
+        },
         "  control socket",
-        socket_exists,
-        format!("{}", socket.display()),
+        socket.display().to_string(),
     );
     // A stale socket file with no listener is the common failure, so the reply
     // is what decides this rather than the file's existence.
@@ -1822,47 +1925,127 @@ fn cmd_diagnose() -> Result<()> {
             pending_changes,
             ..
         }) => {
-            check("  daemon responding", true, "");
-            check("  mounted at", true, mountpoint);
-            check("  network", online, if online { "" } else { "offline" });
+            report.finding(DiagnoseLevel::Ok, "  daemon responding", "");
+            let live_type = mounted_fs_type(Path::new(&mountpoint));
+            let is_fuse = live_type
+                .as_deref()
+                .is_some_and(|kind| kind.starts_with("fuse"));
+            report.finding(
+                if is_fuse {
+                    DiagnoseLevel::Ok
+                } else {
+                    DiagnoseLevel::Fail
+                },
+                "  active mount",
+                live_type.map_or_else(
+                    || format!("{mountpoint} is not mounted"),
+                    |kind| format!("{mountpoint} ({kind})"),
+                ),
+            );
+            report.finding(
+                if online {
+                    DiagnoseLevel::Ok
+                } else {
+                    DiagnoseLevel::Warn
+                },
+                "  network",
+                if online {
+                    "online"
+                } else {
+                    "offline; cached data remains available"
+                },
+            );
             let pending = pending_uploads + pending_changes;
-            check(
+            report.finding(
+                if pending == 0 {
+                    DiagnoseLevel::Ok
+                } else {
+                    DiagnoseLevel::Warn
+                },
                 "  queued writes",
-                true,
                 if pending == 0 {
                     "none".to_string()
                 } else {
                     format!("{pending} waiting to upload")
                 },
             );
+            match control_request(CtlRequest::CacheInspect { deep: true }) {
+                Ok(CtlResponse::CacheReport {
+                    integrity_problems, ..
+                }) if integrity_problems.is_empty() => report.finding(
+                    DiagnoseLevel::Ok,
+                    "  database integrity",
+                    "SQLite integrity_check passed",
+                ),
+                Ok(CtlResponse::CacheReport {
+                    integrity_problems, ..
+                }) => report.finding(
+                    DiagnoseLevel::Fail,
+                    "  database integrity",
+                    format!(
+                        "{} problem(s): {}",
+                        integrity_problems.len(),
+                        integrity_problems.join("; ")
+                    ),
+                ),
+                Ok(other) => report.finding(
+                    DiagnoseLevel::Fail,
+                    "  database integrity",
+                    format!("unexpected: {other:?}"),
+                ),
+                Err(e) => report.finding(
+                    DiagnoseLevel::Fail,
+                    "  database integrity",
+                    format!("check failed: {e:#}"),
+                ),
+            }
         }
         Ok(other) => {
-            all_ok &= check(
+            report.finding(
+                DiagnoseLevel::Fail,
                 "  daemon responding",
-                false,
                 format!("unexpected: {other:?}"),
             );
         }
         Err(e) => {
             // Not a failure of the installation: a stopped daemon is a normal
             // state, and the rest of the report is still worth printing.
-            check("  daemon responding", false, format!("{e:#}"));
-            println!("         (start it with `systemctl --user start pdfs.service`)");
+            report.finding(
+                DiagnoseLevel::Warn,
+                "  daemon responding",
+                format!("stopped or unreachable: {e:#}"),
+            );
+            println!("         (start it with `systemctl --user start proton-drive.service`)");
         }
     }
 
     let mountpoint = dirs.resolved_mountpoint(&config);
-    check(
-        "  mountpoint exists",
-        mountpoint.is_dir(),
-        format!("{}", mountpoint.display()),
+    report.finding(
+        if mountpoint.is_dir() {
+            DiagnoseLevel::Ok
+        } else {
+            DiagnoseLevel::Warn
+        },
+        "  configured mountpoint",
+        mountpoint.display().to_string(),
     );
 
-    if all_ok {
-        println!("\nNo problems found.");
+    if report.failures == 0 {
+        if report.warnings == 0 {
+            println!("\nNo problems found.");
+        } else {
+            println!(
+                "\nNo critical problems found; {} warning(s) need attention.",
+                report.warnings
+            );
+        }
         Ok(())
     } else {
-        bail!("one or more checks failed; see the report above")
+        bail!(
+            "{} check(s) failed and {} warning(s) were reported; see above",
+            report.failures,
+            report.warnings
+        )
     }
 }
 
@@ -1873,3 +2056,39 @@ fn control_request(req: CtlRequest) -> Result<CtlResponse> {
     pdfs_core::control::send(&socket, &req)
         .with_context(|| format!("talk to mount daemon at {}", socket.display()))
 }
+
+#[cfg(test)]
+mod diagnose_tests {
+    use super::*;
+
+    #[test]
+    fn finding_severity_is_counted_centrally() {
+        let mut report = DiagnoseReport::default();
+        report.finding(DiagnoseLevel::Ok, "ok", "");
+        report.finding(DiagnoseLevel::Warn, "warn", "");
+        report.finding(DiagnoseLevel::Fail, "fail", "");
+        assert_eq!(report.warnings, 1);
+        assert_eq!(report.failures, 1);
+    }
+
+    #[test]
+    fn writable_probe_never_replaces_an_existing_file() {
+        let dir = std::env::temp_dir().join(format!(
+            "pdfs-diagnose-test-{}-{:?}",
+            std::process::id(),
+            std::thread::current().id()
+        ));
+        std::fs::create_dir_all(&dir).unwrap();
+        let collision = dir.join(format!(".pdfs-diagnose-probe-{}", std::process::id()));
+        std::fs::write(&collision, b"keep me").unwrap();
+
+        assert_eq!(
+            writable_probe(&dir).unwrap_err().kind(),
+            std::io::ErrorKind::AlreadyExists
+        );
+        assert_eq!(std::fs::read(&collision).unwrap(), b"keep me");
+
+        std::fs::remove_file(collision).unwrap();
+        std::fs::remove_dir(dir).unwrap();
+    }
+}

crates/pdfs-core/src/cache.rs

@@ -153,10 +153,12 @@ pub struct StagedWrite {
 /// The identity of a remote revision, as far as we can observe it: a file whose
 /// size and mtime both still match the ones a queued change was made against has
 /// not been rewritten by anyone else in the meantime.
-#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
 pub struct Baseline {
     pub mtime: i64,
     pub size: u64,
+    #[serde(default)]
+    pub hash: Option<String>,
 }
 
 /// Content cache rooted at a directory, with a sibling pin-registry file.
@@ -431,7 +433,12 @@ impl ContentCache {
         // 64-char hex key with no `.`, so this appends rather than replaces.
         // `store_thumbnail` cannot use the same idiom — see the note there.
         let tmp = blob.with_extension("tmp");
-        std::fs::write(&tmp, bytes)?;
+        {
+            let mut f = std::fs::File::create(&tmp)?;
+            use std::io::Write;
+            f.write_all(bytes)?;
+            f.sync_all()?;
+        }
         std::fs::rename(&tmp, &blob)?;
         let meta = serde_json::to_vec(&Meta { mtime, size })?;
         std::fs::write(self.meta_path(uid), meta)?;
@@ -464,6 +471,9 @@ impl ContentCache {
         if std::fs::hard_link(src, &tmp).is_err() {
             std::fs::copy(src, &tmp)?;
         }
+        if let Ok(f) = std::fs::File::open(&tmp) {
+            let _ = f.sync_all();
+        }
         let bytes = std::fs::metadata(&tmp)?.len();
         std::fs::rename(&tmp, &blob)?;
         let meta = serde_json::to_vec(&Meta { mtime, size })?;
@@ -526,7 +536,12 @@ impl ContentCache {
         let tmp = self
             .block_dir
             .join(format!("{}.b{idx}.tmp", Self::key(uid)));
-        std::fs::write(&tmp, bytes)?;
+        {
+            let mut f = std::fs::File::create(&tmp)?;
+            use std::io::Write;
+            f.write_all(bytes)?;
+            f.sync_all()?;
+        }
         std::fs::rename(&tmp, &blob)?;
         std::fs::write(
             self.block_meta(uid, idx),
@@ -733,14 +748,40 @@ impl ContentCache {
                 continue;
             }
             let side = Self::scratch_sidecar(&blob);
-            // Parsed, not merely present: an unreadable sidecar cannot drive a
-            // recovery, so the blob is rubbish like any other leftover.
-            if std::fs::read(&side)
+            if !side.exists() {
+                // Not marked durable, or durability marker was explicitly cleared on release
+                continue;
+            }
+            // Parsed if valid; if sidecar exists but is corrupted, build synthetic StagedWrite
+            let has_valid_sidecar = std::fs::read(&side)
                 .ok()
                 .and_then(|b| serde_json::from_slice::<StagedWrite>(&b).ok())
-                .is_none()
-            {
-                continue;
+                .is_some();
+            if !has_valid_sidecar {
+                if let Ok(meta) = std::fs::metadata(&blob)
+                    && meta.len() > 0
+                {
+                    let blob_name = blob
+                        .file_name()
+                        .map(|n| n.to_string_lossy().to_string())
+                        .unwrap_or_default();
+                    let synthetic = StagedWrite {
+                        uid: format!("recovered~{blob_name}"),
+                        len: meta.len(),
+                        base_size: meta.len(),
+                        base_mtime: 0,
+                        authored: vec![(0, meta.len())],
+                        complete: true,
+                        based_on: None,
+                    };
+                    if let Ok(data) = serde_json::to_vec(&synthetic) {
+                        let _ = std::fs::write(&side, data);
+                    } else {
+                        continue;
+                    }
+                } else {
+                    continue;
+                }
             }
             let Some(name) = blob.file_name() else {
                 continue;
@@ -755,6 +796,34 @@ impl ContentCache {
         }
     }
 
+    /// Emergency eviction of unpinned blobs when local disk runs out of space (ENOSPC).
+    pub fn emergency_evict(&self) {
+        let pinned: HashSet<String> = self
+            .db
+            .pinned_uids()
+            .unwrap_or_default()
+            .iter()
+            .map(|uid| Self::key_str(uid))
+            .collect();
+        let content_dir = self.content_dir.clone();
+        // Force pool enforcement ignoring current cap check to free disk space immediately
+        let Ok(list) = self.db.cache_eviction_candidates(KIND_BLOB, 10) else {
+            return;
+        };
+        for (key, bytes) in list {
+            if pinned.contains(&key) {
+                continue;
+            }
+            let p = content_dir.join(&key);
+            let m = content_dir.join(format!("{key}.meta"));
+            let _ = std::fs::remove_file(&p);
+            let _ = std::fs::remove_file(&m);
+            let _ = self.db.cache_remove(&key);
+            self.blob_bytes.fetch_sub(bytes, Ordering::Relaxed);
+            break; // Evict one item at a time until space is freed
+        }
+    }
+
     /// Writes rescued from an unclean shutdown, as `(blob, meta)` pairs for the
     /// daemon to hand to the upload queue. A blob whose sidecar did not survive
     /// the rescue is deleted here — nothing can address it.
@@ -1759,6 +1828,7 @@ mod tests {
             based_on: Some(Baseline {
                 mtime: 100,
                 size: 40,
+                hash: None,
             }),
         };
         let staged = c.stage_write(&meta, &scratch).unwrap();

crates/pdfs-core/src/db/nodes.rs

@@ -118,6 +118,18 @@ impl Db {
         Ok(())
     }
 
+    /// Check if a folder node has any non-trashed children in the database.
+    pub fn has_children(&self, parent_uid: &NodeUid) -> Result<bool> {
+        let uid_str = parent_uid.to_string();
+        let conn = self.conn.lock();
+        let count: i64 = conn.query_row(
+            "SELECT COUNT(*) FROM nodes WHERE parent_uid = ?1 AND trashed = 0",
+            params![uid_str],
+            |row| row.get(0),
+        )?;
+        Ok(count > 0)
+    }
+
     /// Full-text search over node names, newest schema's trigram index giving
     /// substring (not just prefix) matches. Returns up to `limit` non-trashed
     /// hits, each with its mountpoint-relative path resolved. Queries shorter

crates/pdfs-core/src/db/ops.rs

@@ -138,8 +138,8 @@ impl Db {
         };
         conn.execute(
             "INSERT INTO pending_op
-               (kind, uid, parent_uid, name, blob_path, meta_json, created_at)
-             VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)",
+               (kind, uid, parent_uid, name, blob_path, meta_json, created_at, next_attempt_at)
+             VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)",
             params![
                 op.kind,
                 op.uid,
@@ -147,7 +147,8 @@ impl Db {
                 op.name,
                 op.blob_path,
                 op.meta_json,
-                op.created_at
+                op.created_at,
+                op.next_attempt_at
             ],
         )?;
         Ok((conn.last_insert_rowid(), superseded))
@@ -229,6 +230,17 @@ impl Db {
         Ok(n > 0)
     }
 
+    /// Check if a queued create or mkdir op exists for `uid`.
+    pub fn has_create_op(&self, uid: &str) -> Result<bool> {
+        let conn = self.conn.lock();
+        let count: i64 = conn.query_row(
+            "SELECT COUNT(*) FROM pending_op WHERE uid = ?1 AND kind IN (?2, ?3)",
+            params![uid, OP_CREATE, OP_MKDIR],
+            |row| row.get(0),
+        )?;
+        Ok(count > 0)
+    }
+
     /// Drop every op targeting a node **or anything queued beneath it**,
     /// returning the staged blobs they held so the caller can delete them.
     ///
@@ -347,6 +359,28 @@ impl Db {
         Ok(op)
     }
 
+    /// The earliest `next_attempt_at` among all queued ops, or `None` if the
+    /// queue is empty. Used by the drain loop to sleep exactly until the next
+    /// debounced or backed-off op becomes eligible rather than waiting the full
+    /// idle-poll interval.
+    pub fn earliest_due_at(&self) -> Result<Option<i64>> {
+        let conn = self.conn.lock();
+        let ts: Option<i64> = conn
+            .query_row(
+                &format!(
+                    "SELECT MIN(next_attempt_at) FROM pending_op \
+                     WHERE parent_uid IS NULL OR substr(parent_uid, 1, {n}) <> '{v}~'",
+                    v = LOCAL_VOLUME,
+                    n = LOCAL_VOLUME.len() + 1,
+                ),
+                [],
+                |r| r.get(0),
+            )
+            .optional()?
+            .flatten();
+        Ok(ts)
+    }
+
     /// Every queued op, oldest first. For status read-outs and the CLI — the
     /// drain wants [`next_due_op`](Self::next_due_op) instead.
     pub fn pending_ops(&self) -> Result<Vec<PendingOp>> {

crates/pdfs-core/src/db/tests.rs

@@ -1522,3 +1522,91 @@ fn db_contention_under_fuse_worker_load() {
         serial / total as u32
     );
 }
+
+#[test]
+fn test_db_has_children_and_trashed_filtering() {
+    use proton_drive_rs::proton_sdk::ids::{LinkId, VolumeId};
+    let db = Db::open_in_memory().unwrap();
+    let parent_uid = NodeUid::new(VolumeId::from("vol"), LinkId::from("parent"));
+    let child_uid = NodeUid::new(VolumeId::from("vol"), LinkId::from("child"));
+
+    assert!(
+        !db.has_children(&parent_uid).unwrap(),
+        "no children initially"
+    );
+
+    let parent_node = Node {
+        uid: parent_uid.clone(),
+        parent_uid: None,
+        name: "parent".into(),
+        kind: NodeKind::Folder,
+        creation_time: 100,
+        modification_time: 100,
+        trashed: false,
+        is_shared: false,
+        is_shared_publicly: false,
+        signature_email: None,
+        verification: Default::default(),
+    };
+    db.upsert_node(&parent_node).unwrap();
+
+    let mut child_node = Node {
+        uid: child_uid.clone(),
+        parent_uid: Some(parent_uid.clone()),
+        name: "child.txt".into(),
+        kind: NodeKind::File {
+            media_type: "text/plain".into(),
+            total_size_on_storage: 10,
+            active_revision_state: None,
+            claimed_size: Some(10),
+            claimed_modification_time: None,
+        },
+        creation_time: 100,
+        modification_time: 100,
+        trashed: false,
+        is_shared: false,
+        is_shared_publicly: false,
+        signature_email: None,
+        verification: Default::default(),
+    };
+    db.upsert_node(&child_node).unwrap();
+
+    assert!(db.has_children(&parent_uid).unwrap(), "child node present");
+
+    // Trashing child removes it from active children
+    child_node.trashed = true;
+    db.upsert_node(&child_node).unwrap();
+
+    assert!(
+        !db.has_children(&parent_uid).unwrap(),
+        "trashed child ignored"
+    );
+}
+
+#[test]
+fn test_db_has_create_op() {
+    let db = Db::open_in_memory().unwrap();
+    let local_uid = "local~testnode12345678901234567890";
+
+    assert!(!db.has_create_op(local_uid).unwrap(), "no op initially");
+
+    let op = ops::PendingOp {
+        id: 0,
+        kind: ops::OP_CREATE.to_string(),
+        uid: local_uid.to_string(),
+        parent_uid: Some("vol~parent".to_string()),
+        name: Some("test.txt".to_string()),
+        blob_path: None,
+        meta_json: None,
+        created_at: 1000,
+        attempts: 0,
+        last_error: None,
+        next_attempt_at: 0,
+    };
+    db.enqueue_op(&op).unwrap();
+
+    assert!(db.has_create_op(local_uid).unwrap(), "create op present");
+
+    db.delete_ops_for_uid(local_uid).unwrap();
+    assert!(!db.has_create_op(local_uid).unwrap(), "op deleted");
+}

crates/pdfs-fuse/src/background.rs

@@ -0,0 +1,268 @@
+//! Remote-event invalidation and local-index background workers.
+
+use super::*;
+
+/// Apply one remote event to the local cache and notify the kernel so it drops
+/// any stale cached metadata/data for the affected inodes.
+///
+/// The cache is authoritative-by-absence: dropping a directory's `children`
+/// entry forces the next `lookup`/`readdir` to re-enumerate from the remote, so
+/// most events only need to invalidate listings rather than re-fetch eagerly.
+fn apply_event(
+    state: &Mutex<State>,
+    content: &ContentCache,
+    pending: &Mutex<HashMap<NodeUid, PendingRevision>>,
+    notifier: &Notifier,
+    event: &DriveEvent,
+) {
+    match event {
+        DriveEvent::NodeUpdated {
+            node_uid,
+            parent_node_uid,
+            is_trashed,
+            ..
+        } => {
+            let mut st = state.lock();
+            if *is_trashed {
+                // Trashing makes a node vanish from its parent listing.
+                let child = st.by_uid.get(node_uid).copied();
+                if let Some((parent, name)) = st.forget(node_uid) {
+                    content.evict(node_uid);
+                    match child {
+                        Some(child) => {
+                            let _ =
+                                notifier.delete(INodeNo(parent), INodeNo(child), OsStr::new(&name));
+                        }
+                        None => {
+                            let _ = notifier.inval_entry(INodeNo(parent), OsStr::new(&name));
+                        }
+                    }
+                }
+            } else if pending.lock().contains_key(node_uid) {
+                // A node we owe an upload for is *ahead* of the remote, not
+                // behind it: this event is almost always the echo of our own
+                // empty-file create, and re-fetching would replace the size and
+                // mtime of the write we just accepted with the stale revision's
+                // — making a file that was copied in seconds ago read as empty
+                // until its upload lands (offline.md Phase 3).
+                debug!(uid = %node_uid, "ignoring remote event for a node with a queued write");
+            } else if let Some(&ino) = st.by_uid.get(node_uid) {
+                // Known node changed: drop its cached attrs/data (and listing if
+                // it is a directory) so the next access re-fetches. Its content
+                // blob may now be stale, so evict it too.
+                st.invalidate_listing(ino);
+                content.evict(node_uid);
+                let _ = notifier.inval_inode(INodeNo(ino), 0, 0);
+            }
+            // A create (or move-in) shows up as a change to the parent listing;
+            // drop it so the new child is picked up on the next readdir.
+            if let Some(parent_uid) = parent_node_uid
+                && let Some(&parent) = st.by_uid.get(parent_uid)
+            {
+                st.invalidate_listing(parent);
+                let _ = notifier.inval_inode(INodeNo(parent), 0, 0);
+            }
+        }
+        DriveEvent::NodeDeleted { node_uid, .. } => {
+            let mut st = state.lock();
+            // Capture the inode before `forget` clears the uid mapping.
+            let child = st.by_uid.get(node_uid).copied();
+            content.evict(node_uid);
+            if let Some((parent, name)) = st.forget(node_uid) {
+                match child {
+                    Some(child) => {
+                        let _ = notifier.delete(INodeNo(parent), INodeNo(child), OsStr::new(&name));
+                    }
+                    None => {
+                        let _ = notifier.inval_entry(INodeNo(parent), OsStr::new(&name));
+                    }
+                }
+            }
+        }
+        // Continuity or scope was lost: our cached listings may be arbitrarily
+        // stale, so drop every listing and tell the kernel to forget all
+        // metadata. Inodes stay stable; dirs simply re-enumerate on next access.
+        DriveEvent::ContinuityLost { .. } | DriveEvent::ScopeAccessLost { .. } => {
+            warn!("event continuity lost; dropping all cached listings, resyncing lazily");
+            let mut st = state.lock();
+            let dirs: Vec<u64> = st.children.keys().copied().collect();
+            for &ino in &dirs {
+                st.invalidate_listing(ino);
+                let _ = notifier.inval_inode(INodeNo(ino), 0, 0);
+            }
+        }
+        // No substantive local change; the cursor advance is handled by the
+        // caller persisting the event id.
+        DriveEvent::CursorAdvanced { .. } | DriveEvent::SharedWithMeUpdated { .. } => {}
+    }
+}
+
+/// Poll the remote event cursor forever, applying each batch to the shared
+/// state. Resumes from the cursor persisted in the DB so changes made while
+/// unmounted are applied; only a first-ever mount seeds from the server head.
+/// The cursor is persisted after every batch. Runs as a Tokio task; returns
+/// only on fatal error.
+pub(super) async fn run_event_sync(
+    client: ProtonDriveClient,
+    scope: DriveEventScopeId,
+    state: Arc<Mutex<State>>,
+    content: Arc<ContentCache>,
+    db: Arc<Db>,
+    pending: Arc<Mutex<HashMap<NodeUid, PendingRevision>>>,
+    notifier: Notifier,
+) {
+    let mut cursor: Option<DriveEventId> = match db.get_event_cursor() {
+        // Resume: pick up exactly where the last run left off.
+        Ok(Some(saved)) => Some(DriveEventId::from(saved)),
+        // First mount: a `None` cursor yields a single `CursorAdvanced` at the
+        // server head; persist it so the next restart resumes instead of
+        // reseeding (which would skip everything that changed offline).
+        // Seeding needs the network, and this task also runs on mounts that
+        // started offline (offline.md Phase 1) — so retry rather than giving up,
+        // which used to disable live sync for the life of the daemon.
+        Ok(None) => {
+            let mut delay = ONLINE_PROBE_MIN;
+            loop {
+                match client.enumerate_events(&scope, None).await {
+                    Ok(events) => {
+                        let head = events.last().map(|e| e.id().clone());
+                        if let Some(c) = &head
+                            && let Err(e) = db.set_event_cursor(c.as_str())
+                        {
+                            warn!(error = %e, "persist seed cursor failed");
+                        }
+                        break head;
+                    }
+                    Err(e) => {
+                        warn!(error = %e, ?delay, "seed event cursor failed; retrying");
+                        tokio::time::sleep(delay).await;
+                        delay = (delay * 2).min(ONLINE_PROBE_MAX);
+                    }
+                }
+            }
+        }
+        Err(e) => {
+            error!(error = %e, "read persisted cursor failed; live sync disabled");
+            return;
+        }
+    };
+    info!(?cursor, "event sync started");
+
+    loop {
+        tokio::time::sleep(POLL_INTERVAL).await;
+        let events = match client.enumerate_events(&scope, cursor.as_ref()).await {
+            Ok(events) => events,
+            Err(e) => {
+                warn!(error = %e, "event poll failed; retrying after interval");
+                continue;
+            }
+        };
+        if events.is_empty() {
+            continue;
+        }
+        debug!(count = events.len(), "applying remote events");
+        for event in &events {
+            // Converge the SDK's own caches (folder keys, entity cache) on the
+            // server before applying the event to our tree. Without this, a node
+            // re-keyed/moved by another client keeps a stale key in the SDK for
+            // the life of the daemon (SDK plan #9). `apply_event` only touches
+            // our FUSE state, so nothing else does this.
+            if let Err(e) = client.invalidate_caches_for_event(event).await {
+                warn!(error = %e, "sdk cache invalidation for event failed");
+            }
+            apply_event(&state, &content, &pending, &notifier, event);
+        }
+        cursor = events.last().map(|e| e.id().clone());
+        if let Some(c) = &cursor
+            && let Err(e) = db.set_event_cursor(c.as_str())
+        {
+            warn!(error = %e, "persist event cursor failed");
+        }
+    }
+}
+
+/// Keep the local-file index fresh for the launcher prompt's "This computer"
+/// results. Rebuilds the index whenever it is older than [`LOCAL_INDEX_TTL`],
+/// then sleeps; runs on its own thread for the life of the daemon.
+///
+/// The walk is the one part of the daemon that touches the wider filesystem, so
+/// it is deliberately kept off every hot path: it never runs on a FUSE or
+/// control-socket thread, and it excludes the mountpoint (walking it would fault
+/// every remote node in through FUSE, defeating on-demand hydration).
+pub(super) fn run_local_index(
+    db: Arc<Db>,
+    indexing: Arc<AtomicBool>,
+    transfers: Arc<TransferRegistry>,
+    mountpoint: PathBuf,
+) {
+    loop {
+        let age = db.local_indexed_at().ok().flatten();
+        let stale =
+            age.is_none_or(|at| now_secs().saturating_sub(at) >= LOCAL_INDEX_TTL.as_secs() as i64);
+        if stale {
+            scan_local_once(&db, &indexing, &transfers, &mountpoint);
+        }
+        std::thread::sleep(LOCAL_INDEX_CHECK);
+    }
+}
+
+/// Walk `$HOME` once and replace the local-file index with what it finds.
+/// Batches stream straight into SQLite, so peak memory is one batch — not the
+/// whole home directory.
+///
+/// Reports itself as a job: the first scan after a fresh install walks the whole
+/// home directory, and `indexing` alone only tells the launcher prompt to say
+/// "still indexing" — nothing else showed that the daemon was busy.
+fn scan_local_once(
+    db: &Db,
+    indexing: &AtomicBool,
+    transfers: &Arc<TransferRegistry>,
+    mountpoint: &Path,
+) {
+    let dirs = match AppDirs::new() {
+        Ok(d) => d,
+        Err(e) => {
+            warn!(error = %e, "local index: cannot resolve app dirs");
+            return;
+        }
+    };
+    let Some(home) = dirs.home_dir() else {
+        warn!("local index: cannot resolve home directory");
+        return;
+    };
+    let generation = match db.local_begin_scan() {
+        Ok(g) => g,
+        Err(e) => {
+            warn!(error = %e, "local index: cannot open scan generation");
+            return;
+        }
+    };
+
+    let excludes = localindex::default_excludes(mountpoint, &dirs.state_dir(), &dirs.cache_dir());
+    indexing.store(true, Ordering::Relaxed);
+    let started = Instant::now();
+
+    // The walk has no idea how many files it will find, so the job counts what it
+    // has seen and stays indeterminate.
+    let job = transfers.begin_job("Indexing this computer");
+    job.detail("Scanning your files");
+    let walked = localindex::scan(&[home], &excludes, |batch| {
+        if let Err(e) = db.local_upsert_batch(generation, &batch) {
+            warn!(error = %e, "local index: batch write failed");
+        }
+    });
+
+    // Prune what this scan did not see and rebuild the FTS index over the rest,
+    // even if some batches failed — a partial index still beats none.
+    job.detail("Building the search index");
+    match db.local_finish_scan(generation, now_secs()) {
+        Ok(indexed) => info!(
+            walked,
+            indexed,
+            elapsed_ms = started.elapsed().as_millis() as u64,
+            "local index rebuilt"
+        ),
+        Err(e) => warn!(error = %e, "local index: finish failed"),
+    }
+    indexing.store(false, Ordering::Relaxed);
+}

crates/pdfs-fuse/src/devices.rs

@@ -494,6 +494,7 @@ impl Core {
             by_uid: HashMap::new(),
             children: HashMap::new(),
             next_ino: 2,
+            active_writes: HashMap::new(),
             handles: HashMap::new(),
             next_fh: 1,
             db: self.db.clone(),
@@ -682,26 +683,22 @@ impl Core {
                 // fails, since eviction may already have deleted part of the tree.
                 // Recovery is the user's explicit switch back to `mirror`, whose arm
                 // clears the baseline and re-downloads.
-                self.db
-                    .sync_folder_set_mode(id, "ondemand")
-                    .map_err(|e| SwitchBlocked::Failed(format!("db: {e:?}")))?;
-
-                // Reclaim the disk: empty the local dir (keep it as the mountpoint).
-                if let Err(e) = evict_dir_contents(&local) {
-                    let _ = self.db.sync_folder_set_state(id, "error", now_secs());
-                    return Err(SwitchBlocked::Failed(format!(
-                        "evict {}: {e}",
-                        local.display()
-                    )));
+                if let Err(e) = self.db.sync_folder_set_mode(id, "ondemand") {
+                    return Err(SwitchBlocked::Failed(format!("db: {e:?}")));
                 }
 
-                let session = match self.spawn_ondemand_mount(&local, root) {
-                    Ok(session) => session,
-                    Err(e) => {
-                        let _ = self.db.sync_folder_set_state(id, "error", now_secs());
-                        return Err(SwitchBlocked::Failed(e.to_string()));
-                    }
-                };
+                // Reclaim the disk before mounting. Once FUSE covers `local`, a
+                // directory walk addresses the remote namespace, so evicting at
+                // that point sends unlink/rmdir requests to Drive and leaves the
+                // underlying mirror hidden and untouched.
+                if let Err(e) = evict_dir_contents(&local) {
+                    warn!(id, path = %local.display(), error = %e, "evict local dir contents failed");
+                }
+                let session = self.spawn_ondemand_mount(&local, root).map_err(|e| {
+                    SwitchBlocked::Failed(format!(
+                        "mount ondemand failed after local cache eviction; switch back to mirror to restore it: {e}"
+                    ))
+                })?;
                 self.mounts
                     .lock()
                     .insert(id, (session, fuse_connection_id(&local)));

crates/pdfs-fuse/src/drain.rs

@@ -23,6 +23,7 @@
 use std::fs::File;
 use std::path::{Path, PathBuf};
 use std::sync::atomic::Ordering;
+use std::time::Duration;
 
 use pdfs_core::cache::{Baseline, StagedWrite};
 use pdfs_core::control::{ActivityKind, TransferDirection};
@@ -62,23 +63,30 @@ impl Core {
             let due = self.db.next_due_op(now).unwrap_or_default();
 
             let Some(op) = due.filter(|_| self.online.load(Ordering::Relaxed)) else {
-                self.wait_for_drain_work();
+                self.recover_fsynced_writes();
+                // A debounced or backed-off op may be waiting: sleep only
+                // until it becomes due rather than the full idle-poll.
+                self.wait_for_drain_work_or_due();
                 continue;
             };
             if let Err(e) = self.drain_op(&op) {
                 let attempts = op.attempts + 1;
+                let err_str = e.to_string();
+                // Never infer that user data is disposable from an error string
+                // or an arbitrary retry count. The staged blob and this row are
+                // the only durable description of an accepted write. Even a
+                // permission/quota error can become recoverable after the user
+                // changes account state, and deleting the row here made the blob
+                // unreachable after five ordinary network failures.
                 let backoff = DRAIN_BACKOFF_MIN
                     .saturating_mul(1u32 << attempts.min(6))
                     .min(DRAIN_BACKOFF_MAX);
-                warn!(uid = %op.uid, attempts, error = %e, "pending upload failed; will retry");
+                warn!(uid = %op.uid, attempts, error = %err_str, "pending upload failed; will retry");
                 if let Err(e) = self.db.record_op_failure(
                     op.id,
-                    &e.to_string(),
+                    &err_str,
                     now_millis() + backoff.as_millis() as i64,
                 ) {
-                    // The backoff is the only thing keeping a failing op from
-                    // being picked again immediately, so without it the loop
-                    // would spin on this op as fast as the API can refuse it.
                     error!(uid = %op.uid, error = %e, "recording a drain failure failed");
                     self.wait_for_drain_work();
                 }
@@ -97,6 +105,25 @@ impl Core {
         *woken = false;
     }
 
+    /// Like [`wait_for_drain_work`](Self::wait_for_drain_work), but first
+    /// checks whether a debounced or backed-off op is due before the idle-poll
+    /// ceiling. A 2-second debounce must not sleep 30 seconds.
+    fn wait_for_drain_work_or_due(&self) {
+        let timeout = match self.db.earliest_due_at() {
+            Ok(Some(ts)) => {
+                let remaining = (ts - now_millis()).max(0) as u64;
+                Duration::from_millis(remaining).min(DRAIN_IDLE_POLL)
+            }
+            _ => DRAIN_IDLE_POLL,
+        };
+        let (lock, cv) = &*self.drain_wake;
+        let mut woken = lock.lock();
+        if !*woken {
+            cv.wait_for(&mut woken, timeout);
+        }
+        *woken = false;
+    }
+
     /// Perform one queued op and retire it.
     pub(crate) fn drain_op(&self, op: &PendingOp) -> Result<(), Box<dyn std::error::Error>> {
         match op.kind.as_str() {
@@ -467,7 +494,7 @@ impl Core {
         uid: &NodeUid,
         meta: &StagedWrite,
     ) -> Result<Option<String>, Box<dyn std::error::Error>> {
-        let Some(base) = meta.based_on else {
+        let Some(ref base) = meta.based_on else {
             return Ok(None);
         };
         let Some(node) = self.fetch_node_remote(uid)? else {
@@ -727,7 +754,14 @@ impl Core {
         // an orphaned file (harmless), whereas the reverse would leave a queued
         // op pointing at nothing.
         self.db.delete_op(op.id)?;
-        self.pending.lock().remove(&uid);
+        {
+            let mut p = self.pending.lock();
+            if let Some(op_in_mem) = p.get(&uid)
+                && op_in_mem.path == blob
+            {
+                p.remove(&uid);
+            }
+        }
 
         // The staged blob now matches the sealed revision, so a pinned file keeps
         // it as its cached content rather than re-downloading what we just sent.
@@ -780,6 +814,28 @@ impl Core {
                 return;
             }
         };
+        // Rebase any *open* write handles targeting this node. A handle opened
+        // before this upload carries a stale base — its `base_mtime`/`base_size`
+        // name the revision we just replaced. Without this update,
+        // `remote_baseline` will build a `based_on` from those stale values, the
+        // drain will compare them against the revision we sealed, and the write
+        // will be diverted into a conflict copy of itself.
+        //
+        // This is the open-handle counterpart of `rebaseline_pending`, which
+        // covers the same gap for *queued* ops.
+        {
+            let sealed_mtime = node.modification_time;
+            let sealed_size = node_size(&node);
+            let mut st = self.state.lock();
+            for aw in st.active_writes.values_mut() {
+                if aw.uid == *uid {
+                    aw.base_mtime = sealed_mtime;
+                    aw.base_size = sealed_size;
+                    debug!(%uid, mtime = sealed_mtime, size = sealed_size,
+                           "rebased open write handle onto the revision just uploaded");
+                }
+            }
+        }
         // Ordered so that a write queued *during* the fetch above is still
         // caught: it took its baseline from the node's optimistic stamp, and
         // this overwrites it with the revision the server actually holds.
@@ -818,12 +874,13 @@ impl Core {
         let base = Baseline {
             mtime: sealed.modification_time,
             size: node_size(sealed),
+            hash: None,
         };
         let mut pending = self.pending.lock();
         let Some(p) = pending.get_mut(uid) else {
             return false;
         };
-        p.meta.based_on = Some(base);
+        p.meta.based_on = Some(base.clone());
         match serde_json::to_string(&p.meta) {
             Ok(json) => {
                 if let Err(e) = self.db.update_op_meta(&uid.to_string(), OP_REVISION, &json) {

crates/pdfs-fuse/src/mount.rs

@@ -0,0 +1,392 @@
+//! Mount lifecycle and background-service orchestration.
+
+use super::*;
+
+/// Why a [`mount`] call returned. Lets the daemon decide whether to exit (clean
+/// shutdown) or remount (the mount went away under it).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MountOutcome {
+    /// The daemon was asked to stop (SIGTERM/SIGINT) and we lazily unmounted
+    /// ourselves. The caller should exit cleanly.
+    Shutdown,
+    /// The kernel mount ended on its own (e.g. an external `fusermount -u`).
+    /// The caller may want to remount.
+    Unmounted,
+}
+
+/// Whether `path` is a mountpoint whose FUSE connection is dead — the state a
+/// daemon killed before it could unmount leaves behind.
+///
+/// The kernel answers every operation on such a path with `ENOTCONN`, which the
+/// ordinary existence checks (`is_dir`, `exists`) report as plain `false`: the
+/// path looks *absent* rather than broken. Callers that would otherwise treat
+/// that as "nothing to mount here" use this to tell the two apart.
+pub(crate) fn is_stale_mount(path: &Path) -> bool {
+    matches!(
+        std::fs::metadata(path).map_err(|e| e.raw_os_error()),
+        Err(Some(libc::ENOTCONN))
+    )
+}
+
+/// A secondary (on-demand sync folder) FUSE session, paired with its FUSE
+/// connection id so teardown can abort a mid-transfer connection rather than
+/// block on it. See [`Core::mounts`] and [`umount_session_unblocked`].
+pub(super) type SecondaryMount = (BackgroundSession, Option<u32>);
+
+/// The kernel's id for the FUSE connection backing the mount at `mountpoint` —
+/// the directory name under `/sys/fs/fuse/connections`, which is the minor
+/// number of the mountpoint's device. Must be read *while still mounted*; after
+/// unmount the path resolves to the underlying directory on another device.
+/// `None` when the path can't be stat'd.
+pub(super) fn fuse_connection_id(mountpoint: &Path) -> Option<u32> {
+    use std::os::unix::fs::MetadataExt;
+    let dev = std::fs::metadata(mountpoint).ok()?.dev();
+    Some(libc::minor(dev))
+}
+
+/// Force the kernel to abort FUSE connection `id`, erroring every in-flight
+/// request.
+///
+/// On a stop signal we unmount lazily (`MNT_DETACH`) so the call succeeds even
+/// mid-transfer — but detach only removes the mountpoint; it does *not* end the
+/// connection while a request is still in flight. fuser's session loop then
+/// blocks on `/dev/fuse` waiting for a next request that never comes, so `join`
+/// hangs — long enough during a transfer that systemd's stop timeout SIGKILLs
+/// the daemon mid-unmount, stranding the on-demand mounts as dead endpoints.
+/// Writing the connection's `abort` file makes the pending reads fail with
+/// `ENODEV`, so the loop returns and `join` completes at once. Best-effort:
+/// there is nothing more to do on the shutdown path if it fails.
+pub(super) fn abort_fuse_connection(id: u32) {
+    let path = format!("/sys/fs/fuse/connections/{id}/abort");
+    if std::fs::write(&path, b"1").is_ok() {
+        info!(id, "aborted FUSE connection to unblock unmount");
+    }
+}
+
+/// Unmount a background session that may be mid-transfer without wedging: abort
+/// its connection first (so the session loop exits promptly), then lazily
+/// unmount and join. `conn` is the id captured at mount time; `None` skips the
+/// abort and just unmounts (a healthy idle mount joins on its own `Destroy`).
+pub(super) fn umount_session_unblocked(
+    session: BackgroundSession,
+    conn: Option<u32>,
+) -> std::io::Result<()> {
+    if let Some(id) = conn {
+        abort_fuse_connection(id);
+    }
+    session.umount_and_join()
+}
+
+/// Best-effort teardown of a stale mount left behind by a crashed daemon. A
+/// previous run that died without unmounting leaves the kernel mount in place,
+/// so the fresh `Session::new` below would fail with EBUSY ("Device or resource
+/// busy"). `fusermount3 -u -z` is the lazy (detach) unmount, which succeeds even
+/// when the old mount is still busy. Swallow all output/errors: if there is no
+/// stale mount this is simply a no-op.
+pub(super) fn clear_stale_mount(mountpoint: &Path) {
+    for bin in ["fusermount3", "fusermount"] {
+        let ok = std::process::Command::new(bin)
+            .arg("-u")
+            .arg("-z")
+            .arg(mountpoint)
+            .stdout(std::process::Stdio::null())
+            .stderr(std::process::Stdio::null())
+            .status()
+            .map(|s| s.success())
+            .unwrap_or(false);
+        if ok {
+            info!(mountpoint = %mountpoint.display(), "cleared stale mount before remount");
+            return;
+        }
+    }
+}
+
+/// `sync_state` key holding the uid of the My Files root, so a later run can
+/// recover it from `nodes` without the API (offline.md Phase 1).
+const ROOT_UID_KEY: &str = "root_uid";
+
+/// The My Files root, and whether we got it from the API (`true`) or from the
+/// cache because the API was unreachable (`false`).
+///
+/// A successful fetch also records the root's uid, which is what makes the
+/// fallback possible on a later run: `nodes` is keyed by uid, so without this we
+/// would have the root's row on disk and no way to tell which one it is.
+///
+/// Failing to fetch is only fatal on a genuinely cold start — no cached root
+/// means an empty tree, and mounting that would show the user an empty Drive
+/// rather than an honest error.
+fn fetch_or_recall_root(
+    client: &ProtonDriveClient,
+    rt: &tokio::runtime::Handle,
+    db: &Db,
+) -> std::io::Result<(Node, bool)> {
+    let err = match rt.block_on(client.get_my_files_folder()) {
+        Ok(root) => {
+            if let Err(e) = db.set_state_str(ROOT_UID_KEY, &root.uid.to_string()) {
+                warn!(error = %e, "persist root uid failed");
+            }
+            return Ok((root, true));
+        }
+        Err(e) => e,
+    };
+    let cached = db
+        .state_str(ROOT_UID_KEY)
+        .ok()
+        .flatten()
+        .and_then(|uid| db.node_by_uid(&uid).ok().flatten());
+    match cached {
+        Some(root) => {
+            warn!(error = %err, "fetch My Files root failed; mounting from cache (offline)");
+            Ok((root, false))
+        }
+        None => Err(std::io::Error::other(format!("fetch My Files root: {err}"))),
+    }
+}
+
+/// Mount the filesystem at `mountpoint` and block until it is unmounted or the
+/// daemon is asked to stop.
+///
+/// Resolves the My Files root up front — from the API, or from the cached tree
+/// when the API is unreachable (`fetch_or_recall_root`) — then spawns the
+/// Phase 2 event-sync task, the
+/// Phase 4 control socket, and runs the FUSE session on its own thread while
+/// this thread waits for either a stop signal (SIGTERM/SIGINT) or the kernel
+/// mount ending on its own. On a stop signal we lazily unmount ourselves
+/// (`umount_and_join`, the MNT_DETACH path that succeeds even while downloads
+/// are in flight), so `systemctl --user stop` is always a clean teardown.
+/// `rt` must be a handle to a *running* multi-threaded runtime.
+pub fn mount(
+    client: ProtonDriveClient,
+    rt: tokio::runtime::Handle,
+    mountpoint: &Path,
+    cache: ContentCache,
+    control_socket: &Path,
+    db: Arc<Db>,
+    username: String,
+) -> std::io::Result<MountOutcome> {
+    let (root, online) = fetch_or_recall_root(&client, &rt, &db)?;
+    let scope = root.tree_event_scope_id();
+
+    // The folder-sync engine (devices.md Phase 2) runs on its own thread and is
+    // nudged over this channel; the sender lives in Core so control-socket
+    // handlers can trigger reconciles.
+    let (sync_tx, sync_rx) = std::sync::mpsc::channel::<sync::SyncMsg>();
+
+    let core = Core {
+        client: client.clone(),
+        rt: rt.clone(),
+        state: Arc::new(Mutex::new(State {
+            entries: HashMap::new(),
+            by_uid: HashMap::new(),
+            children: HashMap::new(),
+            next_ino: 2,
+            active_writes: HashMap::new(),
+            handles: HashMap::new(),
+            next_fh: 1,
+            db: db.clone(),
+        })),
+        cache: Arc::new(cache),
+        readers: Arc::new(Mutex::new(HashMap::new())),
+        stream_ring: Arc::new(Mutex::new(StreamRing::default())),
+        workers: Arc::new(Workers::new(FUSE_WORKERS)?),
+        db,
+        online: Arc::new(AtomicBool::new(online)),
+        pending: Arc::new(Mutex::new(HashMap::new())),
+        drain_wake: Arc::new((Mutex::new(false), Condvar::new())),
+        timeline_refreshing: Arc::new(AtomicBool::new(false)),
+        trash_refreshing: Arc::new(AtomicBool::new(false)),
+        thumb_gen: Arc::new(Mutex::new(HashSet::new())),
+        no_thumbnail: Arc::new(Mutex::new(HashMap::new())),
+        size_upgrades: Arc::new(Mutex::new(HashMap::new())),
+        notifier: Arc::new(OnceLock::new()),
+        transfers: TransferRegistry::new(),
+        indexing: Arc::new(AtomicBool::new(false)),
+        sync_progress: Arc::new(Mutex::new(HashMap::new())),
+        sync_tx,
+        mounts: Arc::new(Mutex::new(HashMap::new())),
+        sync_locks: Arc::new(Mutex::new(HashMap::new())),
+    };
+
+    // Writes queued by a previous run (or left behind by a crash) are still owed
+    // an upload, and reads must be served from their staged blobs until they land.
+    core.hydrate_pending();
+    // Then the writes that were fsynced but never closed, which the cache moved
+    // aside at open. After `hydrate_pending`, so a recovered partial write can
+    // see an already-queued write to the same node.
+    core.recover_fsynced_writes();
+    {
+        let core = core.clone();
+        std::thread::Builder::new()
+            .name("pdfs-drain".into())
+            .spawn(move || core.run_pending_drain())?;
+    }
+
+    // Start the folder-sync engine. It watches every mirror folder, polls the
+    // remotes, and reconciles on its own thread — never in front of a FUSE call.
+    sync::spawn(core.clone(), sync_rx);
+
+    // Mounted from the cache: watch for the network coming back so the mount can
+    // stop being read-only-ish without the user restarting the daemon.
+    if !online {
+        let core = core.clone();
+        std::thread::Builder::new()
+            .name("pdfs-online-probe".into())
+            .spawn(move || core.run_online_probe())?;
+    }
+
+    // Re-establish on-demand mounts left over from a previous run (devices.md
+    // Phase 4). On its own thread: each remount fetches a remote node, and we
+    // must not block the main mount below on the network.
+    {
+        let core = core.clone();
+        std::thread::Builder::new()
+            .name("pdfs-restore-ondemand".into())
+            .spawn(move || core.restore_ondemand_mounts())?;
+    }
+
+    // Keep the launcher prompt's "This computer" index fresh. Its own thread:
+    // the walk is I/O-heavy and must never sit in front of a FUSE callback.
+    {
+        let db = core.db.clone();
+        let indexing = core.indexing.clone();
+        let transfers = core.transfers.clone();
+        let mountpoint = mountpoint.to_path_buf();
+        std::thread::Builder::new()
+            .name("pdfs-localindex".into())
+            .spawn(move || run_local_index(db, indexing, transfers, mountpoint))?;
+    }
+
+    let mut config = Config::default();
+    config.mount_options = vec![
+        MountOption::FSName("protondrive".to_string()),
+        MountOption::Subtype("protondrive".to_string()),
+        MountOption::DefaultPermissions,
+    ];
+
+    // A crashed previous run can leave the kernel mount in place, which makes
+    // the fresh mount below fail with EBUSY. Lazily detach any leftover first.
+    clear_stale_mount(mountpoint);
+    info!(mountpoint = %mountpoint.display(), "mounting Proton Drive");
+
+    // Bind the control socket before the FUSE session takes over the thread. A
+    // stale socket file from a previous run would block the bind, so clear it.
+    let _ = std::fs::remove_file(control_socket);
+    let old_umask = unsafe { libc::umask(0o77) };
+    let listener_res = UnixListener::bind(control_socket);
+    unsafe { libc::umask(old_umask) };
+    let listener = listener_res?;
+    // Owner-only before anything can connect: a peer on this socket commands the
+    // daemon's authenticated session without a credential of its own (B6).
+    if let Err(e) = pdfs_core::config::restrict_socket(control_socket) {
+        error!(error = %e, "cannot restrict control socket permissions; refusing to serve");
+        let _ = std::fs::remove_file(control_socket);
+        return Err(std::io::Error::other(format!(
+            "control socket permissions: {e}"
+        )));
+    }
+    {
+        let core = core.clone();
+        let username = username.clone();
+        let mountpoint = mountpoint.to_path_buf();
+        std::thread::Builder::new()
+            .name("pdfs-control".into())
+            .spawn(move || run_control_socket(core, username, mountpoint, listener))?;
+    }
+
+    let fs = ProtonFs::new(core.clone(), root);
+    // Warm the in-memory maps from the DB so a cold start serves previously
+    // seen metadata without re-hitting the API (plan.md P1).
+    core.hydrate();
+
+    // Build the session explicitly (not `mount2`) so we can grab a `Notifier`
+    // for the event task. `spawn` runs the session loop on its own background
+    // thread; we then wait here for either a stop signal or the mount ending.
+    let bg = Session::new(fs, mountpoint, &config)?.spawn()?;
+    // The connection id, captured now while the mount is live, so a stop signal
+    // mid-transfer can abort it rather than block `join` (see `abort_fuse_connection`).
+    let main_conn = fuse_connection_id(mountpoint);
+    let notifier = bg.notifier();
+    // Same channel, kept on the `Core` so background work (a size upgrade, say)
+    // can invalidate kernel-cached metadata without threading a handle through.
+    let _ = core.notifier.set(notifier.clone());
+    rt.spawn(run_event_sync(
+        client,
+        scope,
+        core.state,
+        core.cache,
+        core.db,
+        core.pending,
+        notifier,
+    ));
+
+    // Stop signals (SIGTERM from `systemctl --user stop`, SIGINT from Ctrl-C)
+    // are delivered onto the async runtime; bridge them onto a sync channel so
+    // the loop below can react without blocking a worker thread. A bounded
+    // channel of 1 is enough — we only need to know that *a* stop arrived.
+    let (sig_tx, sig_rx) = std::sync::mpsc::sync_channel::<()>(1);
+    rt.spawn(async move {
+        let mut sigterm =
+            match tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate()) {
+                Ok(s) => s,
+                Err(e) => {
+                    warn!(error = %e, "install SIGTERM handler failed");
+                    return;
+                }
+            };
+        let mut sigint =
+            match tokio::signal::unix::signal(tokio::signal::unix::SignalKind::interrupt()) {
+                Ok(s) => s,
+                Err(e) => {
+                    warn!(error = %e, "install SIGINT handler failed");
+                    return;
+                }
+            };
+        tokio::select! {
+            _ = sigterm.recv() => info!("received SIGTERM"),
+            _ = sigint.recv() => info!("received SIGINT"),
+        }
+        let _ = sig_tx.try_send(());
+    });
+
+    // Wait for whichever happens first: a stop signal (→ we unmount ourselves
+    // via the lazy MNT_DETACH path, clean even mid-download), or the kernel
+    // mount ending on its own (→ the session thread finishes). Poll instead of
+    // blocking on `join` so we can also notice the signal.
+    let outcome = loop {
+        match sig_rx.recv_timeout(Duration::from_millis(500)) {
+            Ok(()) => {
+                info!("stop requested; unmounting");
+                if let Err(e) = umount_session_unblocked(bg, main_conn) {
+                    warn!(error = %e, "umount_and_join failed");
+                }
+                break MountOutcome::Shutdown;
+            }
+            Err(std::sync::mpsc::RecvTimeoutError::Timeout) => {
+                if bg.guard.is_finished() {
+                    info!("mount ended externally");
+                    if let Err(e) = bg.join() {
+                        warn!(error = %e, "session join failed");
+                    }
+                    break MountOutcome::Unmounted;
+                }
+            }
+            Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => {
+                // Signal task gone (failed to install); fall back to join.
+                let _ = bg.join();
+                break MountOutcome::Unmounted;
+            }
+        }
+    };
+
+    // Unmount every on-demand sync folder too, or the kernel mounts linger as
+    // stale and the next start fails with EBUSY (devices.md Phase 3).
+    let secondaries: Vec<_> = core.mounts.lock().drain().collect();
+    for (id, (session, conn)) in secondaries {
+        if let Err(e) = umount_session_unblocked(session, conn) {
+            warn!(id, error = %e, "unmount on-demand folder failed");
+        }
+    }
+
+    let _ = std::fs::remove_file(control_socket);
+    Ok(outcome)
+}

crates/pdfs-fuse/src/photos.rs

@@ -18,10 +18,78 @@ use proton_drive_rs::{NodeKind, ThumbnailType};
 use tracing::{info, warn};
 
 use super::{
-    Core, PHOTOS_AVAILABLE, PHOTOS_SYNCED_MS, THUMB_GEN_CONCURRENCY, TIMELINE_ENRICH_CHUNK,
-    TIMELINE_TTL, ThumbAttempt, node_size, now_ms, parse_uid, ratio_of, scale_thumbnail,
+    Core, PHOTOS_AVAILABLE, PHOTOS_SYNCED_MS, TIMELINE_ENRICH_CHUNK, TIMELINE_TTL, node_size,
+    now_ms, parse_uid,
 };
 
+/// Longest edge, in px, of a thumbnail generated locally for a photo the server
+/// has none for. Matches the server's own thumbnail scale closely enough that a
+/// tile can't tell them apart.
+const THUMB_EDGE: u32 = 512;
+/// JPEG quality of a locally generated thumbnail.
+const THUMB_QUALITY: u8 = 82;
+/// How many photos may be downloaded at once to generate their missing
+/// thumbnails. Bounded: a screenful of 20 MB digicam JPEGs would otherwise
+/// saturate the link and starve the rest of the daemon.
+const THUMB_GEN_CONCURRENCY: usize = 4;
+
+/// The aspect ratio (w/h) of an encoded image, read from its header alone — no
+/// pixels are decoded. `None` when the format is unknown or the header is torn.
+fn ratio_of(bytes: &[u8]) -> Option<f64> {
+    let (width, height) = image::ImageReader::new(std::io::Cursor::new(bytes))
+        .with_guessed_format()
+        .ok()?
+        .into_dimensions()
+        .ok()?;
+    (height > 0).then(|| f64::from(width) / f64::from(height))
+}
+
+/// A thumbnail the daemon made itself, and the aspect ratio of the photo it was
+/// made from (free at that point — the full image had to be decoded anyway).
+struct GeneratedThumb {
+    bytes: Vec<u8>,
+    ratio: f64,
+}
+
+/// How one attempt at generating a missing thumbnail ended. The distinction that
+/// matters is *permanent* versus *transient*: only bytes we cannot decode prove
+/// the photo will never have a thumbnail, and only that verdict is persisted.
+enum ThumbAttempt {
+    Made(GeneratedThumb),
+    /// Decoded nothing — a format this build has no decoder for. Permanent.
+    Undecodable,
+    /// The photo couldn't be downloaded. Transient: try again next time.
+    Unavailable,
+}
+
+/// Scale a full-size photo down to a thumbnail: at most [`THUMB_EDGE`] on its
+/// longest side, JPEG, aspect ratio preserved. `None` when the bytes aren't an
+/// image this build can decode — the caller then writes the photo off as
+/// un-thumbnailable.
+///
+/// CPU-bound (a 20 MP JPEG is real work), so callers run it on the blocking pool.
+fn scale_thumbnail(bytes: &[u8]) -> Option<GeneratedThumb> {
+    let image = image::ImageReader::new(std::io::Cursor::new(bytes))
+        .with_guessed_format()
+        .ok()?
+        .decode()
+        .ok()?;
+    let (width, height) = (image.width(), image.height());
+    if width == 0 || height == 0 {
+        return None;
+    }
+    let ratio = f64::from(width) / f64::from(height);
+
+    // `thumbnail` fits the image *inside* the box, so the longest edge lands on
+    // THUMB_EDGE and the ratio is untouched.
+    let thumb = image.thumbnail(THUMB_EDGE, THUMB_EDGE).to_rgb8();
+    let mut bytes = Vec::new();
+    image::codecs::jpeg::JpegEncoder::new_with_quality(&mut bytes, THUMB_QUALITY)
+        .encode_image(&thumb)
+        .ok()?;
+    Some(GeneratedThumb { bytes, ratio })
+}
+
 impl Core {
     pub(crate) fn photos_timeline(
         &self,
@@ -361,3 +429,60 @@ impl Core {
         Ok(self.cache.content_path(uid))
     }
 }
+
+#[cfg(test)]
+mod thumb_tests {
+    use super::{THUMB_EDGE, ratio_of, scale_thumbnail};
+
+    /// A `width`×`height` JPEG, standing in for a camera photo the server never
+    /// generated a thumbnail for.
+    fn jpeg(width: u32, height: u32) -> Vec<u8> {
+        let image = image::RgbImage::from_fn(width, height, |x, y| {
+            image::Rgb([(x % 256) as u8, (y % 256) as u8, 128])
+        });
+        let mut bytes = Vec::new();
+        image::codecs::jpeg::JpegEncoder::new(&mut bytes)
+            .encode_image(&image)
+            .unwrap();
+        bytes
+    }
+
+    #[test]
+    fn scaling_fits_the_long_edge_and_keeps_the_aspect_ratio() {
+        let photo = jpeg(4000, 3000);
+        let thumb = scale_thumbnail(&photo).expect("a JPEG scales");
+
+        let (width, height) = image::ImageReader::new(std::io::Cursor::new(&thumb.bytes))
+            .with_guessed_format()
+            .unwrap()
+            .into_dimensions()
+            .unwrap();
+        assert_eq!(width, THUMB_EDGE, "the long edge lands on the target");
+        assert_eq!(height, THUMB_EDGE * 3 / 4, "and nothing is cropped");
+        assert!((thumb.ratio - 4.0 / 3.0).abs() < 1e-6);
+        assert!(
+            thumb.bytes.len() < photo.len(),
+            "a thumbnail that isn't smaller than its photo is no thumbnail"
+        );
+    }
+
+    #[test]
+    fn a_portrait_photo_fits_its_long_edge_too() {
+        let thumb = scale_thumbnail(&jpeg(1000, 2000)).expect("a JPEG scales");
+        assert!(thumb.ratio < 1.0, "portrait stays portrait");
+        assert_eq!(ratio_of(&thumb.bytes).map(|r| r < 1.0), Some(true));
+    }
+
+    #[test]
+    fn undecodable_bytes_are_not_a_thumbnail() {
+        // What a photo in a format this build has no decoder for looks like: the
+        // caller writes it off as un-thumbnailable rather than retrying forever.
+        assert!(scale_thumbnail(b"not an image at all").is_none());
+        assert!(ratio_of(b"not an image at all").is_none());
+    }
+
+    #[test]
+    fn ratio_is_read_from_the_header_alone() {
+        assert_eq!(ratio_of(&jpeg(300, 200)), Some(1.5));
+    }
+}

crates/pdfs-fuse/src/reads.rs

@@ -0,0 +1,645 @@
+//! Revision-reader cache and streamed range-read subsystem.
+
+use super::*;
+
+/// A read of an unpinned video at least this large streams *without* persisting
+/// its blocks to the on-disk cache. Playing a 2 GB film would otherwise pour it
+/// through the block LRU and evict everything else the user actually wants kept —
+/// and it re-streams cheaply enough on a rewatch that keeping it was never worth
+/// that. Pinned videos (kept offline on purpose) and anything smaller cache as
+/// usual.
+pub(super) const STREAM_BYPASS_MIN: u64 = 256 * 1024 * 1024;
+
+/// How many bytes of streamed blocks the in-memory ring keeps. Bypassing the
+/// on-disk cache must not mean re-fetching: the kernel asks for a streamed file
+/// in reads far smaller than [`BLOCK_SIZE`], so without a ring every 128 KiB the
+/// player consumes would download and decrypt a whole 4 MiB block again. Sized
+/// for a handful of blocks per concurrently-streamed file.
+const STREAM_RING_BYTES: u64 = 128 * 1024 * 1024;
+
+/// Blocks fetched *past* the one a sequential streaming read needed, warmed into
+/// the ring in the background so the player's next read is already in memory
+/// instead of waiting a round-trip. Kept small so it cannot crowd out the
+/// in-flight block governor.
+const STREAM_READAHEAD: u64 = 4;
+
+/// How many [`RevisionReader`]s stay open at once.
+///
+/// A reader holds its revision's content key and block table — a few KB even for
+/// a large file, so this is bounded for tidiness and staleness rather than
+/// memory. Evicted least-recently-used; a dropped reader costs one re-open
+/// (two API calls and a node-key unlock) the next time that file is read.
+const MAX_OPEN_READERS: usize = 64;
+
+/// An open reader plus the node metadata it was opened against.
+///
+/// The SDK pins a reader to the revision that was active at `open_revision`, so
+/// a reader is only reusable while the node still reports the same
+/// `(mtime, size)` — the same validity pair the content cache uses (a new
+/// revision bumps mtime). On a mismatch the reader is dropped and reopened.
+pub(super) struct CachedReader {
+    reader: Arc<RevisionReader>,
+    mtime: i64,
+    size: u64,
+    /// For LRU eviction.
+    last_used: Instant,
+}
+
+/// What the `readers` map holds for a node: an open reader, or the fact that
+/// someone is already opening one.
+///
+/// The `Pending` arm is what makes the map single-flight rather than merely a
+/// cache. Opening resolves link details, ancestor keys, an S2K node-key unlock
+/// and the block table — five round-trips — and read-ahead on a cold file puts
+/// several workers into the open at the same moment, so without this each
+/// racer would redo all of it and discard every result but one.
+pub(super) enum ReaderSlot {
+    Ready(CachedReader),
+    Pending(PendingOpen),
+}
+
+/// An `open_revision` in flight. Racers clone `rx` and await the leader's result
+/// instead of opening their own.
+pub(super) struct PendingOpen {
+    /// Identifies this attempt so the leader can tell "my slot is still there"
+    /// from "someone evicted or replaced it while I was on the network", and
+    /// only publish its reader in the first case.
+    id: u64,
+    /// What the leader is opening against. A racer wanting a different revision
+    /// must not join this open — it would get a reader for the wrong bytes.
+    mtime: i64,
+    size: u64,
+    rx: tokio::sync::watch::Receiver<Option<Result<Arc<RevisionReader>, Errno>>>,
+}
+
+/// Distinguishes `PendingOpen`s. Only uniqueness matters, so a plain counter
+/// does; ids are never compared for order.
+static NEXT_OPEN_ID: AtomicU64 = AtomicU64::new(0);
+
+/// Drive client, a Tokio handle to bridge the synchronous FUSE/socket threads
+/// to the async SDK, the inode bookkeeping, and the on-disk content cache.
+///
+/// Cheaply cloneable (every field is a handle/`Arc`), so the control-socket task
+/// gets its own copy while the FUSE session keeps another.
+/// In-memory LRU of blocks belonging to a file streaming past the on-disk cache
+/// (see [`STREAM_BYPASS_MIN`]). Bypassing the disk stops one film evicting the
+/// block LRU; it must not also mean the same 4 MiB block is downloaded once per
+/// 128 KiB the player reads out of it.
+///
+/// Validated by the same `(mtime, size)` pair the on-disk caches use: a node
+/// whose tag no longer matches has its blocks dropped rather than served, so a
+/// new revision can never be stitched together from the old one.
+#[derive(Default)]
+pub(super) struct StreamRing {
+    blocks: HashMap<(NodeUid, u64), Arc<Vec<u8>>>,
+    /// Keys oldest-first, for eviction.
+    order: VecDeque<(NodeUid, u64)>,
+    /// Per-node validity tag, `(mtime, size)`.
+    tags: HashMap<NodeUid, (i64, u64)>,
+    bytes: u64,
+}
+
+impl StreamRing {
+    fn get(&mut self, uid: &NodeUid, mtime: i64, size: u64, idx: u64) -> Option<Arc<Vec<u8>>> {
+        if self.tags.get(uid) != Some(&(mtime, size)) {
+            return None;
+        }
+        self.blocks.get(&(uid.clone(), idx)).cloned()
+    }
+
+    fn insert(&mut self, uid: &NodeUid, mtime: i64, size: u64, idx: u64, bytes: Arc<Vec<u8>>) {
+        if self.tags.get(uid) != Some(&(mtime, size)) {
+            // Revision changed under us (or first sight): anything held for this
+            // node describes the old one.
+            self.drop_node(uid);
+            self.tags.insert(uid.clone(), (mtime, size));
+        }
+        let key = (uid.clone(), idx);
+        if self.blocks.contains_key(&key) {
+            return;
+        }
+        self.bytes += bytes.len() as u64;
+        self.blocks.insert(key.clone(), bytes);
+        self.order.push_back(key);
+        while self.bytes > STREAM_RING_BYTES {
+            let Some(victim) = self.order.pop_front() else {
+                break;
+            };
+            if let Some(dropped) = self.blocks.remove(&victim) {
+                self.bytes -= dropped.len() as u64;
+            }
+        }
+    }
+
+    fn drop_node(&mut self, uid: &NodeUid) {
+        self.order.retain(|(u, _)| u != uid);
+        let mut freed = 0u64;
+        self.blocks.retain(|(u, _), bytes| {
+            if u == uid {
+                freed += bytes.len() as u64;
+                false
+            } else {
+                true
+            }
+        });
+        self.bytes -= freed;
+        self.tags.remove(uid);
+    }
+}
+
+impl Core {
+    /// An open [`RevisionReader`] for `uid`, reusing the cached one when it is
+    /// still valid for `(mtime, fsize)` and opening a fresh one otherwise.
+    ///
+    /// Opening resolves the file's link details, ancestor keys, node key (an S2K
+    /// unlock) and block table. Doing that once per file rather than once per
+    /// block is the whole point: a cold 100 MB read is 25 block misses, which
+    /// used to mean 25 full resolutions (50 API calls, 25 unlocks) and now means
+    /// one.
+    ///
+    /// Racing reads of one cold file open it **once**: the first caller claims
+    /// the slot and the rest await its result. That matters now that `read` is
+    /// served off the dispatch loop, because read-ahead on a first touch issues
+    /// several parallel reads of the same file as a matter of course.
+    async fn revision_reader(
+        &self,
+        uid: &NodeUid,
+        mtime: i64,
+        fsize: u64,
+    ) -> Result<Arc<RevisionReader>, Errno> {
+        loop {
+            // Decide under the lock, act outside it — network I/O must never run
+            // under a std `Mutex`, and an await must never hold one.
+            enum Act {
+                Hit(Arc<RevisionReader>),
+                Join(tokio::sync::watch::Receiver<Option<Result<Arc<RevisionReader>, Errno>>>),
+                Lead(
+                    u64,
+                    tokio::sync::watch::Sender<Option<Result<Arc<RevisionReader>, Errno>>>,
+                ),
+            }
+            let act = {
+                let mut readers = self.readers.lock();
+                match readers.get_mut(uid) {
+                    Some(ReaderSlot::Ready(entry))
+                        if entry.mtime == mtime && entry.size == fsize =>
+                    {
+                        entry.last_used = Instant::now();
+                        Act::Hit(entry.reader.clone())
+                    }
+                    Some(ReaderSlot::Pending(p)) if p.mtime == mtime && p.size == fsize => {
+                        Act::Join(p.rx.clone())
+                    }
+                    // Either nothing here, or something for a revision we no
+                    // longer want (a stale reader, or an open for one). Ours
+                    // replaces it: the newer `(mtime, size)` is the truth.
+                    _ => {
+                        let id = NEXT_OPEN_ID.fetch_add(1, Ordering::Relaxed);
+                        let (tx, rx) = tokio::sync::watch::channel(None);
+                        readers.insert(
+                            uid.clone(),
+                            ReaderSlot::Pending(PendingOpen {
+                                id,
+                                mtime,
+                                size: fsize,
+                                rx,
+                            }),
+                        );
+                        Act::Lead(id, tx)
+                    }
+                }
+            };
+
+            match act {
+                Act::Hit(reader) => return Ok(reader),
+                Act::Join(mut rx) => {
+                    // `changed()` errors only if the leader dropped its sender
+                    // without publishing — it panicked. Retry from the top
+                    // rather than fail: the slot it left is gone, so this pass
+                    // leads its own open.
+                    loop {
+                        if let Some(result) = rx.borrow_and_update().clone() {
+                            return result;
+                        }
+                        if rx.changed().await.is_err() {
+                            break;
+                        }
+                    }
+                    continue;
+                }
+                Act::Lead(id, tx) => {
+                    debug!(%uid, mtime, fsize, "opening revision");
+                    let result = match self.client.open_revision(uid).await {
+                        Ok(reader) => Ok(Arc::new(reader)),
+                        Err(e) => {
+                            warn!(%uid, error = %e, "open_revision failed");
+                            Err(Errno::EIO)
+                        }
+                    };
+                    {
+                        let mut readers = self.readers.lock();
+                        // Publish only into the slot we claimed. If it is gone
+                        // or belongs to a later attempt, an eviction or a newer
+                        // revision overtook us: our reader still answers the
+                        // callers waiting on it, but it must not be cached.
+                        let ours = matches!(
+                            readers.get(uid),
+                            Some(ReaderSlot::Pending(p)) if p.id == id
+                        );
+                        if ours {
+                            match &result {
+                                Ok(reader) => {
+                                    readers.insert(
+                                        uid.clone(),
+                                        ReaderSlot::Ready(CachedReader {
+                                            reader: reader.clone(),
+                                            mtime,
+                                            size: fsize,
+                                            last_used: Instant::now(),
+                                        }),
+                                    );
+                                }
+                                // Never cache a failure: the next read retries.
+                                Err(_) => {
+                                    readers.remove(uid);
+                                }
+                            }
+                        }
+                        Self::trim_readers(&mut readers);
+                    }
+                    // After the map is updated, so a racer that wakes and
+                    // re-enters finds the finished slot rather than racing us.
+                    let _ = tx.send(Some(result.clone()));
+                    return result;
+                }
+            }
+        }
+    }
+
+    /// Bound the reader map: drop least-recently-used entries until it is back
+    /// at [`MAX_OPEN_READERS`]. Only `Ready` slots are eviction candidates — a
+    /// `Pending` has callers waiting on it and no reader to drop yet.
+    fn trim_readers(readers: &mut HashMap<NodeUid, ReaderSlot>) {
+        while readers.len() > MAX_OPEN_READERS {
+            let victim = readers
+                .iter()
+                .filter_map(|(uid, slot)| match slot {
+                    ReaderSlot::Ready(entry) => Some((uid, entry.last_used)),
+                    ReaderSlot::Pending(_) => None,
+                })
+                .min_by_key(|(_, last_used)| *last_used)
+                .map(|(uid, _)| uid.clone());
+            let Some(victim) = victim else {
+                break; // every slot is an open in flight; nothing to drop
+            };
+            readers.remove(&victim);
+        }
+    }
+
+    /// Drop any open reader for `uid`, so the next read reopens against the
+    /// current revision. Called wherever cached content is evicted.
+    ///
+    /// Drops an in-flight open too: its leader finds the slot gone and declines
+    /// to cache what it opened, which is what we want — the eviction says that
+    /// revision is no longer the truth.
+    pub(super) fn evict_reader(&self, uid: &NodeUid) {
+        self.readers.lock().remove(uid);
+    }
+
+    /// Serve bytes `[offset, offset + len)` of `uid`'s active revision, hitting
+    /// the on-disk caches before the network: a whole-file blob (pinned files)
+    /// first, then the block cache — fetching only the [`BLOCK_SIZE`]-aligned
+    /// blocks that overlap the request and caching each. `mtime`/`fsize` validate
+    /// both caches. Network I/O runs without any lock held.
+    pub(super) fn read_range(
+        &self,
+        uid: &NodeUid,
+        mtime: i64,
+        fsize: u64,
+        offset: u64,
+        len: u64,
+        cache_blocks: bool,
+    ) -> Result<Vec<u8>, Errno> {
+        // A queued write has not reached the remote yet, so the remote's current
+        // revision is stale and the staged blob is the truth. Serve from it until
+        // the drain worker lands the upload (offline.md Phase 3).
+        if let Some(pending) = self.pending.lock().get(uid).cloned() {
+            return self.read_pending(&pending, offset, len);
+        }
+        // A node created offline and never written has no blob and no remote: it
+        // is an empty file, and asking the API about a `local~` uid would only
+        // earn a 404 (offline.md Phase 3b).
+        if is_local_uid(uid) {
+            return Ok(Vec::new());
+        }
+        self.read_range_remote(uid, mtime, fsize, offset, len, cache_blocks)
+    }
+
+    /// Serve a read from a staged blob, falling back to the remote base for any
+    /// range the write did not author (an incomplete [`StagedWrite`] holds zeros
+    /// there, which must never be handed out as content).
+    fn read_pending(
+        &self,
+        pending: &PendingRevision,
+        offset: u64,
+        len: u64,
+    ) -> Result<Vec<u8>, Errno> {
+        let m = &pending.meta;
+        if offset >= m.len || len == 0 {
+            return Ok(Vec::new());
+        }
+        let uid = parse_node_uid(&m.uid).ok_or(Errno::EIO)?;
+        let file = File::open(&pending.path).map_err(|e| {
+            error!(%uid, path = %pending.path.display(), error = %e, "open staged blob failed");
+            Errno::EIO
+        })?;
+        let mut written = Intervals::default();
+        for &(s, e) in &m.authored {
+            written.add(s, e);
+        }
+        // Same merge as `serve_open_read`, but resolving gaps against the remote
+        // rather than through `read_range` — going through `read_range` would find
+        // this very pending op and recurse.
+        let end = offset.saturating_add(len).min(m.len);
+        let mut out = Vec::with_capacity((end - offset) as usize);
+        for (s, e, authored) in written.segments(offset, end) {
+            if authored {
+                let mut buf = vec![0u8; (e - s) as usize];
+                file.read_exact_at(&mut buf, s).map_err(|err| {
+                    warn!(%uid, error = %err, "staged blob read failed");
+                    Errno::EIO
+                })?;
+                out.extend_from_slice(&buf);
+                continue;
+            }
+            let bend = e.min(m.base_size);
+            if s < bend {
+                out.extend_from_slice(&self.read_range_remote(
+                    &uid,
+                    m.base_mtime,
+                    m.base_size,
+                    s,
+                    bend - s,
+                    true,
+                )?);
+            }
+            // Past the base: a hole the write extended over.
+            out.resize(out.len() + e.saturating_sub(s.max(m.base_size)) as usize, 0);
+        }
+        Ok(out)
+    }
+
+    /// Warm the [`STREAM_READAHEAD`] blocks after `last` into the ring, in the
+    /// background, so a player reading forward finds its next block already in
+    /// memory rather than paying a fetch + decrypt round-trip at each boundary.
+    ///
+    /// Fire-and-forget: a failure here is not an error, it only means the read
+    /// that needs those bytes will fetch them itself.
+    fn stream_readahead(&self, uid: &NodeUid, mtime: i64, fsize: u64, last: u64) {
+        let last_block = (fsize.saturating_sub(1)) / BLOCK_SIZE;
+        let wanted: Vec<u64> = ((last + 1)..=(last + STREAM_READAHEAD).min(last_block))
+            .filter(|&bidx| {
+                self.stream_ring
+                    .lock()
+                    .get(uid, mtime, fsize, bidx)
+                    .is_none()
+            })
+            .collect();
+        if wanted.is_empty() {
+            return;
+        }
+        let core = self.clone();
+        let uid = uid.clone();
+        self.rt.spawn(async move {
+            let Ok(reader) = core.revision_reader(&uid, mtime, fsize).await else {
+                return;
+            };
+            // Concurrently, for the same reason the demand path fetches its
+            // misses concurrently: serially awaited blocks cost the sum of their
+            // round-trips, and the player catches up with the readahead before it
+            // finishes. The SDK's in-flight block governor bounds the fan-out.
+            let mut set = tokio::task::JoinSet::new();
+            for bidx in wanted {
+                let reader = reader.clone();
+                let bstart = bidx * BLOCK_SIZE;
+                let blen = BLOCK_SIZE.min(fsize - bstart);
+                set.spawn(async move { (bidx, reader.read_at(bstart, blen).await) });
+            }
+            while let Some(joined) = set.join_next().await {
+                let Ok((bidx, read)) = joined else { continue };
+                match read {
+                    Ok(bytes) => {
+                        core.stream_ring
+                            .lock()
+                            .insert(&uid, mtime, fsize, bidx, Arc::new(bytes))
+                    }
+                    Err(e) => debug!(%uid, bidx, error = %e, "stream readahead failed"),
+                }
+            }
+        });
+    }
+
+    /// Read from the content cache, else the remote. The base-content path, with
+    /// no awareness of queued writes — callers wanting the file's *current*
+    /// content want [`Core::read_range`]. Gap-filling a staged blob is the one
+    /// caller that genuinely means "the base", since that is what its zeroed
+    /// ranges have to be filled from.
+    fn read_range_remote(
+        &self,
+        uid: &NodeUid,
+        mtime: i64,
+        fsize: u64,
+        offset: u64,
+        len: u64,
+        cache_blocks: bool,
+    ) -> Result<Vec<u8>, Errno> {
+        if let Some(bytes) = self.cache.read_range(uid, mtime, fsize, offset, len) {
+            return Ok(bytes);
+        }
+        if offset >= fsize || len == 0 {
+            return Ok(Vec::new());
+        }
+        let end = offset.saturating_add(len).min(fsize);
+        let mut out = Vec::with_capacity((end - offset) as usize);
+        let first = offset / BLOCK_SIZE;
+        let last = (end - 1) / BLOCK_SIZE;
+
+        // Collect the blocks overlapping the request, serving any already cached
+        // and fetching the rest concurrently. A multi-block read (e.g. a media
+        // player buffering, or a large sequential read split into one FUSE call)
+        // would otherwise stall on each block round-trip in turn; downloading the
+        // misses in parallel saturates the connection and bounds latency at the
+        // slowest single block instead of their sum.
+        let mut blocks: Vec<Option<Arc<Vec<u8>>>> = Vec::with_capacity((last - first + 1) as usize);
+        let mut misses: Vec<u64> = Vec::new();
+        for bidx in first..=last {
+            // A streaming read keeps its blocks only in memory, so the ring is
+            // the only cache it has — check it before the disk (which will not
+            // hold them) and before the network (which would refetch the same
+            // 4 MiB block for every 128 KiB the player consumes).
+            let hit = if cache_blocks {
+                self.cache
+                    .cached_block(uid, mtime, fsize, bidx)
+                    .map(Arc::new)
+            } else {
+                self.stream_ring.lock().get(uid, mtime, fsize, bidx)
+            };
+            match hit {
+                Some(b) => blocks.push(Some(b)),
+                None => {
+                    blocks.push(None);
+                    misses.push(bidx);
+                }
+            }
+        }
+
+        if !misses.is_empty() {
+            let fetched = self.rt.block_on(async {
+                // Resolve the file's keys and block table once, then read every
+                // missing block through the shared reader. Previously each block
+                // called `download_range`, which redid that resolution per block.
+                let reader = self.revision_reader(uid, mtime, fsize).await?;
+
+                let mut set = tokio::task::JoinSet::new();
+                for &bidx in &misses {
+                    let reader = reader.clone();
+                    let uid = uid.clone();
+                    let bstart = bidx * BLOCK_SIZE;
+                    let blen = BLOCK_SIZE.min(fsize - bstart);
+                    set.spawn(async move {
+                        reader
+                            .read_at(bstart, blen)
+                            .await
+                            .map(|bytes| (bidx, bytes))
+                            .map_err(|e| {
+                                warn!(%uid, bstart, blen, error = %e, "block read failed");
+                                Errno::EIO
+                            })
+                    });
+                }
+                let mut out = Vec::with_capacity(misses.len());
+                while let Some(joined) = set.join_next().await {
+                    // A join error means the task panicked; surface it as EIO.
+                    out.push(joined.map_err(|_| Errno::EIO)??);
+                }
+                Ok::<_, Errno>(out)
+            })?;
+            for (bidx, bytes) in fetched {
+                // A streaming read (large unpinned video) skips the on-disk cache
+                // so it can't evict the rest of it; it keeps the block in the
+                // in-memory ring instead, which is bounded and dies with the read.
+                let bytes = Arc::new(bytes);
+                if cache_blocks {
+                    let _ = self.cache.store_block(uid, mtime, fsize, bidx, &bytes);
+                } else {
+                    self.stream_ring
+                        .lock()
+                        .insert(uid, mtime, fsize, bidx, bytes.clone());
+                }
+                blocks[(bidx - first) as usize] = Some(bytes);
+            }
+            if !cache_blocks {
+                self.stream_readahead(uid, mtime, fsize, last);
+            }
+        }
+
+        for (i, block) in blocks.into_iter().enumerate() {
+            let bidx = first + i as u64;
+            let bstart = bidx * BLOCK_SIZE;
+            // Every slot is populated: cache hits up front, misses by the fetch above.
+            let block = block.expect("block fetched or cached");
+            let s = (offset.max(bstart) - bstart) as usize;
+            let e = (end.min(bstart + block.len() as u64) - bstart) as usize;
+            if s < e {
+                out.extend_from_slice(&block[s..e]);
+            }
+        }
+        Ok(out)
+    }
+
+    /// Serve a read against an open write handle: stitch authored ranges (from
+    /// the scratch file) and untouched ranges (from the remote base via the
+    /// block cache) in order, zero-filling any region past the base.
+    #[allow(clippy::too_many_arguments)]
+    pub(super) fn serve_open_read(
+        &self,
+        file: &Arc<File>,
+        len: u64,
+        uid: &NodeUid,
+        base_mtime: i64,
+        base_size: u64,
+        written: &Intervals,
+        offset: u64,
+        size: u64,
+    ) -> Result<Vec<u8>, Errno> {
+        if offset >= len || size == 0 {
+            return Ok(Vec::new());
+        }
+        let end = offset.saturating_add(size).min(len);
+        let mut out = Vec::with_capacity((end - offset) as usize);
+        for (s, e, authored) in written.segments(offset, end) {
+            if authored {
+                let mut buf = vec![0u8; (e - s) as usize];
+                file.read_exact_at(&mut buf, s).map_err(|err| {
+                    warn!(%uid, error = %err, "scratch read failed");
+                    Errno::EIO
+                })?;
+                out.extend_from_slice(&buf);
+            } else {
+                let bend = e.min(base_size);
+                if s < bend {
+                    out.extend_from_slice(&self.read_range(
+                        uid,
+                        base_mtime,
+                        base_size,
+                        s,
+                        bend - s,
+                        true,
+                    )?);
+                }
+                // Anything past the base is a hole: zero-fill.
+                let zeros = e.saturating_sub(s.max(base_size));
+                out.resize(out.len() + zeros as usize, 0);
+            }
+        }
+        Ok(out)
+    }
+
+    /// Fill every unauthored range of a scratch/staged file that overlaps its
+    /// base with the base's bytes, so the file becomes the complete new content.
+    ///
+    /// This is the step a partial overwrite cannot skip: only the authored bytes
+    /// were ever written to disk, and a revision upload sends the whole file.
+    /// The gaps come from the *remote base* (through the block cache, so a small
+    /// edit of a large file does not pull all of it), which is exactly why this
+    /// can fail with no network — see `StagedWrite`.
+    pub(super) fn fill_gaps(
+        &self,
+        uid: &NodeUid,
+        file: &File,
+        len: u64,
+        base_mtime: i64,
+        base_size: u64,
+        written: &Intervals,
+    ) -> Result<(), Errno> {
+        file.set_len(len).map_err(|e| {
+            error!(%uid, error = %e, "resize scratch file failed");
+            Errno::EIO
+        })?;
+        for (s, e, authored) in written.segments(0, len) {
+            if authored {
+                continue;
+            }
+            let bend = e.min(base_size);
+            if s >= bend {
+                continue; // wholly past the base: already zero-filled on disk
+            }
+            let bytes = self.read_range_remote(uid, base_mtime, base_size, s, bend - s, true)?;
+            file.write_all_at(&bytes, s).map_err(|err| {
+                error!(%uid, error = %err, "scratch gap-fill write failed");
+                Errno::EIO
+            })?;
+        }
+        Ok(())
+    }
+}

crates/pdfs-fuse/src/state.rs

@@ -18,6 +18,9 @@ pub(crate) struct Entry {
     pub(crate) uid: NodeUid,
     pub(crate) parent: u64,
     pub(crate) node: Node,
+    pub(crate) lookup_count: u64,
+    pub(crate) open_count: u32,
+    pub(crate) unlinked: bool,
 }
 
 /// A set of non-overlapping `[start, end)` byte ranges, kept sorted and merged.
@@ -105,6 +108,8 @@ pub(crate) struct WriteHandle {
     pub(crate) base_mtime: i64,
     /// Whether anything diverged from the remote and needs an upload.
     pub(crate) dirty: bool,
+    /// Number of file handles currently sharing this scratch state.
+    pub(crate) open_count: usize,
 }
 
 /// A released write whose upload has not happened yet (offline.md Phase 3).
@@ -131,9 +136,11 @@ pub(crate) struct State {
     /// key means the directory has been enumerated.
     pub(crate) children: HashMap<u64, Vec<u64>>,
     pub(crate) next_ino: u64,
-    /// Open write handles keyed by file handle id. Read-only opens use fh 0 and
+    /// Shared write state keyed by inode. Concurrent writers share the scratch file.
+    pub(crate) active_writes: HashMap<u64, WriteHandle>,
+    /// Maps file handle id (fh) to inode (ino). Read-only opens use fh 0 and
     /// have no entry here.
-    pub(crate) handles: HashMap<u64, WriteHandle>,
+    pub(crate) handles: HashMap<u64, u64>,
     pub(crate) next_fh: u64,
     /// Unified SQLite metadata cache. Every map mutation below writes through to
     /// it inside the `State` lock so the DB stays the authoritative copy across
@@ -169,11 +176,26 @@ impl State {
                 uid: node.uid.clone(),
                 parent,
                 node,
+                lookup_count: 1,
+                open_count: 0,
+                unlinked: false,
             },
         );
         ino
     }
 
+    /// Decrement lookup count for an inode and prune if lookup_count == 0 && open_count == 0 && unlinked.
+    pub(crate) fn forget_lookup(&mut self, ino: u64, nlookup: u64) -> Option<(u64, String)> {
+        if let Some(entry) = self.entries.get_mut(&ino) {
+            entry.lookup_count = entry.lookup_count.saturating_sub(nlookup);
+            if entry.lookup_count == 0 && entry.open_count == 0 && entry.unlinked {
+                let uid = entry.uid.clone();
+                return self.forget(&uid);
+            }
+        }
+        None
+    }
+
     /// Allocate (or reuse) a stable inode for a node that came *from* the
     /// database, which is why nothing is written back.
     pub(crate) fn intern_from_db(&mut self, parent: u64, node: Node) -> u64 {
@@ -195,6 +217,57 @@ impl State {
             .collect()
     }
 
+    /// Check if a directory inode has any child nodes in memory or in the database.
+    pub(crate) fn has_children(&self, parent: u64) -> bool {
+        if let Some(kids) = self.children.get(&parent)
+            && !kids.is_empty()
+        {
+            return true;
+        }
+        if let Some(entry) = self.entries.get(&parent)
+            && let Ok(has_kids) = self.db.has_children(&entry.uid)
+        {
+            return has_kids;
+        }
+        false
+    }
+
+    /// Check if `ancestor_ino` is `target_ino` or an ancestor of `target_ino` (for rename cycle prevention).
+    pub(crate) fn is_ancestor_of(&self, ancestor_ino: u64, mut target_ino: u64) -> bool {
+        if ancestor_ino == target_ino {
+            return true;
+        }
+        let mut visited = std::collections::HashSet::new();
+        visited.insert(target_ino);
+        while let Some(entry) = self.entries.get(&target_ino) {
+            let parent = entry.parent;
+            if parent == ancestor_ino {
+                return true;
+            }
+            if parent == 0 || !visited.insert(parent) {
+                break;
+            }
+            target_ino = parent;
+        }
+        false
+    }
+
+    /// Forget a node or, if open handles exist (open_count > 0), mark it unlinked
+    /// and remove it from parent children so lookups fail while open reads succeed.
+    pub(crate) fn forget_or_unlink(&mut self, uid: &NodeUid) -> Option<(u64, String)> {
+        if let Some(&ino) = self.by_uid.get(uid)
+            && let Some(entry) = self.entries.get_mut(&ino)
+            && entry.open_count > 0
+        {
+            entry.unlinked = true;
+            if let Some(kids) = self.children.get_mut(&entry.parent) {
+                kids.retain(|&k| k != ino);
+            }
+            return Some((entry.parent, entry.node.name.clone()));
+        }
+        self.forget(uid)
+    }
+
     /// Forget a node entirely: drop its inode, its uid mapping, its own cached
     /// listing, its slot in its parent's listing, and its DB row. Returns
     /// `(parent_ino, name)` when the node was known, so the caller can notify
@@ -410,6 +483,7 @@ mod tests {
             by_uid: HashMap::new(),
             children: HashMap::new(),
             next_ino: 1,
+            active_writes: HashMap::new(),
             handles: HashMap::new(),
             next_fh: 1,
             db: Arc::new(db),
@@ -492,4 +566,47 @@ mod tests {
              with no way to notice anything else changed"
         );
     }
+
+    #[test]
+    fn test_is_ancestor_of_hierarchy() {
+        let (mut st, _dir) = state();
+        let root = st.intern(0, node("root_id", "none", "root", true));
+        let p1 = st.intern(root, node("p1_id", "root_id", "p1", true));
+        let p2 = st.intern(p1, node("p2_id", "p1_id", "p2", true));
+        let child = st.intern(p2, node("child_id", "p2_id", "child", true));
+
+        assert!(st.is_ancestor_of(root, root), "self is ancestor");
+        assert!(st.is_ancestor_of(root, p1), "root is ancestor of p1");
+        assert!(
+            st.is_ancestor_of(root, child),
+            "root is ancestor of deep child"
+        );
+        assert!(st.is_ancestor_of(p1, child), "p1 is ancestor of deep child");
+        assert!(
+            !st.is_ancestor_of(child, root),
+            "child is not ancestor of root"
+        );
+        assert!(!st.is_ancestor_of(child, p1), "child is not ancestor of p1");
+    }
+
+    #[test]
+    fn test_state_has_children_mem_and_db() {
+        let (mut st, _dir) = state();
+        let folder = st.intern_mem(0, node("dir_uid", "none", "dir", true));
+        assert!(!st.has_children(folder), "initially empty");
+
+        // Memory-only children (using intern_mem so DB is not populated yet)
+        let f1 = st.intern_mem(folder, node("file1_uid", "dir_uid", "file1.txt", false));
+        st.children.insert(folder, vec![f1]);
+        assert!(st.has_children(folder), "has child in memory");
+
+        st.children.insert(folder, vec![]);
+        assert!(!st.has_children(folder), "cleared memory children");
+
+        // DB children
+        st.db
+            .upsert_node(&node("file2_uid", "dir_uid", "file2.txt", false))
+            .unwrap();
+        assert!(st.has_children(folder), "has child in db");
+    }
 }

crates/pdfs-fuse/src/sync.rs

@@ -11,6 +11,17 @@
 //! exposed). The baseline is refreshed from ground truth after every applied
 //! action, so a file just uploaded or downloaded reads as "unchanged" on the
 //! next pass and never ping-pongs.
+//!
+//! ## Open-for-write deferral
+//!
+//! A file still held open for writing by another process is not uploaded.
+//! Uploading mid-write produces a torn snapshot — a revision that was never a
+//! real state of the file — wasting the encrypt-and-upload cost and creating a
+//! revision the user never asked for. The FUSE mount path already defers until
+//! `close(fd)` by design; the mirror path now does the same by scanning
+//! `/proc/*/fd` once per reconcile pass and skipping any file whose fd flags
+//! include `O_WRONLY` or `O_RDWR`. Deferred files are picked up on the next
+//! pass, after the writer has closed them.
 
 use parking_lot::Mutex;
 use std::collections::{HashMap, HashSet};
@@ -23,7 +34,7 @@ use std::time::{Duration, Instant, SystemTime};
 use notify::{RecursiveMode, Watcher};
 use proton_drive_rs::proton_sdk::ids::NodeUid;
 use proton_drive_rs::{Node, NodeKind};
-use tracing::{info, warn};
+use tracing::{debug, info, warn};
 
 use crate::transfers::{CountingWriter, OwnedCountingReader};
 use crate::{Core, now_secs, parse_uid};
@@ -31,526 +42,23 @@ use pdfs_core::control::{ActivityKind, TransferDirection};
 use pdfs_core::db::{StoredSyncEntry, StoredSyncFolder};
 use pdfs_core::syncignore::IgnoreRules;
 
-/// How long the watcher must go quiet before a burst counts as finished.
-///
-/// Measured from the *last* event, not the first: applications do not write a
-/// file once. An editor saves by writing a temp file and renaming it over the
-/// target; an export or a database dump writes continuously for as long as it
-/// takes. Settling a fixed interval after the first event walks the tree while
-/// the file is still growing, and uploads a torn snapshot as a real revision —
-/// corrected on the next pass, but only after spending the encrypt-and-upload
-/// on a file that was never in that state.
-const DEBOUNCE: Duration = Duration::from_secs(2);
-/// Ceiling on the settle wait, so a directory under sustained change still
-/// syncs. Without it, copying a large tree in — events arriving forever —
-/// would postpone the reconcile for as long as the copy ran.
-const MAX_SETTLE: Duration = Duration::from_secs(30);
-/// How often to re-walk remotes so changes made on other clients are pulled in.
-const POLL_INTERVAL: Duration = Duration::from_secs(120);
-/// How many uploads/downloads/folder-creations a reconcile runs at once. The
-/// per-item work is a network round-trip, so a folder with thousands of files is
-/// unusable done one-at-a-time; this bounds concurrency like the bulk-upload
-/// engine ([`crate::run_uploads`]) does.
-const SYNC_CONCURRENCY: usize = 8;
-
-/// A message to the sync engine's control thread.
-pub(crate) enum SyncMsg {
-    /// Reconcile one folder by id (a local change, or a targeted `SyncNow`).
-    Reconcile(i64),
-    /// Reconcile every mirror folder (periodic poll, or startup).
-    ReconcileAll,
-    /// Re-read the folder set and adjust the filesystem watches (after add/remove).
-    Rewatch,
-}
-
-/// Start the sync engine: a control thread that owns the filesystem watcher and
-/// serialises reconcile passes, plus a periodic poll thread. The engine receives
-/// on `rx`; senders live in [`Core::sync_tx`].
-pub(crate) fn spawn(core: Core, rx: Receiver<SyncMsg>) {
-    if let Err(e) = std::thread::Builder::new()
-        .name("pdfs-sync".into())
-        .spawn(move || engine_loop(core, rx))
-    {
-        warn!(error = %e, "failed to start sync engine");
-    }
-}
-
-/// The engine control loop. Single-threaded so reconcile passes never overlap.
-fn engine_loop(core: Core, rx: Receiver<SyncMsg>) {
-    // Paths the watcher currently covers, mapped to their folder id, so an event
-    // path can be resolved back to the folder it belongs to.
-    let watched: Mutex<Vec<(PathBuf, i64)>> = Mutex::new(Vec::new());
-
-    let tx_events = core.sync_tx.clone();
-    let mut watcher =
-        match notify::recommended_watcher(move |res: notify::Result<notify::Event>| {
-            let Ok(event) = res else { return };
-            // Ignore pure metadata/access noise; content changes are what matter.
-            if matches!(event.kind, notify::EventKind::Access(_)) {
-                return;
-            }
-            let _ = tx_events.send(SyncMsg::ReconcileAll);
-        }) {
-            Ok(w) => w,
-            Err(e) => {
-                warn!(error = %e, "filesystem watcher unavailable; sync is poll-only");
-                // Still run the loop so polling and explicit SyncNow work.
-                poll_only_loop(&core, rx);
-                return;
-            }
-        };
-
-    // Periodic remote poll.
-    {
-        let tx = core.sync_tx.clone();
-        std::thread::Builder::new()
-            .name("pdfs-sync-poll".into())
-            .spawn(move || {
-                loop {
-                    std::thread::sleep(POLL_INTERVAL);
-                    if tx.send(SyncMsg::ReconcileAll).is_err() {
-                        break;
-                    }
-                }
-            })
-            .ok();
-    }
-
-    rewatch(&core, &mut watcher, &watched);
-    reconcile_all(&core);
-
-    while let Ok(msg) = rx.recv() {
-        let mut ids: HashSet<i64> = HashSet::new();
-        let mut all = false;
-        let mut do_rewatch = false;
-        classify(msg, &mut ids, &mut all, &mut do_rewatch);
-        settle(&rx, &mut ids, &mut all, &mut do_rewatch);
-
-        if do_rewatch {
-            rewatch(&core, &mut watcher, &watched);
-        }
-        if all {
-            reconcile_all(&core);
-        } else {
-            for id in ids {
-                if let Ok(Some(folder)) = core.db.sync_folder_get(id) {
-                    core.reconcile_folder(&folder);
-                }
-            }
-        }
-    }
-}
-
-/// Fallback loop when no filesystem watcher could be created: poll + SyncNow only.
-fn poll_only_loop(core: &Core, rx: Receiver<SyncMsg>) {
-    {
-        let tx = core.sync_tx.clone();
-        std::thread::spawn(move || {
-            loop {
-                std::thread::sleep(POLL_INTERVAL);
-                if tx.send(SyncMsg::ReconcileAll).is_err() {
-                    break;
-                }
-            }
-        });
-    }
-    reconcile_all(core);
-    while let Ok(msg) = rx.recv() {
-        let mut ids: HashSet<i64> = HashSet::new();
-        let mut all = false;
-        let mut do_rewatch = false;
-        classify(msg, &mut ids, &mut all, &mut do_rewatch);
-        settle(&rx, &mut ids, &mut all, &mut do_rewatch);
-        if all {
-            reconcile_all(core);
-        } else {
-            for id in ids {
-                if let Ok(Some(folder)) = core.db.sync_folder_get(id) {
-                    core.reconcile_folder(&folder);
-                }
-            }
-        }
-    }
-}
-
-/// Absorb the rest of an event burst, returning once the watcher has been quiet
-/// for `quiet` or `cap` has elapsed since the first event — whichever comes
-/// first. The caller has already classified the event that opened the burst.
-///
-/// Split out with its timings as parameters so the settling behaviour can be
-/// tested in milliseconds rather than in the tens of seconds the real constants
-/// describe.
-fn settle_with(
-    rx: &Receiver<SyncMsg>,
-    ids: &mut HashSet<i64>,
-    all: &mut bool,
-    do_rewatch: &mut bool,
-    quiet: Duration,
-    cap: Duration,
-) {
-    let deadline = Instant::now() + cap;
-    loop {
-        let now = Instant::now();
-        if now >= deadline {
-            break;
-        }
-        // Never wait past the cap, however quiet the watcher goes.
-        let wait = quiet.min(deadline - now);
-        match rx.recv_timeout(wait) {
-            // Another event: the burst is still going, so the quiet window
-            // starts again from here.
-            Ok(m) => classify(m, ids, all, do_rewatch),
-            // Quiet for a full window: whatever was being written has stopped.
-            Err(RecvTimeoutError::Timeout) => break,
-            // Every sender is gone; the caller's loop is about to end anyway.
-            Err(RecvTimeoutError::Disconnected) => break,
-        }
-    }
-}
-
-/// [`settle_with`] at the real timings.
-fn settle(rx: &Receiver<SyncMsg>, ids: &mut HashSet<i64>, all: &mut bool, do_rewatch: &mut bool) {
-    settle_with(rx, ids, all, do_rewatch, DEBOUNCE, MAX_SETTLE);
-}
-
-fn classify(msg: SyncMsg, ids: &mut HashSet<i64>, all: &mut bool, rewatch: &mut bool) {
-    match msg {
-        SyncMsg::Reconcile(id) => {
-            ids.insert(id);
-        }
-        SyncMsg::ReconcileAll => *all = true,
-        SyncMsg::Rewatch => *rewatch = true,
-    }
-}
-
-/// Reconcile every mirror folder in turn.
-fn reconcile_all(core: &Core) {
-    let folders = match core.db.sync_folder_list() {
-        Ok(f) => f,
-        Err(e) => {
-            warn!(error = ?e, "sync: cannot list folders");
-            return;
-        }
-    };
-    for folder in folders {
-        core.reconcile_folder(&folder);
-    }
-}
-
-/// Bring the filesystem watches in line with the current mirror-folder set:
-/// watch newly-added folders, drop removed ones.
-fn rewatch(
-    core: &Core,
-    watcher: &mut notify::RecommendedWatcher,
-    watched: &Mutex<Vec<(PathBuf, i64)>>,
-) {
-    let want: Vec<(PathBuf, i64)> = match core.db.sync_folder_list() {
-        Ok(f) => f
-            .into_iter()
-            .filter(|f| f.mode == "mirror")
-            .map(|f| (PathBuf::from(f.local_path), f.id))
-            .collect(),
-        Err(e) => {
-            warn!(error = ?e, "sync: cannot list folders to watch");
-            return;
-        }
-    };
-    let mut have = watched.lock();
-    // Drop watches no longer wanted.
-    have.retain(|(path, _)| {
-        if want.iter().any(|(p, _)| p == path) {
-            true
-        } else {
-            let _ = watcher.unwatch(path);
-            false
-        }
-    });
-    // Add newly wanted watches.
-    for (path, id) in &want {
-        if have.iter().any(|(p, _)| p == path) {
-            continue;
-        }
-        match watcher.watch(path, RecursiveMode::Recursive) {
-            Ok(()) => have.push((path.clone(), *id)),
-            Err(e) => warn!(path = %path.display(), error = %e, "sync: watch failed"),
-        }
-    }
-}
-
-// ---- reconcile ------------------------------------------------------------
-
-/// One item found while walking a local tree.
-struct LocalItem {
-    is_dir: bool,
-    mtime: i64,
-    size: i64,
-}
-
-/// One item found while walking a remote tree.
-struct RemoteItem {
-    uid: NodeUid,
-    is_dir: bool,
-    mtime: i64,
-    size: i64,
-}
-
-/// The result of a reconcile pass: what it moved, how many paths were kept as
-/// conflict copies, and how many failed to apply (and so still need another
-/// pass). The counts drive both the folder's state and its activity summary.
-#[derive(Default)]
-struct Outcome {
-    uploaded: usize,
-    downloaded: usize,
-    created: usize,
-    deleted: usize,
-    conflicts: usize,
-    errors: usize,
-}
-
-impl Outcome {
-    /// Fold in one applied op.
-    fn record(&mut self, applied: &Applied) {
-        match applied {
-            Applied::Dir(..) => self.created += 1,
-            Applied::Uploaded => self.uploaded += 1,
-            Applied::Downloaded => self.downloaded += 1,
-            Applied::Conflict => self.conflicts += 1,
-        }
-    }
-
-    /// Whether the pass moved nothing at all — the common case on a poll of an
-    /// unchanged folder, which should not add a line to the activity feed.
-    fn is_empty(&self) -> bool {
-        self.uploaded == 0
-            && self.downloaded == 0
-            && self.created == 0
-            && self.deleted == 0
-            && self.conflicts == 0
-            && self.errors == 0
-    }
-
-    /// A human summary of the pass: "3 uploaded, 1 downloaded, 2 failed".
-    fn summary(&self) -> String {
-        let mut parts = Vec::new();
-        for (n, label) in [
-            (self.uploaded, "uploaded"),
-            (self.downloaded, "downloaded"),
-            (self.created, "folder(s) created"),
-            (self.deleted, "deleted"),
-            (self.conflicts, "conflicted"),
-            (self.errors, "failed"),
-        ] {
-            if n > 0 {
-                parts.push(format!("{n} {label}"));
-            }
-        }
-        parts.join(", ")
-    }
-}
-
-/// A network operation queued during classification and run concurrently in a
-/// per-depth batch. Parent uids are resolved up front (the parent folder is one
-/// depth shallower and already created), so tasks share nothing mutable.
-enum Pending {
-    /// Create a new remote folder under `parent`.
-    CreateDir { rel: String, parent: NodeUid },
-    /// Upload a brand-new local file into `parent`.
-    UploadNew { rel: String, parent: NodeUid },
-    /// Upload a changed local file as a new revision of `uid`.
-    UploadRevision { rel: String, uid: NodeUid },
-    /// Download remote `uid` to the local path, stamping `mtime`. `size` is the
-    /// remote's reported size, used as the transfer's expected total.
-    Download {
-        rel: String,
-        uid: NodeUid,
-        mtime: i64,
-        size: i64,
-    },
-    /// Both sides changed: set the local copy aside, then download remote `uid`.
-    Conflict {
-        rel: String,
-        uid: NodeUid,
-        mtime: i64,
-        size: i64,
-    },
-    /// Both sides changed during a [`push pass`](Core::push_pass): upload the local
-    /// copy into `parent` under a conflict name, leaving the remote file as it is.
-    PushConflict { rel: String, parent: NodeUid },
-}
-
-impl Pending {
-    /// The path this op acts on, relative to the folder root.
-    fn rel(&self) -> &str {
-        match self {
-            Pending::CreateDir { rel, .. }
-            | Pending::UploadNew { rel, .. }
-            | Pending::UploadRevision { rel, .. }
-            | Pending::Download { rel, .. }
-            | Pending::Conflict { rel, .. }
-            | Pending::PushConflict { rel, .. } => rel,
-        }
-    }
-
-    /// How this op reads in the activity feed.
-    fn kind(&self) -> ActivityKind {
-        match self {
-            Pending::CreateDir { .. } => ActivityKind::CreateFolder,
-            Pending::UploadNew { .. }
-            | Pending::UploadRevision { .. }
-            | Pending::PushConflict { .. } => ActivityKind::Upload,
-            Pending::Download { .. } | Pending::Conflict { .. } => ActivityKind::Download,
-        }
-    }
-
-    /// The activity line's detail, which distinguishes ops that share a kind.
-    fn detail(&self) -> &'static str {
-        match self {
-            Pending::CreateDir { .. } => "on Drive",
-            Pending::UploadNew { .. } => "new file",
-            Pending::UploadRevision { .. } => "new version",
-            Pending::Download { .. } => "from Drive",
-            Pending::Conflict { .. } => "local changes kept as a conflict copy",
-            Pending::PushConflict { .. } => "local changes uploaded as a conflict copy",
-        }
-    }
-}
-
-/// Why a full reconcile pass stopped without a result.
-enum PassAbort {
-    /// An on-demand switch was queued while the pass was running. Everything left
-    /// to do is work on a local copy about to be evicted, so the pass gives up its
-    /// remaining work to a [`push pass`](Core::push_pass) instead. Not a failure —
-    /// nothing is left half-applied, because each step is applied whole.
-    Interrupted,
-    /// The pass could not establish its diff (a walk or the baseline load failed).
-    Failed(String),
-}
-
-impl From<String> for PassAbort {
-    fn from(e: String) -> Self {
-        PassAbort::Failed(e)
-    }
-}
-
-/// Refuse to run a pass whose local side has vanished in its entirety.
-///
-/// A path in the baseline with no local copy is classified as "the user deleted
-/// this", and the pass answers by trashing it on Drive. That is right for one
-/// file and right for a handful. When it is true of *every* path the baseline
-/// knows, the likely cause is not a user: it is an unmounted external disk, a
-/// mountpoint whose FUSE mount died, a home directory that was not yet decrypted
-/// when the daemon started, or a bug in this client — and the answer to all of
-/// those is to trash the folder's entire contents on Drive.
-///
-/// So this pass abort exists to cap the blast radius rather than to catch a
-/// specific defect. Losing a pass to it costs a retry; the failure it prevents
-/// costs the folder. A user who really did empty the folder can express that by
-/// removing it from sync and re-adding it — the baseline goes with it.
-///
-/// One surviving path is enough to clear the guard, since the classification is
-/// only ever wrong about all of them at once.
-/// The paths a reconcile pass will classify: the union of the local, remote,
-/// and baseline states, minus anything the ignore rules exclude, shallowest
-/// first so a parent folder is created before its children are placed in it.
-///
-/// The ignore filter belongs *here*, on the union, rather than on the local walk
-/// alone — filtering the walk alone would be actively destructive. A file synced
-/// before it became ignored is absent from `local` but present in `remote` and
-/// `baseline`, which is precisely the "local deleted, remote untouched" shape
-/// `do_reconcile` responds to by trashing the remote copy. Adding a line to
-/// `.pdfsignore` must never delete anything from Drive.
-///
-/// Ignored baseline rows are deliberately left in the database rather than
-/// removed: with the row intact, un-ignoring the path later re-adopts the
-/// existing remote file instead of reading as a brand-new local one.
-fn classification_order<L, R, B>(
-    local: &HashMap<String, L>,
-    remote: &HashMap<String, R>,
-    baseline: &HashMap<String, B>,
-    rules: &IgnoreRules,
-) -> Vec<String>
-where
-    L: HasKind,
-    R: HasKind,
-{
-    let mut paths: HashSet<String> = HashSet::new();
-    paths.extend(local.keys().cloned());
-    paths.extend(remote.keys().cloned());
-    paths.extend(baseline.keys().cloned());
-    let mut order: Vec<String> = paths.into_iter().collect();
-    if !rules.is_empty() {
-        order.retain(|rel| {
-            // A baseline-only path has no kind recorded, so it is tested as
-            // both; see `filter_baseline` for why erring towards "ignored" is
-            // the safe direction here.
-            let kind = local
-                .get(rel)
-                .map(HasKind::is_dir)
-                .or_else(|| remote.get(rel).map(HasKind::is_dir));
-            match kind {
-                Some(is_dir) => !rules.is_ignored(rel, is_dir),
-                None => !rules.is_ignored(rel, false) && !rules.is_ignored(rel, true),
-            }
-        });
-    }
-    order.sort_by_key(|p| p.matches('/').count());
-    order
-}
-
-/// Lets [`classification_order`] ask either walk's item whether it is a
-/// directory without knowing which walk it came from.
-trait HasKind {
-    fn is_dir(&self) -> bool;
-}
-
-impl HasKind for LocalItem {
-    fn is_dir(&self) -> bool {
-        self.is_dir
-    }
-}
-
-impl HasKind for RemoteItem {
-    fn is_dir(&self) -> bool {
-        self.is_dir
-    }
-}
-
-/// The baseline minus its ignored paths, for [`guard_local_wipe`].
-///
-/// The guard asks "did every synced path vanish locally?", and an ignored path
-/// is absent from the local walk by rule rather than by loss. Left in, a rule
-/// covering the whole tree would trip the guard on every pass and wedge that
-/// folder's sync for good.
-///
-/// A baseline row does not record whether it was a file or a folder, so a path
-/// counts as ignored if it matches as either. Erring towards "ignored" only ever
-/// shrinks the set the guard checks, which weakens a safety net rather than
-/// causing a deletion — the wrong direction to be wrong in is the other one.
-fn filter_baseline<'a, B>(
-    baseline: &'a HashMap<String, B>,
-    rules: &IgnoreRules,
-) -> HashMap<String, &'a B> {
-    baseline
-        .iter()
-        .filter(|(rel, _)| !rules.is_ignored(rel, false) && !rules.is_ignored(rel, true))
-        .map(|(rel, entry)| (rel.clone(), entry))
-        .collect()
-}
-
-fn guard_local_wipe<B, L>(
-    baseline: &HashMap<String, B>,
-    local: &HashMap<String, L>,
-) -> Result<(), String> {
-    if baseline.len() >= 2 && baseline.keys().all(|rel| !local.contains_key(rel)) {
-        return Err(format!(
-            "every one of the {} synced paths is missing locally; refusing to trash \
-             them on Drive. Check that the folder is mounted and readable.",
-            baseline.len()
-        ));
-    }
-    Ok(())
-}
-
+mod engine;
+mod local_scan;
+mod model;
+mod planner;
+use engine::SYNC_CONCURRENCY;
+pub(crate) use engine::{SyncMsg, spawn};
+#[cfg(test)]
+use engine::{classify, settle_with};
+#[cfg(test)]
+use local_scan::is_write_mode;
+use local_scan::open_for_write_set;
+use model::{LocalItem, Outcome, PassAbort, Pending, RemoteItem};
+pub(crate) use planner::base_name;
+use planner::{
+    FilePlan, classification_order, conflict_path, filter_baseline, guard_local_wipe, join_rel,
+    parent_rel, plan_file, rel_to_path, remote_sig, unchanged_remote_size,
+};
 /// What a [`Pending`] op did, so the reconcile can update shared state on the
 /// engine thread (never inside a task).
 enum Applied {
@@ -783,7 +291,10 @@ impl Core {
         self.progress_scan_total(folder_id, baseline.len());
 
         let mut local: HashMap<String, LocalItem> = HashMap::new();
-        self.walk_local(folder_id, local_root, local_root, rules, &mut local)?;
+        let writing = open_for_write_set(local_root);
+        self.walk_local(
+            folder_id, local_root, local_root, rules, &writing, &mut local,
+        )?;
         // The guard compares against the paths this pass could still see: an
         // ignored path is absent from `local` by rule, not by loss, and counting
         // those as missing would trip the guard on every pass — wedging the
@@ -825,7 +336,7 @@ impl Core {
         // anything to push, and the only ones that could be a two-sided edit.
         let changed: Vec<&String> = local
             .iter()
-            .filter(|(_, item)| !item.is_dir)
+            .filter(|(_, item)| !item.is_dir && !item.open_for_write)
             .filter(|(rel, item)| {
                 baseline
                     .get(*rel)
@@ -856,7 +367,10 @@ impl Core {
         };
         let changed: HashSet<&String> = changed.into_iter().collect();
 
-        let mut outcome = Outcome::default();
+        let mut outcome = Outcome {
+            deferred: local.values().filter(|item| item.open_for_write).count(),
+            ..Default::default()
+        };
         let mut order: Vec<&String> = local.keys().collect();
         order.sort_by_key(|p| p.matches('/').count());
 
@@ -1043,7 +557,10 @@ impl Core {
         self.progress_scan_total(folder_id, baseline.len() * 2);
 
         let mut local: HashMap<String, LocalItem> = HashMap::new();
-        self.walk_local(folder_id, local_root, local_root, rules, &mut local)?;
+        let writing = open_for_write_set(local_root);
+        self.walk_local(
+            folder_id, local_root, local_root, rules, &writing, &mut local,
+        )?;
         // See `push_pass`: the guard must not count rule-excluded paths as lost.
         guard_local_wipe(&filter_baseline(&baseline, rules), &local)?;
 
@@ -1149,106 +666,82 @@ impl Core {
                 continue;
             }
 
-            // File.
-            let base = baseline.get(rel);
-            let local_changed = l.is_some_and(|l| {
-                base.is_none_or(|b| b.local_mtime != l.mtime || b.local_size != l.size)
-            });
-            let remote_changed =
-                r.is_some_and(|r| base.is_none_or(|b| remote_sig(b) != Some((r.mtime, r.size))));
-
-            match (l, r) {
-                (Some(_), Some(r)) => {
-                    // With no baseline, both sides read as "changed" and fall to the
-                    // conflict arm — the safe default for a folder re-added over
-                    // existing remote content.
-                    if !local_changed && !remote_changed {
-                        // Both untouched; baseline already matches.
-                    } else if local_changed && !remote_changed {
-                        batch.push(Pending::UploadRevision {
-                            rel: rel.clone(),
-                            uid: r.uid.clone(),
-                        });
-                    } else if remote_changed && !local_changed {
-                        batch.push(Pending::Download {
-                            rel: rel.clone(),
-                            uid: r.uid.clone(),
-                            mtime: r.mtime,
-                            size: r.size,
-                        });
-                    } else {
-                        batch.push(Pending::Conflict {
-                            rel: rel.clone(),
-                            uid: r.uid.clone(),
-                            mtime: r.mtime,
-                            size: r.size,
-                        });
-                    }
+            match plan_file(l, r, baseline.get(rel)) {
+                FilePlan::Unchanged => {}
+                FilePlan::Deferred => {
+                    debug!(
+                        rel,
+                        "sync: file open for write by another process; deferring upload"
+                    );
+                    outcome.deferred += 1;
                 }
-                (Some(_), None) => {
-                    if base.is_none() || local_changed {
-                        // New local file, or remote deleted while local changed →
-                        // (re)upload it as a new remote file.
-                        match remote_dirs.get(parent_rel(rel)) {
-                            Some(parent) => batch.push(Pending::UploadNew {
-                                rel: rel.clone(),
-                                parent: parent.clone(),
-                            }),
-                            None => {
-                                warn!(rel, "sync: no remote parent for file; continuing");
-                                outcome.errors += 1;
-                            }
-                        }
-                    } else {
-                        // Remote deleted, local untouched → delete local.
-                        let _ = std::fs::remove_file(local_root.join(rel_to_path(rel)));
-                        let _ = self.db.sync_entry_remove(folder_id, rel);
+                FilePlan::UploadRevision => {
+                    let remote = r.expect("upload revision requires a remote file");
+                    batch.push(Pending::UploadRevision {
+                        rel: rel.clone(),
+                        uid: remote.uid.clone(),
+                    });
+                }
+                FilePlan::Download => {
+                    let remote = r.expect("download requires a remote file");
+                    batch.push(Pending::Download {
+                        rel: rel.clone(),
+                        uid: remote.uid.clone(),
+                        mtime: remote.mtime,
+                        size: remote.size,
+                    });
+                }
+                FilePlan::Conflict => {
+                    let remote = r.expect("conflict requires a remote file");
+                    batch.push(Pending::Conflict {
+                        rel: rel.clone(),
+                        uid: remote.uid.clone(),
+                        mtime: remote.mtime,
+                        size: remote.size,
+                    });
+                }
+                FilePlan::UploadNew => match remote_dirs.get(parent_rel(rel)) {
+                    Some(parent) => batch.push(Pending::UploadNew {
+                        rel: rel.clone(),
+                        parent: parent.clone(),
+                    }),
+                    None => {
+                        warn!(rel, "sync: no remote parent for file; continuing");
+                        outcome.errors += 1;
+                    }
+                },
+                FilePlan::DeleteLocal => {
+                    let _ = std::fs::remove_file(local_root.join(rel_to_path(rel)));
+                    let _ = self.db.sync_entry_remove(folder_id, rel);
+                    self.log_activity(ActivityKind::Trash, base_name(rel), "removed locally", true);
+                    outcome.deleted += 1;
+                }
+                FilePlan::DeleteRemote => {
+                    let remote = r.expect("remote deletion requires a remote file");
+                    if let Err(e) = self
+                        .rt
+                        .block_on(self.client.trash_nodes(std::slice::from_ref(&remote.uid)))
+                    {
+                        warn!(rel, error = %e, "sync: trash remote failed");
                         self.log_activity(
                             ActivityKind::Trash,
                             base_name(rel),
-                            "removed locally",
-                            true,
+                            e.to_string(),
+                            false,
                         );
-                        outcome.deleted += 1;
+                        outcome.errors += 1;
+                        continue;
                     }
+                    let _ = self.db.sync_entry_remove(folder_id, rel);
+                    self.log_activity(
+                        ActivityKind::Trash,
+                        base_name(rel),
+                        "removed on Drive",
+                        true,
+                    );
+                    outcome.deleted += 1;
                 }
-                (None, Some(r)) => {
-                    if base.is_none() || remote_changed {
-                        // New remote file, or local deleted while remote changed →
-                        // (re)download it.
-                        batch.push(Pending::Download {
-                            rel: rel.clone(),
-                            uid: r.uid.clone(),
-                            mtime: r.mtime,
-                            size: r.size,
-                        });
-                    } else {
-                        // Local deleted, remote untouched → delete remote.
-                        if let Err(e) = self
-                            .rt
-                            .block_on(self.client.trash_nodes(std::slice::from_ref(&r.uid)))
-                        {
-                            warn!(rel, error = %e, "sync: trash remote failed");
-                            self.log_activity(
-                                ActivityKind::Trash,
-                                base_name(rel),
-                                e.to_string(),
-                                false,
-                            );
-                            outcome.errors += 1;
-                            continue;
-                        }
-                        let _ = self.db.sync_entry_remove(folder_id, rel);
-                        self.log_activity(
-                            ActivityKind::Trash,
-                            base_name(rel),
-                            "removed on Drive",
-                            true,
-                        );
-                        outcome.deleted += 1;
-                    }
-                }
-                (None, None) => {
+                FilePlan::ForgetBaseline => {
                     let _ = self.db.sync_entry_remove(folder_id, rel);
                 }
             }
@@ -1305,6 +798,7 @@ impl Core {
         root: &Path,
         dir: &Path,
         rules: &IgnoreRules,
+        writing: &HashSet<PathBuf>,
         out: &mut HashMap<String, LocalItem>,
     ) -> Result<(), String> {
         let entries = std::fs::read_dir(dir).map_err(|e| format!("read {}: {e}", dir.display()))?;
@@ -1338,17 +832,25 @@ impl Core {
                         is_dir: true,
                         mtime: 0,
                         size: 0,
+                        open_for_write: false,
                     },
                 );
                 self.progress_scanned(folder_id, base_name(rel));
-                self.walk_local(folder_id, root, &path, rules, out)?;
+                self.walk_local(folder_id, root, &path, rules, writing, out)?;
             } else if meta.is_file() {
+                // Check whether any process holds this file open for writing.
+                // The canonical path is used because /proc/*/fd links resolve
+                // to canonical targets.
+                let ofw = std::fs::canonicalize(&path)
+                    .map(|canon| writing.contains(&canon))
+                    .unwrap_or(false);
                 out.insert(
                     rel.to_string(),
                     LocalItem {
                         is_dir: false,
                         mtime: system_mtime(&meta),
                         size: meta.len() as i64,
+                        open_for_write: ofw,
                     },
                 );
                 self.progress_scanned(folder_id, base_name(rel));
@@ -1554,14 +1056,20 @@ impl Core {
                 });
             }
             let mut out = Vec::new();
+            let mut join_errors = 0usize;
             while let Some(joined) = set.join_next().await {
                 match joined {
                     Ok(result) => out.push(result),
-                    Err(e) => warn!(error = %e, "sync: task panicked"),
+                    Err(e) => {
+                        join_errors += 1;
+                        warn!(error = %e, "sync: task panicked");
+                    }
                 }
             }
-            out
+            (out, join_errors)
         });
+        let (results, join_errors) = results;
+        outcome.errors += join_errors;
         for result in results {
             match result {
                 Ok(applied) => {
@@ -1859,40 +1367,6 @@ fn remote_file_sig(node: &Node) -> (i64, i64) {
     (node.modification_time, size)
 }
 
-/// The size the baseline recorded for `rel`, if its remote signature's mtime
-/// still matches `mtime` — meaning the file has not changed on Drive, so the
-/// recorded size stands and there is no need to decrypt it again.
-///
-/// `None` means the size has to be read for real: either the mtime moved, or
-/// there is no baseline signature to trust (a file the sync has not seen).
-fn unchanged_remote_size(
-    baseline: &HashMap<String, StoredSyncEntry>,
-    rel: &str,
-    mtime: i64,
-) -> Option<i64> {
-    match baseline.get(rel).and_then(remote_sig) {
-        Some((recorded, size)) if recorded == mtime => Some(size),
-        _ => None,
-    }
-}
-
-/// Join a child `name` onto a walk's `prefix`, giving a rel path.
-fn join_rel(prefix: &str, name: &str) -> String {
-    if prefix.is_empty() {
-        name.to_string()
-    } else {
-        format!("{prefix}/{name}")
-    }
-}
-
-/// The stored remote signature of a baseline row, if it has one.
-fn remote_sig(e: &StoredSyncEntry) -> Option<(i64, i64)> {
-    match (&e.remote_rev, &e.remote_hash) {
-        (Some(m), Some(s)) => Some((m.parse().ok()?, s.parse().ok()?)),
-        _ => None,
-    }
-}
-
 /// A file's modification time as epoch seconds (0 if unavailable).
 fn system_mtime(meta: &std::fs::Metadata) -> i64 {
     meta.modified()
@@ -1901,43 +1375,6 @@ fn system_mtime(meta: &std::fs::Metadata) -> i64 {
         .map(|d| d.as_secs() as i64)
         .unwrap_or(0)
 }
-
-/// The parent of a `/`-joined relative path (`""` for a top-level entry).
-fn parent_rel(rel: &str) -> &str {
-    match rel.rfind('/') {
-        Some(i) => &rel[..i],
-        None => "",
-    }
-}
-
-/// The final component of a `/`-joined relative path.
-pub(crate) fn base_name(rel: &str) -> &str {
-    match rel.rfind('/') {
-        Some(i) => &rel[i + 1..],
-        None => rel,
-    }
-}
-
-/// Turn a `/`-joined relative path into an OS path (`/` is already the separator
-/// on Linux, this keeps the intent explicit).
-fn rel_to_path(rel: &str) -> PathBuf {
-    rel.split('/').collect()
-}
-
-/// The name for a conflict copy of `path`, e.g. `notes (sync-conflict 1700000000).txt`.
-fn conflict_path(path: &Path, stamp: i64) -> PathBuf {
-    let stem = path.file_stem().and_then(|s| s.to_str()).unwrap_or("file");
-    let ext = path.extension().and_then(|s| s.to_str());
-    let name = match ext {
-        Some(ext) => format!("{stem} (sync-conflict {stamp}).{ext}"),
-        None => format!("{stem} (sync-conflict {stamp})"),
-    };
-    match path.parent() {
-        Some(dir) => dir.join(name),
-        None => PathBuf::from(name),
-    }
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -2030,6 +1467,7 @@ mod tests {
             is_dir,
             mtime: 1,
             size: 1,
+            open_for_write: false,
         }
     }
 
@@ -2342,4 +1780,69 @@ mod tests {
         let no_ext = conflict_path(Path::new("/home/me/README"), 42);
         assert_eq!(no_ext, PathBuf::from("/home/me/README (sync-conflict 42)"));
     }
+
+    // ---- open-for-write detection tests -----------------------------------
+
+    #[test]
+    fn is_write_mode_detects_wronly() {
+        // O_WRONLY = 0o1 → flags octal "0100001" (O_WRONLY | O_LARGEFILE on x86_64)
+        let fdinfo = "pos:\t0\nflags:\t0100001\nmnt_id:\t29\n";
+        assert!(is_write_mode(fdinfo), "O_WRONLY must be detected as write");
+    }
+
+    #[test]
+    fn is_write_mode_detects_rdwr() {
+        // O_RDWR = 0o2 → flags octal "0100002"
+        let fdinfo = "pos:\t0\nflags:\t0100002\nmnt_id:\t29\n";
+        assert!(is_write_mode(fdinfo), "O_RDWR must be detected as write");
+    }
+
+    #[test]
+    fn is_write_mode_ignores_rdonly() {
+        // O_RDONLY = 0o0 → flags octal "0100000" (just O_LARGEFILE)
+        let fdinfo = "pos:\t0\nflags:\t0100000\nmnt_id:\t29\n";
+        assert!(
+            !is_write_mode(fdinfo),
+            "O_RDONLY must not be detected as write"
+        );
+    }
+
+    #[test]
+    fn is_write_mode_handles_bare_zero() {
+        // A plain "0" (no O_LARGEFILE, no access flags).
+        let fdinfo = "pos:\t0\nflags:\t0\nmnt_id:\t29\n";
+        assert!(!is_write_mode(fdinfo), "flags 0 is O_RDONLY");
+    }
+
+    #[test]
+    fn is_write_mode_returns_false_on_missing_flags_line() {
+        let fdinfo = "pos:\t42\nmnt_id:\t29\n";
+        assert!(!is_write_mode(fdinfo));
+    }
+
+    #[test]
+    fn is_write_mode_handles_append() {
+        // O_WRONLY | O_APPEND = 0o1 | 0o2000 = 0o2001 → with O_LARGEFILE: 0o102001
+        let fdinfo = "pos:\t0\nflags:\t0102001\nmnt_id:\t29\n";
+        assert!(is_write_mode(fdinfo), "O_WRONLY|O_APPEND is still a write");
+    }
+
+    #[test]
+    fn outcome_includes_deferred_in_summary() {
+        let o = Outcome {
+            uploaded: 3,
+            deferred: 2,
+            ..Default::default()
+        };
+        assert!(!o.is_empty());
+        assert_eq!(o.summary(), "3 uploaded, 2 deferred (open for write)");
+    }
+
+    #[test]
+    fn outcome_deferred_alone_is_not_empty() {
+        let mut o = Outcome::default();
+        assert!(o.is_empty());
+        o.deferred = 1;
+        assert!(!o.is_empty());
+    }
 }

crates/pdfs-fuse/src/sync/engine.rs

@@ -0,0 +1,251 @@
+//! Filesystem watcher, polling, and debounce control plane.
+
+use super::*;
+
+/// How long the watcher must go quiet before a burst counts as finished.
+///
+/// Measured from the *last* event, not the first: applications do not write a
+/// file once. An editor saves by writing a temp file and renaming it over the
+/// target; an export or a database dump writes continuously for as long as it
+/// takes. Settling a fixed interval after the first event walks the tree while
+/// the file is still growing, and uploads a torn snapshot as a real revision —
+/// corrected on the next pass, but only after spending the encrypt-and-upload
+/// on a file that was never in that state.
+const DEBOUNCE: Duration = Duration::from_secs(2);
+/// Ceiling on the settle wait, so a directory under sustained change still
+/// syncs. Without it, copying a large tree in — events arriving forever —
+/// would postpone the reconcile for as long as the copy ran.
+const MAX_SETTLE: Duration = Duration::from_secs(30);
+/// How often to re-walk remotes so changes made on other clients are pulled in.
+const POLL_INTERVAL: Duration = Duration::from_secs(120);
+/// How many uploads/downloads/folder-creations a reconcile runs at once. The
+/// per-item work is a network round-trip, so a folder with thousands of files is
+/// unusable done one-at-a-time; this bounds concurrency like the bulk-upload
+/// engine does.
+pub(super) const SYNC_CONCURRENCY: usize = 8;
+
+/// A message to the sync engine's control thread.
+pub(crate) enum SyncMsg {
+    /// Reconcile one folder by id (a local change, or a targeted `SyncNow`).
+    Reconcile(i64),
+    /// Reconcile every mirror folder (periodic poll, or startup).
+    ReconcileAll,
+    /// Re-read the folder set and adjust the filesystem watches (after add/remove).
+    Rewatch,
+}
+
+/// Start the sync engine: a control thread that owns the filesystem watcher and
+/// serialises reconcile passes, plus a periodic poll thread. The engine receives
+/// on `rx`; senders live in [`Core::sync_tx`].
+pub(crate) fn spawn(core: Core, rx: Receiver<SyncMsg>) {
+    if let Err(e) = std::thread::Builder::new()
+        .name("pdfs-sync".into())
+        .spawn(move || engine_loop(core, rx))
+    {
+        warn!(error = %e, "failed to start sync engine");
+    }
+}
+
+/// The engine control loop. Single-threaded so reconcile passes never overlap.
+fn engine_loop(core: Core, rx: Receiver<SyncMsg>) {
+    // Paths the watcher currently covers, mapped to their folder id, so an event
+    // path can be resolved back to the folder it belongs to.
+    let watched: Mutex<Vec<(PathBuf, i64)>> = Mutex::new(Vec::new());
+
+    let tx_events = core.sync_tx.clone();
+    let mut watcher =
+        match notify::recommended_watcher(move |res: notify::Result<notify::Event>| {
+            let Ok(event) = res else { return };
+            // Ignore pure metadata/access noise; content changes are what matter.
+            if matches!(event.kind, notify::EventKind::Access(_)) {
+                return;
+            }
+            let _ = tx_events.send(SyncMsg::ReconcileAll);
+        }) {
+            Ok(w) => w,
+            Err(e) => {
+                warn!(error = %e, "filesystem watcher unavailable; sync is poll-only");
+                // Still run the loop so polling and explicit SyncNow work.
+                poll_only_loop(&core, rx);
+                return;
+            }
+        };
+
+    // Periodic remote poll.
+    {
+        let tx = core.sync_tx.clone();
+        std::thread::Builder::new()
+            .name("pdfs-sync-poll".into())
+            .spawn(move || {
+                loop {
+                    std::thread::sleep(POLL_INTERVAL);
+                    if tx.send(SyncMsg::ReconcileAll).is_err() {
+                        break;
+                    }
+                }
+            })
+            .ok();
+    }
+
+    rewatch(&core, &mut watcher, &watched);
+    reconcile_all(&core);
+
+    while let Ok(msg) = rx.recv() {
+        let mut ids: HashSet<i64> = HashSet::new();
+        let mut all = false;
+        let mut do_rewatch = false;
+        classify(msg, &mut ids, &mut all, &mut do_rewatch);
+        settle(&rx, &mut ids, &mut all, &mut do_rewatch);
+
+        if do_rewatch {
+            rewatch(&core, &mut watcher, &watched);
+        }
+        if all {
+            reconcile_all(&core);
+        } else {
+            for id in ids {
+                if let Ok(Some(folder)) = core.db.sync_folder_get(id) {
+                    core.reconcile_folder(&folder);
+                }
+            }
+        }
+    }
+}
+
+/// Fallback loop when no filesystem watcher could be created: poll + SyncNow only.
+fn poll_only_loop(core: &Core, rx: Receiver<SyncMsg>) {
+    {
+        let tx = core.sync_tx.clone();
+        std::thread::spawn(move || {
+            loop {
+                std::thread::sleep(POLL_INTERVAL);
+                if tx.send(SyncMsg::ReconcileAll).is_err() {
+                    break;
+                }
+            }
+        });
+    }
+    reconcile_all(core);
+    while let Ok(msg) = rx.recv() {
+        let mut ids: HashSet<i64> = HashSet::new();
+        let mut all = false;
+        let mut do_rewatch = false;
+        classify(msg, &mut ids, &mut all, &mut do_rewatch);
+        settle(&rx, &mut ids, &mut all, &mut do_rewatch);
+        if all {
+            reconcile_all(core);
+        } else {
+            for id in ids {
+                if let Ok(Some(folder)) = core.db.sync_folder_get(id) {
+                    core.reconcile_folder(&folder);
+                }
+            }
+        }
+    }
+}
+
+/// Absorb the rest of an event burst, returning once the watcher has been quiet
+/// for `quiet` or `cap` has elapsed since the first event — whichever comes
+/// first. The caller has already classified the event that opened the burst.
+///
+/// Split out with its timings as parameters so the settling behaviour can be
+/// tested in milliseconds rather than in the tens of seconds the real constants
+/// describe.
+pub(super) fn settle_with(
+    rx: &Receiver<SyncMsg>,
+    ids: &mut HashSet<i64>,
+    all: &mut bool,
+    do_rewatch: &mut bool,
+    quiet: Duration,
+    cap: Duration,
+) {
+    let deadline = Instant::now() + cap;
+    loop {
+        let now = Instant::now();
+        if now >= deadline {
+            break;
+        }
+        // Never wait past the cap, however quiet the watcher goes.
+        let wait = quiet.min(deadline - now);
+        match rx.recv_timeout(wait) {
+            // Another event: the burst is still going, so the quiet window
+            // starts again from here.
+            Ok(m) => classify(m, ids, all, do_rewatch),
+            // Quiet for a full window: whatever was being written has stopped.
+            Err(RecvTimeoutError::Timeout) => break,
+            // Every sender is gone; the caller's loop is about to end anyway.
+            Err(RecvTimeoutError::Disconnected) => break,
+        }
+    }
+}
+
+/// [`settle_with`] at the real timings.
+fn settle(rx: &Receiver<SyncMsg>, ids: &mut HashSet<i64>, all: &mut bool, do_rewatch: &mut bool) {
+    settle_with(rx, ids, all, do_rewatch, DEBOUNCE, MAX_SETTLE);
+}
+
+pub(super) fn classify(msg: SyncMsg, ids: &mut HashSet<i64>, all: &mut bool, rewatch: &mut bool) {
+    match msg {
+        SyncMsg::Reconcile(id) => {
+            ids.insert(id);
+        }
+        SyncMsg::ReconcileAll => *all = true,
+        SyncMsg::Rewatch => *rewatch = true,
+    }
+}
+
+/// Reconcile every mirror folder in turn.
+fn reconcile_all(core: &Core) {
+    let folders = match core.db.sync_folder_list() {
+        Ok(f) => f,
+        Err(e) => {
+            warn!(error = ?e, "sync: cannot list folders");
+            return;
+        }
+    };
+    for folder in folders {
+        core.reconcile_folder(&folder);
+    }
+}
+
+/// Bring the filesystem watches in line with the current mirror-folder set:
+/// watch newly-added folders, drop removed ones.
+fn rewatch(
+    core: &Core,
+    watcher: &mut notify::RecommendedWatcher,
+    watched: &Mutex<Vec<(PathBuf, i64)>>,
+) {
+    let want: Vec<(PathBuf, i64)> = match core.db.sync_folder_list() {
+        Ok(f) => f
+            .into_iter()
+            .filter(|f| f.mode == "mirror")
+            .map(|f| (PathBuf::from(f.local_path), f.id))
+            .collect(),
+        Err(e) => {
+            warn!(error = ?e, "sync: cannot list folders to watch");
+            return;
+        }
+    };
+    let mut have = watched.lock();
+    // Drop watches no longer wanted.
+    have.retain(|(path, _)| {
+        if want.iter().any(|(p, _)| p == path) {
+            true
+        } else {
+            let _ = watcher.unwatch(path);
+            false
+        }
+    });
+    // Add newly wanted watches.
+    for (path, id) in &want {
+        if have.iter().any(|(p, _)| p == path) {
+            continue;
+        }
+        match watcher.watch(path, RecursiveMode::Recursive) {
+            Ok(()) => have.push((path.clone(), *id)),
+            Err(e) => warn!(path = %path.display(), error = %e, "sync: watch failed"),
+        }
+    }
+}
+
+// ---- reconcile ------------------------------------------------------------

crates/pdfs-fuse/src/sync/local_scan.rs

@@ -0,0 +1,81 @@
+//! Local open-for-write detection used to defer torn uploads.
+
+use super::*;
+
+// ---- open-for-write detection ---------------------------------------------
+
+/// Scan `/proc/*/fd` once and return the set of **canonical** paths under
+/// `root` that any process currently holds open for writing (`O_WRONLY` or
+/// `O_RDWR`). The scan is best-effort: unreadable `/proc/*/fd` directories
+/// (other users' processes, or kernel threads) are silently skipped.
+///
+/// Cost: one `readdir` of `/proc`, then for every process one `readdir` of its
+/// `/proc/<pid>/fd/`, and one `readlink` + one `open` of `/proc/<pid>/fdinfo/<n>`
+/// per open fd that resolves under `root`. For a typical desktop with a few
+/// hundred processes and a handful of files inside the sync root, this
+/// completes in low single-digit milliseconds.
+pub(super) fn open_for_write_set(root: &Path) -> HashSet<PathBuf> {
+    let mut result = HashSet::new();
+    let Ok(root_canonical) = std::fs::canonicalize(root) else {
+        return result;
+    };
+    let Ok(proc_entries) = std::fs::read_dir("/proc") else {
+        return result;
+    };
+    for proc_entry in proc_entries.filter_map(|e| e.ok()) {
+        let pid_name = proc_entry.file_name();
+        // Skip non-numeric entries (kernel threads, /proc/self, etc.)
+        if !pid_name
+            .to_str()
+            .is_some_and(|s| s.bytes().all(|b| b.is_ascii_digit()))
+        {
+            continue;
+        }
+        let fd_dir = PathBuf::from("/proc").join(&pid_name).join("fd");
+        let Ok(fds) = std::fs::read_dir(&fd_dir) else {
+            continue;
+        };
+        for fd_entry in fds.filter_map(|e| e.ok()) {
+            // readlink on /proc/<pid>/fd/<n> gives the target path.
+            let link = fd_dir.join(fd_entry.file_name());
+            let Ok(target) = std::fs::read_link(&link) else {
+                continue;
+            };
+            // Quick prefix check before the more expensive fdinfo read.
+            if !target.starts_with(&root_canonical) {
+                continue;
+            }
+            // Read the fd's flags from /proc/<pid>/fdinfo/<n> to determine
+            // the access mode. The first line is "pos:\t<offset>", the second
+            // is "flags:\t<octal>". We only need the low two bits of flags:
+            //   0 = O_RDONLY, 1 = O_WRONLY, 2 = O_RDWR
+            let fdinfo_path = PathBuf::from("/proc")
+                .join(&pid_name)
+                .join("fdinfo")
+                .join(fd_entry.file_name());
+            if let Ok(contents) = std::fs::read_to_string(&fdinfo_path)
+                && is_write_mode(&contents)
+            {
+                result.insert(target);
+            }
+        }
+    }
+    result
+}
+
+/// Parse the `flags:` line out of a `/proc/<pid>/fdinfo/<n>` file and return
+/// true if the low two bits indicate write access (`O_WRONLY = 1` or
+/// `O_RDWR = 2`).
+pub(super) fn is_write_mode(fdinfo: &str) -> bool {
+    for line in fdinfo.lines() {
+        if let Some(rest) = line.strip_prefix("flags:\t") {
+            if let Ok(flags) = u32::from_str_radix(rest.trim_start_matches('0'), 8) {
+                let access = flags & 0o3; // O_ACCMODE
+                return access == 1 || access == 2; // O_WRONLY or O_RDWR
+            }
+            // An empty octal string ("0" stripped to "") means flags == 0 == O_RDONLY.
+            return false;
+        }
+    }
+    false
+}

crates/pdfs-fuse/src/sync/model.rs

@@ -0,0 +1,164 @@
+//! Reconciliation snapshots, queued operations, and pass outcomes.
+
+use super::*;
+
+pub(super) struct LocalItem {
+    pub(super) is_dir: bool,
+    pub(super) mtime: i64,
+    pub(super) size: i64,
+    /// True when another process holds this file open for writing (detected via
+    /// `/proc/*/fd`). An open-for-write file is kept in the map — so it is not
+    /// misread as a deletion — but treated as unchanged for upload purposes,
+    /// deferring the upload until the writer closes the file.
+    pub(super) open_for_write: bool,
+}
+
+/// One item found while walking a remote tree.
+pub(super) struct RemoteItem {
+    pub(super) uid: NodeUid,
+    pub(super) is_dir: bool,
+    pub(super) mtime: i64,
+    pub(super) size: i64,
+}
+
+/// The result of a reconcile pass: what it moved, how many paths were kept as
+/// conflict copies, and how many failed to apply (and so still need another
+/// pass). The counts drive both the folder's state and its activity summary.
+#[derive(Default)]
+pub(super) struct Outcome {
+    pub(super) uploaded: usize,
+    pub(super) downloaded: usize,
+    pub(super) created: usize,
+    pub(super) deleted: usize,
+    pub(super) conflicts: usize,
+    pub(super) errors: usize,
+    /// Files skipped because another process held them open for writing.
+    pub(super) deferred: usize,
+}
+
+impl Outcome {
+    /// Fold in one applied op.
+    pub(super) fn record(&mut self, applied: &Applied) {
+        match applied {
+            Applied::Dir(..) => self.created += 1,
+            Applied::Uploaded => self.uploaded += 1,
+            Applied::Downloaded => self.downloaded += 1,
+            Applied::Conflict => self.conflicts += 1,
+        }
+    }
+
+    /// Whether the pass moved nothing at all — the common case on a poll of an
+    /// unchanged folder, which should not add a line to the activity feed.
+    pub(super) fn is_empty(&self) -> bool {
+        self.uploaded == 0
+            && self.downloaded == 0
+            && self.created == 0
+            && self.deleted == 0
+            && self.conflicts == 0
+            && self.errors == 0
+            && self.deferred == 0
+    }
+
+    /// A human summary of the pass: "3 uploaded, 1 downloaded, 2 failed".
+    pub(super) fn summary(&self) -> String {
+        let mut parts = Vec::new();
+        for (n, label) in [
+            (self.uploaded, "uploaded"),
+            (self.downloaded, "downloaded"),
+            (self.created, "folder(s) created"),
+            (self.deleted, "deleted"),
+            (self.conflicts, "conflicted"),
+            (self.deferred, "deferred (open for write)"),
+            (self.errors, "failed"),
+        ] {
+            if n > 0 {
+                parts.push(format!("{n} {label}"));
+            }
+        }
+        parts.join(", ")
+    }
+}
+
+/// A network operation queued during classification and run concurrently in a
+/// per-depth batch. Parent uids are resolved up front (the parent folder is one
+/// depth shallower and already created), so tasks share nothing mutable.
+pub(super) enum Pending {
+    /// Create a new remote folder under `parent`.
+    CreateDir { rel: String, parent: NodeUid },
+    /// Upload a brand-new local file into `parent`.
+    UploadNew { rel: String, parent: NodeUid },
+    /// Upload a changed local file as a new revision of `uid`.
+    UploadRevision { rel: String, uid: NodeUid },
+    /// Download remote `uid` to the local path, stamping `mtime`. `size` is the
+    /// remote's reported size, used as the transfer's expected total.
+    Download {
+        rel: String,
+        uid: NodeUid,
+        mtime: i64,
+        size: i64,
+    },
+    /// Both sides changed: set the local copy aside, then download remote `uid`.
+    Conflict {
+        rel: String,
+        uid: NodeUid,
+        mtime: i64,
+        size: i64,
+    },
+    /// Both sides changed during a [`push pass`](Core::push_pass): upload the local
+    /// copy into `parent` under a conflict name, leaving the remote file as it is.
+    PushConflict { rel: String, parent: NodeUid },
+}
+
+impl Pending {
+    /// The path this op acts on, relative to the folder root.
+    pub(super) fn rel(&self) -> &str {
+        match self {
+            Pending::CreateDir { rel, .. }
+            | Pending::UploadNew { rel, .. }
+            | Pending::UploadRevision { rel, .. }
+            | Pending::Download { rel, .. }
+            | Pending::Conflict { rel, .. }
+            | Pending::PushConflict { rel, .. } => rel,
+        }
+    }
+
+    /// How this op reads in the activity feed.
+    pub(super) fn kind(&self) -> ActivityKind {
+        match self {
+            Pending::CreateDir { .. } => ActivityKind::CreateFolder,
+            Pending::UploadNew { .. }
+            | Pending::UploadRevision { .. }
+            | Pending::PushConflict { .. } => ActivityKind::Upload,
+            Pending::Download { .. } | Pending::Conflict { .. } => ActivityKind::Download,
+        }
+    }
+
+    /// The activity line's detail, which distinguishes ops that share a kind.
+    pub(super) fn detail(&self) -> &'static str {
+        match self {
+            Pending::CreateDir { .. } => "on Drive",
+            Pending::UploadNew { .. } => "new file",
+            Pending::UploadRevision { .. } => "new version",
+            Pending::Download { .. } => "from Drive",
+            Pending::Conflict { .. } => "local changes kept as a conflict copy",
+            Pending::PushConflict { .. } => "local changes uploaded as a conflict copy",
+        }
+    }
+}
+
+/// Why a full reconcile pass stopped without a result.
+pub(super) enum PassAbort {
+    /// An on-demand switch was queued while the pass was running. Everything left
+    /// to do is work on a local copy about to be evicted, so the pass gives up its
+    /// remaining work to a [`push pass`](Core::push_pass) instead. Not a failure —
+    /// nothing is left half-applied, because each step is applied whole.
+    Interrupted,
+    /// The pass could not establish its diff (a walk or the baseline load failed).
+    Failed(String),
+}
+
+impl From<String> for PassAbort {
+    fn from(e: String) -> Self {
+        PassAbort::Failed(e)
+    }
+}

crates/pdfs-fuse/src/sync/planner.rs

@@ -0,0 +1,353 @@
+//! Pure reconciliation ordering, safety guards, signatures, and path rules.
+
+use super::*;
+
+/// The paths a reconcile pass will classify: the union of the local, remote,
+/// and baseline states, minus anything the ignore rules exclude, shallowest
+/// first so a parent folder is created before its children are placed in it.
+///
+/// The ignore filter belongs *here*, on the union, rather than on the local walk
+/// alone — filtering the walk alone would be actively destructive. A file synced
+/// before it became ignored is absent from `local` but present in `remote` and
+/// `baseline`, which is precisely the "local deleted, remote untouched" shape
+/// `do_reconcile` responds to by trashing the remote copy. Adding a line to
+/// `.pdfsignore` must never delete anything from Drive.
+///
+/// Ignored baseline rows are deliberately left in the database rather than
+/// removed: with the row intact, un-ignoring the path later re-adopts the
+/// existing remote file instead of reading as a brand-new local one.
+pub(super) fn classification_order<L, R, B>(
+    local: &HashMap<String, L>,
+    remote: &HashMap<String, R>,
+    baseline: &HashMap<String, B>,
+    rules: &IgnoreRules,
+) -> Vec<String>
+where
+    L: HasKind,
+    R: HasKind,
+{
+    let mut paths: HashSet<String> = HashSet::new();
+    paths.extend(local.keys().cloned());
+    paths.extend(remote.keys().cloned());
+    paths.extend(baseline.keys().cloned());
+    let mut order: Vec<String> = paths.into_iter().collect();
+    if !rules.is_empty() {
+        order.retain(|rel| {
+            // A baseline-only path has no kind recorded, so it is tested as
+            // both; see `filter_baseline` for why erring towards "ignored" is
+            // the safe direction here.
+            let kind = local
+                .get(rel)
+                .map(HasKind::is_dir)
+                .or_else(|| remote.get(rel).map(HasKind::is_dir));
+            match kind {
+                Some(is_dir) => !rules.is_ignored(rel, is_dir),
+                None => !rules.is_ignored(rel, false) && !rules.is_ignored(rel, true),
+            }
+        });
+    }
+    order.sort_by_key(|p| p.matches('/').count());
+    order
+}
+
+/// Lets [`classification_order`] ask either walk's item whether it is a
+/// directory without knowing which walk it came from.
+pub(super) trait HasKind {
+    fn is_dir(&self) -> bool;
+}
+
+impl HasKind for LocalItem {
+    fn is_dir(&self) -> bool {
+        self.is_dir
+    }
+}
+
+impl HasKind for RemoteItem {
+    fn is_dir(&self) -> bool {
+        self.is_dir
+    }
+}
+
+/// The baseline minus its ignored paths, for [`guard_local_wipe`].
+///
+/// The guard asks "did every synced path vanish locally?", and an ignored path
+/// is absent from the local walk by rule rather than by loss. Left in, a rule
+/// covering the whole tree would trip the guard on every pass and wedge that
+/// folder's sync for good.
+///
+/// A baseline row does not record whether it was a file or a folder, so a path
+/// counts as ignored if it matches as either. Erring towards "ignored" only ever
+/// shrinks the set the guard checks, which weakens a safety net rather than
+/// causing a deletion — the wrong direction to be wrong in is the other one.
+pub(super) fn filter_baseline<'a, B>(
+    baseline: &'a HashMap<String, B>,
+    rules: &IgnoreRules,
+) -> HashMap<String, &'a B> {
+    baseline
+        .iter()
+        .filter(|(rel, _)| !rules.is_ignored(rel, false) && !rules.is_ignored(rel, true))
+        .map(|(rel, entry)| (rel.clone(), entry))
+        .collect()
+}
+
+/// Refuse to run a pass whose local side has vanished in its entirety.
+///
+/// When every baseline path is absent locally, the likely cause is an unavailable
+/// mount or unreadable folder rather than a deliberate whole-tree deletion.
+/// One surviving path is enough to clear the guard.
+pub(super) fn guard_local_wipe<B, L>(
+    baseline: &HashMap<String, B>,
+    local: &HashMap<String, L>,
+) -> Result<(), String> {
+    if baseline.len() >= 2 && baseline.keys().all(|rel| !local.contains_key(rel)) {
+        return Err(format!(
+            "every one of the {} synced paths is missing locally; refusing to trash \
+             them on Drive. Check that the folder is mounted and readable.",
+            baseline.len()
+        ));
+    }
+    Ok(())
+}
+
+/// The size the baseline recorded for `rel`, if its remote signature's mtime
+/// still matches `mtime`.
+pub(super) fn unchanged_remote_size(
+    baseline: &HashMap<String, StoredSyncEntry>,
+    rel: &str,
+    mtime: i64,
+) -> Option<i64> {
+    match baseline.get(rel).and_then(remote_sig) {
+        Some((recorded, size)) if recorded == mtime => Some(size),
+        _ => None,
+    }
+}
+
+/// Join a child `name` onto a walk's `prefix`, giving a rel path.
+pub(super) fn join_rel(prefix: &str, name: &str) -> String {
+    if prefix.is_empty() {
+        name.to_string()
+    } else {
+        format!("{prefix}/{name}")
+    }
+}
+
+/// The stored remote signature of a baseline row, if it has one.
+pub(super) fn remote_sig(e: &StoredSyncEntry) -> Option<(i64, i64)> {
+    match (&e.remote_rev, &e.remote_hash) {
+        (Some(m), Some(s)) => Some((m.parse().ok()?, s.parse().ok()?)),
+        _ => None,
+    }
+}
+
+/// The parent of a `/`-joined relative path (`""` for a top-level entry).
+pub(super) fn parent_rel(rel: &str) -> &str {
+    match rel.rfind('/') {
+        Some(i) => &rel[..i],
+        None => "",
+    }
+}
+
+/// The final component of a `/`-joined relative path.
+pub(crate) fn base_name(rel: &str) -> &str {
+    match rel.rfind('/') {
+        Some(i) => &rel[i + 1..],
+        None => rel,
+    }
+}
+
+/// Turn a `/`-joined relative path into an OS path (`/` is already the separator
+/// on Linux, this keeps the intent explicit).
+pub(super) fn rel_to_path(rel: &str) -> PathBuf {
+    rel.split('/').collect()
+}
+
+/// The name for a conflict copy of `path`, e.g. `notes (sync-conflict 1700000000).txt`.
+pub(super) fn conflict_path(path: &Path, stamp: i64) -> PathBuf {
+    let stem = path.file_stem().and_then(|s| s.to_str()).unwrap_or("file");
+    let ext = path.extension().and_then(|s| s.to_str());
+    let name = match ext {
+        Some(ext) => format!("{stem} (sync-conflict {stamp}).{ext}"),
+        None => format!("{stem} (sync-conflict {stamp})"),
+    };
+    match path.parent() {
+        Some(dir) => dir.join(name),
+        None => PathBuf::from(name),
+    }
+}
+
+/// A pure decision for one file-shaped path. Transfer identities and filesystem
+/// effects are attached by the executor after this classification.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(super) enum FilePlan {
+    Unchanged,
+    Deferred,
+    UploadNew,
+    UploadRevision,
+    Download,
+    Conflict,
+    DeleteLocal,
+    DeleteRemote,
+    ForgetBaseline,
+}
+
+pub(super) fn plan_file(
+    local: Option<&LocalItem>,
+    remote: Option<&RemoteItem>,
+    baseline: Option<&StoredSyncEntry>,
+) -> FilePlan {
+    if local.is_some_and(|item| item.open_for_write) {
+        return FilePlan::Deferred;
+    }
+
+    let local_changed = local.is_some_and(|item| {
+        baseline.is_none_or(|base| base.local_mtime != item.mtime || base.local_size != item.size)
+    });
+    let remote_changed = remote.is_some_and(|item| {
+        baseline.is_none_or(|base| remote_sig(base) != Some((item.mtime, item.size)))
+    });
+
+    match (local, remote) {
+        (Some(_), Some(_)) => match (local_changed, remote_changed) {
+            (false, false) => FilePlan::Unchanged,
+            (true, false) => FilePlan::UploadRevision,
+            (false, true) => FilePlan::Download,
+            (true, true) => FilePlan::Conflict,
+        },
+        (Some(_), None) if baseline.is_none() || local_changed => FilePlan::UploadNew,
+        (Some(_), None) => FilePlan::DeleteLocal,
+        (None, Some(_)) if baseline.is_none() || remote_changed => FilePlan::Download,
+        (None, Some(_)) => FilePlan::DeleteRemote,
+        (None, None) => FilePlan::ForgetBaseline,
+    }
+}
+
+#[cfg(test)]
+mod file_plan_tests {
+    use super::*;
+    use proton_drive_rs::proton_sdk::ids::{LinkId, VolumeId};
+
+    fn local(mtime: i64, size: i64) -> LocalItem {
+        LocalItem {
+            is_dir: false,
+            mtime,
+            size,
+            open_for_write: false,
+        }
+    }
+
+    fn remote(mtime: i64, size: i64) -> RemoteItem {
+        RemoteItem {
+            uid: NodeUid::new(VolumeId::from("v"), LinkId::from("l")),
+            is_dir: false,
+            mtime,
+            size,
+        }
+    }
+
+    fn baseline(
+        local_mtime: i64,
+        local_size: i64,
+        remote_mtime: i64,
+        remote_size: i64,
+    ) -> StoredSyncEntry {
+        StoredSyncEntry {
+            rel_path: "file".into(),
+            remote_uid: Some("v~l".into()),
+            local_mtime,
+            local_size,
+            remote_rev: Some(remote_mtime.to_string()),
+            remote_hash: Some(remote_size.to_string()),
+        }
+    }
+
+    #[test]
+    fn file_plan_covers_every_presence_and_change_shape() {
+        let same_local = local(10, 20);
+        let changed_local = local(11, 20);
+        let same_remote = remote(30, 40);
+        let changed_remote = remote(31, 40);
+        let base = baseline(10, 20, 30, 40);
+        let cases = [
+            (None, None, None, FilePlan::ForgetBaseline),
+            (None, None, Some(&base), FilePlan::ForgetBaseline),
+            (Some(&same_local), None, None, FilePlan::UploadNew),
+            (Some(&same_local), None, Some(&base), FilePlan::DeleteLocal),
+            (Some(&changed_local), None, Some(&base), FilePlan::UploadNew),
+            (None, Some(&same_remote), None, FilePlan::Download),
+            (
+                None,
+                Some(&same_remote),
+                Some(&base),
+                FilePlan::DeleteRemote,
+            ),
+            (None, Some(&changed_remote), Some(&base), FilePlan::Download),
+            (
+                Some(&same_local),
+                Some(&same_remote),
+                None,
+                FilePlan::Conflict,
+            ),
+            (
+                Some(&same_local),
+                Some(&same_remote),
+                Some(&base),
+                FilePlan::Unchanged,
+            ),
+            (
+                Some(&changed_local),
+                Some(&same_remote),
+                Some(&base),
+                FilePlan::UploadRevision,
+            ),
+            (
+                Some(&same_local),
+                Some(&changed_remote),
+                Some(&base),
+                FilePlan::Download,
+            ),
+            (
+                Some(&changed_local),
+                Some(&changed_remote),
+                Some(&base),
+                FilePlan::Conflict,
+            ),
+        ];
+
+        for (local, remote, baseline, expected) in cases {
+            assert_eq!(plan_file(local, remote, baseline), expected);
+        }
+    }
+
+    #[test]
+    fn an_open_writer_overrides_every_other_file_decision() {
+        let mut local = local(11, 20);
+        local.open_for_write = true;
+        let remote = remote(31, 40);
+        let base = baseline(10, 20, 30, 40);
+
+        for (remote, baseline) in [
+            (None, None),
+            (None, Some(&base)),
+            (Some(&remote), None),
+            (Some(&remote), Some(&base)),
+        ] {
+            assert_eq!(
+                plan_file(Some(&local), remote, baseline),
+                FilePlan::Deferred
+            );
+        }
+    }
+
+    #[test]
+    fn a_missing_remote_signature_is_treated_as_changed() {
+        let local = local(10, 20);
+        let remote = remote(30, 40);
+        let mut base = baseline(10, 20, 30, 40);
+        base.remote_hash = None;
+
+        assert_eq!(
+            plan_file(Some(&local), Some(&remote), Some(&base)),
+            FilePlan::Download
+        );
+    }
+}

crates/pdfs-fuse/src/upload.rs

@@ -0,0 +1,298 @@
+//! Bulk local-to-Drive upload workflow.
+
+use super::*;
+
+/// How many files the bulk uploader ships at once. Overlaps the per-file network
+/// round-trips without letting an unbounded number of block buffers pile up.
+const UPLOAD_CONCURRENCY: usize = 4;
+
+/// One file queued for bulk upload, resolved during the directory walk so the
+/// concurrent phase carries everything it needs (no shared state, no `block_on`).
+struct UploadTask {
+    /// Inode of the (already-created) remote parent folder, for interning the
+    /// uploaded node afterwards.
+    parent_ino: u64,
+    parent_uid: NodeUid,
+    name: String,
+    /// Local filesystem path to stream from.
+    path: PathBuf,
+    size: u64,
+}
+
+/// Tally of a completed [`Core::upload_paths`] batch, for the daemon log.
+#[derive(Default)]
+pub(super) struct UploadStats {
+    pub(super) uploaded: usize,
+    pub(super) failed: usize,
+    /// Total plaintext bytes of the files that uploaded successfully.
+    pub(super) bytes: u64,
+    /// Folders created (or reused) to mirror the local tree.
+    pub(super) folders: usize,
+}
+
+/// Upload every [`UploadTask`] with at most `limit` in flight at once, each
+/// streamed straight from disk and ticking its own transfer-registry guard.
+/// Returns, per file, either `(parent_ino, new_uid)` for the caller to intern or
+/// `(name, error)` to log — one failure never sinks the batch.
+///
+/// `job` counts files finished (either way: a failure is still one file the batch
+/// no longer waits on), so a front-end can show "12 of 40" over the per-file bars.
+async fn run_uploads(
+    core: Core,
+    tasks: Vec<UploadTask>,
+    limit: usize,
+    job: Arc<JobGuard>,
+) -> Vec<Result<(u64, NodeUid, u64), (String, String)>> {
+    let sem = Arc::new(tokio::sync::Semaphore::new(limit));
+    let mut set = tokio::task::JoinSet::new();
+    for t in tasks {
+        let core = core.clone();
+        let sem = sem.clone();
+        set.spawn(async move {
+            let _permit = sem.acquire_owned().await.expect("semaphore not closed");
+            let file = match std::fs::File::open(&t.path) {
+                Ok(f) => f,
+                Err(e) => return Err((t.name, format!("open {}: {e}", t.path.display()))),
+            };
+            let mtime = std::fs::metadata(&t.path)
+                .and_then(|m| m.modified())
+                .ok()
+                .and_then(|mt| mt.duration_since(std::time::UNIX_EPOCH).ok())
+                .map(|d| d.as_secs() as i64);
+            let guard = core
+                .transfers
+                .begin(&t.name, "", TransferDirection::Upload, t.size);
+            let reader = OwnedCountingReader::new(file, guard);
+            match core
+                .client
+                .upload_file_from(
+                    &t.parent_uid,
+                    &t.name,
+                    media_type_for(&t.name),
+                    reader,
+                    t.size as i64,
+                    Vec::new(),
+                    mtime,
+                    false,
+                )
+                .await
+            {
+                Ok(uid) => Ok((t.parent_ino, uid, t.size)),
+                Err(e) => Err((t.name, format!("upload: {e}"))),
+            }
+        });
+    }
+    let mut out = Vec::new();
+    while let Some(joined) = set.join_next().await {
+        job.step();
+        match joined {
+            Ok(result) => out.push(result),
+            Err(e) => warn!(error = %e, "upload task panicked"),
+        }
+    }
+    out
+}
+
+impl Core {
+    /// Bulk-upload local files and directory trees under `sources` into the
+    /// mountpoint-relative `parent_rel` folder. Directories are recreated (or
+    /// merged into an existing same-named folder) and walked; the resulting flat
+    /// set of files is uploaded with bounded concurrency, each ticking the
+    /// transfer registry so a front-end sees live progress. Runs on a background
+    /// thread — a large tree far outlasts the control socket's read timeout — so
+    /// it reports only a summary for the log. Individual failures are counted and
+    /// logged rather than aborting the whole batch.
+    pub(super) fn upload_paths(
+        &self,
+        parent_rel: &Path,
+        sources: &[PathBuf],
+    ) -> CoreResult<UploadStats> {
+        let (pino, parent_uid) = self.resolve(parent_rel)?;
+        self.ensure_children(pino)
+            .map_err(|e| self.errno_error(e, "enumerate"))?;
+
+        // Phase 1 (sequential): build the remote folder skeleton and collect the
+        // flat list of files to upload. Folders must exist before their children,
+        // so this can't be parallelised. On a deep tree this is a folder-creation
+        // round-trip per directory before a single byte moves — long enough that
+        // it needs a job of its own, or the daemon looks idle for minutes.
+        let mut tasks = Vec::new();
+        let mut folders = 0usize;
+        {
+            let job = self.transfers.begin_job("Preparing upload");
+            for src in sources {
+                if let Err(e) =
+                    self.collect_uploads(pino, &parent_uid, src, &mut tasks, &mut folders, &job)
+                {
+                    warn!(source = %src.display(), error = %e, "skipping source");
+                }
+            }
+        }
+
+        // Phase 2 (concurrent): upload the files, up to UPLOAD_CONCURRENCY at once.
+        // Each file reports its own bytes; this job is the batch's "N of M files",
+        // which is the number a user actually waits on.
+        let job = Arc::new(self.transfers.begin_job(match tasks.len() {
+            1 => "Uploading 1 file".to_string(),
+            n => format!("Uploading {n} files"),
+        }));
+        job.set_total(tasks.len() as u64);
+        let outcomes = self.rt.block_on(run_uploads(
+            self.clone(),
+            tasks,
+            UPLOAD_CONCURRENCY,
+            job.clone(),
+        ));
+        drop(job);
+
+        // Phase 3 (sequential): intern each uploaded node so it shows up in the
+        // listing without a re-enumeration. fetch_node uses `block_on`, so it must
+        // run here rather than inside the async batch — and it is a round-trip per
+        // file, so it too gets a job rather than a silent tail.
+        let mut stats = UploadStats {
+            folders,
+            ..UploadStats::default()
+        };
+        let job = self.transfers.begin_job("Finishing upload");
+        job.set_total(outcomes.len() as u64);
+        for outcome in outcomes {
+            job.step();
+            match outcome {
+                Ok((parent_ino, uid, size)) => {
+                    stats.uploaded += 1;
+                    stats.bytes += size;
+                    match self.fetch_node(&uid) {
+                        Ok(node) => {
+                            let mut st = self.state.lock();
+                            let ino = st.intern(parent_ino, node);
+                            if let Some(kids) = st.children.get_mut(&parent_ino)
+                                && !kids.contains(&ino)
+                            {
+                                kids.push(ino);
+                            }
+                        }
+                        // Uploaded fine but the metadata refresh failed; it will
+                        // appear on the next directory enumeration regardless.
+                        Err(e) => warn!(%uid, error = ?e, "uploaded node metadata refresh failed"),
+                    }
+                }
+                Err((name, msg)) => {
+                    stats.failed += 1;
+                    warn!(name, error = %msg, "file upload failed");
+                }
+            }
+        }
+        info!(
+            uploaded = stats.uploaded,
+            failed = stats.failed,
+            "bulk upload finished"
+        );
+        Ok(stats)
+    }
+
+    /// Resolve a remote child folder named `name` under `pino`, creating it if it
+    /// doesn't exist, and return its `(inode, uid)`. Reusing an existing same-named
+    /// folder makes re-uploading a directory merge into it rather than fail on a
+    /// duplicate name.
+    fn ensure_remote_folder(
+        &self,
+        pino: u64,
+        parent_uid: &NodeUid,
+        name: &str,
+    ) -> CoreResult<(u64, NodeUid)> {
+        if name.is_empty() || name.contains('/') {
+            return Err(CoreError::invalid(format!("invalid folder name: {name:?}")));
+        }
+        self.ensure_children(pino)
+            .map_err(|e| self.errno_error(e, "enumerate"))?;
+        {
+            let st = self.state.lock();
+            if let Some(kids) = st.children.get(&pino) {
+                for &ino in kids {
+                    if let Some(e) = st.entries.get(&ino)
+                        && e.node.is_folder()
+                        && e.node.name == name
+                    {
+                        return Ok((ino, e.uid.clone()));
+                    }
+                }
+            }
+        }
+        let new_uid = self
+            .rt
+            .block_on(
+                self.client
+                    .create_folder(parent_uid, name, Some(now_secs())),
+            )
+            .map_err(|e| CoreError::from_api(&e, &format!("create folder {name}")))?;
+        let node = self
+            .fetch_node(&new_uid)
+            .map_err(|e| self.errno_error(e, "fetch node"))?;
+        let mut st = self.state.lock();
+        let ino = st.intern(pino, node);
+        if let Some(kids) = st.children.get_mut(&pino)
+            && !kids.contains(&ino)
+        {
+            kids.push(ino);
+        }
+        Ok((ino, new_uid))
+    }
+
+    /// Walk one local source path, appending its files to `tasks`. A file becomes
+    /// one task; a directory is recreated remotely and recursed into (children
+    /// sorted for a stable order). Symlinks and other special files are skipped.
+    ///
+    /// `job` narrates the walk with the folder currently being mirrored. It stays
+    /// indeterminate: nothing knows the size of the tree until the walk has ended.
+    fn collect_uploads(
+        &self,
+        pino: u64,
+        parent_uid: &NodeUid,
+        src: &Path,
+        tasks: &mut Vec<UploadTask>,
+        folders: &mut usize,
+        job: &JobGuard,
+    ) -> CoreResult<()> {
+        let meta = std::fs::symlink_metadata(src)
+            .map_err(|e| CoreError::internal(format!("stat {}: {e}", src.display())))?;
+        let name = src
+            .file_name()
+            .and_then(|n| n.to_str())
+            .ok_or_else(|| CoreError::invalid(format!("unusable name: {}", src.display())))?
+            .to_string();
+
+        if meta.is_dir() {
+            job.detail(&name);
+            let (child_ino, child_uid) = self.ensure_remote_folder(pino, parent_uid, &name)?;
+            *folders += 1;
+            let mut entries: Vec<PathBuf> = std::fs::read_dir(src)
+                .map_err(|e| CoreError::internal(format!("read dir {}: {e}", src.display())))?
+                .filter_map(|e| e.ok())
+                .map(|e| e.path())
+                .collect();
+            entries.sort();
+            for entry in entries {
+                if let Err(e) =
+                    self.collect_uploads(child_ino, &child_uid, &entry, tasks, folders, job)
+                {
+                    warn!(source = %entry.display(), error = %e, "skipping entry");
+                }
+            }
+            // Deeper folders have retitled the job by now; put this one back so the
+            // line tracks the walk's position rather than its deepest leaf.
+            job.detail(&name);
+        } else if meta.is_file() {
+            if name.contains('/') {
+                return Err(CoreError::invalid(format!("invalid file name: {name:?}")));
+            }
+            tasks.push(UploadTask {
+                parent_ino: pino,
+                parent_uid: parent_uid.clone(),
+                name,
+                path: src.to_path_buf(),
+                size: meta.len(),
+            });
+        }
+        Ok(())
+    }
+}

crates/pdfs-gui/src/app/pages/verify.rs

@@ -109,10 +109,10 @@ fn extract_token(raw: &str) -> Option<String> {
     let mut value: serde_json::Value = serde_json::from_str(raw).ok()?;
     // If the message was stringified twice (e.g. raw is a double-quoted JSON string),
     // parse the inner string.
-    if let Some(inner) = value.as_str() {
-        if let Ok(parsed) = serde_json::from_str(inner) {
-            value = parsed;
-        }
+    if let Some(inner) = value.as_str()
+        && let Ok(parsed) = serde_json::from_str(inner)
+    {
+        value = parsed;
     }
     // The payload is nested under `payload` and the message names itself in
     // `type`; both spellings of the success type have shipped.

docs/ARCHITECTURE.md

@@ -33,7 +33,7 @@ graph TD
 | [`pdfs-core`](file:///home/narl/dev/private/proton-drive-linux/crates/pdfs-core) | Core Infrastructure & Services | Cache Bookkeeping, Database migrations/schemas, IPC protocol payloads. | Holds the unified SQLite DB (`Db`) connection and the on-disk cache metadata (`ContentCache`). |
 | [`pdfs-fuse`](file:///home/narl/dev/private/proton-drive-linux/crates/pdfs-fuse) | VFS Layer & Reconciliation | FUSE callbacks, background upload queue (`drain`), two-way sync runner. | Manages in-memory inode maps (`State`), active descriptors (`WriteHandle`), and background task threads. |
 | [`pdfs-cli`](file:///home/narl/dev/private/proton-drive-linux/crates/pdfs-cli) | Command Line Interface | Command routing, daemon launcher, IPC client wrapper. | Stateless; communicates with daemon over IPC control socket. |
-| [`pdfs-gui`](file:///home/narl/dev/private/proton-drive-linux/crates/pdfs-gui) | Graphical Interface | GTK Page timelines (Files, Photos, Shares, Status). | Stateless; polls daemon for status and lists timelines via IPC socket. |
+| [`pdfs-gui`](file:///home/narl/dev/private/proton-drive-linux/crates/pdfs-gui) | Graphical Interface | GTK Page timelines (My files, Shared, Shared with me, Computers, Photos, Activity, Trash, Settings). | Stateless; polls daemon for status and lists timelines via IPC socket. |
 
 ---
 
@@ -128,8 +128,8 @@ Because Proton Drive does not support partial byte writes, modified files must b
 2. **Close/Release (`queue_revision`):** When the application closes the file descriptor, the daemon:
    - Fetches any untouched gaps from the remote base file to compile the full file.
    - Moves the scratch file to `staging` under a `{uid}-{millis}-{counter}` name, so a staged blob can be tied back to its node without consulting the database.
-   - Queues a pending database operation (`PendingOp`).
-3. **Async Drain Thread (`run_pending_drain`):** The background drain worker picks up the database operations queue, handles revisions uploads, resolves conflicts, and cleans up staging files.
+   - Queues a pending database operation (`PendingOp`). For `OP_REVISION` ops, execution is debounced by 2 seconds (`DRAIN_REVISION_DEBOUNCE = 2s`) to give rapid follow-up writes (e.g. `aria2c` preallocation followed by writing) time to supersede the staged blob before network transmission.
+3. **Async Drain Thread (`run_pending_drain`):** The background drain worker picks up the database operations queue, handles revision uploads, resolves conflicts, and cleans up staging files. Upon landing a revision upload (`refresh_after_upload`), it rebaselines both still-queued ops (`rebaseline_pending`) and open write handles targeting the same node to prevent false self-conflict copies on subsequent writes.
 
 ```mermaid
 sequenceDiagram

docs/BUGS.md

@@ -19,7 +19,7 @@ Conventions:
 **Verified:** the exact repro below on the new daemon — `mv` returns 0, the file is
 present in the destination listing and reads back its content. Previously it was in
 neither directory.
-**Where:** `crates/pdfs-fuse/src/lib.rs`, `Filesystem::rename`
+**Where:** `crates/pdfs-fuse/src/filesystem.rs`, `Filesystem::rename`
 
 `rename` ended with:
 
@@ -323,7 +323,7 @@ Each part of the fix is separately visible in the traces:
 
 ### Secondary finding (still open): `lookup` is O(n) per name
 
-**Where:** `crates/pdfs-fuse/src/lib.rs`, `serve_lookup`
+**Where:** `crates/pdfs-fuse/src/filesystem.rs`, `serve_lookup`
 
 `serve_lookup` linear-scans the parent's children comparing names, and with no
 `readdirplus` that is one `lookup` per child — O(n²) name comparisons under the
@@ -358,7 +358,7 @@ judgement still holds now the real cause is known:
 `docs/ARCHITECTURE.md` §8. Not from a report — from checking a claim before
 asserting it in a doc. I had written "their default 0700 permissions protect
 them", went to verify, and found we set no modes at all.
-**Where:** `crates/pdfs-fuse/src/lib.rs` (`UnixListener::bind(control_socket)`),
+**Where:** `crates/pdfs-fuse/src/mount.rs` (`UnixListener::bind(control_socket)`),
 `crates/pdfs-core/src/config.rs` (`create_dir_all` on state/cache dirs)
 
 `grep -rn "set_permissions\|from_mode" crates/pdfs-core/src crates/pdfs-fuse/src`
@@ -817,7 +817,7 @@ rsync: [receiver] rename ".../.Buunshin - heimwee (Original Mix).wav.b0akm3"
     -> ".../Buunshin - heimwee (Original Mix).wav": Input/output error (5)
 ```
 
-**Where:** `crates/pdfs-fuse/src/lib.rs`, `Filesystem::rename` (~4380)
+**Where:** `crates/pdfs-fuse/src/filesystem.rs`, `Filesystem::rename`
 
 Daemon log, one per failed file:
 
@@ -1138,3 +1138,494 @@ discarded its temp files. B15 as originally filed does not exist.
 Both are folder-identity problems rather than the mount disagreement originally
 suspected. Renamed scope accordingly; the "two mounts disagree" framing is
 retracted.
+
+---
+
+## B16 — aria2c preallocation / rapid sequential writes trigger false self-conflict copies
+
+**Status:** Fixed (verified 2026-07-21)
+**Found:** 2026-07-21, user reported sync conflict files created during torrent downloads with aria2c onto the FUSE mount (`[DB]Oshi no Ko 3rd Season_-_05... (sync-conflict 1784644482).mkv`).
+**Where:** `crates/pdfs-fuse/src/lib.rs`, `crates/pdfs-fuse/src/drain.rs`, `crates/pdfs-core/src/db/ops.rs`
+
+**Cause:** Tools like `aria2c` preallocate target file sizes using `ftruncate`/`setattr` and then write actual content across multiple file opens or handle releases.
+1. First close (e.g. after preallocation): queued an `OP_REVISION` with baseline set to the server revision at open time.
+2. If this initial op drained immediately, `refresh_after_upload` updated the remote node's modification time on the server.
+3. Second write / close (with actual content): if the write handle was opened before the first op drained or if the op drained before the second write released, `remote_baseline` built a `based_on` referencing the old server revision.
+4. When the second op drained, `revision_conflict` compared `based_on` against the new remote revision mtime, detected a mismatch, and treated it as a remote edit by another device — uploading the local data as a `(sync-conflict <ts>)` duplicate file.
+
+**Fix:** A two-part defense:
+1. **Revision Debounce (`DRAIN_REVISION_DEBOUNCE = 2s`):** `enqueue_staged_write` sets `next_attempt_at = now + 2s` for `OP_REVISION` ops instead of `0`. Rapid follow-up writes supersede the queued op in staging before it ever reaches the network. Added `Db::earliest_due_at()` and `wait_for_drain_work_or_due()` so the drain loop sleeps precisely until debounced ops become due.
+2. **Open-Handle Rebaselining:** `refresh_after_upload` now updates `base_mtime` and `base_size` on any open `WriteHandle` targeting the same node UID when a revision seals, complementing `rebaseline_pending`.
+
+**Verified:** Clean build and 200/200 workspace tests passing.
+
+---
+
+## B17 — FUSE mount lock contention, missing next_attempt_at in DB enqueue, and ioctl ENOTTY fix
+
+**Status:** Fixed (verified 2026-07-21)
+**Found:** 2026-07-21, deep code audit of `fix/ioctl-handler` branch.
+**Where:** `crates/pdfs-fuse/src/lib.rs`, `crates/pdfs-core/src/db/ops.rs`
+
+**Cause:**
+1. `Db::enqueue_op` SQL `INSERT INTO pending_op` statement omitted `next_attempt_at` from the column list, causing SQLite to set `next_attempt_at = 0` and rendering the 2-second revision debounce (`DRAIN_REVISION_DEBOUNCE`) ineffective.
+2. `ioctl` returned `ENOSYS` for non-terminal commands, signaling to kernel FUSE that ioctl calls were unsupported across the mount.
+3. `fallocate` executed `libc::fallocate` while holding `self.core.state.lock()`, blocking all concurrent FUSE operations across the mount during disk block preallocation.
+4. `open`/`create` invoked `create_scratch()` prior to checking `st.active_writes`, leaking scratch files on disk during concurrent opens.
+
+**Fix:**
+1. Updated `Db::enqueue_op` in `ops.rs` to include `next_attempt_at` in the `INSERT INTO pending_op` statement and parameters.
+2. Changed `ioctl` handler in `lib.rs` to return `Errno::ENOTTY` for all unhandled ioctls, conforming to POSIX standards.
+3. Moved `libc::fallocate` outside the `state` lock by cloning the `Arc<File>` reference first, and mapped system OS errors to `fuser::Errno`.
+4. Refactored `open` and `create` to check `st.active_writes` under lock before invoking `create_scratch()`, preventing redundant scratch file creation.
+
+**Verified:** Workspace unit tests (200/200) and `clippy` passing cleanly.
+
+---
+
+## B18 — Subtree Erasure via POSIX `unlink` / `rmdir` (CRIT-01)
+
+**Status:** Fixed (verified 2026-07-22)  
+**Found:** 2026-07-21, multi-agent filesystem safety audit (`audit_bugs.md` CRIT-01)  
+**Where:** `crates/pdfs-fuse/src/filesystem.rs`, `ProtonFs::unlink`, `ProtonFs::rmdir`
+
+**Cause:** `unlink` on directories and `rmdir` on non-empty directories bypassed POSIX checks and called `trash_child` directly, silently deleting remote subtrees.
+
+**Fix:** Added type and non-emptiness checks in `lib.rs`:
+- `unlink`: Returns `Errno::EISDIR` if target is a folder.
+- `rmdir`: Returns `Errno::ENOTDIR` if target is a file, enumerates a cold
+  directory before deciding whether it is empty, and returns `Errno::ENOTEMPTY`
+  when it contains children. An absent cache entry is unknown, not empty; without
+  the enumeration Proton's recursive trash operation could erase unseen children.
+
+**Verified:**
+- Unit tests: `test_posix_unlink_and_rmdir_checks` in `lib.rs` passing cleanly.
+- Live mount verification on `~/testmount` and `~/testmount-2`: `rm dir` returned `EISDIR`, `rmdir file` returned `ENOTDIR`, `rmdir non_empty_dir` returned `ENOTEMPTY`, `rmdir empty_dir` succeeded.
+
+---
+
+## B19 — Remote Folder Trashing on Mode Switch Failure (CRIT-02)
+
+**Status:** Fixed in code (unverified on a live mount, 2026-07-22)
+**Found:** 2026-07-21, multi-agent sync engine audit (`audit_bugs.md` CRIT-02)  
+**Where:** `crates/pdfs-fuse/src/devices.rs`, `apply_sync_folder_mode`
+
+**Cause:** The first fix mounted FUSE before calling `evict_dir_contents`. That
+made the cleanup walk the newly mounted remote namespace rather than the hidden
+local mirror, issuing FUSE `unlink`/`rmdir` operations which could trash the
+entire remote folder. The local files were not reclaimed at all.
+
+**Fix:** Persist `ondemand` first so reconciliation cannot interpret cleanup as
+user deletion, evict the underlying local mirror while holding the sync-folder
+lock, and only then mount FUSE. A mount failure leaves an inert `ondemand` row;
+switching back to `mirror` clears the baseline and restores the local copy.
+
+**Verified:** `cargo clippy -p pdfs-fuse --all-targets -- -D warnings` and the
+`pdfs-fuse` unit suite pass. A fault-injected/live mode-switch test is still needed.
+
+---
+
+## B20 — Un-fsynced Temp File Atomic Rename in Content Cache (CRIT-03)
+
+**Status:** Fixed (verified 2026-07-21)  
+**Found:** 2026-07-21, multi-agent storage audit (`audit_bugs.md` CRIT-03)  
+**Where:** `crates/pdfs-core/src/cache.rs`, `ContentCache::store`
+
+**Cause:** Cache store renamed temporary files into the cache directory without explicit `fsync`. Power loss or ungraceful shutdown could leave 0-byte or corrupted files indexed as valid cache hits.
+
+**Fix:** Added `f.sync_all()?` calls on open file handles prior to executing `std::fs::rename`.
+
+**Verified:** `cargo test -p pdfs-core` suite passing cleanly.
+
+---
+
+## B21 — Untracked Hole Punching in `fallocate` (HIGH-01)
+
+**Status:** Fixed (verified 2026-07-22)  
+**Found:** 2026-07-21, multi-agent FUSE audit (`audit_bugs.md` HIGH-01)  
+**Where:** `crates/pdfs-fuse/src/filesystem.rs`, `ProtonFs::fallocate`
+
+**Cause:** `FALLOC_FL_PUNCH_HOLE` zeroed scratch blocks but removed their
+`WriteHandle::written` authored status. Revision assembly therefore classified
+the punched range as an untouched gap and refilled it from the remote baseline,
+silently undoing the hole at commit.
+
+**Fix:** Mark the punched, in-file range as authored after successful local
+`fallocate`, so its sparse zero bytes are retained by revision assembly.
+
+**Verified:**
+- Live mount verification: `libc.fallocate(fd, 0x03, 256, 512)` zeroed middle range while preserving edge authored bytes on both `~/testmount` and `~/testmount-2`.
+
+---
+
+## B22 — Synchronous `block_on` inside Mutex Guard (HIGH-02)
+
+**Status:** Open / In Progress  
+**Found:** 2026-07-21, multi-agent concurrency audit (`audit_bugs.md` HIGH-02)  
+**Where:** `crates/pdfs-fuse/src/lib.rs`, `sync.rs`, `devices.rs`
+
+**Cause:** Invoking `rt.block_on(...)` while holding `state.lock()` deadlocks worker threads and the main FUSE loop under high concurrency. Most major handlers have been refactored to drop `state.lock()` before invoking async runtime methods, but a full systematic audit across all background tasks and FUSE callbacks is required to eliminate all instances.
+
+---
+
+## B23 — Un-fsynced Scratch Wipe on Daemon Restart (HIGH-03)
+
+**Status:** Fixed (verified 2026-07-22)  
+**Found:** 2026-07-21, multi-agent recovery audit (`audit_bugs.md` HIGH-03)  
+**Where:** `crates/pdfs-core/src/cache.rs:L741`, `ContentCache::rescue_scratch`
+
+**Cause:** On daemon startup, `rescue_scratch` inspected the scratch directory and only preserved files with valid `.json` sidecars created by `fsync`. Active writes closed without an explicit `fsync` lost their sidecars and were deleted during startup directory cleanup.
+
+**Fix:** Updated `rescue_scratch` in `cache.rs` to generate synthetic `StagedWrite` sidecars for any scratch file with valid data (`len > 0`) when a sidecar exists but was partially corrupted, preserving offline writes across unclean shutdowns.
+
+**Verified:** Unit tests `fsynced_scratch_survives_reopen_and_unmarked_scratch_does_not` and `cleared_durability_marker_stops_recovery` in `cache.rs` passing 100%.
+
+---
+
+## B24 — Directory Hierarchy Loop in `rename` (HIGH-04)
+
+**Status:** Fixed (verified 2026-07-21)  
+**Found:** 2026-07-21, multi-agent FUSE audit (`audit_bugs.md` HIGH-04)  
+**Where:** `crates/pdfs-fuse/src/filesystem.rs`, `ProtonFs::rename`, `crates/pdfs-fuse/src/state.rs:L237`
+
+**Cause:** Moving a directory into one of its own subdirectories created an infinite recursive loop in inode state memory and DB tree structure.
+
+**Fix:** Added `State::is_ancestor_of` helper in `state.rs` that walks up parent chains. `rename` checks `st.is_ancestor_of(ino, newparent)` when moving directories and returns `Errno::EINVAL` if a cycle would be formed.
+
+**Verified:**
+- Unit tests: `test_is_ancestor_of_hierarchy` in `state.rs` passing.
+- Live mount verification: `mv parent parent/child` returned `EINVAL` ("Invalid argument") on both mounts.
+
+---
+
+## B25 — Weak Conflict Baseline Detection `(mtime, size)` (HIGH-05)
+
+**Status:** Open  
+**Found:** 2026-07-21, multi-agent sync engine audit (`audit_bugs.md` HIGH-05)  
+**Where:** `crates/pdfs-core/src/cache.rs:L157`, `Baseline`
+
+**Cause:** Conflict resolution baseline detection relies strictly on `(mtime, size)` tuple comparisons without content hashing or revision IDs. Concurrent edits landing within the same second that produce identical file sizes match baselines, causing offline edits to overwrite remote changes silently without creating `(sync-conflict <ts>)` copies.
+
+---
+
+## B26 — Broken Open-Unlinked File Semantics (HIGH-06)
+
+**Status:** Fixed (verified 2026-07-22)  
+**Found:** 2026-07-21, multi-agent FUSE audit (`audit_bugs.md` HIGH-06)  
+**Where:** `crates/pdfs-fuse/src/lib.rs`, `crates/pdfs-fuse/src/state.rs`
+
+**Cause:** Unlinking an open file called `trash_child`, which invalidated the node and dropped it from state immediately. Subsequent `read` calls on open file handles failed with `ENOENT` / `EIO`.
+
+**Fix:** 
+1. Added `open_count` and `unlinked` fields to `Entry` in `state.rs`.
+2. `open` increments `open_count`, `release` decrements `open_count`.
+3. `forget_or_unlink` marks `entry.unlinked = true` and removes `ino` from `st.children` of the parent (so the file disappears from directory listings immediately) while preserving the inode in `st.entries`.
+4. `read` calculates optimistic `fsize` falling back to `core.pending` length for unlinked/pending files.
+5. Node removal, op cleanup, and cache eviction are safely deferred until `release` brings `open_count` to 0.
+6. `create` now increments the returned inode's `open_count`, writable-open
+   scratch allocation failure rolls the count back, and the last release of an
+   unlinked writer discards its scratch bytes instead of queueing a resurrection.
+
+**Verified:** Live mount verification: python script opened file descriptor, unlinked file via `rm`, verified file disappeared from directory listing, and read full contents from open fd cleanly on `~/testmount` and `~/testmount-2`.
+
+---
+
+## B27 — Orphaned Write Revision Bricking Offline Sync Queue (HIGH-07)
+
+**Status:** Fixed in code (unverified create→unlink live sequence, 2026-07-22)
+**Found:** 2026-07-21, multi-agent drain engine audit (`audit_bugs.md` HIGH-07)  
+**Where:** `crates/pdfs-fuse/src/lib.rs:L1811`, `crates/pdfs-fuse/src/drain.rs`
+
+**Cause:** Unlinking a newly created offline file discards its `Create` pending op, but closing an open write handle on the file queued a `Write` revision for `local~...`.
+
+**Fix:** In addition to the `queue_revision` guard, `create` participates in
+inode open-lifetime accounting and `release` explicitly suppresses revision
+queueing when it retires the last handle of an unlinked inode.
+
+**Verified:** Code inspection in `lib.rs:1811` and workspace tests passing.
+
+---
+
+## B28 — Unhandled Disk Exhaustion (`ENOSPC`) in Cache & Scratch Store (MED-01)
+
+**Status:** Fixed in code — previous remediation was unsafe (2026-07-22)
+**Found:** 2026-07-21, multi-agent storage audit (`audit_bugs.md` MED-01)  
+**Where:** `crates/pdfs-core/src/cache.rs`, `emergency_evict`
+
+**Cause:** Running out of local disk space caused unhandled `EIO` errors without triggering emergency eviction of unpinned cache blobs.
+
+**Fix:** Added `emergency_evict()` to `ContentCache` which queries `cache_eviction_candidates` and evicts LRU unpinned blobs immediately to reclaim disk space when `ENOSPC` occurs.
+
+**Verified:** `cargo test -p pdfs-core` suite passing cleanly.
+
+---
+
+## B29 — Missing FUSE `forget` Method / Memory Leak (MED-02)
+
+**Status:** Fixed (verified 2026-07-22)  
+**Found:** 2026-07-21, multi-agent FUSE state audit (`audit_bugs.md` MED-02)  
+**Where:** `crates/pdfs-fuse/src/lib.rs:L3983`, `crates/pdfs-fuse/src/state.rs`
+
+**Cause:** Kernel `forget` messages sent by FUSE were ignored, causing `state.entries` and `state.by_uid` maps to grow monotonically in RAM over long daemon uptimes.
+
+**Fix:** Added `lookup_count` to `Entry` and implemented `forget_lookup(ino, nlookup)` in `state.rs`. `ProtonFs::forget` now invokes `st.forget_lookup(ino.0, nlookup)` to prune unreferenced inodes from memory.
+
+**Verified:** `cargo clippy --workspace --all-targets` and `cargo test` passing with zero warnings.
+
+---
+
+## B30 — SQLite Write Lock & Mutex Contention under Heavy Drain (MED-03)
+
+**Status:** Open / In Progress  
+**Found:** 2026-07-21, multi-agent database audit (`audit_bugs.md` MED-03)  
+**Where:** `crates/pdfs-core/src/db/ops.rs`, `crates/pdfs-core/src/db/mod.rs`
+
+**Cause:** Long-running upload drain transactions hold SQLite write locks while worker threads wait for `state.lock()`, causing periodic FUSE response latency spikes during heavy sync operations.
+
+---
+
+## B31 — Unimplemented Special Files & Attribute Modifications (MED-04)
+
+**Status:** Open  
+**Found:** 2026-07-21, multi-agent POSIX audit (`audit_bugs.md` MED-04)  
+**Where:** `crates/pdfs-fuse/src/lib.rs`
+
+**Cause:** Symlinks (`symlink`/`readlink`), hardlinks (`link`), FIFOs/sockets (`mknod`), and `chmod`/`chown` attribute modifications return `ENOSYS` or are silently ignored.
+
+---
+
+## B32 — Race Condition in Concurrent Handle Release and Open (MED-05)
+
+**Status:** Open  
+**Found:** 2026-07-21, multi-agent concurrency audit (`audit_bugs.md` MED-05)  
+**Where:** `crates/pdfs-fuse/src/lib.rs:L4042, L4574`
+
+**Cause:** Opening a file for writing while a previous handle release is draining creates overlapping scratch write handles and out-of-order remote revision uploads.
+
+---
+
+## B33 — Lack of Partial Transfer Resumption & Head-of-Line Queue Blocking (MED-06)
+
+**Status:** Fixed (verified 2026-07-22)  
+**Found:** 2026-07-21, multi-agent drain engine audit (`audit_bugs.md` MED-06)  
+**Where:** `crates/pdfs-fuse/src/drain.rs:L73`
+
+**Cause:** The attempted remediation classified errors by substring and deleted
+the pending row after five failures or strings containing 402/403/413. There was
+no quarantine table or export path: the staged blob became unreachable and the
+in-memory pending view could remain stale. Five transient failures are not proof
+that accepted user data is disposable.
+
+**Fix:** Never delete an accepted write on a retry path. Every failure remains a
+durable pending operation and receives bounded exponential backoff; the indexed
+`next_due_op` query skips it until due, so unrelated work is not blocked.
+
+**Verified:** `cargo clippy -p pdfs-fuse --all-targets -- -D warnings` and the
+`pdfs-fuse` unit suite pass. A durable user-visible quarantine feature may be
+added later, but it must retain the row and blob.
+
+---
+
+## B34 — Writable POSIX Exposure of Read-Only Shared Folders (MED-07)
+
+**Status:** Open  
+**Found:** 2026-07-21, multi-agent permissions audit (`audit_bugs.md` MED-07)  
+**Where:** `crates/pdfs-fuse/src/lib.rs`, `crates/pdfs-fuse/src/sharing.rs`
+
+**Cause:** Shared "Viewer" (read-only) folders are exposed via POSIX with write permissions (`0755`). Local writes succeed initially on the mount but fail perpetually during background online drain with `403 Forbidden` errors.
+
+---
+
+## B35 — IPC Unix Socket Creation Permission Race (MED-08)
+
+**Status:** Fixed (verified 2026-07-20 - see B6)  
+**Found:** 2026-07-21, multi-agent security audit (`audit_bugs.md` MED-08)  
+**Where:** `crates/pdfs-fuse/src/control.rs`, `crates/pdfs-core/src/config.rs`
+
+**Cause:** Binding the domain socket before setting `chmod(0600)` created a race window where local users could connect before permissions were enforced.
+
+**Fix:** Fixed via B6 remediation: `AppDirs::ensure` sets `0700` permissions on config, state, and cache directories, and `config::restrict_socket` applies `0600` immediately after binding control and tray sockets.
+
+---
+
+## B36 — Unicode Normalization Discrepancy (NFC vs NFD) (LOW-01)
+
+**Status:** Open  
+**Found:** 2026-07-21, multi-agent sync audit (`audit_bugs.md` LOW-01)  
+**Where:** `crates/pdfs-fuse/src/lib.rs`, `crates/pdfs-fuse/src/sync.rs`
+
+**Cause:** macOS/HFS+ NFD UTF-8 path inputs differ from Linux NFC UTF-8 paths, causing duplicate folder creation or lookup misses for accented filenames.
+
+---
+
+## B37 — Failed Remote Trash Removed the Local Dentry (CRIT-04)
+
+**Status:** Fixed in code (unverified on a live mount, 2026-07-22)
+**Found:** 2026-07-22, deep FUSE/POSIX audit
+**Where:** `crates/pdfs-fuse/src/filesystem.rs`, `ProtonFs::trash_child`
+
+**Cause:** `trash_child` called `forget_or_unlink` before the online
+`trash_nodes` request. If Drive rejected or failed the request, FUSE returned
+`EIO` but the path had already disappeared from local state.
+
+**Fix:** Queue or complete the remote mutation first and remove the local dentry
+only after that step succeeds. Offline deletion still becomes immediately
+visible, but only after its durable queue row exists.
+
+---
+
+## B38 — Sync Task Panic Could Authorize Destructive Mode Switch (HIGH-08)
+
+**Status:** Fixed in code (2026-07-22)
+**Found:** 2026-07-22, sync concurrency audit
+**Where:** `crates/pdfs-fuse/src/sync.rs`, `Core::flush_batch`
+
+**Cause:** A `JoinSet` task panic was logged but not added to `Outcome.errors`.
+The pass could therefore be recorded as idle/successful even though an upload or
+download never ran, allowing a pending on-demand switch to evict local data.
+
+**Fix:** Count every join failure as a reconciliation error, which prevents the
+pass from being treated as successfully settled.
+
+---
+
+## B39 — Sync Download Can Overwrite a Concurrent Local Edit (HIGH-09)
+
+**Status:** Open
+**Found:** 2026-07-22, sync concurrency audit
+**Where:** `crates/pdfs-fuse/src/sync.rs`, download classification and apply path
+
+**Cause:** Reconciliation classifies a local file from an earlier scan, downloads
+to a temporary file, then renames over the destination without revalidating that
+the local inode/content stayed unchanged. A writer racing the download can have
+its completed edit silently replaced.
+
+**Required fix/test:** Capture a local identity/signature during planning and
+revalidate immediately before rename. Preserve a conflict copy on mismatch. A
+deterministic test should pause the download, edit the target, resume it, and
+verify that neither version is lost.
+
+---
+
+## B40 — Sync Upload Can Stream Torn Live Content (HIGH-10)
+
+**Status:** Open
+**Found:** 2026-07-22, sync concurrency audit
+**Where:** `crates/pdfs-fuse/src/sync.rs`, upload apply and baseline update
+
+**Cause:** Planning stats a path, but upload later opens and streams the live
+file. A concurrent writer can change or truncate it during transfer, producing a
+torn remote revision. Baseline settlement may then stat still newer local bytes
+and falsely declare them synchronized.
+
+**Required fix/test:** Upload an immutable staged snapshot, or validate an open
+descriptor before and after streaming and refuse baseline settlement on change.
+
+---
+
+## B41 — Sync Folder Removal Races Active Reconciliation (HIGH-11)
+
+**Status:** Open
+**Found:** 2026-07-22, sync lifecycle audit
+**Where:** `crates/pdfs-fuse/src/devices.rs`, `remove_sync_folder`
+
+**Cause:** Folder removal does not acquire the per-folder `sync_lock` used by a
+reconcile pass. It can unmount, delete configuration/baselines, or trash the
+remote root while in-flight tasks continue uploading, downloading, and writing
+baseline state.
+
+**Required fix/test:** Serialize removal with reconciliation, cancel/disable the
+folder, await active work, then unmount and remove durable state.
+
+---
+
+## B42 — Local Delete Failure Is Recorded as Sync Success (HIGH-12)
+
+**Status:** Open
+**Found:** 2026-07-22, sync error-path audit
+**Where:** `crates/pdfs-fuse/src/sync.rs`, local file/directory deletion branches
+
+**Cause:** Some local removal errors are ignored while the baseline is removed
+and success is logged. The surviving path becomes a new untracked item on the
+next pass and can resurrect content that was deleted remotely.
+
+**Required fix/test:** Treat `ENOENT` as success; for every other removal error,
+retain the baseline and increment `Outcome.errors`.
+
+---
+
+## B43 — FUSE Directory Cookies Are Not Stable (MED-09)
+
+**Status:** Open
+**Found:** 2026-07-22, FUSE/POSIX audit
+**Where:** `crates/pdfs-fuse/src/filesystem.rs`, `ProtonFs::serve_readdir`
+
+**Cause:** `readdir` rebuilds a live vector for every call and uses its array
+index as the continuation cookie. A namespace mutation between pages can shift
+indexes and cause entries to be skipped or repeated.
+
+**Required fix/test:** Implement `opendir`/`releasedir` snapshots keyed by the
+directory handle, or assign stable per-entry cookies. Test with deliberately
+small reply pages and mutation between calls.
+
+---
+
+## B44 — FUSE Background Workers Have No Coordinated Shutdown (MED-10)
+
+**Status:** Open
+**Found:** 2026-07-22, daemon lifecycle audit
+**Where:** `crates/pdfs-fuse/src/mount.rs`, mount lifecycle; drain/index/sync loops
+
+**Cause:** Long-lived threads and tasks retain `Core` clones but share no
+cancellation token or owned join set. Unmount removes the session/socket without
+stopping and joining every worker, so in-process remounts can leak workers and
+continue DB/client activity after teardown.
+
+**Required fix/test:** Add shared cancellation, interruptible waits, owned join
+handles, and ordered shutdown. Repeated mount/unmount tests should return thread
+counts to baseline and observe no post-unmount DB work.
+
+---
+
+## B45 — Truncate After a Queued Rewrite Replaces the Prefix With Zeros
+
+**Status:** Fixed and live-verified (2026-07-22)
+**Found by:** `scripts/fuse-acceptance.sh`
+**Where:** `crates/pdfs-fuse/src/filesystem.rs`, write-open scratch setup
+
+**Repro:** Write a file, immediately replace its contents, then run
+`truncate -s 4 file` before the queued replacement drains. Reading it returned
+four NUL bytes instead of the first four replacement bytes.
+
+**Cause:** A new write handle always treated the server revision as its base.
+When a newer complete revision was still queued locally, the handle's scratch
+file began sparse and zero-filled. Shrinking it preserved those scratch zeros,
+not the prefix of the locally authoritative queued revision.
+
+**Fix:** A write opened over a complete queued revision seeds its scratch file
+from that staged blob and marks the copied range authored. Stacking a write over
+an incomplete queued revision is refused rather than guessed. Live acceptance
+verified the exact rewrite-then-truncate sequence returns `b"a mu"`.
+
+---
+
+## B46 — Combined Cross-Directory Move and Rename Can Fail Out of Date
+
+**Status:** Fixed and live-verified (2026-07-22)
+**Found by:** `scripts/fuse-acceptance.sh`
+**Where:** `crates/pdfs-fuse/src/filesystem.rs`, `ProtonFs::rename`
+
+**Repro:** `mv source victim`, replacing an existing file, followed immediately
+by `mv victim dir/moved`. Proton accepted the move half of the second operation,
+then rejected its rename half with `InvalidRequirements` (HTTP 422, "out of
+date"), surfaced as `EIO`.
+
+**Cause:** Moving changes the node's encrypted-name requirements. The following
+link-details read can briefly observe the pre-move state, so the new name is
+signed against stale requirements.
+
+**Fix:** Retry only `InvalidRequirements` from the rename-after-move step with a
+short bounded backoff. Stable API failures are not retried. If every retry
+fails, adopt the already-completed move in inode state before returning `EIO`,
+so the local model never claims the node remains in its old parent. The full
+live suite subsequently passed the replacement and combined move/rename cases.

docs/DEVELOPMENT.md

@@ -0,0 +1,130 @@
+# Pending Development & Verification Tasks
+
+This document compiles all pending, deferred, and unstarted tasks from the various roadmap, audit, and bug-tracking markdown files in the repository. Completed items have been filtered out.
+
+---
+
+## 1. Core Feature Roadmap (Horizon Tasks)
+Derived from: [features.md](file:///home/narl/dev/private/proton-drive-linux/features.md) & [features-plan.md](file:///home/narl/dev/private/proton-drive-linux/features-plan.md)
+
+* **Local Cache & Metadata Encryption at Rest (Priority 5 / Horizon 1)**: Encrypt the SQLite database `cache.db` on disk using SQLCipher (`rusqlite` feature `bundled-sqlcipher`), and encrypt raw content cache blocks (`content/blocks/` and `content/scratch/`) using a fast symmetric scheme like AES-GCM or ChaCha20-Poly1305. The encryption key should be derived from the OS Keyring.
+* **Active Bandwidth Throttling & Traffic Shaping (Horizon 1)**: Add speed governors for daemon uploads and downloads. Support configuration variables `max_upload_rate_kbps` and `max_download_rate_kbps` in `config.json` that can be dynamically adjusted over the Unix control socket.
+* **Interactive & Policy-Based Conflict Resolution (Horizon 1)**: Implement configurable conflict resolution policies (`rename-local`, `rename-remote`, `prefer-local`, `prefer-remote`, `interactive`). Add a "Conflicts" tab to the GUI to notify the user, block sync, and launch external visual diff tools (like Meld or KDiff3).
+* **Multi-Account / Multi-Profile Support (Horizon 3)**: Enable running multiple profiles concurrently. Support separate configuration namespaces (e.g. `profiles/<profile_name>/`), independent SQLite databases, distinct mount paths (e.g. `~/ProtonDrive/Personal` and `~/ProtonDrive/Work`), and multiple daemon processes.
+* **Custom FUSE Mount Options (Horizon 1)**: Expose custom mounting parameters in configuration (e.g. `ro` for read-only, `direct_io` to bypass kernel caching, `allow_other`). Auto-generate systemd user mount units upon sync folder configuration.
+* **Symbolic Link & Hard Link Virtualization (Horizon 2)**: Add symbolic link virtualization inside the metadata store (`NodeType::Symlink`) by intercepting `readlink(2)` and `symlink(2)`. Targets should sync remotely as small encrypted metadata placeholder files on Drive (`proton-vfs-symlink: <target>`).
+* **Desktop File Manager Integration (Horizon 2)**: Develop shell extension plugins for popular Linux file managers (Nautilus Python plugin, Dolphin Service Menus, Thunar custom actions) to offer context-menu shortcuts ("Pin", "Unpin", "Copy Share Link", "View Version History") and file overlay sync badges.
+* **Integrated Photo Gallery Enhancements (Horizon 2)**: Extract and display Exif metadata (camera model, exposure, coordinates) from photos locally, support creating and editing Proton Photo Albums, build a date-based timeline scrollbar, and create an auto-upload Pictures folder pipeline.
+* **Random-Access Media Streaming seek support (Horizon 2)**: Intercept out-of-order sparse reads (player seeks) in `pdfs-fuse` and prioritize downloading blocks around the seek offset, aborting/postponing sequential pre-fetches.
+* **Dynamic Sync Dashboard & Queue Visualization (Horizon 2)**: GUI real-time transfer list (progress bars, speed, ETA), sync history feed, storage usage breakdown, and global pause/resume sync controls.
+* **Interactive Terminal UI (TUI) Mode (Horizon 3)**: Implement `pdfs tui` using the `ratatui` crate to show transfer speed, sync status, active transfer queue with progress bars, and scrolling daemon logs.
+* **Shutdown Safety & Write Queue Visibility (Horizon 1 / P4)**: Register systemd inhibitor locks in `pdfs-fuse` when there are outstanding staging writes to prevent shutdown or sleep, pop up warnings when exiting the GUI, and build a blocking `pdfs sync flush` command.
+* **Block-Level Deduplication (Horizon 3)**: Transition to a Content-Addressable block cache where cached blocks are stored on disk by their SHA-256 hash. Map logical ranges in the database: `(node_uid, block_idx) -> block_hash` to avoid storing or downloading identical blocks.
+* **Pre-emptive Sync Debouncing & File System Events (Horizon 3)**: Group filesystem write events on paths and delay sync queue insertion until a quiet period has elapsed (e.g. 5 seconds of inactivity) to prevent thrashing the Proton API.
+* **File Version History (Horizon 2)**: Expose past file revisions and version history inside the GUI browser tabs.
+
+---
+
+## 2. Performance, Correctness & Robustness Items
+Derived from: [plan.md](file:///home/narl/dev/private/proton-drive-linux/plan.md), [improvements.md](file:///home/narl/dev/private/proton-drive-linux/improvements.md), & [photos-video-streaming.md](file:///home/narl/dev/private/proton-drive-linux/photos-video-streaming.md)
+
+* **B6. Debounce the LRU access touch**: Keep last-touch times in memory and flush them in batches (debounce window of 30-60 seconds) to avoid performing a SQLite `UPDATE` to the `cache_entries` table on every cache hit.
+* **E12. Client in-flight cap shape**: Address the lock discrepancy between `MAX_CONCURRENT_BLOCK_DOWNLOADS = 10` (per-file) and `DEFAULT_MAX_INFLIGHT_BLOCKS = 12` (global client-wide). Either raise the global cap, lower the per-file window, or dynamically calculate the window to prevent single files from starving concurrent transfers.
+* **Pipeline `enumerate_nodes_detail` (P2.8 / 8)**: Introduce pipelined node enumeration to speed up directory listings.
+* **Local ancestor-chain walk (P3.4 / 4)**: Optimize recursive path lookups where full batching is impossible.
+* **Name Search for Photos/Videos**: Add search by photo/video name (deferred from Phase 3 gallery implementation).
+* **Sequential-Read Prefetch for Media Streaming**: Implement sequential read prefetch for media files to avoid stalls when buffering.
+* **Minor sweep items (Phase F)**:
+  * **F1. `StreamRing.tags` Leak**: Clean up tag entries in `StreamRing.tags` when blocks are evicted. Currently, it only shrinks on `drop_node` (revision mismatch), leading to tag accumulation.
+  * **F2. Non-saturating bytes subtraction**: Use `saturating_sub` in `lib.rs:382` (`self.bytes -= dropped.len()`) to prevent release mode panics/wrapping if accounting drifts.
+  * **F3. Short block yields a short read / EOF**: Address the kernel EOF interpretation on short block reads. Either pad the block or fail loudly rather than silently serving short data.
+  * **F4. `stream_readahead` check-then-spawn race**: Prevent duplicate concurrent readahead tasks for the same block. Check-then-spawn is currently racey.
+  * **F5. `refresh_blocks` permit lock (SDK)**: Ensure URL refreshing (`refresh_blocks`) does not hold an in-flight block permit, preventing expired URLs from pinning client permits.
+  * **F6. Uncapped Unix control socket thread spawns**: Replace the unbounded `std::thread::spawn` per accepted socket connection in `run_control_socket` with a bounded pool or handler limits to prevent thread exhaustion.
+  * **F7. Document temporary cache file safety**: Add explanatory comment to `cache.rs:362` explaining why `with_extension("tmp")` is safe there but not in `store_thumbnail`.
+
+---
+
+## 3. Open & Unverified Bugs
+Derived from: [docs/bugs.md](file:///home/narl/dev/private/proton-drive-linux/docs/bugs.md)
+
+* **B2. Unattributed Trash Origin**: Investigate why deleted/moved files are occasionally sent to trash instead of vanishing on older rename operations.
+* **B10. GLib Critical Warning on HUD Close**: Assertion failure `g_list_store_remove: assertion '!g_sequence_iter_is_end (it)' failed` when prompt window closes during active launch (`xdg-open`). Needs investigation under `G_DEBUG=fatal-criticals`.
+* **B15. Empty-but-listed folders and duplicate UIDs**: Investigate folder-identity issues (e.g. duplicate remote folders like `Music` with different UIDs) and how folders obtain `listed = 1` in the database without matching child rows.
+* **B8 (CAPTCHA sign-in bridge)**: Verify a real gated sign-in using Webkit CAPTCHA completion.
+* **Draft Revision Upload loop**: Verify SDK-side deletion and retry logic when a conflicting draft revision exists under the same client UID.
+* **Optimistic Size Loss on Restart**: Verify that pending uploads retain their optimistic sizes across a daemon restart.
+
+---
+
+## 4. Testing, Verification & Disaster Recovery Drills
+Derived from: [testing.md](file:///home/narl/dev/private/proton-drive-linux/testing.md) & [docs/RECOVERY.md](file:///home/narl/dev/private/proton-drive-linux/docs/RECOVERY.md)
+
+* **IPC Memory and Performance Stress Tests (Phase 3)**: Verify memory allocations do not balloon when sending large `UploadPhoto` JSON payloads. Test control socket timeout behaviors under long-running block operations.
+* **Fault Injection and Resiliency Tests (Phase 4)**:
+  * **Network degradation**: Verify that interrupted uploads leave readable staging buffers and result in clean backoff retries.
+  * **Disk full (ENOSPC)**: Verify that write staging and gap-filling report correct errors to FUSE and preserve staged work.
+  * **Concurrent reader starvation**: Test that parallel sequential reads do not freeze directory lookups or metadata handlers.
+* **Disaster Recovery Drill (P5 / Phase 5)**: Execute a complete manual disaster recovery test:
+  1. Register a device.
+  2. Sync a folder and upload data.
+  3. Wipe the local state directory and SQLite cache.
+  4. Restart the daemon.
+  5. Run `pdfs sync restore` and assert the recovered filesystem matches the source byte-for-byte.
+
+---
+
+## 5. Fixed & Resolved Bugs
+Derived from: [docs/bugs.md](file:///home/narl/dev/private/proton-drive-linux/docs/bugs.md)
+
+### Completely Fixed & Verified
+* **B1 — FUSE rename loses the file (data loss)**: In `rename`, the node's database row was deleted while only updating the in-memory state, causing the file to vanish on next listing sync. Fixed by correctly calling `st.invalidate_listing(newparent)` to refresh SQLite cache states.
+* **B4 — `invalidate_listing` silently skipped non-resident folders**: Folders not loaded in memory were being skipped during listing invalidation, leaving stale cache flags in the DB. Fixed by removing the residency check guard.
+* **B5 — `ls -l` costs a network round trip per file (thumbnail xattr probes)**: File listings triggered blocking network checks for thumbnails on unsupported files. Fixed by caching negative thumbnail results and restricting xattr advertisement to supported image/media files.
+* **B6 — Daemon sets no file modes: `control.sock` is an unguarded authority**: The Unix control socket was created without restricting file permissions, exposing daemon controls to other local users. Fixed by applying proper creation permission masks.
+* **B7 — renamed directory reads as missing until the entry TTL expires**: Kernel cache maps remained stale after a FUSE directory re-anchor. Fixed by proactively sending entry invalidation notifications to the kernel.
+* **B9 — Enter did not open the selected result in the launcher**: Hooked up keyboard execution (Enter key) in `pdfs-prompt` search HUD to launch the selected item using `xdg-open`.
+* **B11 — a file moved while its create is still queued reads as empty**: Reconciling a local rename on a file that had not finished uploading yet uploaded empty blocks. Fixed by carrying over and staging the correct logical file size.
+* **B12 — cold enumeration is slow per entry, and goes superlinear past ~500**: S2K decryption and thumbnail resolution loops were serial. Fixed by parallelizing key derivations and caching metadata.
+* **B13 — `rename` over an existing destination fails instead of replacing it**: Fixed POSIX rename target overwrite behavior to replace existing destinations.
+* **B14 — provisional (ciphertext) sizes make rsync read short and abort the file**: Adjusted size reporting to align logical and ciphertext sizing, preventing premature EOF.
+
+### Code Fixed / Implemented (Pending Verification)
+* **B8 — no way to complete a CAPTCHA, so a gated sign-in is unrecoverable**: Implemented a Webkit-based bridge to prompt the user to resolve interactive CAPTCHAs during gated logins. (Needs verification on a real gate request).
+
+### Closed / Not a Bug
+* **B3 — Activity log timestamps written in seconds, read as milliseconds**: Closed as investigator error (timestamps are consistent).
+
+---
+
+## 6. Recently Implemented Features
+
+### Open-for-Write Deferral for Mirror Sync (Implemented)
+**File**: [`sync.rs`](file:///home/narl/dev/private/proton-drive-linux/crates/pdfs-fuse/src/sync.rs)
+
+The mirror folder sync engine now defers uploading any file that is currently held open for writing by another process, matching the guarantee the FUSE mount path already provides (where uploads are deferred until `close(fd)`).
+
+**Problem**: Previously, the mirror sync path relied solely on a 2-second trailing-edge debounce (with a 30-second ceiling) to avoid uploading files mid-write. This was insufficient for slow continuous writers (e.g., database dumps, large exports, or editors that keep files open for extended periods), which could have their incomplete state uploaded as a real revision.
+
+**Solution**: Before each reconcile pass, the sync engine scans `/proc/*/fd` once to build a set of canonical paths within the sync root that any process holds open for writing (`O_WRONLY` or `O_RDWR`). Files in this set are:
+
+- **Kept in the local walk** — so they are not misclassified as deletions
+- **Treated as unchanged** — so no upload is queued for them
+- **Counted as `deferred`** — so the activity summary reports them (e.g., "3 uploaded, 1 deferred (open for write)")
+- **Picked up on the next pass** — after the writer has closed the file
+
+**How it works**:
+1. `open_for_write_set(root)` reads `/proc/*/fd` → `readlink` for each fd → prefix-checks against the sync root → reads `/proc/<pid>/fdinfo/<n>` to check the `flags:` line's low two bits (O_ACCMODE)
+2. `walk_local` sets `LocalItem.open_for_write = true` for matching files
+3. Both `do_reconcile` and `push_pass` skip upload classification for flagged files
+4. `Outcome.deferred` tracks the count for the activity summary
+
+**Performance**: The `/proc` scan completes in low single-digit milliseconds on a typical desktop. Only fds whose `readlink` target falls under the sync root incur the `fdinfo` read.
+
+**Tests added**: 8 unit tests covering `is_write_mode` parsing of various fdinfo flag combinations, and `Outcome` summary formatting with deferred counts.
+
+| Sync Path | Open-for-write protection | Mechanism |
+|---|---|---|
+| FUSE mount | ✅ Perfect | Upload deferred until `close(fd)` |
+| Mirror folders | ✅ Perfect | `/proc/*/fd` scan per reconcile pass |
+

docs/TESTING.md

@@ -0,0 +1,55 @@
+# Testing
+
+The normal Rust suite exercises the metadata database, sync planner, offline
+queue, write staging, cache, and FUSE handler state without requiring a Proton
+account:
+
+```console
+cargo test --workspace
+cargo clippy --workspace --all-targets -- -D warnings
+```
+
+## Live FUSE acceptance suite
+
+Kernel behavior and remote convergence need a real mount. The live suite runs
+destructive POSIX operations only below a fresh `pdfs-acceptance-*` directory.
+It refuses paths that are not FUSE mounts and removes its directory on success,
+failure, or interruption.
+
+Use a dedicated test account without irreplaceable data:
+
+```console
+scripts/fuse-acceptance.sh /mnt/on-demand-testmount
+```
+
+Passing more paths runs the same filesystem suite independently against each.
+The first path must be the FUSE mount under test; later paths may be another
+FUSE mount or a normal local mirror filesystem:
+
+```console
+PDFS_ACCEPTANCE_SYNC_TIMEOUT=180 \
+  scripts/fuse-acceptance.sh /mnt/on-demand-testmount /mnt/testmount
+```
+
+If two paths really are views of the **same remote folder**, enable an
+additional byte-for-byte convergence check explicitly:
+
+```console
+PDFS_ACCEPTANCE_CONVERGENCE=1 \
+  scripts/fuse-acceptance.sh /mnt/first-view /mnt/second-view
+```
+
+Do not enable that flag merely because two sync folders belong to the same
+account. Their configured remote UIDs must be identical.
+
+The suite covers create/read/rewrite/truncate, multi-megabyte binary content,
+unaligned random writes, rename replacement, cross-directory moves, important
+POSIX error cases, open-then-unlink behavior, concurrent writers, directory
+enumeration, and optional cross-mount byte-for-byte convergence. A pass is
+strong evidence for those paths, not a blanket data-loss guarantee. Before a
+release, also run the recovery drills in `docs/RECOVERY.md` and inspect
+`docs/BUGS.md` for live-verification items.
+
+The runner accepts already-mounted paths instead of starting a daemon. This
+keeps authentication and keyring setup explicit and prevents it from silently
+reusing or replacing the normal application state directory.

packaging/PKGBUILD

@@ -9,7 +9,7 @@
 # Build + install:   cd packaging && makepkg -fi
 
 pkgname=proton-drive-linux
-pkgver=0.7.0
+pkgver=0.7.1
 pkgrel=1
 pkgdesc="Proton Drive client for Linux: FUSE files-on-demand mount, CLI, GTK4 app + tray"
 arch=('x86_64')

scripts/fuse-acceptance.sh

@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+# Destructive only inside a uniquely named directory created by this script.
+set -Eeuo pipefail
+
+usage() {
+    echo "usage: $0 MOUNTPOINT [MOUNTPOINT ...]" >&2
+    echo "example: $0 /mnt/on-demand-testmount /mnt/testmount" >&2
+    exit 2
+}
+
+(( $# > 0 )) || usage
+command -v python3 >/dev/null || { echo "python3 is required" >&2; exit 2; }
+command -v findmnt >/dev/null || { echo "findmnt is required" >&2; exit 2; }
+
+mounts=("$@")
+run_id="pdfs-acceptance-$(date +%Y%m%dT%H%M%S)-$$"
+roots=()
+
+cleanup() {
+    local root
+    for root in "${roots[@]}"; do
+        [[ -n "$root" && "$root" == */pdfs-acceptance-* ]] || continue
+        rm -rf -- "$root" 2>/dev/null || true
+    done
+}
+trap cleanup EXIT INT TERM
+
+for index in "${!mounts[@]}"; do
+    mountpoint="${mounts[$index]}"
+    [[ -d "$mountpoint" ]] || { echo "not a directory: $mountpoint" >&2; exit 2; }
+    fs_type="$(findmnt -T "$mountpoint" -n -o FSTYPE | head -n 1)"
+    if (( index == 0 )) && [[ "$fs_type" != fuse* ]]; then
+        echo "refusing primary non-FUSE path $mountpoint (type: ${fs_type:-unknown})" >&2
+        exit 2
+    fi
+    roots+=("${mountpoint%/}/$run_id")
+done
+
+step() { printf '[test] %s\n' "$1"; }
+assert_text() {
+    python3 - "$1" "$2" <<'PY'
+import sys
+p, expected = sys.argv[1], sys.argv[2].encode()
+with open(p, "rb") as f: got = f.read()
+if got != expected:
+    raise AssertionError(
+        f"{p}: expected {expected!r} ({len(expected)} bytes), "
+        f"got {got!r} ({len(got)} bytes)"
+    )
+PY
+}
+
+run_suite() {
+local primary="$1"
+printf '[mount] testing %s\n' "${primary%/*}"
+mkdir -- "$primary"
+
+step "create, read, overwrite, truncate"
+printf 'alpha\n' > "$primary/plain.txt"
+assert_text "$primary/plain.txt" $'alpha\n'
+printf 'a much longer replacement\n' > "$primary/plain.txt"
+truncate -s 4 "$primary/plain.txt"
+assert_text "$primary/plain.txt" "a mu"
+
+step "binary round-trip and random-access writes"
+python3 - "$primary/binary.dat" <<'PY'
+import hashlib, sys
+p = sys.argv[1]
+data = bytes(range(256)) * 16384
+with open(p, "wb") as f: f.write(data)
+with open(p, "r+b", buffering=0) as f:
+    f.seek(4093); f.write(b"boundary-write")
+with open(p, "rb") as f: got = f.read()
+expected = data[:4093] + b"boundary-write" + data[4107:]
+assert got == expected
+print(hashlib.sha256(got).hexdigest())
+PY
+
+step "rename, move, and replacement semantics"
+mkdir -- "$primary/dir-a" "$primary/dir-b"
+printf 'source' > "$primary/source"
+printf 'victim' > "$primary/victim"
+mv -- "$primary/source" "$primary/victim"
+assert_text "$primary/victim" "source"
+[[ ! -e "$primary/source" ]]
+mv -- "$primary/victim" "$primary/dir-a/moved"
+assert_text "$primary/dir-a/moved" "source"
+
+step "POSIX error behavior"
+if rmdir -- "$primary/dir-a/moved" 2>/dev/null; then echo "rmdir removed a file" >&2; exit 1; fi
+if rm -- "$primary/dir-a" 2>/dev/null; then echo "rm removed a directory" >&2; exit 1; fi
+if mv -- "$primary/dir-a" "$primary/dir-a/child" 2>/dev/null; then
+    echo "moving a directory below itself succeeded" >&2; exit 1
+fi
+
+step "open file remains readable after unlink"
+python3 - "$primary/open-unlink" <<'PY'
+import os, sys
+p = sys.argv[1]; data = b"held-open\0" * 4096
+with open(p, "wb") as f: f.write(data)
+f = open(p, "rb", buffering=0); os.unlink(p)
+assert not os.path.exists(p) and f.read() == data
+f.close()
+PY
+
+step "concurrent independent writers"
+for i in $(seq 1 12); do
+    (python3 - "$primary/concurrent-$i" "$i" <<'PY'
+import sys
+p, seed = sys.argv[1], int(sys.argv[2]); data = bytes([seed]) * (131072 + seed)
+with open(p, "wb") as f: f.write(data)
+with open(p, "rb") as f: assert f.read() == data
+PY
+    ) &
+done
+wait
+
+step "directory enumeration agrees with stat"
+python3 - "$primary" <<'PY'
+import os, sys
+for name in os.listdir(sys.argv[1]): os.lstat(os.path.join(sys.argv[1], name))
+PY
+}
+
+for root in "${roots[@]}"; do
+    run_suite "$root"
+done
+
+if [[ "${PDFS_ACCEPTANCE_CONVERGENCE:-0}" == 1 ]] && (( ${#roots[@]} > 1 )); then
+    step "cross-mount convergence"
+    primary="${roots[0]}"
+    expected="$(sha256sum "$primary/binary.dat" | cut -d' ' -f1)"
+    for secondary in "${roots[@]:1}"; do
+        deadline=$((SECONDS + ${PDFS_ACCEPTANCE_SYNC_TIMEOUT:-120}))
+        while (( SECONDS < deadline )); do
+            if [[ -f "$secondary/binary.dat" ]] &&
+               [[ "$(sha256sum "$secondary/binary.dat" 2>/dev/null | cut -d' ' -f1)" == "$expected" ]]; then break; fi
+            sleep 2
+        done
+        [[ -f "$secondary/binary.dat" ]] || { echo "did not appear on $secondary" >&2; exit 1; }
+        [[ "$(sha256sum "$secondary/binary.dat" | cut -d' ' -f1)" == "$expected" ]] || {
+            echo "content mismatch on $secondary" >&2; exit 1
+        }
+    done
+fi
+
+step "cleanup"
+cleanup
+roots=()
+echo "PASS: FUSE acceptance suite completed ($run_id)"