feat(sync): replicate history via copy instead of running SQLite live in iCloud

Looper now always reads and writes a fast local DB at the platform data
directory. When a sync folder is configured, it pulls from there at
startup (if the cloud copy has more recent activity by max(last_played_at))
and pushes back on quit via WAL checkpoint + atomic temp+rename.

Previously the cloud folder hosted the live DB, which led to:

- "authorization denied" crashes when macOS TCC blocked iCloud mid-session
- WAL/SHM corruption from iCloud syncing live SQLite sidecars
- Hangs while iCloud rehydrated an evicted database file

iCloud Drive is no longer auto-detected; opt in explicitly via
`looper config set sync-folder`. Failed pulls surface a SyncWarning
banner; failed pushes log a stderr warning instead of crashing on quit.

Drops the now-dead merge_old_db_into + its tests; replaces with three
tests covering pull-skip / pull-replace / push-create semantics. README's
sync section is rewritten to match, including the macOS TCC requirement
for iCloud Drive replication.

Author: program247365

README.md

@@ -141,94 +141,64 @@ Playback history and favorites live in a SQLite database (`looper.sqlite3`). Whe
 
 ## Cross-Device Sync
 
-looper keeps history in sync across your computers by storing `looper.sqlite3` in a shared folder (iCloud Drive, Dropbox, or any folder you choose). No account, no server — just a file in a folder you already sync.
+looper always reads and writes a fast local copy of `looper.sqlite3`. If you point it at a cloud folder (iCloud Drive, Dropbox, anything that syncs files), looper will pull from that folder at startup and push to it on quit. The cloud folder never holds the live database — it's just a passive copy that the cloud provider replicates between your machines on its own.
 
-### How it picks where to store the database
+This avoids the long-standing footguns of running SQLite directly on a cloud-synced filesystem (corrupted WAL/SHM sidecars, surprise permission denials, evicted files).
 
-On every launch, looper resolves the database location in this order:
+### Where the live database lives
 
-1. **Configured sync folder** — if you've run `looper config set sync-folder`, that path wins
-2. **iCloud Drive (macOS only)** — if iCloud Drive is active, looper automatically uses `~/Library/Mobile Documents/com~apple~CloudDocs/looper/looper.sqlite3`
-3. **Platform default** — fallback when neither of the above applies
-
-| Platform | Default database path |
-|----------|-----------------------|
-| macOS (no iCloud) | `~/Library/Application Support/sh.kbr.looper/looper.sqlite3` |
+| Platform | Live database path |
+|----------|--------------------|
+| macOS | `~/Library/Application Support/sh.kbr.looper/looper.sqlite3` |
 | Linux | `~/.local/share/looper/looper.sqlite3` |
 
-### iCloud Drive (zero config on macOS)
-
-If you use iCloud Drive, nothing extra is needed. On first launch after installing (or upgrading to) this version, looper:
-
-1. Detects iCloud Drive is active
-2. Creates `~/Library/Mobile Documents/com~apple~CloudDocs/looper/looper.sqlite3`
-3. Merges any existing local history into the iCloud database automatically
-4. Archives the old local database to `.sqlite3.bak` so it's never run twice
+By default no replication runs. Looper just uses the local path above.
 
-Once the iCloud file syncs to your other Macs (usually within a minute), every machine shares the same history. No commands needed.
-
-**Verify it's working:**
-
-```shell
-looper config show
-# sync_folder = (auto — iCloud Drive if available, otherwise platform default)
-
-ls ~/Library/Mobile\ Documents/com~apple~CloudDocs/looper/
-# looper.sqlite3
-```
-
-### Dropbox, OneDrive, or any synced folder
+### Replicate via a cloud folder
 
 Point looper at any folder your cloud provider keeps in sync:
 
 ```shell
-looper config set sync-folder ~/Dropbox/looper
-# Sync folder set to: /Users/you/Dropbox/looper
-# looper will use this folder for looper.sqlite3 on next launch.
+looper config set sync-folder "$HOME/Library/Mobile Documents/com~apple~CloudDocs/looper"
+# Replication folder set to: ...
+# looper will pull from this folder at startup and push to it on quit.
+# The live DB stays at the platform data directory.
 ```
 
