feat(core,fuse,cli,gui): report changes Drive refuses as sync issues

A change Drive refuses because the storage is full, access was taken away,
its folder is gone, a folder limit is reached or the change was rejected
used to look like any other failure until six attempts had passed. The
drain now sorts the refusal into an issue and stores it on the queued op
(schema 38), so it needs attention at once in the app, tray and CLI. The
change stays queued and is retried; nothing is deleted.

The queue listing carries the issue and whether the op has file content.
ExportPendingOp copies that content to a new file: the Sync page offers it
as an Export button next to each issue, and the CLI as
`pdfs sync export <id> <dest>`. `pdfs sync issues` lists what needs
attention, and `pdfs sync queue` shows the issue per change.

docs/MILESTONE-3.0.0-STATUS.md tracks what is left for 3.0.0.

crates/pdfs-cli/src/main.rs

@@ -14,7 +14,7 @@ use pdfs_core::cache::ContentCache;
 use pdfs_core::config::AppDirs;
 use pdfs_core::control::{
     ConflictKeep, ErrorKind, MountKind, RefreshScope, Request as CtlRequest,
-    Response as CtlResponse, RestoreItem as CtlRestoreItem, ShareEntryKind, SyncPhase,
+    Response as CtlResponse, RestoreItem as CtlRestoreItem, ShareEntryKind, SyncIssue, SyncPhase,
     pending_summary,
 };
 use pdfs_core::db::Db;
@@ -677,6 +677,15 @@ enum SyncCmd {
     },
     /// List uploads and changes not yet on Proton Drive.
     Queue,
+    /// List queued changes Proton Drive refused or that keep failing, and what to do.
+    Issues,
+    /// Save the content of a queued upload (by id from `sync queue`) to a file.
+    Export {
+        /// Queue id.
+        id: i64,
+        /// Where to save it: a new file, or an existing folder to save it in.
+        dest: PathBuf,
+    },
     /// Retry a queued operation now (by id from `sync queue`), or every failed one.
     Retry {
         /// Queue id; omit to retry every failed operation.
@@ -1028,6 +1037,8 @@ fn cmd_sync(action: SyncCmd) -> Result<()> {
             })?)?
         }
         SyncCmd::Queue => return cmd_sync_queue(),
+        SyncCmd::Issues => return cmd_sync_issues(),
+        SyncCmd::Export { id, dest } => return cmd_sync_export(id, &dest),
         SyncCmd::Limit { up, down } => return cmd_sync_limit(up, down),
         SyncCmd::Retry { id } => ok_or_bail(control_request(CtlRequest::RetryPendingOp { id })?)?,
         SyncCmd::Resume { folder: None } => {
@@ -1106,6 +1117,9 @@ fn cmd_sync_queue() -> Result<()> {
                     (false, _) => "due now".to_string(),
                 };
                 println!("[{}]  {}  {}  ({state})", op.id, op.kind, op.path);
+                if let Some(issue) = op.issue {
+                    println!("      needs attention: {}", issue_text(issue));
+                }
                 if let Some(error) = &op.last_error {
                     println!("      failed {} time(s): {error}", op.attempts);
                 }
@@ -1117,6 +1131,91 @@ fn cmd_sync_queue() -> Result<()> {
     Ok(())
 }
 
+/// `pdfs sync issues`: the queued changes that need the user, and what to do.
+fn cmd_sync_issues() -> Result<()> {
+    let response = control_request(CtlRequest::ListPendingOps)?;
+    let items = match response {
+        CtlResponse::PendingOps { items } => items,
+        CtlResponse::Error { message, kind } => bail!("{}", cli_error(kind, &message)),
+        other => bail!("unexpected response: {other:?}"),
+    };
+    let issues: Vec<_> = items.into_iter().filter(|op| op.failing).collect();
+    if json_enabled() {
+        println!("{}", serde_json::to_string_pretty(&issues)?);
+        return Ok(());
+    }
+    if issues.is_empty() {
+        println!("No sync issues.");
+        return Ok(());
+    }
+    for op in issues {
+        println!("[{}]  {}  {}", op.id, op.kind, op.path);
+        match op.issue {
+            Some(issue) => println!("      {}", issue_text(issue)),
+            None => println!("      keeps failing; it is retried."),
+        }
+        if let Some(error) = &op.last_error {
+            println!("      last error: {error}");
+        }
+        if op.exportable {
+            println!(
+                "      save a copy: pdfs sync export {} <file or folder>",
+                op.id
+            );
+        }
+    }
+    Ok(())
+}
+
+/// What a sync issue means, and what the user can do about it.
+fn issue_text(issue: SyncIssue) -> &'static str {
+    match issue {
+        SyncIssue::Quota => {
+            "Proton Drive storage is full. Free up space or upgrade; the change is retried."
+        }
+        SyncIssue::Access => {
+            "you can no longer change this on Proton Drive, for example because a share was \
+             revoked. Save a copy to keep the content."
+        }
+        SyncIssue::Missing => {
+            "the file or its folder is gone from Proton Drive. Save a copy to keep the content."
+        }
+        SyncIssue::Limit => {
+            "the folder holds too many items or is nested too deep. Move the file to another \
+             folder."
+        }
+        SyncIssue::Rejected => {
+            "Proton Drive rejected the change, for example the name. Rename the file."
+        }
+        SyncIssue::Unknown => "Proton Drive refused the change.",
+    }
+}
+
+/// `pdfs sync export`: save a queued upload's content. A folder as `dest`
+/// gets the file under its own name.
+fn cmd_sync_export(id: i64, dest: &Path) -> Result<()> {
+    let mut dest =
+        std::path::absolute(dest).with_context(|| format!("resolving {}", dest.display()))?;
+    if dest.is_dir() {
+        let items = match control_request(CtlRequest::ListPendingOps)? {
+            CtlResponse::PendingOps { items } => items,
+            CtlResponse::Error { message, kind } => bail!("{}", cli_error(kind, &message)),
+            other => bail!("unexpected response: {other:?}"),
+        };
+        let Some(op) = items.iter().find(|op| op.id == id) else {
+            bail!("no queued change {id}; see `pdfs sync queue`");
+        };
+        let name = Path::new(&op.path)
+            .file_name()
+            .with_context(|| format!("{} has no file name", op.path))?;
+        dest.push(name);
+    }
+    ok_or_bail(control_request(CtlRequest::ExportPendingOp {
+        id,
+        dest: dest.display().to_string(),
+    })?)
+}
+
 /// `pdfs sync restore`: list what this machine's device holds, confirm where
 /// each folder should land, then hand the mapping to the daemon.
 ///

