@capgo/capacitor-updater 7.50.2 → 7.51.15

package/android/src/main/java/ee/forgr/capacitor_updater/CapgoUpdater.java

@@ -13,7 +13,14 @@ import android.content.pm.PackageManager;
 import android.os.Build;
 import androidx.annotation.NonNull;
 import androidx.lifecycle.LifecycleOwner;
+import androidx.work.Constraints;
 import androidx.work.Data;
+import androidx.work.ExistingPeriodicWorkPolicy;
+import androidx.work.ExistingWorkPolicy;
+import androidx.work.ListenableWorker;
+import androidx.work.NetworkType;
+import androidx.work.OneTimeWorkRequest;
+import androidx.work.PeriodicWorkRequest;
 import androidx.work.WorkInfo;
 import androidx.work.WorkManager;
 import com.google.common.util.concurrent.Futures;
@@ -32,7 +39,9 @@ import java.security.SecureRandom;
 import java.util.ArrayList;
 import java.util.Date;
 import java.util.HashMap;
+import java.util.HashSet;
 import java.util.Iterator;
+import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Map;
 import java.util.Objects;
@@ -45,6 +54,7 @@ import java.util.concurrent.Executors;
 import java.util.concurrent.ScheduledExecutorService;
 import java.util.concurrent.ScheduledFuture;
 import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.zip.ZipEntry;
 import java.util.zip.ZipInputStream;
 import okhttp3.*;
