feat: async iCloud prefetch + keep-local for Mackup folder

lib/icloud.sh (new):
  ssr::icloud::prefetch <dir>    — spawn background open -g requests for
    all .icloud stubs; returns immediately so other work can run in parallel.
  ssr::icloud::wait <dir> [sec]  — poll until stubs are gone or timeout
    (default 180s). Logs progress every 5s.
  ssr::icloud::keep_local <dir>  — after sync, removes
    com.apple.icloud.evictable xattr from every real file + updates
    access-time (LRU delay), preventing iCloud from re-creating stubs
    before the next run. Best-effort (no public pin API on macOS CLI).

bin/ssr-sync:
  - prefetch Mackup folder immediately after cloud is available (before
    brew update/upgrade) so downloads proceed in the background.
  - ssr::icloud::wait called just before mackup backup.
  - ssr::icloud::keep_local called after sync completes.
  - SSR_ICLOUD_WAIT_TIMEOUT (default 180) and SSR_ICLOUD_KEEP_LOCAL
    (default true) config toggles added.

bin/ssr-restore:
  - prefetch Mackup folder right after cloud is validated, before the
    brew bundle install step, maximising download time available.

config/ssr.conf.example:
  Added SSR_ICLOUD_WAIT_TIMEOUT and SSR_ICLOUD_KEEP_LOCAL keys.

Co-authored-by: Cursor <cursoragent@cursor.com>

bin/ssr-restore

@@ -21,6 +21,8 @@ source "$SSR_ROOT/lib/macos.sh"
 source "$SSR_ROOT/lib/macos-prefs.sh"
 # shellcheck source=../lib/restore-state.sh
 source "$SSR_ROOT/lib/restore-state.sh"
+# shellcheck source=../lib/icloud.sh
+source "$SSR_ROOT/lib/icloud.sh"
 
 ssr::require_macos
 ssr::load_config
@@ -74,9 +76,14 @@ ssr::log "Using Brewfile: $brewfile"
 # Initialise state (archives previous state file if present).
 ssr::rs::init "$brewfile"
 
+# Trigger async iCloud prefetch for the Mackup folder as early as possible
+# so files have time to download while brew bundle install runs.
+ssr::icloud::prefetch "$mackup_dir"
+
 # --- Step helpers ------------------------------------------------------------
 
 # Groups mackup install + configure + restore into a single resumable step.
+# ssr::mackup::restore already calls ssr::icloud::wait internally.
 _ssr_mackup_restore_step() {
     ssr::mackup::ensure_installed
     ssr::mackup::configure "$mackup_dir"

bin/ssr-sync

@@ -15,6 +15,8 @@ source "$SSR_ROOT/lib/mackup.sh"
 source "$SSR_ROOT/lib/apps.sh"
 # shellcheck source=../lib/macos-prefs.sh
 source "$SSR_ROOT/lib/macos-prefs.sh"
+# shellcheck source=../lib/icloud.sh
+source "$SSR_ROOT/lib/icloud.sh"
 
 ssr::require_macos
 ssr::load_config
@@ -28,12 +30,22 @@ mackup_dir="$(ssr::cloud::mackup_dir)"
 ssr::ensure_dir "$backup_dir"
 ssr::ensure_dir "$mackup_dir"
 
+# Kick off async iCloud download for the Mackup folder immediately so that
+# files have maximum time to download while brew update/upgrade runs.
+# ssr::icloud::wait is called just before mackup backup below.
+ssr::icloud::prefetch "$mackup_dir"
+
 ssr::brew::ensure_installed
 ssr::mackup::ensure_installed
 ssr::mackup::configure "$mackup_dir"
 
 ssr::brew::update
 ssr::brew::upgrade
+
+# Wait for iCloud downloads triggered above before handing off to mackup.
+# Timeout (seconds) is configurable; default 180s.
+ssr::icloud::wait "$mackup_dir" "${SSR_ICLOUD_WAIT_TIMEOUT:-180}"
+
 ssr::mackup::backup
 ssr::brew::dump "$backup_dir"
 ssr::brew::cleanup
@@ -67,5 +79,11 @@ state_dir="${SSR_STATE_DIR:-$HOME/.local/state/ssr}"
 ssr::ensure_dir "$state_dir"
 date '+%Y-%m-%dT%H:%M:%S%z' > "$state_dir/last-sync"
 
+# Mark Mackup folder files as keep-local so iCloud doesn't evict them
+# before the next sync run, avoiding slow on-demand downloads next time.
+if [[ "${SSR_ICLOUD_KEEP_LOCAL:-true}" == "true" ]]; then
+    ssr::icloud::keep_local "$mackup_dir"
+fi
+
 ssr::ok "ssr sync completed → $backup_dir"
 ssr::syslog "sync completed"