crates/pdfs-core/src/control.rs

@@ -477,6 +477,10 @@ pub enum Request {
     /// Retry a backed-off queued op now instead of waiting out its backoff;
     /// every failed op when `id` is `None`. Replies with [`Response::Ok`].
     RetryPendingOp { id: Option<i64> },
+    /// Copy the content of a queued upload (`id` from
+    /// [`Request::ListPendingOps`]) to `dest`, an absolute path that must not
+    /// exist yet. The op stays queued. Replies with [`Response::Ok`].
+    ExportPendingOp { id: i64, dest: String },
     /// List the `(sync-conflict …)` copies under My Files and in synced
     /// folders. Replies with
     /// [`Response::Conflicts`].
@@ -880,6 +884,59 @@ pub struct PendingOpInfo {
     pub parked: bool,
     /// Failed often enough to count as stuck.
     pub failing: bool,
+    /// Why Drive refused it, when it did; such an op needs attention at once.
+    #[serde(default)]
+    pub issue: Option<SyncIssue>,
+    /// Carries file content that [`Request::ExportPendingOp`] can save.
+    #[serde(default)]
+    pub exportable: bool,
+}
+
+/// Why Drive refused a queued change (in [`PendingOpInfo`]). The change stays
+/// queued and keeps being retried; nothing is deleted.
+#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum SyncIssue {
+    /// The account's storage is full.
+    Quota,
+    /// The account may no longer change the file or its folder, for example
+    /// because a share was revoked.
+    Access,
+    /// The file or the folder it goes into is gone from Drive.
+    Missing,
+    /// The folder holds too many items, or is nested too deep.
+    Limit,
+    /// Drive rejected the change, for example a name it does not accept.
+    Rejected,
+    /// An issue from a newer daemon.
+    #[serde(other)]
+    Unknown,
+}
+
+impl SyncIssue {
+    /// The name stored in the database and sent on the wire.
+    pub fn as_str(self) -> &'static str {
+        match self {
+            SyncIssue::Quota => "quota",
+            SyncIssue::Access => "access",
+            SyncIssue::Missing => "missing",
+            SyncIssue::Limit => "limit",
+            SyncIssue::Rejected => "rejected",
+            SyncIssue::Unknown => "unknown",
+        }
+    }
+
+    /// The issue stored as `name`.
+    pub fn parse(name: &str) -> Self {
+        match name {
+            "quota" => SyncIssue::Quota,
+            "access" => SyncIssue::Access,
+            "missing" => SyncIssue::Missing,
+            "limit" => SyncIssue::Limit,
+            "rejected" => SyncIssue::Rejected,
+            _ => SyncIssue::Unknown,
+        }
+    }
 }
 
 /// One synced local folder on this machine's device (in [`Response::SyncFolders`]).
@@ -3290,6 +3347,13 @@ mod tests {
                 },
                 r#"{"SaveRevisionAsByUid":{"uid":"vol~link","revision_id":"rev-3","dest":"/tmp/out.bin"}}"#,
             ),