-Run this once on each computer. On the next launch, looper moves (with merge) to that folder.
+Run this once on each computer that should share history. The cloud provider takes care of moving `looper.sqlite3` between machines in the background.
 
 **Verify it's working:**
 
 ```shell
 looper config show
-# sync_folder = /Users/you/Dropbox/looper
+# sync_folder = /Users/you/Library/Mobile Documents/.../looper (replicated on startup/quit)
 
-ls ~/Dropbox/looper/
+ls "$HOME/Library/Mobile Documents/com~apple~CloudDocs/looper/"
 # looper.sqlite3
 ```
 
-### Check current config at any time
+### macOS: iCloud Drive needs Files-and-Folders permission
 
-```shell
-looper config show
-```
+The first time looper tries to read or write inside `~/Library/Mobile Documents/...`, macOS will silently deny access until you grant the terminal app that launches looper permission. Open **System Settings → Privacy & Security → Files and Folders** (or **Full Disk Access**) and toggle on **iCloud Drive** for your terminal (Terminal, iTerm, Ghostty, etc.). Restart the terminal so the new entitlement takes effect.
 
-### Two-computer upgrade scenario
+If permission isn't granted, looper still runs against the local DB, surfaces a `History sync disabled` banner at startup, and prints a one-line warning to stderr on quit. Nothing crashes.
 
-If both computers already have local history from an older version of looper:
+### Sync semantics: last-quitter wins
 
