fix(sync,gui,cli): get a synced folder unstuck when its local copy is gone (#46)

A mirror folder whose files were all gone from this computer stayed in
error for good. The wipe guard rightly refuses to trash the whole folder
on Drive, but nothing got the folder out of that state: a queued switch
to on-demand waits for a pass that ends idle, and its push pass hit the
same guard. Only removing the folder from sync cleared the baseline that
made the empty folder read as "delete everything".

- The push pass for a switch to on-demand forgets the baseline rows of a
  local copy that is gone in full instead of trashing them, so the
  switch goes ahead and the mount shows what Drive has.
- New Request::ResetSyncFolder, `pdfs sync reset ID` and "Sync From
  Scratch…" in a synced folder's menu clear a mirror folder's baseline
  (and a queued switch to on-demand, whose push pass would upload a
  duplicate of every file). The next pass compares both sides as on the
  first sync: one-sided files are copied across, files that differ keep
  both versions, nothing is deleted.
- The wipe guards' messages name the reset; restore logs why it skipped
  a folder.

Two simulations cover it. The on-demand one failed in exactly the
reported state (mirror, pending ondemand, error) before the fix.
All 8 catalogs translated.

docs/BUGS.md

@@ -101,6 +101,7 @@ a live account since.
 | Entry | Title |
 |---|---|
 | [B256](#b256--pdfs-copy-right-after-a-save-copies-the-old-version) | `pdfs copy` right after a save copies the old version |
+| [B255](#b255--a-synced-folder-whose-files-are-all-gone-here-is-stuck-for-good) | A synced folder whose files are all gone here is stuck for good |
 | [B254](#b254--an-edit-in-the-same-second-as-a-new-upload-never-arrives) | An edit in the same second as a new upload never arrives |
 | [B253](#b253--the-app-shows-the-sign-in-page-when-the-keyring-is-locked) | The app shows the sign-in page when the keyring is locked |
 | [B252](#b252--computers-sharing-a-device-overwrite-each-others-profile) | Computers sharing a device overwrite each other's profile |
@@ -382,6 +383,36 @@ A move checks the same set.
 
 ---
 
+### B255 — A synced folder whose files are all gone here is stuck for good
+
+**Status:** Fixed, not verified live
+**Found:** 2026-10-26, issue #46: a folder restored from another computer never downloaded.
+**Where:** `push_pass` in `crates/pdfs-fuse/src/sync.rs`; `reset_sync_folder` in
+`crates/pdfs-fuse/src/devices.rs`
+
+**Repro:** Sync a folder in mirror mode, then delete all of its files on this computer while
+the folder is paused. Resume it. Every pass stops with `every one of the N synced paths is
+missing locally`, the folder stays in error, and a switch to online only waits for good.
+
+**Cause.** The wipe guard is right to stop a pass that would trash the whole folder on Drive.
+But nothing got the folder out of that state. A switch to on-demand waits for a pass that ends
+`idle`, and its push pass hit the same guard. The baseline that made the empty folder read as
+"delete everything" could only be cleared by removing the folder from sync. How the reporter's
+folder lost its files is not known yet.
+
+**Fix.** The push pass for a switch to on-demand forgets the baseline rows of a local copy that
+is gone in full, instead of trashing them on Drive, so the switch goes ahead and the mount shows
+what Drive has. **Sync From Scratch…** in the app and `pdfs sync reset ID` clear a mirror
+folder's baseline, so the next pass compares both sides as on the first sync: one-sided files
+are copied across, files that differ keep both versions, and nothing is deleted. Restore now
+logs why it skipped a folder.
+
+**Test:** The simulations `a_folder_whose_local_copy_is_gone_still_goes_on_demand` (which
+failed in exactly the reported state before the fix) and
+`a_folder_whose_local_copy_is_gone_downloads_again_after_a_reset`.
+
+---
+
 ### B254 — An edit in the same second as a new upload never arrives
 
 **Status:** Fixed, not verified live

docs/CHANGELOG.md

@@ -33,6 +33,11 @@ scratch (user data in `staging/` and `recovery/` is never touched by this).
 - **Folder sizes.** **Details** shows how much a folder holds and how many items are in it, as
   Proton Drive counts it, including items in the trash. From a terminal: `pdfs du PATH`.
 
+- **Sync a folder from scratch.** In a synced folder's menu on **Sync → Folders**, **Sync From
+  Scratch…** forgets what was synced before and compares the folder with Proton Drive again. A
+  file on one side only is copied to the other, and a file that differs keeps both versions.
+  Nothing is deleted. From the terminal: `pdfs sync reset ID`.
+
 ### Changed
 - **Copying a file inside the mount is faster** when the computer already has the file, for
   example with `cp` or a file manager: the copy is made on this computer, about four times
@@ -48,6 +53,12 @@ scratch (user data in `staging/` and `recovery/` is never touched by this).
 
 ### Fixed
 
+- **A synced folder whose files were all gone from this computer no longer gets stuck** (#46).
+  The sync still refuses to delete everything on Proton Drive, but a switch to online only now
+  goes ahead and shows what Proton Drive has, instead of waiting for good. To download the
+  files again instead, sync the folder from scratch. Restoring folders also logs why it
+  skipped a folder.
+
 - **Saved public links show the name of what they point at**, in the app and in `pdfs bookmarks`,
   instead of "Shared link". For a link with a custom password, the address no longer has the custom
   password stuck to its end, so it matches the link the web shows and the page asks for the

docs/CLI.md

@@ -84,6 +84,7 @@ commands are for scripts and for cases where the mount is not available.
 | `pdfs sync rm ID [--delete-remote]` | Stop syncing. Local files stay; `--delete-remote` also removes the copy on Proton Drive. |
 | `pdfs sync mode ID mirror\|ondemand` | Switch between a full local copy (`mirror`) and online only (`ondemand`). |
 | `pdfs sync now [ID]` | Start a sync pass now, for all folders or one. |
+| `pdfs sync reset ID` | Forget what a synced folder synced before and compare it with Proton Drive again. A file on one side only is copied to the other, and a file that differs keeps both versions. Nothing is deleted. |
 | `pdfs sync pause [--for 1h] [--folder ID]` | Pause uploads and synced folders. Reading files keeps working. `--for` ends the pause by itself (`30m`, `1h`, `2d`). |
 | `pdfs sync resume [--folder ID]` | Resume after a pause. |
 | `pdfs sync limit [--up RATE] [--down RATE]` | Cap bandwidth, for example `500K` or `2M` per second. `0` removes a cap. Without options, prints the current caps. |

docs/SYNCED_FOLDERS.md

@@ -76,6 +76,14 @@ again when they move into a synced one.
 Proton Drive. To delete the copy on Proton Drive as well, tick **Also delete from Proton Drive**,
 or add `--delete-remote`.
 
+## Sync a folder from scratch
+
+**Sync From Scratch…** in the folder's menu, or `pdfs sync reset ID`, makes this computer forget
+what it synced in the folder before and compare it with Proton Drive again, as on the first sync.
+A file on one side only is copied to the other, and a file that differs keeps both versions.
+Nothing is deleted. Use it when a folder's files went missing on this computer and the sync
+refuses to go on (see [Troubleshooting](TROUBLESHOOTING.md#a-synced-folder-stays-in-error-and-nothing-downloads)).
+
 ## Excluding files with `.pdfsignore`
 
 Synced folders skip build output, dependency folders and editor leftovers. Two sets of rules

docs/TROUBLESHOOTING.md

@@ -226,6 +226,22 @@ Check that:
 
 `pdfs sync now` starts a sync pass at once.
 
+### A synced folder stays in error and nothing downloads
+
+The log says `every one of the N synced paths is missing locally; refusing to trash them on
+Drive`. The folder synced before, and now none of its files are on this computer. The sync
+stops so that it does not delete them on Proton Drive too. Check that the folder is the right
+one and that its disk is mounted. To get the files back, choose **Sync From Scratch…** in the
+folder's menu on **Sync → Folders**, or run:
+
+```bash
+pdfs sync list            # find the folder's ID
+pdfs sync reset 1
+```
+
+This downloads what Proton Drive has and uploads what only this computer has. Nothing is deleted.
+If you deleted the files on purpose, delete them on Proton Drive too, or stop syncing the folder.
+
 ### Files named `(sync-conflict …)` appeared
 
 The file changed in two places at once. Nothing was lost. See