@@ -65,16 +75,24 @@ public class CapgoUpdater {
     private static final String FALLBACK_VERSION = "pastVersion";
     private static final String NEXT_VERSION = "nextVersion";
     private static final String PREVIEW_FALLBACK_VERSION = "previewFallbackVersion";
+    private static final String PENDING_DELETE_IDS = "pendingDeleteIds";
     private static final String bundleDirectory = "versions";
     private static final String TEMP_UNZIP_PREFIX = "capgo_unzip_";
+    private static final long DELETE_PACE_MS = 75L;
+    private final Object deleteLock = new Object();
     private static final String CAPACITOR_CONFIG_ASSET = "capacitor.config.json";
     private static final String BACKGROUND_RUNNER_CONFIG_KEY = "BackgroundRunner";
+    private static final String BACKGROUND_RUNNER_WORKER_CLASS = "io.ionic.backgroundrunner.plugin.RunnerWorker";
 
     public static final String TAG = "Capacitor-updater";
     public SharedPreferences.Editor editor;
+
+    /** Optional gate run before any download touches disk (e.g. wait for launch cleanup). */
+    public Runnable downloadGate = null;
     public SharedPreferences prefs;
 
     public File documentsDir;
+    public File noBackupDir;
     public Boolean directUpdate = false;
     public Activity activity;
     public String pluginVersion = "";
@@ -96,17 +114,31 @@ public class CapgoUpdater {
     // Cached key ID calculated once from publicKey
     private String cachedKeyId = "";
 
-    // Flag to track if we received a 429 response - stops requests until app restart
-    private static volatile boolean rateLimitExceeded = false;
+    // Temporary 429 block until this epoch ms (Retry-After / rateLimitResetAt). No sticky latch.
+    // Guarded by rateLimitStateLock so concurrent 429s cannot shorten the window or mix metadata.
+    private static final Object rateLimitStateLock = new Object();
+    private static long rateLimitBlockedUntilMs = 0L;
+    private static String rateLimitBlockedError = "too_many_requests";
+    private static String rateLimitBlockedMessage = "Too many requests";
+
+    // Flag to track if we've already sent the rate limit statistic - prevents infinite loop.
+    // Released again when the send fails, so a later 429 can retry it.
+    private static boolean rateLimitStatisticSent = false;
 
-    // Flag to track if we've already sent the rate limit statistic - prevents infinite loop
-    private static volatile boolean rateLimitStatisticSent = false;
+    // Upper bound for a client-side 429 block, so a bogus Retry-After cannot block the app for days.
+    private static final long MAX_RATE_LIMIT_WINDOW_MS = 24 * 60 * 60 * 1000L;
 
     // Stats batching - queue events and send max once per second
     private final List<QueuedStatsEvent> statsQueue = new CopyOnWriteArrayList<>();
+    private final List<QueuedStatsEvent> statsInFlight = new ArrayList<>();
+    private final Object pendingStatsPersistLock = new Object();
     private final ScheduledExecutorService statsScheduler = Executors.newSingleThreadScheduledExecutor();
     private ScheduledFuture<?> statsFlushTask = null;
+    private final AtomicBoolean statsFlushInFlight = new AtomicBoolean(false);
+    private final AtomicBoolean statsStopped = new AtomicBoolean(false);
     private static final long STATS_FLUSH_INTERVAL_MS = 1000;
+    private static final String PENDING_STATS_FILE = "capgo_pending_stats.json";
+    private static final int MAX_PENDING_STATS = 200;
 
     private static final class QueuedStatsEvent {
 
@@ -128,7 +160,7 @@ public class CapgoUpdater {
 
     private final FilenameFilter filter = (f, name) -> {
         // ignore directories generated by mac os x
-        return (!name.startsWith("__MACOSX") && !name.startsWith(".") && !name.startsWith(".DS_Store"));
+        return !name.startsWith("__MACOSX") && !name.startsWith(".") && !name.startsWith(".DS_Store");
     };
 
     private boolean isProd() {
@@ -283,14 +315,17 @@ public class CapgoUpdater {
         return this.cachedKeyId;
     }
 
-    private File unzip(final String id, final File zipFile, final String dest) throws IOException {
+    File unzip(final String id, final File zipFile, final String dest) throws IOException {
+        return unzip(id, zipFile, dest, CryptoCipher.ioBufferBytes());
+    }
+
+    File unzip(final String id, final File zipFile, final String dest, final int bufferSize) throws IOException {
         final File targetDirectory = new File(this.documentsDir, dest);
         try (
             final BufferedInputStream bis = new BufferedInputStream(new FileInputStream(zipFile));
             final ZipInputStream zis = new ZipInputStream(bis)
         ) {
             int count;
-            final int bufferSize = 8192;
             final byte[] buffer = new byte[bufferSize];
             final long lengthTotal = zipFile.length();
             long lengthRead = bufferSize;
@@ -370,7 +405,7 @@ public class CapgoUpdater {
         io.execute(() -> cacheBundleFiles(id));
     }
 
-    private void cacheBundleFiles(final String id) {
+    void cacheBundleFiles(final String id) {
         if (this.activity == null) {
             logger.debug("Skip delta cache population: activity is null");
             return;
@@ -392,20 +427,32 @@ public class CapgoUpdater {
             return;
         }
 
+        final File builtinFolder = new File(this.activity.getFilesDir(), "public");
+
         final List<File> files = new ArrayList<>();
         collectFiles(bundleDir, files);
+        final int bundlePrefixLength = bundleDir.getAbsolutePath().length() + 1;
         for (File file : files) {
             final String checksum = CryptoCipher.calcChecksum(file);
             if (checksum.isEmpty()) {
                 continue;
             }
+
+            // Builtin is already a permanent reuse source (see isManifestEntryAvailableLocally),
+            // so there's no need to also duplicate a byte-identical file into the delta cache.
+            final String relativePath = file.getAbsolutePath().substring(bundlePrefixLength);
+            final File builtinFile = new File(builtinFolder, relativePath);
+            if (verifyChecksum(builtinFile, checksum)) {
+                continue;
+            }
+
             final String cacheName = checksum + "_" + file.getName();
             final File cacheFile = new File(cacheDir, cacheName);
             if (cacheFile.exists()) {
                 continue;
             }
             try {
-                copyFile(file, cacheFile);
+                copyFileAtomically(file, cacheFile);
             } catch (IOException e) {
                 logger.debug("Delta cache copy failed: " + file.getPath());
             }
@@ -431,7 +478,7 @@ public class CapgoUpdater {
 
     private void copyFile(final File source, final File dest) throws IOException {
         try (final FileInputStream input = new FileInputStream(source); final FileOutputStream output = new FileOutputStream(dest)) {
-            final byte[] buffer = new byte[1024 * 1024];
+            final byte[] buffer = new byte[CryptoCipher.copyBufferBytes()];
             int length;
             while ((length = input.read(buffer)) != -1) {
                 output.write(buffer, 0, length);
@@ -471,28 +518,74 @@ public class CapgoUpdater {
             return false;
         }
 
-        final File builtinFile = new File(this.activity.getFilesDir(), "public/" + fileName);
-        if (verifyChecksum(builtinFile, fileHash)) {
+        if (DownloadService.builtinAssetMatches(this.activity.getAssets(), fileName, fileHash)) {
             return true;
         }
 
+        try {
+            final File builtinFile = DownloadService.resolveManifestBuiltinFile(new File(this.activity.getFilesDir(), "public"), fileName);
+            if (verifyChecksum(builtinFile, fileHash)) {
+                return true;
+            }
+        } catch (IOException ignored) {
+            // Invalid path; fall through to cache lookup.
+        }
+
         final boolean isBrotli = fileName.endsWith(".br");
         final String fileNameWithoutPath = new File(fileName).getName();
         final String cacheBaseName = isBrotli ? fileNameWithoutPath.substring(0, fileNameWithoutPath.length() - 3) : fileNameWithoutPath;
-        final File cacheFolder = new File(this.activity.getCacheDir(), "capgo_downloads");
-        final File cacheFile = new File(cacheFolder, fileHash + "_" + cacheBaseName);
-        if (verifyChecksum(cacheFile, fileHash)) {
-            return true;
-        }
+        if (isSafeCacheHash(fileHash)) {
+            final File cacheFolder = new File(this.activity.getCacheDir(), "capgo_downloads");
+            final File cacheFile = new File(cacheFolder, fileHash + "_" + cacheBaseName);
+            // Cache files are named `{hash}_{filename}` and were checksum-verified
+            // when written. Re-hashing every hit re-reads the whole bundle and
+            // OOMs/janks low-RAM devices during getMissing / delta apply.
+            if (isReusableCacheFile(cacheFile, fileHash)) {
+                return true;
+            }
 
-        if (isBrotli) {
-            final File legacyCacheFile = new File(cacheFolder, fileHash + "_" + fileNameWithoutPath);
-            return verifyChecksum(legacyCacheFile, fileHash);
+            if (isBrotli) {
+                final File legacyCacheFile = new File(cacheFolder, fileHash + "_" + fileNameWithoutPath);
+                return isReusableCacheFile(legacyCacheFile, fileHash);
+            }
         }
 
         return false;
     }
 
+    static final String EMPTY_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+
+    static boolean isSafeCacheHash(final String hash) {
+        if (hash == null) {
+            return false;
+        }
+        final int len = hash.length();
+        if (len != 64 && len != 8) {
+            return false;
+        }
+        for (int i = 0; i < len; i++) {
+            final char c = hash.charAt(i);
+            if (!((c >= '0' && c <= '9') || (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F'))) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    // SHA-256 hash-named cache files were verified when written. Existence is
+    // enough for non-empty files; empty files are reused only for the empty SHA-256.
+    // CRC32 (8 hex) is too collision-prone to trust without a re-read.
+    static boolean isReusableCacheFile(final File file, final String expectedHash) {
+        if (file == null || !file.isFile() || !isSafeCacheHash(expectedHash) || expectedHash.length() != 64) {
+            return false;
+        }
+        final long length = file.length();
+        if (length > 0) {
+            return true;
+        }
+        return length == 0 && EMPTY_SHA256.equalsIgnoreCase(expectedHash);
+    }
+
     public JSONArray getMissingBundleFiles(final JSONArray manifest, final String sessionKey) throws JSONException {
         final JSONArray missing = new JSONArray();
         for (int i = 0; i < manifest.length(); i++) {
@@ -656,6 +749,9 @@ public class CapgoUpdater {
                                 if ("low_mem_fail".equals(error)) {
                                     sendStats("low_mem_fail", failedVersion);
                                 }
+                                if ("insufficient_disk_space".equals(error)) {
+                                    sendStats("insufficient_disk_space", failedVersion);
+                                }
                                 ret.put("error", error != null ? error : "download_fail");
                                 sendStats("download_fail", failedVersion);
                                 notifyListeners("downloadFailed", ret);
@@ -667,6 +763,13 @@ public class CapgoUpdater {
                                 }
                             });
                             break;
+                        case CANCELLED:
+                            DataManager.getInstance().clearManifest(id);
+                            CompletableFuture<BundleInfo> cancelledFuture = downloadFutures.remove(id);
+                            if (cancelledFuture != null) {
+                                cancelledFuture.cancel(true);
+                            }
+                            break;
                     }
                 });
         });
@@ -688,6 +791,10 @@ public class CapgoUpdater {
         }
         observeWorkProgress(this.activity, id, setNext);
 
+        if (manifest != null) {
+            DataManager.getInstance().setManifest(id, manifest);
+        }
+
         DownloadWorkerManager.enqueueDownload(
             this.activity,
             url,
@@ -712,10 +819,6 @@ public class CapgoUpdater {
             this.customId,
             this.defaultChannel
         );
-
-        if (manifest != null) {
-            DataManager.getInstance().setManifest(manifest);
-        }
     }
 
     public Boolean finishDownload(
@@ -916,6 +1019,11 @@ public class CapgoUpdater {
 
                 try {
                     this.deleteDirectory(entry, threadToCheck);
+                    if (entry.exists()) {
+                        logger.error("Orphan bundle directory still present after delete");
+                        logger.debug("Bundle ID: " + id);
+                        continue;
+                    }
                     this.removeBundleInfo(id);
                     logger.info("Deleted orphan bundle directory");
                     logger.debug("Bundle ID: " + id);
@@ -927,6 +1035,43 @@ public class CapgoUpdater {
         }
     }
 
+    public Set<String> allowedBundleIdsForCleanup() {
+        final Set<String> allowedIds = new HashSet<>();
+        for (final BundleInfo info : this.list(true)) {
+            if (info == null || info.getId() == null || info.getId().isEmpty()) {
+                continue;
+            }
+            // DELETED tombstones must not protect leftover folders.
+            // DELETING stays protected so drainPendingDeletes owns the removal.
+            if (info.isDeleted()) {
+                continue;
+            }
+            allowedIds.add(info.getId());
+        }
+        final String currentId = this.getCurrentBundleId();
+        if (currentId != null && !currentId.isEmpty()) {
+            allowedIds.add(currentId);
+        }
+        final BundleInfo fallback = this.getFallbackBundle();
+        if (fallback != null && fallback.getId() != null && !fallback.getId().isEmpty() && !fallback.isDeleting()) {
+            allowedIds.add(fallback.getId());
+        }
+        final BundleInfo next = this.getNextBundle();
+        if (next != null && next.getId() != null && !next.getId().isEmpty() && !next.isDeleting()) {
+            allowedIds.add(next.getId());
+        }
+        final BundleInfo previewFallback = this.getPreviewFallbackBundle();
+        if (
+            previewFallback != null &&
+            previewFallback.getId() != null &&
+            !previewFallback.getId().isEmpty() &&
+            !previewFallback.isDeleting()
+        ) {
+            allowedIds.add(previewFallback.getId());
+        }
+        return allowedIds;
+    }
+
     public void cleanupOrphanedTempFolders(final Thread threadToCheck) {
         if (this.documentsDir == null) {
             logger.warn("Documents directory is null, skipping temp folder cleanup");
@@ -983,7 +1128,7 @@ public class CapgoUpdater {
     }
 
     private void setCurrentBundle(final File bundle) {
-        this.cancelBackgroundRunnerWorkBeforeBundleSwitch();
+        this.resetBackgroundRunnerWorkForBundleSwitch(bundle);
         this.editor.putString(this.CAP_SERVER_PATH, bundle.getPath());
         logger.info("Current bundle set to: " + bundle);
         this.editor.commit();
@@ -993,7 +1138,33 @@ public class CapgoUpdater {
         return bundlePath != null && !bundlePath.trim().isEmpty() && !isBuiltin && !hasStoredBundleInfo;
     }
 
-    static String getBackgroundRunnerLabelFromConfig(final String configJson) {
+    static final class BackgroundRunnerWorkConfig {
+
+        final String label;
+        final String src;
+        final String event;
+        final boolean autoStart;
+        final boolean repeat;
+        final int interval;
+
+        BackgroundRunnerWorkConfig(
+            final String label,
+            final String src,
+            final String event,
+            final boolean autoStart,
+            final boolean repeat,
+            final int interval
+        ) {
+            this.label = label;
+            this.src = src;
+            this.event = event;
+            this.autoStart = autoStart;
+            this.repeat = repeat;
+            this.interval = interval;
+        }
+    }
+
+    static BackgroundRunnerWorkConfig getBackgroundRunnerWorkConfigFromConfig(final String configJson) {
         if (configJson == null || configJson.trim().isEmpty()) {
             return null;
         }
@@ -1011,12 +1182,30 @@ public class CapgoUpdater {
             }
 
             final String label = backgroundRunner.optString("label", "").trim();
-            return label.isEmpty() ? null : label;
+            if (label.isEmpty()) {
+                return null;
+            }
+
+            final String src = backgroundRunner.optString("src", "").trim();
+            final String event = backgroundRunner.optString("event", "").trim();
+            return new BackgroundRunnerWorkConfig(
+                label,
+                src,
+                event,
+                backgroundRunner.optBoolean("autoStart", false),
+                backgroundRunner.optBoolean("repeat", false),
+                backgroundRunner.optInt("interval", 0)
+            );
         } catch (JSONException ignored) {
             return null;
         }
     }
 
+    static String getBackgroundRunnerLabelFromConfig(final String configJson) {
+        final BackgroundRunnerWorkConfig config = getBackgroundRunnerWorkConfigFromConfig(configJson);
+        return config == null ? null : config.label;
+    }
+
     private String readAssetAsString(final String assetPath) throws IOException {
         final StringBuilder buffer = new StringBuilder();
         try (
@@ -1032,32 +1221,131 @@ public class CapgoUpdater {
         return buffer.toString();
     }
 
-    private void cancelBackgroundRunnerWorkBeforeBundleSwitch() {
+    private void copyFileAtomically(final File source, final File dest) throws IOException {
+        final File parent = dest.getParentFile();
+        if (parent != null && !parent.exists() && !parent.mkdirs()) {
+            throw new IOException("Failed to create parent directory: " + parent.getAbsolutePath());
+        }
+
+        final File tempFile = File.createTempFile("capgo-", ".tmp", parent);
+        try {
+            try (
+                final FileInputStream input = new FileInputStream(source);
+                final FileOutputStream output = new FileOutputStream(tempFile)
+            ) {
+                final byte[] buffer = new byte[CryptoCipher.copyBufferBytes()];
+                int length;
+                while ((length = input.read(buffer)) != -1) {
+                    output.write(buffer, 0, length);
+                }
+            }
+            CryptoCipher.replaceFile(tempFile, dest);
+        } finally {
+            if (tempFile.exists()) {
+                tempFile.delete();
+            }
+        }
+    }
+
+    private void syncBackgroundRunnerScriptFromBundle(final File bundle, final BackgroundRunnerWorkConfig config) {
+        if (this.activity == null || bundle == null || config == null || config.src == null || config.src.isEmpty()) {
+            return;
+        }
+
+        if (bundle.getPath().endsWith("/public") || "public".equals(bundle.getName())) {
+            return;
+        }
+
+        try {
+            final File source = resolvePathInsideDirectory(bundle, config.src);
+            if (!source.isFile()) {
+                return;
+            }
+
+            final File publicDir = new File(this.activity.getFilesDir(), "public");
+            final File dest = resolvePathInsideDirectory(publicDir, config.src);
+            this.copyFileAtomically(source, dest);
+            logger.info("Synced Background Runner script into native public storage before bundle switch.");
+            logger.debug("Background Runner script path: " + dest.getAbsolutePath());
+        } catch (Exception e) {
+            logger.debug("Background Runner script sync skipped: " + e.getMessage());
+        }
+    }
+
+    private void resetBackgroundRunnerWorkForBundleSwitch(final File bundle) {
         if (this.activity == null) {
             return;
         }
 
-        final String label;
+        final BackgroundRunnerWorkConfig config;
         try {
-            label = getBackgroundRunnerLabelFromConfig(this.readAssetAsString(CAPACITOR_CONFIG_ASSET));
+            config = getBackgroundRunnerWorkConfigFromConfig(this.readAssetAsString(CAPACITOR_CONFIG_ASSET));
         } catch (IOException ignored) {
             return;
         }
 
-        if (label == null) {
+        if (config == null) {
             return;
         }
 
         try {
             final WorkManager workManager = WorkManager.getInstance(this.activity.getApplicationContext());
-            workManager.cancelUniqueWork(label);
-            workManager.cancelAllWorkByTag(label);
+            workManager.cancelUniqueWork(config.label);
+            workManager.cancelAllWorkByTag(config.label);
             logger.info("Cancelled Background Runner work before bundle switch.");
-            logger.debug("Background Runner label: " + label);
+            logger.debug("Background Runner label: " + config.label);
         } catch (Exception e) {
             logger.warn("Failed to cancel Background Runner work before bundle switch.");
             logger.debug("Background Runner cancellation error: " + e.getMessage());
         }
+
+        this.syncBackgroundRunnerScriptFromBundle(bundle, config);
+        this.rescheduleBackgroundRunnerWork(config);
+    }
+
+    private void rescheduleBackgroundRunnerWork(final BackgroundRunnerWorkConfig config) {
+        if (!config.autoStart || config.interval <= 0 || config.src.isEmpty()) {
+            return;
+        }
+
+        try {
+            @SuppressWarnings("unchecked")
+            final Class<? extends ListenableWorker> workerClass = (Class<? extends ListenableWorker>) Class.forName(
+                BACKGROUND_RUNNER_WORKER_CLASS
+            );
+            final Data data = new Data.Builder()
+                .putString("label", config.label)
+                .putString("src", config.src)
+                .putString("event", config.event)
+                .build();
+            final Constraints constraints = new Constraints.Builder().setRequiredNetworkType(NetworkType.CONNECTED).build();
+            final WorkManager workManager = WorkManager.getInstance(this.activity.getApplicationContext());
+
+            if (!config.repeat) {
+                final OneTimeWorkRequest work = new OneTimeWorkRequest.Builder(workerClass)
+                    .setInitialDelay(config.interval, TimeUnit.MINUTES)
+                    .setInputData(data)
+                    .addTag(config.label)
+                    .setConstraints(constraints)
+                    .build();
+                workManager.enqueueUniqueWork(config.label, ExistingWorkPolicy.REPLACE, work);
+            } else {
+                final PeriodicWorkRequest work = new PeriodicWorkRequest.Builder(workerClass, config.interval, TimeUnit.MINUTES)
+                    .setInitialDelay(config.interval, TimeUnit.MINUTES)
+                    .setInputData(data)
+                    .addTag(config.label)
+                    .setConstraints(constraints)
+                    .build();
+                workManager.enqueueUniquePeriodicWork(config.label, ExistingPeriodicWorkPolicy.UPDATE, work);
+            }
+
+            logger.info("Rescheduled Background Runner work after bundle switch.");
+        } catch (ClassNotFoundException ignored) {
+            logger.debug("Background Runner plugin not installed, skipping reschedule.");
+        } catch (Exception e) {
+            logger.warn("Failed to reschedule Background Runner work after bundle switch.");
+            logger.debug("Background Runner reschedule error: " + e.getMessage());
+        }
     }
 
     private boolean hasStoredBundleInfo(final String id) {
@@ -1070,6 +1358,27 @@ public class CapgoUpdater {
         );
     }
 
+    private void runDownloadGate() throws IOException {
+        if (this.downloadGate == null) {
+            return;
+        }
+        try {
+            this.downloadGate.run();
+        } catch (final RuntimeException e) {
+            throw new IOException(e.getMessage() == null ? "Download gate failed" : e.getMessage(), e);
+        }
+    }
+
+    private boolean runDownloadGateQuiet() {
+        try {
+            this.runDownloadGate();
+            return true;
+        } catch (final IOException e) {
+            logger.error("Download blocked by cleanup gate: " + e.getMessage());
+            return false;
+        }
+    }
+
     public void downloadBackground(
         final String url,
         final String version,
@@ -1088,6 +1397,9 @@ public class CapgoUpdater {
         final JSONArray manifest,
         final boolean setNext
     ) {
+        if (!this.runDownloadGateQuiet()) {
+            return;
+        }
         final String id = this.randomString();
 
         // Check if version is already downloading, but allow retry if previous download failed
@@ -1096,7 +1408,10 @@ public class CapgoUpdater {
             BundleInfo existingBundle = this.getBundleInfoByName(version);
             if (existingBundle != null && existingBundle.isErrorStatus()) {
                 // Cancel the failed download and allow retry
-                DownloadWorkerManager.cancelVersionDownload(this.activity, version);
+                if (!DownloadWorkerManager.cancelVersionDownloadAndAwait(this.activity, version)) {
+                    logger.error("Failed to cancel previous download before retry");
+                    return;
+                }
                 logger.info("Retrying failed download for version: " + version);
             } else {
                 logger.info("Version already downloading: " + version);
@@ -1112,11 +1427,14 @@ public class CapgoUpdater {
     }
 
     public BundleInfo download(final String url, final String version, final String sessionKey, final String checksum) throws IOException {
+        this.runDownloadGate();
         // Check for existing bundle with same version and clean up if in error state
         BundleInfo existingBundle = this.getBundleInfoByName(version);
-        if (existingBundle != null && (existingBundle.isErrorStatus() || existingBundle.isDeleted())) {
+        if (existingBundle != null && (existingBundle.isErrorStatus() || existingBundle.isDeleted() || existingBundle.isDeleting())) {
             logger.info("Found existing failed bundle for version " + version + ", deleting before retry");
-            this.delete(existingBundle.getId(), true);
+            if (!Boolean.TRUE.equals(this.delete(existingBundle.getId(), true))) {
+                throw new IOException("Failed to delete existing bundle before retry");
+            }
         }
 
         final String id = this.randomString();
@@ -1160,15 +1478,18 @@ public class CapgoUpdater {
         final String checksum,
         final JSONArray manifest
     ) throws IOException {
+        this.runDownloadGate();
         if (manifest == null) {
             return download(url, version, sessionKey, checksum);
         }
 
         // Check for existing bundle with same version and clean up if in error state
         BundleInfo existingBundle = this.getBundleInfoByName(version);
-        if (existingBundle != null && (existingBundle.isErrorStatus() || existingBundle.isDeleted())) {
+        if (existingBundle != null && (existingBundle.isErrorStatus() || existingBundle.isDeleted() || existingBundle.isDeleting())) {
             logger.info("Found existing failed bundle for version " + version + ", deleting before retry");
-            this.delete(existingBundle.getId(), true);
+            if (!Boolean.TRUE.equals(this.delete(existingBundle.getId(), true))) {
+                throw new IOException("Failed to delete existing bundle before retry");
+            }
         }
 
         final String id = this.randomString();
@@ -1233,51 +1554,96 @@ public class CapgoUpdater {
     }
 
     public Boolean delete(final String id, final Boolean removeInfo) throws IOException {
-        final BundleInfo deleted = this.getBundleInfo(id);
-        if (deleted.isBuiltin() || this.getCurrentBundleId().equals(id)) {
-            logger.error("Cannot delete current or builtin bundle");
-            logger.debug("Bundle ID: " + id);
-            return false;
-        }
-        final BundleInfo previewFallback = this.getPreviewFallbackBundle();
-        if (
-            previewFallback != null &&
-            !previewFallback.isDeleted() &&
-            !previewFallback.isErrorStatus() &&
-            previewFallback.getId().equals(id)
-        ) {
-            logger.error("Cannot delete the preview fallback bundle");
-            logger.debug("Bundle ID: " + id);
-            return false;
-        }
-        final BundleInfo next = this.getNextBundle();
-        if (next != null && !next.isDeleted() && !next.isErrorStatus() && next.getId().equals(id)) {
-            logger.error("Cannot delete the next bundle");
-            logger.debug("Bundle ID: " + id);
-            return false;
-        }
-        // Cancel download for this version if active
-        if (this.activity != null) {
-            DownloadWorkerManager.cancelVersionDownload(this.activity, deleted.getVersionName());
-        }
-        final File bundle = new File(this.documentsDir, bundleDirectory + "/" + id);
-        if (bundle.exists()) {
-            this.deleteDirectory(bundle);
-            if (!removeInfo) {
-                this.saveBundleInfo(id, deleted.setStatus(BundleStatus.DELETED));
+        return this.delete(id, removeInfo, true);
+    }
+
+    public Boolean delete(final String id, final Boolean removeInfo, final boolean cancelActiveDownload) throws IOException {
+        synchronized (this.deleteLock) {
+            final BundleInfo deleted = this.getBundleInfo(id);
+            if (deleted.isBuiltin() || this.getCurrentBundleId().equals(id)) {
+                logger.error("Cannot delete current or builtin bundle");
+                logger.debug("Bundle ID: " + id);
+                return false;
+            }
+            final BundleInfo previewFallback = this.getPreviewFallbackBundle();
+            if (
+                previewFallback != null &&
+                !previewFallback.isDeleted() &&
+                !previewFallback.isErrorStatus() &&
+                !previewFallback.isDeleting() &&
+                previewFallback.getId().equals(id)
+            ) {
+                logger.error("Cannot delete the preview fallback bundle");
+                logger.debug("Bundle ID: " + id);
+                return false;
+            }
+            final BundleInfo next = this.getNextBundle();
+            if (next != null && !next.isDeleted() && !next.isErrorStatus() && !next.isDeleting() && next.getId().equals(id)) {
+                logger.error("Cannot delete the next bundle");
+                logger.debug("Bundle ID: " + id);
+                return false;
+            }
+
+            final File bundle = this.getBundleDirectory(id);
+            final boolean hadRegistry = this.hasStoredBundleInfo(id);
+            final boolean hadFolder = bundle.exists();
+            if (!hadRegistry && !hadFolder) {
+                logger.error("Cannot delete unknown bundle");
+                logger.debug("Bundle ID: " + id);
+                return false;
+            }
+
+            // Persist DELETING before touching disk so kill/OOM can resume on next launch.
+            if (!deleted.isDeleting()) {
+                if (!this.saveBundleInfo(id, deleted.setStatus(BundleStatus.DELETING))) {
+                    logger.error("Failed to persist DELETING marker, aborting disk delete");
+                    logger.debug("Bundle ID: " + id);
+                    return false;
+                }
+            }
+
+            // Cancel download for this version if active
+            if (cancelActiveDownload && this.activity != null) {
+                if (!DownloadWorkerManager.cancelVersionDownloadAndAwait(this.activity, deleted.getVersionName())) {
+                    logger.error("Failed to cancel active download before delete");
+                    return false;
+                }
+            }
+
+            if (bundle.exists()) {
+                try {
+                    this.deleteDirectory(bundle);
+                } catch (final IOException e) {
+                    logger.error("Failed to delete bundle folder, will retry later");
+                    logger.debug("Bundle ID: " + id + ", Error: " + e.getMessage());
+                    return false;
+                }
+            }
+
+            // Only drop registry after the folder is confirmed gone.
+            if (bundle.exists()) {
+                logger.error("Bundle folder still present after delete, will retry later");
+                logger.debug("Bundle ID: " + id);
+                return false;
+            }
+
+            final boolean finalized;
+            if (Boolean.FALSE.equals(removeInfo)) {
+                finalized = this.saveBundleInfo(id, deleted.setStatus(BundleStatus.DELETED));
             } else {
-                this.removeBundleInfo(id);
+                finalized = this.saveBundleInfo(id, null);
             }
+            if (!finalized) {
+                logger.error("Failed to finalize delete registry update, will retry later");
+                logger.debug("Bundle ID: " + id);
+                return false;
+            }
+            this.sendStats("delete", deleted.getVersionName());
+            this.dequeuePendingDelete(id);
+            logger.info("Bundle deleted and confirmed gone");
+            logger.debug("Bundle ID: " + id);
             return true;
         }
-        logger.info("Bundle not found on disk");
-        logger.debug("Version: " + deleted.getVersionName());
-        // perhaps we did not find the bundle in the files, but if the user requested a delete, we delete
-        if (removeInfo) {
-            this.removeBundleInfo(id);
-        }
-        this.sendStats("delete", deleted.getVersionName());
-        return false;
     }
 
     public Boolean delete(final String id) {
@@ -1290,6 +1656,82 @@ public class CapgoUpdater {
         }
     }
 
+    /**
+     * Resume incomplete deletes one-by-one. Safe across app kill / OOM because
+     * delete() marks DELETING before disk work and only clears registry after confirm.
+     */
+    public void drainPendingDeletes() {
+        final LinkedHashSet<String> pendingIds = new LinkedHashSet<>();
+        for (final BundleInfo info : this.list(true)) {
+            if (info != null && info.isDeleting() && info.getId() != null && !info.getId().isEmpty()) {
+                pendingIds.add(info.getId());
+            }
+        }
+        pendingIds.addAll(this.getPendingDeleteIds());
+        for (final String id : pendingIds) {
+            try {
+                logger.info("Resuming pending delete for bundle: " + id);
+                if (Boolean.TRUE.equals(this.delete(id, true))) {
+                    this.dequeuePendingDelete(id);
+                }
+            } catch (final Exception e) {
+                logger.error("Pending delete failed, will retry next launch");
+                logger.debug("Bundle ID: " + id + ", Error: " + e.getMessage());
+            }
+            try {
+                Thread.sleep(DELETE_PACE_MS);
+            } catch (final InterruptedException ie) {
+                Thread.currentThread().interrupt();
+                return;
+            }
+        }
+    }
+
+    private Set<String> getPendingDeleteIds() {
+        final Set<String> ids = new LinkedHashSet<>();
+        if (this.prefs == null) {
+            return ids;
+        }
+        final String raw = this.prefs.getString(PENDING_DELETE_IDS, "");
+        if (raw == null || raw.isEmpty()) {
+            return ids;
+        }
+        for (final String part : raw.split(",")) {
+            if (part != null && !part.isEmpty()) {
+                ids.add(part);
+            }
+        }
+        return ids;
+    }
+
+    private void enqueuePendingDelete(final String id) {
+        if (id == null || id.isEmpty() || this.editor == null || this.prefs == null) {
+            return;
+        }
+        final Set<String> ids = this.getPendingDeleteIds();
+        if (!ids.add(id)) {
+            return;
+        }
+        this.editor.putString(PENDING_DELETE_IDS, String.join(",", ids));
+        this.editor.commit();
+    }
+
+    private void dequeuePendingDelete(final String id) {
+        if (id == null || id.isEmpty() || this.editor == null || this.prefs == null) {
+            return;
+        }
+        final Set<String> ids = this.getPendingDeleteIds();
+        if (!ids.remove(id)) {
+            return;
+        }
+        if (ids.isEmpty()) {
+            this.editor.remove(PENDING_DELETE_IDS);
+        } else {
+            this.editor.putString(PENDING_DELETE_IDS, String.join(",", ids));
+        }
+        this.editor.commit();
+    }
+
     private File getBundleDirectory(final String id) {
         return new File(this.documentsDir, bundleDirectory + "/" + id);
     }
@@ -1297,7 +1739,13 @@ public class CapgoUpdater {
     private boolean bundleExists(final String id) {
         final File bundle = this.getBundleDirectory(id);
         final BundleInfo bundleInfo = this.getBundleInfo(id);
-        return (bundle.isDirectory() && bundle.exists() && new File(bundle.getPath(), "/index.html").exists() && !bundleInfo.isDeleted());
+        return (
+            bundle.isDirectory() &&
+            bundle.exists() &&
+            new File(bundle.getPath(), "/index.html").exists() &&
+            !bundleInfo.isDeleted() &&
+            !bundleInfo.isDeleting()
+        );
     }
 
     static final class ResetState {
@@ -1476,21 +1924,54 @@ public class CapgoUpdater {
         // Only attempt to delete when the fallback is a different bundle than the
         // currently loaded one. Otherwise we spam logs with "Cannot delete <id>"
         // because delete() protects the current bundle from removal.
-        if (
-            autoDeletePrevious &&
+        final String previousFallbackId = fallback.getId();
+        final String previousFallbackVersion = fallback.getVersionName();
+        final BundleInfo nextBundle = this.getNextBundle();
+        final boolean previousIsNext =
+            nextBundle != null &&
+            previousFallbackId != null &&
+            previousFallbackId.equals(nextBundle.getId()) &&
+            !nextBundle.isDeleted() &&
+            !nextBundle.isErrorStatus() &&
+            !nextBundle.isDeleting();
+        final boolean shouldDeletePrevious =
+            Boolean.TRUE.equals(autoDeletePrevious) &&
             !fallback.isBuiltin() &&
-            fallback.getId() != null &&
-            !fallback.getId().equals(bundle.getId()) &&
-            !fallbackIsPreviewFallback
-        ) {
-            final Boolean res = this.delete(fallback.getId());
-            if (res) {
-                logger.info("Deleted previous bundle: " + fallback.getVersionName());
-            } else {
-                logger.debug("Skip deleting previous bundle (same as current or protected): " + fallback.getId());
+            previousFallbackId != null &&
+            !previousFallbackId.equals(bundle.getId()) &&
+            !fallbackIsPreviewFallback &&
+            !previousIsNext;
+        if (shouldDeletePrevious) {
+            if (!this.saveBundleInfo(previousFallbackId, fallback.setStatus(BundleStatus.DELETING))) {
+                logger.error("Failed to persist DELETING for previous bundle; queueing durable retry");
+                logger.debug("Bundle ID: " + previousFallbackId);
+                this.enqueuePendingDelete(previousFallbackId);
             }
         }
+        boolean deletePreviousAsync = shouldDeletePrevious;
         this.setFallbackBundle(bundle);
+        if (deletePreviousAsync) {
+            final String asyncPreviousFallbackId = previousFallbackId;
+            final String asyncPreviousFallbackVersion = previousFallbackVersion;
+            io.execute(() -> {
+                if (this.activity != null) {
+                    if (!DownloadWorkerManager.cancelVersionDownloadAndAwait(this.activity, asyncPreviousFallbackVersion)) {
+                        logger.error("Failed to cancel previous version download before delete");
+                        return;
+                    }
+                }
+                try {
+                    final Boolean res = this.delete(asyncPreviousFallbackId, true, false);
+                    if (Boolean.TRUE.equals(res)) {
+                        logger.info("Deleted previous bundle: " + asyncPreviousFallbackVersion);
+                    } else {
+                        logger.debug("Previous bundle delete incomplete, will retry: " + asyncPreviousFallbackId);
+                    }
+                } catch (final IOException e) {
+                    logger.error("Failed to delete previous bundle: " + asyncPreviousFallbackId + " " + e.getMessage());
+                }
+            });
+        }
     }
 
     public void setError(final BundleInfo bundle) {
@@ -1532,30 +2013,185 @@ public class CapgoUpdater {
         return json;
     }
 
+    private static final class RemoteBlockResult {
+
+        final boolean blocked;
+        final String error;
+        final String message;
+
+        RemoteBlockResult(final boolean blocked, final String error, final String message) {
+            this.blocked = blocked;
+            this.error = error;
+            this.message = message;
+        }
+    }
+
     /**
-     * Check if a 429 (Too Many Requests) response was received and set the flag
+     * Handle HTTP 429 responses by honouring Retry-After / rateLimitResetAt.
+     * All 429s use the same temporary client block — no sticky latch until restart.
      */
-    private boolean checkAndHandleRateLimitResponse(Response response) {
-        if (response.code() == 429) {
-            // Send a statistic about the rate limit BEFORE setting the flag
-            // Only send once to prevent infinite loop if the stat request itself gets rate limited
-            if (!this.previewSession && !rateLimitExceeded && !rateLimitStatisticSent) {
-                rateLimitStatisticSent = true;
-                sendRateLimitStatistic();
-            }
-            rateLimitExceeded = true;
-            logger.warn("Rate limit exceeded (429). Stopping all stats and channel requests until app restart.");
+    private RemoteBlockResult checkAndHandleRateLimitResponse(Response response, String responseData) {
+        if (response == null || response.code() != 429) {
+            return new RemoteBlockResult(false, "", "");
+        }
+
+        final String parsedError = parseRemoteError(responseData);
+        final String parsedMessage = parseRemoteMessage(responseData);
+        final String errorCode = parsedError.isEmpty() ? "too_many_requests" : parsedError;
+        final String message = parsedMessage.isEmpty() ? "Too many requests" : parsedMessage;
+
+        final long retryUntilMs = resolveRateLimitBlockedUntilMs(response, responseData);
+        synchronized (rateLimitStateLock) {
+            if (retryUntilMs > rateLimitBlockedUntilMs) {
+                rateLimitBlockedUntilMs = retryUntilMs;
+                rateLimitBlockedError = errorCode;
+                rateLimitBlockedMessage = message;
+            } else if (rateLimitBlockedUntilMs <= 0L) {
+                rateLimitBlockedError = errorCode;
+                rateLimitBlockedMessage = message;
+            }
+        }
+
+        // Claim last, and only when there is somewhere to send it, so a 429 burst with no
+        // stats URL does not claim and release the latch once per response.
+        if ("too_many_requests".equals(errorCode) && !this.previewSession && this.hasStatsUrl() && claimRateLimitStatistic()) {
+            sendRateLimitStatistic();
+        }
+
+        final long nowMs = System.currentTimeMillis();
+        final long retryAfter = Math.max(0L, (Math.max(retryUntilMs, nowMs) - nowMs + 999L) / 1000L);
+        logger.warn("Received 429 (" + errorCode + "). Honouring Retry-After: " + retryAfter + "s.");
+        return new RemoteBlockResult(true, errorCode, message);
+    }
+
+    private String parseRemoteError(final String responseData) {
+        if (responseData == null || responseData.isEmpty()) {
+            return "";
+        }
+        try {
+            final JSONObject json = new JSONObject(responseData);
+            return json.optString("error", "");
+        } catch (JSONException ignored) {
+            return "";
+        }
+    }
+
+    private String parseRemoteMessage(final String responseData) {
+        if (responseData == null || responseData.isEmpty()) {
+            return "";
+        }
+        try {
+            final JSONObject json = new JSONObject(responseData);
+            return json.optString("message", "");
+        } catch (JSONException ignored) {
+            return "";
+        }
+    }
+
+    private long resolveRateLimitBlockedUntilMs(final Response response, final String responseData) {
+        final long nowMs = System.currentTimeMillis();
+        final double candidate = rawRateLimitDeadlineMs(response, responseData, nowMs);
+        // NaN and past deadlines mean "no client-side block"; anything further out is capped.
+        if (!(candidate > nowMs)) {
+            return 0L;
+        }
+        return (long) Math.min(candidate, (double) nowMs + MAX_RATE_LIMIT_WINDOW_MS);
+    }
+
+    private double rawRateLimitDeadlineMs(final Response response, final String responseData, final long nowMs) {
+        final String header = response.header("Retry-After");
+        if (header != null) {
+            try {
+                final double seconds = Double.parseDouble(header.trim());
+                if (seconds >= 0) {
+                    return nowMs + seconds * 1000d;
+                }
+            } catch (NumberFormatException ignored) {
+                // Fall through to body fields
+            }
+        }
+
+        if (responseData != null && !responseData.isEmpty()) {
+            try {
+                final JSONObject json = new JSONObject(responseData);
+                final JSONObject moreInfo = json.optJSONObject("moreInfo");
+                if (moreInfo != null && moreInfo.has("retryAfterSeconds")) {
+                    final double retryAfter = moreInfo.getDouble("retryAfterSeconds");
+                    if (retryAfter >= 0) {
+                        return nowMs + retryAfter * 1000d;
+                    }
+                } else if (json.has("retryAfterSeconds")) {
+                    final double retryAfter = json.getDouble("retryAfterSeconds");
+                    if (retryAfter >= 0) {
+                        return nowMs + retryAfter * 1000d;
+                    }
+                }
+                if (moreInfo != null && moreInfo.has("rateLimitResetAt")) {
+                    return moreInfo.getDouble("rateLimitResetAt");
+                } else if (json.has("rateLimitResetAt")) {
+                    return json.getDouble("rateLimitResetAt");
+                }
+            } catch (JSONException ignored) {
+                // No retry hint
+            }
+        }
+
+        // No retry hint — do not hold a client-side block; allow immediate retry to the worker
+        return 0d;
+    }
+
+    private static boolean claimRateLimitStatistic() {
+        synchronized (rateLimitStateLock) {
+            if (rateLimitStatisticSent) {
+                return false;
+            }
+            rateLimitStatisticSent = true;
             return true;
         }
-        return false;
     }
 
     /**
-     * Send a synchronous statistic about rate limiting
+     * Give the claim back when the statistic never made it out, so a later 429 can retry it.
+     */
+    private static void releaseRateLimitStatisticClaim() {
+        synchronized (rateLimitStateLock) {
+            rateLimitStatisticSent = false;
+        }
+    }
+
+    private boolean hasStatsUrl() {
+        final String url = this.statsUrl;
+        return url != null && !url.isEmpty();
+    }
+
+    private boolean isRemoteBlocked() {
+        synchronized (rateLimitStateLock) {
+            if (rateLimitBlockedUntilMs <= 0L) {
+                return false;
+            }
+            if (System.currentTimeMillis() >= rateLimitBlockedUntilMs) {
+                rateLimitBlockedUntilMs = 0L;
+                return false;
+            }
+            return true;
+        }
+    }
+
+    private RemoteBlockResult remoteBlockedClientError() {
+        synchronized (rateLimitStateLock) {
+            return new RemoteBlockResult(true, rateLimitBlockedError, rateLimitBlockedMessage);
+        }
+    }
+
+    /**
+     * Send a statistic about rate limiting.
+     * Dispatched through OkHttp so no caller thread waits on the request.
      */
     private void sendRateLimitStatistic() {
         String statsUrl = this.statsUrl;
         if (statsUrl == null || statsUrl.isEmpty()) {
+            // The URL was cleared after the claim was taken; nothing went out, so hand it back.
+            releaseRateLimitStatisticClaim();
             return;
         }
 
@@ -1571,17 +2207,33 @@ public class CapgoUpdater {
                 .post(RequestBody.create(json.toString(), MediaType.get("application/json")))
                 .build();
 
-            // Send synchronously to ensure it goes out before the flag is set
             // User-Agent header is automatically added by DownloadService.sharedClient interceptor
-            try (Response response = DownloadService.sharedClient.newCall(request).execute()) {
-                if (response.isSuccessful()) {
-                    logger.info("Rate limit statistic sent");
-                } else {
-                    logger.error("Error sending rate limit statistic");
-                    logger.debug("Response code: " + response.code());
+            DownloadService.sharedClient.newCall(request).enqueue(
+                new okhttp3.Callback() {
+                    @Override
+                    public void onFailure(@NonNull Call call, @NonNull IOException e) {
+                        releaseRateLimitStatisticClaim();
+                        logger.error("Failed to send rate limit statistic");
+                        logger.debug("Error: " + e.getMessage());
+                    }
+
+                    @Override
+                    public void onResponse(@NonNull Call call, @NonNull Response response) {
+                        // The body is unused here; closing the Response closes it.
+                        try (response) {
+                            if (response.isSuccessful()) {
+                                logger.info("Rate limit statistic sent");
+                            } else {
+                                releaseRateLimitStatisticClaim();
+                                logger.error("Error sending rate limit statistic");
+                                logger.debug("Response code: " + response.code());
+                            }
+                        }
+                    }
                 }
-            }
+            );
         } catch (final Exception e) {
+            releaseRateLimitStatisticClaim();
             logger.error("Failed to send rate limit statistic");
             logger.debug("Error: " + e.getMessage());
         }
@@ -1620,7 +2272,27 @@ public class CapgoUpdater {
 
                         if (jsonResponse != null && (jsonResponse.has("error") || jsonResponse.has("kind"))) {
                             if (statusCode == 429) {
-                                checkAndHandleRateLimitResponse(response);
+                                final RemoteBlockResult rateLimit = checkAndHandleRateLimitResponse(response, responseData);
+                                Map<String, Object> retError = new HashMap<>();
+                                retError.put(
+                                    "error",
+                                    rateLimit.error.isEmpty() ? jsonResponse.optString("error", "too_many_requests") : rateLimit.error
+                                );
+                                retError.put(
+                                    "message",
+                                    rateLimit.message.isEmpty() ? jsonResponse.optString("message", "Too many requests") : rateLimit.message
+                                );
+                                if (jsonResponse.has("kind") && !jsonResponse.isNull("kind")) {
+                                    retError.put("kind", jsonResponse.getString("kind"));
+                                } else {
+                                    retError.put("kind", "failed");
+                                }
+                                if (jsonResponse.has("version") && !jsonResponse.isNull("version")) {
+                                    retError.put("version", jsonResponse.getString("version"));
+                                }
+                                retError.put("statusCode", statusCode);
+                                callback.callback(retError);
+                                return;
                             }
                             Map<String, Object> retError = new HashMap<>();
                             if (jsonResponse.has("error") && !jsonResponse.isNull("error")) {
@@ -1642,11 +2314,12 @@ public class CapgoUpdater {
                             return;
                         }
 
-                        // Check for 429 rate limit
-                        if (checkAndHandleRateLimitResponse(response)) {
+                        // Check for 429 rate limit without JSON body
+                        final RemoteBlockResult rateLimit = checkAndHandleRateLimitResponse(response, responseData);
+                        if (rateLimit.blocked) {
                             Map<String, Object> retError = new HashMap<>();
-                            retError.put("message", "Rate limit exceeded");
-                            retError.put("error", "rate_limit_exceeded");
+                            retError.put("message", rateLimit.message);
+                            retError.put("error", rateLimit.error);
                             retError.put("kind", "failed");
                             retError.put("statusCode", statusCode);
                             callback.callback(retError);
@@ -1699,6 +2372,16 @@ public class CapgoUpdater {
     }
 
     public void getLatest(final String updateUrl, final String channel, final String appIdOverride, final Callback callback) {
+        if (isRemoteBlocked()) {
+            final RemoteBlockResult blocked = remoteBlockedClientError();
+            logger.debug("Skipping getLatest due to remote block (" + blocked.error + ").");
+            final Map<String, Object> retError = new HashMap<>();
+            retError.put("message", blocked.message);
+            retError.put("error", blocked.error);
+            retError.put("kind", "failed");
+            callback.callback(retError);
+            return;
+        }
         JSONObject json;
         try {
             json = this.createInfoObject(appIdOverride);
@@ -1768,12 +2451,12 @@ public class CapgoUpdater {
             return;
         }
 
-        // Check if rate limit was exceeded
-        if (rateLimitExceeded) {
-            logger.debug("Skipping setChannel due to rate limit (429). Requests will resume after app restart.");
+        if (isRemoteBlocked()) {
+            final RemoteBlockResult blocked = remoteBlockedClientError();
+            logger.debug("Skipping setChannel due to remote block (" + blocked.error + ").");
             final Map<String, Object> retError = new HashMap<>();
-            retError.put("message", "Rate limit exceeded");
-            retError.put("error", "rate_limit_exceeded");
+            retError.put("message", blocked.message);
+            retError.put("error", blocked.error);
             callback.callback(retError);
             return;
         }
@@ -1813,7 +2496,6 @@ public class CapgoUpdater {
                 logger.info("Public channel requested, channel override removed");
                 callback.callback(res);
             } else {
-                // Success - persist defaultChannel
                 this.defaultChannel = channel;
                 editor.putString(defaultChannelKey, channel);
                 editor.apply();
@@ -1828,12 +2510,12 @@ public class CapgoUpdater {
     }
 
     public void getChannel(final Callback callback, final SharedPreferences.Editor editor, final String defaultChannelKey) {
-        // Check if rate limit was exceeded
-        if (rateLimitExceeded) {
-            logger.debug("Skipping getChannel due to rate limit (429). Requests will resume after app restart.");
+        if (isRemoteBlocked()) {
+            final RemoteBlockResult blocked = remoteBlockedClientError();
+            logger.debug("Skipping getChannel due to remote block (" + blocked.error + ").");
             final Map<String, Object> retError = new HashMap<>();
-            retError.put("message", "Rate limit exceeded");
-            retError.put("error", "rate_limit_exceeded");
+            retError.put("message", blocked.message);
+            retError.put("error", blocked.error);
             callback.callback(retError);
             return;
         }
@@ -1878,25 +2560,18 @@ public class CapgoUpdater {
                 @Override
                 public void onResponse(@NonNull Call call, @NonNull Response response) throws IOException {
                     try (ResponseBody responseBody = response.body()) {
-                        // Check for 429 rate limit
-                        if (checkAndHandleRateLimitResponse(response)) {
+                        final String responseData = responseBody != null ? responseBody.string() : "";
+                        final RemoteBlockResult rateLimit = checkAndHandleRateLimitResponse(response, responseData);
+                        if (rateLimit.blocked) {
                             Map<String, Object> retError = new HashMap<>();
-                            retError.put("message", "Rate limit exceeded");
-                            retError.put("error", "rate_limit_exceeded");
+                            retError.put("message", rateLimit.message);
+                            retError.put("error", rateLimit.error);
                             callback.callback(retError);
                             return;
                         }
 
                         if (response.code() == 400) {
-                            if (responseBody == null) {
-                                Map<String, Object> retError = new HashMap<>();
-                                retError.put("message", "Empty response body");
-                                retError.put("error", "no_response_body");
-                                callback.callback(retError);
-                                return;
-                            }
-                            String data = responseBody.string();
-                            if (data.contains("channel_not_found") && !defaultChannel.isEmpty()) {
+                            if (responseData.contains("channel_not_found") && !defaultChannel.isEmpty()) {
                                 Map<String, Object> ret = new HashMap<>();
                                 ret.put("channel", defaultChannel);
                                 ret.put("status", "default");
@@ -1914,14 +2589,13 @@ public class CapgoUpdater {
                             return;
                         }
 
-                        if (responseBody == null) {
+                        if (responseData.isEmpty()) {
                             Map<String, Object> retError = new HashMap<>();
                             retError.put("message", "Empty response body");
                             retError.put("error", "no_response_body");
                             callback.callback(retError);
                             return;
                         }
-                        String responseData = responseBody.string();
                         JSONObject jsonResponse = new JSONObject(responseData);
 
                         // Check for server-side errors first
@@ -1979,12 +2653,12 @@ public class CapgoUpdater {
     }
 
     public void listChannels(final Callback callback) {
-        // Check if rate limit was exceeded
-        if (rateLimitExceeded) {
-            logger.debug("Skipping listChannels due to rate limit (429). Requests will resume after app restart.");
+        if (isRemoteBlocked()) {
+            final RemoteBlockResult blocked = remoteBlockedClientError();
+            logger.debug("Skipping listChannels due to remote block (" + blocked.error + ").");
             final Map<String, Object> retError = new HashMap<>();
-            retError.put("message", "Rate limit exceeded");
-            retError.put("error", "rate_limit_exceeded");
+            retError.put("message", blocked.message);
+            retError.put("error", blocked.error);
             callback.callback(retError);
             return;
         }
@@ -2043,11 +2717,12 @@ public class CapgoUpdater {
                 @Override
                 public void onResponse(@NonNull Call call, @NonNull Response response) throws IOException {
                     try (ResponseBody responseBody = response.body()) {
-                        // Check for 429 rate limit
-                        if (checkAndHandleRateLimitResponse(response)) {
+                        final String data = responseBody != null ? responseBody.string() : "";
+                        final RemoteBlockResult rateLimit = checkAndHandleRateLimitResponse(response, data);
+                        if (rateLimit.blocked) {
                             Map<String, Object> retError = new HashMap<>();
-                            retError.put("message", "Rate limit exceeded");
-                            retError.put("error", "rate_limit_exceeded");
+                            retError.put("message", rateLimit.message);
+                            retError.put("error", rateLimit.error);
                             callback.callback(retError);
                             return;
                         }
@@ -2060,14 +2735,13 @@ public class CapgoUpdater {
                             return;
                         }
 
-                        if (responseBody == null) {
+                        if (data.isEmpty()) {
                             Map<String, Object> retError = new HashMap<>();
                             retError.put("message", "Empty response body");
                             retError.put("error", "no_response_body");
                             callback.callback(retError);
                             return;
                         }
-                        String data = responseBody.string();
 
                         try {
                             Map<String, Object> ret = parseListChannelsResponse(data);
@@ -2155,6 +2829,10 @@ public class CapgoUpdater {
         final Map<String, String> metadata,
         final Runnable onSent
     ) {
+        if (statsStopped.get()) {
+            return;
+        }
+
         if (this.previewSession) {
             if (logger != null) {
                 logger.debug("Skipping sendStats during preview session.");
@@ -2162,12 +2840,6 @@ public class CapgoUpdater {
             return;
         }
 
-        // Check if rate limit was exceeded
-        if (rateLimitExceeded) {
-            logger.debug("Skipping sendStats due to rate limit (429). Stats will resume after app restart.");
-            return;
-        }
-
         String statsUrl = this.statsUrl;
         if (statsUrl == null || statsUrl.isEmpty()) {
             return;
@@ -2184,16 +2856,190 @@ public class CapgoUpdater {
                 json.put("metadata", new JSONObject(metadata));
             }
         } catch (JSONException e) {
-            logger.error("Error preparing stats");
-            logger.debug("JSONException: " + e.getMessage());
+            if (logger != null) {
+                logger.error("Error preparing stats");
+                logger.debug("JSONException: " + e.getMessage());
+            }
             return;
         }
 
-        statsQueue.add(new QueuedStatsEvent(json, onSent));
+        synchronized (statsQueue) {
+            if (statsStopped.get()) {
+                return;
+            }
+            while (statsQueue.size() >= MAX_PENDING_STATS) {
+                statsQueue.remove(0);
+            }
+            statsQueue.add(new QueuedStatsEvent(json, onSent));
+        }
         ensureStatsTimerStarted();
     }
 
+    public void restorePendingStats() {
+        File file = pendingStatsFile();
+        if (file == null) {
+            return;
+        }
+        File backup = new File(file.getAbsolutePath() + ".bak");
+        if (!file.exists() && backup.exists() && !backup.renameTo(file)) {
+            if (logger != null) {
+                logger.error("Failed to restore stats backup");
+            }
+            return;
+        }
+        if (!file.exists()) {
+            return;
+        }
+        try {
+            String raw = readFileUtf8(file);
+            JSONArray arr = new JSONArray(raw);
+            synchronized (statsQueue) {
+                for (int i = 0; i < arr.length(); i++) {
+                    if (statsQueue.size() >= MAX_PENDING_STATS) {
+                        break;
+                    }
+                    statsQueue.add(new QueuedStatsEvent(arr.getJSONObject(i), null));
+                }
+            }
+            if (backup.exists() && !backup.delete()) {
+                if (logger != null) {
+                    logger.error("Failed to delete stats backup");
+                }
+            }
+            if (!statsQueue.isEmpty()) {
+                if (logger != null) {
+                    logger.info("Restored " + statsQueue.size() + " pending stats events");
+                }
+                ensureStatsTimerStarted();
+            }
+        } catch (Exception e) {
+            if (logger != null) {
+                logger.error("Failed to restore pending stats");
+                logger.debug("Error: " + e.getMessage());
+            }
+        }
+    }
+
+    int pendingStatsCount() {
+        return statsQueue.size();
+    }
+
+    public void persistPendingStats() {
+        persistStatsQueue();
+    }
+
+    private File pendingStatsFile() {
+        final File dir = this.noBackupDir != null ? this.noBackupDir : this.documentsDir;
+        if (dir == null) {
+            return null;
+        }
+        return new File(dir, PENDING_STATS_FILE);
+    }
+
+    private void persistStatsQueue() {
+        persistStatsQueue(false);
+    }
+
+    private void persistStatsQueue(final boolean force) {
+        File file = pendingStatsFile();
+        if (file == null) {
+            return;
+        }
+        synchronized (pendingStatsPersistLock) {
+            if (statsStopped.get() && !force) {
+                return;
+            }
+            JSONArray arr = new JSONArray();
+            synchronized (statsQueue) {
+                final List<QueuedStatsEvent> combined = new ArrayList<>(statsInFlight.size() + statsQueue.size());
+                combined.addAll(statsInFlight);
+                combined.addAll(statsQueue);
+                final int start = Math.max(0, combined.size() - MAX_PENDING_STATS);
+                for (int i = start; i < combined.size(); i++) {
+                    arr.put(combined.get(i).event);
+                }
+            }
+            try {
+                if (arr.length() == 0) {
+                    writeFileAtomically(file, "[]".getBytes(StandardCharsets.UTF_8));
+                    File backup = new File(file.getAbsolutePath() + ".bak");
+                    if (backup.exists() && !backup.delete()) {
+                        if (logger != null) {
+                            logger.error("Failed to delete empty stats backup");
+                        }
+                    }
+                    return;
+                }
+                writeFileAtomically(file, arr.toString().getBytes(StandardCharsets.UTF_8));
+            } catch (Exception e) {
+                if (logger != null) {
+                    logger.error("Failed to persist stats queue");
+                    logger.debug("Error: " + e.getMessage());
+                }
+            }
+        }
+    }
+
+    private static String readFileUtf8(final File file) throws IOException {
+        final long length = file.length();
+        final byte[] buf = new byte[length > Integer.MAX_VALUE ? Integer.MAX_VALUE : (int) length];
+        try (FileInputStream in = new FileInputStream(file)) {
+            int offset = 0;
+            while (offset < buf.length) {
+                final int read = in.read(buf, offset, buf.length - offset);
+                if (read < 0) {
+                    break;
+                }
+                offset += read;
+            }
+            return new String(buf, 0, offset, StandardCharsets.UTF_8);
+        }
+    }
+
+    private void writeFileAtomically(final File file, final byte[] bytes) throws IOException {
+        final File tmp = new File(file.getAbsolutePath() + ".tmp");
+        File backup = null;
+        try {
+            try (FileOutputStream out = new FileOutputStream(tmp)) {
+                out.write(bytes);
+                out.flush();
+            }
+            if (tmp.renameTo(file)) {
+                return;
+            }
+            if (file.exists()) {
+                backup = new File(file.getAbsolutePath() + ".bak");
+                if (backup.exists() && !backup.delete()) {
+                    throw new IOException("Failed to replace " + file.getAbsolutePath());
+                }
+                if (!file.renameTo(backup)) {
+                    throw new IOException("Failed to replace " + file.getAbsolutePath());
+                }
+            }
+            if (tmp.renameTo(file)) {
+                if (backup != null && backup.exists() && !backup.delete()) {
+                    if (logger != null) {
+                        logger.error("Failed to delete stats backup");
+                    }
+                }
+                backup = null;
+                return;
+            }
+            throw new IOException("Failed to persist " + file.getAbsolutePath());
+        } finally {
+            if (backup != null && !file.exists()) {
+                backup.renameTo(file);
+            }
+            if (tmp.exists() && !tmp.delete()) {
+                tmp.deleteOnExit();
+            }
+        }
+    }
+
     private synchronized void ensureStatsTimerStarted() {
+        if (statsStopped.get()) {
+            return;
+        }
         if (statsFlushTask == null || statsFlushTask.isCancelled() || statsFlushTask.isDone()) {
             statsFlushTask = statsScheduler.scheduleAtFixedRate(
                 this::flushStatsQueue,
@@ -2205,25 +3051,45 @@ public class CapgoUpdater {
     }
 
     private void flushStatsQueue() {
+        if (statsStopped.get()) {
+            return;
+        }
         if (statsQueue.isEmpty()) {
             return;
         }
 
+        // While Retry-After is active, keep stats queued and skip the network call.
+        if (isRemoteBlocked()) {
+            logger.debug("Deferring stats flush until Retry-After expires.");
+            return;
+        }
+
         String statsUrl = this.statsUrl;
         if (statsUrl == null || statsUrl.isEmpty()) {
-            statsQueue.clear();
+            synchronized (statsQueue) {
+                statsQueue.clear();
+                statsInFlight.clear();
+            }
+            persistStatsQueue();
+            return;
+        }
+
+        if (!statsFlushInFlight.compareAndSet(false, true)) {
             return;
         }
 
-        // Copy and clear the queue atomically using synchronized block
-        List<QueuedStatsEvent> eventsToSend;
+        final List<QueuedStatsEvent> eventsToSend;
         synchronized (statsQueue) {
             if (statsQueue.isEmpty()) {
+                statsFlushInFlight.set(false);
                 return;
             }
             eventsToSend = new ArrayList<>(statsQueue);
             statsQueue.clear();
+            statsInFlight.clear();
+            statsInFlight.addAll(eventsToSend);
         }
+        persistStatsQueue();
 
         JSONArray jsonArray = new JSONArray();
         for (QueuedStatsEvent queuedEvent : eventsToSend) {
@@ -2240,32 +3106,93 @@ public class CapgoUpdater {
             new okhttp3.Callback() {
                 @Override
                 public void onFailure(@NonNull Call call, @NonNull IOException e) {
-                    logger.error("Failed to send stats batch");
-                    logger.debug("Error: " + e.getMessage());
+                    if (abandonStoppedStatsFlush()) {
+                        return;
+                    }
+                    requeueStatsEvents(eventsToSend);
+                    if (logger != null) {
+                        logger.error("Failed to send stats batch");
+                        logger.debug("Error: " + e.getMessage());
+                    }
+                    statsFlushInFlight.set(false);
                 }
 
                 @Override
                 public void onResponse(@NonNull Call call, @NonNull Response response) throws IOException {
                     try (ResponseBody responseBody = response.body()) {
-                        // Check for 429 rate limit
-                        if (checkAndHandleRateLimitResponse(response)) {
+                        if (abandonStoppedStatsFlush()) {
+                            return;
+                        }
+                        final String responseData = responseBody != null ? responseBody.string() : "";
+                        if (checkAndHandleRateLimitResponse(response, responseData).blocked) {
+                            requeueStatsEvents(eventsToSend);
                             return;
                         }
 
                         if (response.isSuccessful()) {
-                            logger.info("Stats batch sent successfully");
-                            logger.debug("Sent " + eventCount + " events");
+                            synchronized (statsQueue) {
+                                statsInFlight.clear();
+                            }
+                            persistStatsQueue();
+                            if (logger != null) {
+                                logger.info("Stats batch sent successfully");
+                                logger.debug("Sent " + eventCount + " events");
+                            }
                             runStatsCallbacks(eventsToSend);
+                        } else if (isTransientStatsFailure(response.code())) {
+                            requeueStatsEvents(eventsToSend);
+                            if (logger != null) {
+                                logger.error("Error sending stats batch");
+                                logger.debug("Retrying later, response code: " + response.code());
+                            }
                         } else {
-                            logger.error("Error sending stats batch");
-                            logger.debug("Response code: " + response.code());
+                            synchronized (statsQueue) {
+                                statsInFlight.clear();
+                            }
+                            persistStatsQueue();
+                            if (logger != null) {
+                                logger.error("Dropping stats batch after permanent error");
+                                logger.debug("Response code: " + response.code());
+                            }
                         }
+                    } finally {
+                        statsFlushInFlight.set(false);
                     }
                 }
             }
         );
     }
 
+    private boolean abandonStoppedStatsFlush() {
+        if (!statsStopped.get()) {
+            return false;
+        }
+        statsFlushInFlight.set(false);
+        return true;
+    }
+
+    /**
+     * Only 429, request timeout and 5xx are worth retrying; other 4xx are permanent rejections.
+     */
+    private static boolean isTransientStatsFailure(final int statusCode) {
+        return statusCode == 429 || statusCode == 408 || statusCode >= 500;
+    }
+
+    private void requeueStatsEvents(final List<QueuedStatsEvent> events) {
+        if (statsStopped.get() || events == null || events.isEmpty()) {
+            return;
+        }
+        synchronized (statsQueue) {
+            statsInFlight.clear();
+            statsQueue.addAll(0, events);
+            while (statsQueue.size() > MAX_PENDING_STATS) {
+                statsQueue.remove(0);
+            }
+        }
+        persistStatsQueue();
+        ensureStatsTimerStarted();
+    }
+
     private void runStatsCallbacks(final List<QueuedStatsEvent> sentEvents) {
         for (final QueuedStatsEvent sentEvent : sentEvents) {
             if (sentEvent.onSent == null) {
@@ -2333,10 +3260,10 @@ public class CapgoUpdater {
         this.saveBundleInfo(id, null);
     }
 
-    public void saveBundleInfo(final String id, final BundleInfo info) {
+    public boolean saveBundleInfo(final String id, final BundleInfo info) {
         if (id == null || (info != null && (info.isBuiltin() || info.isUnknown()))) {
             logger.debug("Not saving info for bundle: [" + id + "] " + info);
-            return;
+            return false;
         }
 
         if (info == null) {
@@ -2348,7 +3275,7 @@ public class CapgoUpdater {
             logger.debug("Storing info for bundle [" + id + "] " + update.getClass().getName() + " -> " + jsonString);
             this.editor.putString(id + INFO_SUFFIX, jsonString);
         }
-        this.editor.commit();
+        return this.editor.commit();
     }
 
     private void setBundleStatus(final String id, final BundleStatus status) {
@@ -2453,14 +3380,15 @@ public class CapgoUpdater {
      * Should be called when the plugin is destroyed to prevent resource leaks.
      */
     public void shutdown() {
+        statsStopped.set(true);
         // Cancel the scheduled task
         if (statsFlushTask != null) {
             statsFlushTask.cancel(false);
             statsFlushTask = null;
         }
 
-        // Flush any remaining stats before shutdown
-        flushStatsQueue();
+        // Write once, then ignore later callbacks so they cannot delete a newer instance's file.
+        persistStatsQueue(true);
 
         // Shutdown the scheduler
         statsScheduler.shutdown();