+            (
+                Request::ExportPendingOp {
+                    id: 7,
+                    dest: "/tmp/out.bin".into(),
+                },
+                r#"{"ExportPendingOp":{"id":7,"dest":"/tmp/out.bin"}}"#,
+            ),
         ];
         for (request, wire) in cases {
             assert_eq!(serde_json::to_string(&request).unwrap(), wire);
@@ -3298,6 +3362,25 @@ mod tests {
         }
     }
 
+    /// A daemon that predates sync issues sends neither field, and a newer one
+    /// may send an issue this build does not know.
+    #[test]
+    fn a_queued_op_from_another_daemon_version_still_decodes() {
+        let old = r#"{"id":1,"kind":"create","path":"a.txt","attempts":0,"last_error":null,
+            "queued_at":5,"next_attempt_at":5,"parked":false,"failing":false}"#;
+        let op: PendingOpInfo = serde_json::from_str(old).unwrap();
+        assert_eq!(op.issue, None);
+        assert!(!op.exportable);
+
+        let newer = old.replace(r#""failing":false"#, r#""failing":true,"issue":"embargo""#);
+        let op: PendingOpInfo = serde_json::from_str(&newer).unwrap();
+        assert_eq!(op.issue, Some(SyncIssue::Unknown));
+        assert_eq!(
+            SyncIssue::parse(SyncIssue::Quota.as_str()),
+            SyncIssue::Quota
+        );
+    }
+
     /// A front-end that predates the favorites filter sends no `favorites`
     /// field, and must keep getting the whole timeline rather than an empty page.
     #[test]

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

@@ -11,7 +11,7 @@ use super::Db;
 use crate::Result;
 
 /// Current schema version. Bump on every forward migration added below.
