diff --git a/lib/mackup.sh b/lib/mackup.sh
index 68dd667..b041fd1 100644
--- a/lib/mackup.sh
+++ b/lib/mackup.sh
@@ -101,6 +101,60 @@ ssr::mackup::backup() {
 
 ssr::mackup::restore() {
     ssr::log "mackup restore"
+
+    # Pre-materialize iCloud placeholders so mackup doesn't have to wait for
+    # each file to download one-by-one during the restore walk.
+    local cfg="$HOME/.mackup.cfg" mackup_root="" path dir
+    if [[ -f "$cfg" ]]; then
+        path="$(awk -F= '/^path/{gsub(/^[[:space:]]+|[[:space:]]+$/,"",$2); print $2}' "$cfg")"
+        dir="$( awk -F= '/^directory/{gsub(/^[[:space:]]+|[[:space:]]+$/,"",$2); print $2}' "$cfg")"
+        [[ -n "$path" && -n "$dir" ]] && mackup_root="$path/$dir"
+    fi
+    if [[ -n "$mackup_root" ]]; then
+        ssr::log "Materializing iCloud files in $mackup_root (may take a moment)…"
+        ssr::mackup::_materialize_icloud "$mackup_root"
+        # Count remaining stubs; if there are many, give iCloud more time.
+        local stub_count
+        stub_count="$(find "$mackup_root" -name '*.icloud' -type f 2>/dev/null | wc -l | tr -d ' ')"
+        if [[ "$stub_count" -gt 0 ]]; then
+            ssr::warn "$stub_count placeholder file(s) still pending — waiting 5s for iCloud sync…"
+            sleep 5
+        fi
+    fi
+
+    local stub_total
+    stub_total="$(find "${mackup_root:-/dev/null}" -name '*.icloud' -type f 2>/dev/null | wc -l | tr -d ' ')"
+    if [[ "$stub_total" -gt 0 ]]; then
+        ssr::warn "$stub_total file(s) still need downloading from iCloud — restore may pause between files."
+    fi
+    ssr::log "Running mackup restore (long pauses are normal while iCloud fetches files)…"
+
+    # Background watchdog: prints elapsed time every 15s so the user knows the
+    # process is still alive during iCloud download pauses.
+    local start_ts rc=0 done_flag watchdog_pid
+    start_ts="$(date +%s)"
+    done_flag="$(mktemp)"
+    (
+        while [[ -f "$done_flag" ]]; do
+            sleep 15
+            [[ -f "$done_flag" ]] || break
+            printf '  … mackup restore still running (%ds elapsed — waiting for iCloud)\n' \
+                "$(( $(date +%s) - start_ts ))" >&2
+        done
+    ) &
+    watchdog_pid=$!
+
     # -f: answer "yes" to all prompts (consistent with backup behaviour).
-    mackup -f restore
+    mackup -f restore || rc=$?
+
+    rm -f "$done_flag"
+    kill "$watchdog_pid" 2>/dev/null || true
+    wait "$watchdog_pid" 2>/dev/null || true
+
+    local elapsed=$(( $(date +%s) - start_ts ))
+    if [[ $rc -ne 0 ]]; then
+        ssr::warn "mackup restore finished with errors (rc=$rc, ${elapsed}s elapsed)"
+    else
+        ssr::ok "mackup restore completed in ${elapsed}s"
+    fi
 }