-1. **Computer A** upgrades → detects iCloud (or configured folder) → merges its old local history in → archives old file
-2. iCloud syncs to Computer B (the database now has A's history)
-3. **Computer B** upgrades → opens the iCloud file (already has A's data) → merges its own old local history in
+Replication is a file copy in both directions:
 
-Result: the shared database has all plays from both computers, tagged with the machine that played each track. No data is lost.
+- **At startup**: if the cloud copy has a more recent `MAX(last_played_at)` than the local copy, looper replaces local with the cloud copy.
+- **At quit**: looper checkpoints the WAL, then atomically replaces the cloud copy with the local one.
 
-### Merge rules (when two histories combine)
+This is enough for one-human-at-a-time use across multiple Macs (typical single-user setup). It is **not** a general-purpose multi-master merge: if you play on two machines simultaneously, whichever quits last overwrites the other's session, and your cloud provider may produce conflict copies (e.g. `looper.sqlite3 conflicted-copy 2`). Resolve by closing one, picking the version you want to keep, and deleting the rest.
 
-| Field | Result |
-|-------|--------|
-| Play count | Sum of both |
-| Time played | Sum of both |
-| First played | Earliest of both |
-| Last played | Latest of both |
-| Favorite | `true` if either copy is favorited |
-| Last played on | Computer with the more recent play |
+### Disable replication
 
-### A note on concurrent access
+```shell
+rm "$HOME/.config/looper/sync_folder"
+```
 
-looper enables WAL mode on the database, which makes it safe for one machine to read while another writes. Playing on two machines simultaneously and writing to the same file is unusual and could cause conflicts — for typical single-user use (one active machine at a time) this is not an issue.
+Or just don't set it. Looper falls back to local-only without complaint.
 
 ## Keys
 

src/main.rs

@@ -125,8 +125,11 @@ enum ConfigCmd {
 
 #[derive(StructOpt, Debug)]
 enum ConfigKey {
-    /// Set the folder where looper.sqlite3 is stored (e.g. a Dropbox or custom path).
-    /// Overrides iCloud auto-detection. Run once per machine.
+    /// Set a folder to replicate looper.sqlite3 to (e.g. iCloud Drive, Dropbox).
+    /// looper always reads and writes a fast local copy in the platform data
+    /// directory; on startup it pulls from this folder if it has newer
+    /// activity, and on quit it pushes the local copy back. By default no
+    /// replication runs. Run once per machine.
     SyncFolder { path: String },
 }
 
@@ -207,20 +210,39 @@ fn run_app(opt: Opt) -> Result<()> {
 fn cmd_config(cmd: ConfigCmd) -> Result<()> {
     match cmd {
         ConfigCmd::Set { key: ConfigKey::SyncFolder { path } } => {
-            storage::write_sync_folder_config(std::path::Path::new(&path))?;
-            println!("Sync folder set to: {path}");
-            println!("looper will use this folder for looper.sqlite3 on next launch.");
+            let folder = std::path::Path::new(&path);
+            storage::write_sync_folder_config(folder)?;
+            println!("Replication folder set to: {path}");
+            println!(
+                "looper will pull from this folder at startup and push to it on quit.\n\
+                 The live DB stays at the platform data directory."
+            );
+            if is_under_icloud_drive(folder) {
+                println!();
+                println!(
+                    "note: iCloud Drive uploads are async, so a quit on one machine isn't\n\
+                     visible on another until iCloud syncs. Running looper on two machines\n\
+                     at the same time can produce iCloud conflict copies — close one before\n\
+                     opening the other."
+                );
+            }
         }
         ConfigCmd::Show => match storage::read_sync_folder_config() {
-            Some(folder) => println!("sync_folder = {}", folder.display()),
-            None => println!(
-                "sync_folder = (auto — iCloud Drive if available, otherwise platform default)"
-            ),
+            Some(folder) => println!("sync_folder = {} (replicated on startup/quit)", folder.display()),
+            None => println!("sync_folder = (none — local DB only, no replication)"),
         },
     }
     Ok(())
 }
 
+fn is_under_icloud_drive(path: &std::path::Path) -> bool {
+    let Some(home) = directories::UserDirs::new().map(|d| d.home_dir().to_path_buf()) else {
+        return false;
+    };
+    let icloud = home.join("Library/Mobile Documents/com~apple~CloudDocs");
+    path.starts_with(&icloud)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

src/play_loop.rs

@@ -112,7 +112,10 @@ fn browse_history_session(
         if event::poll(Duration::from_millis(30))? {
             if let Event::Key(key) = event::read()? {
                 match handle_history_browser_key_event(key, &panel) {
-                    KeyCommand::Quit => return Ok(()),
+                    KeyCommand::Quit => {
+                        push_replica_best_effort(&storage);
+                        return Ok(());
+                    }
                     KeyCommand::HistoryNext => {
                         if panel.selected + 1 < panel.rows.len() {
                             panel.selected += 1;
@@ -227,7 +230,10 @@ fn play_file_session(
 
         match next {
             Some(replay_target) => current_url = replay_target,
-            None => return Ok(()),
+            None => {
+                push_replica_best_effort(&storage);
+                return Ok(());
+            }
         }
     }
 }
@@ -912,10 +918,21 @@ fn play_single_track(
         title_state,
         ctx,
     )?;
-    persist_played_time(&storage, &record.track_key, played_seconds(&state))?;
+    if let Err(err) = persist_played_time(&storage, &record.track_key, played_seconds(&state)) {
+        eprintln!("looper: warning — could not record final play time on quit: {err}");
+    }
     Ok(result)
 }
 
+/// Pushes the local DB to the configured replica (e.g. iCloud Drive). Best
+/// effort: any failure is logged and swallowed so quit can't fail.
+fn push_replica_best_effort(storage: &SharedStorage) {
+    let storage = storage.lock().unwrap();
+    if let Err(err) = storage.push_replica() {
+        eprintln!("looper: warning — could not replicate history on quit: {err}");
+    }
+}
+
 struct PrefetchWorker {
     tracks: Arc<Mutex<Vec<TrackInfo>>>,
     sender: SyncSender<PrefetchTask>,