-pub(super) const SCHEMA_VERSION: i64 = 37;
+pub(super) const SCHEMA_VERSION: i64 = 38;
 
 impl Db {
     pub(super) fn migrate(&self) -> Result<()> {
@@ -363,6 +363,22 @@ impl Db {
                 tx.execute_batch(MIGRATION_V37)?;
             }
         }
+        if current < 38 {
+            // Same guards as V26-V37.
+            let has_column: bool = tx.query_row(
+                "SELECT COUNT(*) FROM pragma_table_info('pending_op') WHERE name = 'issue'",
+                [],
+                |row| row.get::<_, i64>(0),
+            )? > 0;
+            let has_ops: bool = tx.query_row(
+                "SELECT COUNT(*) FROM sqlite_master WHERE type = 'table' AND name = 'pending_op'",
+                [],
+                |row| row.get::<_, i64>(0),
+            )? > 0;
+            if has_ops && !has_column {
+                tx.execute_batch(MIGRATION_V38)?;
+            }
+        }
         tx.execute(
             "INSERT INTO sync_state (key, value) VALUES ('schema_version', ?1)
              ON CONFLICT(key) DO UPDATE SET value = excluded.value",
@@ -1164,3 +1180,9 @@ CREATE INDEX pending_op_parent ON pending_op(parent_uid);
 CREATE INDEX idx_pending_op_claimed
     ON pending_op(uid) WHERE claimed_at <> 0;
 ";
+
+/// Schema v38: why Drive refused a queued op, when it did (a sync issue).
+/// `NULL` for an op that has not been refused, which is every op migrated.
+const MIGRATION_V38: &str = "
+ALTER TABLE pending_op ADD COLUMN issue TEXT;
+";

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

@@ -2,6 +2,8 @@
 //! the remote has not yet seen. Rebuilt into memory on mount and drained in row
 //! order, so a child never drains before the parent that gives it a real uid.
 
+use std::collections::HashMap;
+
 use rusqlite::{OptionalExtension, params};
 use serde::{Deserialize, Serialize};
 
@@ -257,7 +259,8 @@ pub struct PendingCounts {
     /// never drain on their own, so counting them as "waiting to upload" would
     /// have the front-end promise progress that is not coming.
     pub parked: i64,
-    /// Ops that have failed at least [`FAILING_ATTEMPTS`] times. A permanently
+    /// Ops that have failed at least [`FAILING_ATTEMPTS`] times, or that Drive
+    /// refused ([`Db::set_op_issue`]). A permanently
     /// failing op never wedges the queue — the backoff sees to that — which is
     /// exactly why it needs surfacing: it retries forever, invisibly.
     pub failing: i64,
@@ -1028,15 +1031,15 @@ impl Db {
             |r| r.get(0),
         )?;
         let failing = conn.query_row(
-            "SELECT COUNT(*) FROM pending_op WHERE attempts >= ?1",
+            "SELECT COUNT(*) FROM pending_op WHERE attempts >= ?1 OR issue IS NOT NULL",
             params![FAILING_ATTEMPTS],
             |r| r.get(0),
         )?;
         let last_error = conn
             .query_row(
                 "SELECT last_error FROM pending_op
-                  WHERE attempts >= ?1 AND last_error IS NOT NULL
-                  ORDER BY attempts DESC LIMIT 1",
+                  WHERE (attempts >= ?1 OR issue IS NOT NULL) AND last_error IS NOT NULL
+                  ORDER BY issue IS NULL, attempts DESC LIMIT 1",
                 params![FAILING_ATTEMPTS],
                 |r| r.get::<_, Option<String>>(0),
             )
@@ -1132,6 +1135,26 @@ impl Db {
         Ok(())
     }
 
+    /// Record why Drive refused op `id`, or that the latest failure was not a
+    /// refusal (`None`). An op with an issue counts as failing at once.
+    pub fn set_op_issue(&self, id: i64, issue: Option<&str>) -> Result<()> {
+        self.conn.lock().execute(
+            "UPDATE pending_op SET issue = ?2 WHERE id = ?1",
+            params![id, issue],
+        )?;
+        Ok(())
+    }
+
+    /// The issue of every op Drive refused, by op id.
+    pub fn op_issues(&self) -> Result<HashMap<i64, String>> {
+        let conn = self.read();
+        let mut stmt = conn.prepare("SELECT id, issue FROM pending_op WHERE issue IS NOT NULL")?;
+        let rows = stmt
+            .query_map([], |r| Ok((r.get(0)?, r.get(1)?)))?
+            .collect::<rusqlite::Result<_>>()?;
+        Ok(rows)
+    }
+
     /// Make a create due again if it was renamed or moved
     /// ([`Db::rewrite_op_target`]) while the attempt that just failed was on
     /// the wire, `parent_uid` and `name` being what that attempt sent. What it

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

@@ -6138,6 +6138,33 @@ fn retry_now_makes_a_backed_off_op_due_but_leaves_parked_ops_parked() {
     assert_eq!(due(parked), ops::PARK_UNTIL);
 }
 
+/// A change Drive refused needs the user now, not after six more failures, and
+/// its refusal is the error the status leads with.
+#[test]
+fn an_op_with_an_issue_counts_as_failing_at_once() {
+    let db = Db::open_in_memory().unwrap();
+    queued_op(&db, "vol~a", 1, 90_000);
+    let refused = queued_op(&db, "vol~b", 1, 90_000);
+    assert_eq!(db.pending_op_counts().unwrap().failing, 0);
+
+    db.record_op_failure(refused, "storage quota exceeded", 90_000)
+        .unwrap();
+    db.set_op_issue(refused, Some("quota")).unwrap();
+    let counts = db.pending_op_counts().unwrap();
+    assert_eq!(counts.failing, 1);
+    assert_eq!(counts.last_error.as_deref(), Some("storage quota exceeded"));
+    assert_eq!(
+        db.op_issues().unwrap(),
+        std::collections::HashMap::from([(refused, "quota".to_string())])
+    );
+
+    // The op stays queued with its bytes; clearing the issue is all it takes.
+    db.set_op_issue(refused, None).unwrap();
+    assert_eq!(db.pending_op_counts().unwrap().failing, 0);
+    assert!(db.op_issues().unwrap().is_empty());
+    assert_eq!(db.pending_ops().unwrap().len(), 2);
+}
+
 #[test]
 fn retry_all_touches_only_ops_that_have_failed() {
     let db = Db::open_in_memory().unwrap();

crates/pdfs-fuse/src/control.rs

@@ -1404,6 +1404,14 @@ fn handle_control_conn(core: &Core, username: &str, mountpoint: &Path, stream: U
             Ok(items) => CtlResponse::PendingOps { items },
             Err(e) => CtlResponse::error(e),
         },
+        Ok(CtlRequest::ExportPendingOp { id, dest }) => {
+            match core.export_pending_op(id, Path::new(&dest)) {
+                Ok(written) => CtlResponse::Ok {
+                    message: format!("wrote {} to {dest}", human_bytes(written)),
+                },
+                Err(e) => CtlResponse::error(e),
+            }
+        }
         Ok(CtlRequest::RetryPendingOp { id }) => match core.retry_pending_ops(id) {
             Ok(0) if id.is_some() => CtlResponse::Ok {
                 message: "nothing to retry: the operation is already due or waiting for a rename"

crates/pdfs-fuse/src/drain.rs

@@ -31,7 +31,7 @@ use parking_lot::Mutex;
 
 use pdfs_core::batch;
 use pdfs_core::cache::{Baseline, StagedWrite};
-use pdfs_core::control::{ActivityKind, TransferDirection};
+use pdfs_core::control::{ActivityKind, SyncIssue, TransferDirection};
 use pdfs_core::db::{
     CreateLanding, CreateRetired, OP_CREATE, OP_MKDIR, OP_RENAME, OP_REVISION, OP_TRASH,
     PARK_EXPIRY_MS, PendingOp, RenameMeta,
@@ -40,6 +40,7 @@ use proton_drive_rs::proton_sdk::ids::NodeUid;
 use proton_drive_rs::{Node, NodeKind};
 use tracing::{debug, error, info, warn};
 
+use super::link::is_network_error;
 use super::state::{Intervals, PendingRevision};
 use super::transfers::CountingReader;
 use super::{
@@ -48,6 +49,8 @@ use super::{
     is_already_exists, is_gone, is_local_uid_str, media_type_for, node_revision_id, node_size,
     now_millis, now_secs, parse_node_uid,
 };
+use proton_drive_rs::proton_sdk::api::ResponseCode;
+use proton_drive_rs::proton_sdk::error::ProtonError;
 
 const DRAIN_ACCESS_RECHECK: Duration = Duration::from_secs(5);
 
@@ -383,6 +386,11 @@ impl Core {
                     self.wait_for_drain_work();
                     continue;
                 }
+                // A failure to reach Drive says nothing about an earlier refusal,
+                // so it keeps the issue that refusal recorded.
+                if let Some(issue) = refusal(e.as_ref()) {
+                    self.record_issue(&op, issue);
+                }
                 match self.db.retry_if_retargeted(
                     op.id,
                     op.parent_uid.as_deref(),
@@ -464,6 +472,9 @@ impl Core {
             {
                 error!(uid = %op.uid, %error, "recording an access-deferral failure failed");
             }
+            if reason != AccessDeferral::RemoteUnreachable {
+                self.record_issue(op, Some(SyncIssue::Access));
+            }
         } else {
             debug!(
                 uid = %op.uid,
@@ -525,6 +536,7 @@ impl Core {
                 ) {
                     error!(uid = %op.uid, %error, "recording a missing-authority failure failed");
                 }
+                self.record_issue(op, Some(SyncIssue::Missing));
                 self.release_claim(op);
             }
             Err(error) => {
@@ -535,6 +547,13 @@ impl Core {
         }
     }
 
+    /// Store why Drive refused `op`, or that its latest failure was no refusal.
+    fn record_issue(&self, op: &PendingOp, issue: Option<SyncIssue>) {
+        if let Err(error) = self.db.set_op_issue(op.id, issue.map(SyncIssue::as_str)) {
+            error!(uid = %op.uid, %error, "recording a sync issue failed");
+        }
+    }
+
     /// Hand a claimed op back to the queue, logging rather than propagating —
     /// there is no caller left to propagate to, and the drain must not stop.
     fn release_claim(&self, op: &PendingOp) {
@@ -2217,6 +2236,30 @@ fn moved_elsewhere(meta: &RenameMeta, node: &Node, parent: &NodeUid, name: &str)
     !at(&meta.original_parent_uid, original_name) && !at(&parent.to_string(), name)
 }
 
+/// What a failed attempt says about its op's sync issue: `None` when Drive
+/// could not be reached, which says nothing; otherwise the issue Drive's answer
+/// is, or `Some(None)` for a failure that is not a refusal.
+fn refusal(e: &(dyn std::error::Error + 'static)) -> Option<Option<SyncIssue>> {
+    let proton = std::iter::successors(Some(e), |e| e.source())
+        .find_map(|e| e.downcast_ref::<ProtonError>())?;
+    if is_network_error(proton) {
+        return None;
+    }
+    let ProtonError::Api(api) = proton else {
+        return Some(None);
+    };
+    Some(match api.code {
+        ResponseCode::InsufficientQuota
+        | ResponseCode::InsufficientSpace
+        | ResponseCode::InsufficientVolumeQuota => Some(SyncIssue::Quota),
+        ResponseCode::Forbidden | ResponseCode::NotEnoughPermissions => Some(SyncIssue::Access),
+        ResponseCode::DoesNotExist => Some(SyncIssue::Missing),
+        ResponseCode::TooManyChildren | ResponseCode::NestingTooDeep => Some(SyncIssue::Limit),
+        ResponseCode::InvalidValue | ResponseCode::IncompatibleState => Some(SyncIssue::Rejected),
+        _ => None,
+    })
+}
+
 /// What the park sweep does with one parked create.
 #[derive(Debug, PartialEq, Eq)]
 enum ParkVerdict {
@@ -2348,6 +2391,57 @@ mod tests {
     /// A transient create is queued a moment before its node is written. A
     /// sweep in between dropped it, and the rename to the finished name then
     /// failed with `EBUSY` (B145).
+    #[test]
+    fn a_refusal_from_drive_is_sorted_into_an_issue_and_the_network_is_not() {
+        use proton_drive_rs::proton_sdk::error::ProtonApiError;
+        let api = |code, http_status| {
+            ProtonError::Api(ProtonApiError {
+                code,
+                http_status,
+                message: String::new(),
+                details: None,
+            })
+        };
+        let issue = |e: ProtonError| refusal(&e);
+        assert_eq!(
+            issue(api(ResponseCode::InsufficientQuota, 422)),
+            Some(Some(SyncIssue::Quota))
+        );
+        assert_eq!(
+            issue(api(ResponseCode::NotEnoughPermissions, 403)),
+            Some(Some(SyncIssue::Access))
+        );
+        assert_eq!(
+            issue(api(ResponseCode::DoesNotExist, 404)),
+            Some(Some(SyncIssue::Missing))
+        );
+        assert_eq!(
+            issue(api(ResponseCode::TooManyChildren, 422)),
+            Some(Some(SyncIssue::Limit))
+        );
+        // A refusal nobody sorted clears an earlier issue; the network keeps it.
+        assert_eq!(issue(api(ResponseCode::AlreadyExists, 422)), Some(None));
+        assert_eq!(issue(api(ResponseCode::RequestTimeout, 408)), None);
+        // An error that is no refusal from Drive at all is no issue either.
+        assert_eq!(refusal(&std::io::Error::other("disk")), None);
+
+        // The drain sees Drive's error wrapped by whatever called it.
+        #[derive(Debug)]
+        struct Wrapped(ProtonError);
+        impl std::fmt::Display for Wrapped {
+            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+                f.write_str("uploading")
+            }
+        }
+        impl std::error::Error for Wrapped {
+            fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+                Some(&self.0)
+            }
+        }
+        let wrapped = Wrapped(api(ResponseCode::InsufficientSpace, 422));
+        assert_eq!(refusal(&wrapped), Some(Some(SyncIssue::Quota)));
+    }
+
     #[test]
     fn a_parked_create_is_dropped_only_once_its_file_is_gone_and_closed() {
         let now = PARK_EXPIRY_MS * 10;

crates/pdfs-fuse/src/queue.rs

@@ -1,12 +1,14 @@
 //! The user's view of the pending-op queue: what has not reached the remote
 //! yet, why, and a way to stop waiting out a backoff.
 //!
-//! Read-only apart from "retry now", which only moves a row's next-attempt time.
-//! Nothing here drops a queued op: its staged blob is the only copy of the
-//! user's write (see `docs/RECOVERY.md`).
+//! Read-only apart from "retry now", which only moves a row's next-attempt time,
+//! and "export", which copies a staged blob out. Nothing here drops a queued op:
+//! its staged blob is the only copy of the user's write (see `docs/RECOVERY.md`).
 
 use super::*;
-use pdfs_core::control::PendingOpInfo;
+use std::io::Write;
+
+use pdfs_core::control::{PendingOpInfo, SyncIssue};
 use pdfs_core::db::{FAILING_ATTEMPTS, PARK_UNTIL};
 
 impl Core {
@@ -16,10 +18,15 @@ impl Core {
             .db
             .pending_ops()
             .map_err(|e| CoreError::internal(format!("listing the queue: {e}")))?;
+        let issues = self
+            .db
+            .op_issues()
+            .map_err(|e| CoreError::internal(format!("listing sync issues: {e}")))?;
         Ok(ops
             .into_iter()
             .map(|op| {
                 let parked = op.next_attempt_at >= PARK_UNTIL;
+                let exportable = exportable(&op).is_some();
                 let path = self
                     .db
                     .node_path(&op.uid)
@@ -37,7 +44,9 @@ impl Core {
                     queued_at: op.created_at / 1000,
                     next_attempt_at: (!parked).then_some(op.next_attempt_at / 1000),
                     parked,
-                    failing: op.attempts >= FAILING_ATTEMPTS,
+                    failing: op.attempts >= FAILING_ATTEMPTS || issues.contains_key(&op.id),
+                    issue: issues.get(&op.id).map(|issue| SyncIssue::parse(issue)),
+                    exportable,
                 }
             })
             .collect())
@@ -57,4 +66,107 @@ impl Core {
         }
         Ok(moved)
     }
+
+    /// Copy the content of queued op `id` to `dest`, which must not exist yet.
+    /// The op stays queued. Returns the bytes written.
+    pub(crate) fn export_pending_op(&self, id: i64, dest: &Path) -> CoreResult<u64> {
+        if !dest.is_absolute() {
+            return Err(CoreError::invalid(format!(
+                "destination must be an absolute path: {}",
+                dest.display()
+            )));
+        }
+        let ops = self
+            .db
+            .pending_ops()
+            .map_err(|e| CoreError::internal(format!("listing the queue: {e}")))?;
+        let op = ops
+            .iter()
+            .find(|op| op.id == id)
+            .ok_or_else(|| CoreError::not_found(format!("no queued change {id}")))?;
+        let blob = exportable(op).ok_or_else(|| {
+            CoreError::invalid(format!("queued change {id} carries no file content"))
+        })?;
+        let written = copy_to_new_file(blob, dest)?;
+        info!(id, dest = %dest.display(), written, "exported a queued change's content");
+        Ok(written)
+    }
+}
+
+/// Copy `blob` to `dest`, which must not exist: never replace something the
+/// user already has.
+fn copy_to_new_file(blob: &Path, dest: &Path) -> CoreResult<u64> {
+    let mut source = File::open(blob)
+        .map_err(|e| CoreError::internal(format!("open {}: {e}", blob.display())))?;
+    let mut out = std::fs::OpenOptions::new()
+        .write(true)
+        .create_new(true)
+        .open(dest)
+        .map_err(|e| match e.kind() {
+            std::io::ErrorKind::AlreadyExists => {
+                CoreError::invalid(format!("{} already exists", dest.display()))
+            }
+            _ => CoreError::internal(format!("create {}: {e}", dest.display())),
+        })?;
+    std::io::copy(&mut source, &mut out)
+        .and_then(|written| out.flush().and(out.sync_all()).map(|()| written))
+        .map_err(|e| CoreError::internal(format!("write {}: {e}", dest.display())))
+}
+
+/// The staged blob of an op that carries file content.
+fn exportable(op: &PendingOp) -> Option<&Path> {
+    matches!(op.kind.as_str(), OP_CREATE | OP_REVISION)
+        .then_some(op.blob_path.as_deref())
+        .flatten()
+        .map(Path::new)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn op(kind: &str, blob: Option<&str>) -> PendingOp {
+        PendingOp {
+            id: 1,
+            kind: kind.to_string(),
+            uid: "vol~a".to_string(),
+            parent_uid: None,
+            name: None,
+            blob_path: blob.map(str::to_string),
+            meta_json: None,
+            created_at: 0,
+            attempts: 0,
+            last_error: None,
+            next_attempt_at: 0,
+        }
+    }
+
+    #[test]
+    fn only_a_change_that_carries_file_content_can_be_exported() {
+        assert!(exportable(&op(OP_CREATE, Some("/staging/a"))).is_some());
+        assert!(exportable(&op(OP_REVISION, Some("/staging/a"))).is_some());
+        assert!(exportable(&op(OP_CREATE, None)).is_none());
+        assert!(exportable(&op(OP_RENAME, None)).is_none());
+        assert!(exportable(&op(OP_TRASH, None)).is_none());
+    }
+
+    #[test]
+    fn an_export_copies_the_bytes_and_never_replaces_a_file() {
+        let dir = std::env::temp_dir().join(format!("pdfs-export-{}", std::process::id()));
+        std::fs::create_dir_all(&dir).unwrap();
+        let blob = dir.join("blob");
+        std::fs::write(&blob, b"queued bytes").unwrap();
+
+        let dest = dir.join("copy.txt");
+        assert_eq!(copy_to_new_file(&blob, &dest).unwrap(), 12);
+        assert_eq!(std::fs::read(&dest).unwrap(), b"queued bytes");
+
+        std::fs::write(&dest, b"the user's own").unwrap();
+        assert!(copy_to_new_file(&blob, &dest).is_err());
+        assert_eq!(std::fs::read(&dest).unwrap(), b"the user's own");
+        // The staged blob is the only copy of the change: an export leaves it.
+        assert_eq!(std::fs::read(&blob).unwrap(), b"queued bytes");
+
+        let _ = std::fs::remove_dir_all(&dir);
+    }
 }

crates/pdfs-gui/src/app/main.rs

@@ -75,8 +75,8 @@ use pdfs_core::control::{
     DirEntry, ErrorKind, ImportSummary, InvitationInfo, JobItem, MappingProgress, PendingOpInfo,
     PhotoItem, PhotoKind, PhotoMonth, PlaceInfo, PublicLinkInfo, RefreshScope, Request, Response,
     RestorableFolder, RestoreItem, RevisionInfo, SearchHit, ShareEntry, ShareEntryKind, SharedItem,
-    SyncFolderInfo, SyncPhase, SyncProgress, ThumbnailBuildStatus, Topic, TransferDirection,
-    TransferItem, send,
+    SyncFolderInfo, SyncIssue, SyncPhase, SyncProgress, ThumbnailBuildStatus, Topic,
+    TransferDirection, TransferItem, send,
 };
 
 use pdfs_core::mounts::{MountAccess, MountKind, MountMode, MountSpec};

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

@@ -70,8 +70,9 @@ pub(crate) struct LocationRow {
     progress: gtk4::ProgressBar,
 }
 
-/// What a queue row shows that can change: id, attempts, next attempt, parked.
-pub(crate) type QueueKey = (i64, i64, Option<i64>, bool);
+/// What a queue row shows that can change: id, attempts, next attempt, parked,
+/// issue.
+pub(crate) type QueueKey = (i64, i64, Option<i64>, bool, Option<SyncIssue>);
 
 /// The "Waiting to Upload" list: the daemon's pending-op queue.
 pub(crate) struct QueueState {
@@ -591,7 +592,7 @@ fn repaint_queue(ui: &Rc<Ui>, items: &[PendingOpInfo]) {
     items.sort_by_key(|op| (!op.failing, op.attempts == 0, op.id));
     let key: Vec<QueueKey> = items
         .iter()
-        .map(|op| (op.id, op.attempts, op.next_attempt_at, op.parked))
+        .map(|op| (op.id, op.attempts, op.next_attempt_at, op.parked, op.issue))
         .collect();
     if *queue.painted.borrow() == key {
         return;
@@ -648,6 +649,10 @@ fn queue_row(ui: &Rc<Ui>, op: &PendingOpInfo, now: i64) -> adw::ActionRow {
         "{action} · {state}",
         &[("action", &action), ("state", &state)],
     );
+    if let Some(issue) = op.issue {
+        subtitle.push('\n');
+        subtitle.push_str(&issue_text(issue));
+    }
     if let Some(error) = &op.last_error {
         subtitle.push('\n');
         // Translators: {n} is how many attempts failed, {error} the last error message.
@@ -662,7 +667,7 @@ fn queue_row(ui: &Rc<Ui>, op: &PendingOpInfo, now: i64) -> adw::ActionRow {
         .title(glib::markup_escape_text(&op.path).as_str())
         .subtitle(glib::markup_escape_text(&subtitle).as_str())
         .title_lines(1)
-        .subtitle_lines(3)
+        .subtitle_lines(if op.issue.is_some() { 5 } else { 3 })
         .tooltip_text(&op.path)
         .build();
     let image = gtk4::Image::from_icon_name(if op.failing {
@@ -687,9 +692,87 @@ fn queue_row(ui: &Rc<Ui>, op: &PendingOpInfo, now: i64) -> adw::ActionRow {
         retry.connect_clicked(move |_| retry_queued(&ui, Some(id)));
         row.add_suffix(&retry);
     }
+    if op.failing && op.exportable {
+        let export = gtk4::Button::builder()
+            .label(gettext("Export"))
+            .tooltip_text(gettext("Save a copy of this file's content elsewhere"))
+            .valign(gtk4::Align::Center)
+            .build();
+        export.add_css_class("flat");
+        let ui = ui.clone();
+        let id = op.id;
+        let name = Path::new(&op.path)
+            .file_name()
+            .map(|name| name.to_string_lossy().into_owned())
+            .unwrap_or_default();
+        export.connect_clicked(move |_| prompt_export_queued(&ui, id, &name));
+        row.add_suffix(&export);
+    }
     row
 }
 
+/// What a sync issue means and what the user can do about it. The change stays
+/// queued either way.
+fn issue_text(issue: SyncIssue) -> String {
+    match issue {
+        SyncIssue::Quota => gettext(
+            "Your Proton Drive storage is full. Free up space or upgrade your plan, and this change uploads on its own.",
+        ),
+        SyncIssue::Access => gettext(
+            "You can no longer change this on Proton Drive. Ask the owner for edit access, or export the file to keep your version.",
+        ),
+        SyncIssue::Missing => gettext(
+            "The folder this change belongs in is gone from Proton Drive. Export the file to keep your version.",
+        ),
+        SyncIssue::Limit => gettext(
+            "Proton Drive's limit on items in a folder or on folder depth is reached. Make room in the folder, then retry.",
+        ),
+        SyncIssue::Rejected | SyncIssue::Unknown => {
+            gettext("Proton Drive refused this change. It stays queued and is tried again.")
+        }
+    }
+}
+
+/// Ask where to save a copy of a queued file's content, then have the daemon
+/// write it there. The change itself stays queued.
+fn prompt_export_queued(ui: &Rc<Ui>, id: i64, name: &str) {
+    let window = ui_window(ui);
+    let dialog = gtk4::FileDialog::builder()
+        .title(gettext("Export File"))
+        .initial_name(name)
+        .build();
+    let ui = ui.clone();
+    dialog.save(window.as_ref(), gio::Cancellable::NONE, move |res| {
+        let Ok(file) = res else { return };
+        let Some(dest) = file.path().and_then(|p| p.to_str().map(str::to_string)) else {
+            toast_error(
+                &ui,
+                &gettext("Couldn't export the file"),
+                &gettext("That location isn't a local file."),
+            );
+            return;
+        };
+        let rx = spawn_request(
+            ui.dirs.control_socket(),
+            Request::ExportPendingOp { id, dest },
+        );
+        let ui = ui.clone();
+        glib::spawn_future_local(async move {
+            match rx.recv().await {
+                Ok(Ok(Response::Ok { .. })) => toast(&ui, &gettext("File exported")),
+                Ok(Ok(Response::Error { message, kind })) => {
+                    toast_failure(&ui, &gettext("Couldn't export the file"), &message, kind)
+                }
+                _ => toast_error(
+                    &ui,
+                    &gettext("Couldn't export the file"),
+                    &gettext("The Proton Drive service didn't respond."),
+                ),
+            }
+        });
+    });
+}
+
 /// Ask the daemon to stop waiting out one op's backoff, or every failed op's.
 fn retry_queued(ui: &Rc<Ui>, id: Option<i64>) {
     let rx = spawn_request(ui.dirs.control_socket(), Request::RetryPendingOp { id });