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"