fix(files): recover folder grant ownership

ADAPTER_ARCHITECTURE.md

@@ -192,8 +192,33 @@ Each boundary has a corresponding test responsibility:
   permission denial, confirmation, adaptive layout, and keyboard/touch access.
 - Platform tests cover credential stores, filesystem paths and providers,
   background scheduling, external handoff, packaging, and lifecycle recovery.
+
+Android folder capability cleanup uses demand-driven one-time WorkManager work.
+Empty stores and committed pairs do not keep cleanup work alive. Outstanding
+selections retain a retry owner until bound or abandoned; reconciliation preserves
+selections already delivered to an open setup.
+Folder-picker acquisition and durable scheduling run on the picker's owned IO
+scope, with result delivery on Main and cancellation cleanup retained on IO.
+New acquisitions and cleanup requests schedule recovery, and unfinished cleanup
+retains bounded WorkManager backoff.
+A process restoration grace period protects pending folder drafts only while
+acquiring or ready selections remain after reconciliation; completed setup and
+cleanup return without waiting. A cancelled pair save preserves authoritative
+ownership recovery and then rethrows cancellation, even when the save committed.
+Abandoned acquisitions and committed pair removals retain cleanup evidence until access
+is released. Cleanup retries do not transfer or delete user file contents.
 - Live-server audits use synthetic disposable accounts, record exact tested
   versions, and remain separate from deterministic unit and integration tests.
+A durably removed Android folder-sync pair reports completion while its previously
+scheduled capability recovery worker retries any remaining permission cleanup.
+Ambiguous coordinator saves still require authoritative confirmation of removal.
+Account retirement remains strict until its capability cleanup finishes.
+Cancellation from grant, storage, and cipher adapters remains cancellation rather
+than being reported as damaged recovery metadata or deferred cleanup.
+Reconciliation records independent cleanup progress before reporting a failed
+provider, so one unavailable grant cannot indefinitely retain unrelated grants.
+A legacy shared root can regain expired access only for an account that still
+owns a recorded pair at that exact root in the authoritative coordinator.
 
 A bug fix adds the smallest regression test at the layer where the invariant
 failed. Tests should assert public behavior, not copied implementation details.

androidApp/src/main/kotlin/dev/obiente/nextcloudnative/AndroidFileSyncCapabilityRecoveryWork.kt

@@ -0,0 +1,84 @@
+package dev.obiente.nextcloudnative
+
+import android.content.Context
+import androidx.work.BackoffPolicy
+import androidx.work.CoroutineWorker
+import androidx.work.ExistingWorkPolicy
+import androidx.work.OneTimeWorkRequestBuilder
+import androidx.work.WorkManager
+import androidx.work.WorkerParameters
+import androidx.work.await
+import java.util.concurrent.TimeUnit
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.runBlocking
+import kotlinx.coroutines.withTimeout
+import kotlinx.coroutines.sync.withLock
+import kotlinx.coroutines.withContext
+
+internal fun startAndroidFileSyncCapabilityRecovery(
+    context: Context,
+    scope: CoroutineScope,
+    load: () -> AndroidFileSyncPersistedState,
+    capabilities: AndroidFileSyncCapabilityLifecycle,
+) {
+    scope.launch {
+        try {
+            // Retire the old unconditional periodic schedule after upgrading.
+            WorkManager.getInstance(context).cancelUniqueWork("file-sync-capability-cleanup-v1").await()
+            AndroidFileSyncEngine.ENGINE_LOCK.withLock {
+                capabilities.reconcile(load())
+                if (capabilities.hasRecoveryWork()) requestAndroidFileSyncCapabilityRecovery(context)
+            }
+        } catch (cancelled: CancellationException) {
+            throw cancelled
+        } catch (failure: Exception) {
+            // A failed immediate cleanup must still have a durable retry owner.
+            try {
+                requestAndroidFileSyncCapabilityRecovery(context)
+            } catch (cancelled: CancellationException) {
+                throw cancelled
+            } catch (schedulingFailure: Exception) {
+                failure.addSuppressed(schedulingFailure)
+            }
+            android.util.Log.w("FolderCapabilityRecovery", "Folder access cleanup is awaiting recovery.", failure)
+        }
+    }
+}
+
+internal fun requestAndroidFileSyncCapabilityRecovery(context: Context) {
+    val request = OneTimeWorkRequestBuilder<AndroidFileSyncCapabilityRecoveryWorker>()
+        .setInitialDelay(1, TimeUnit.MINUTES)
+        .setBackoffCriteria(BackoffPolicy.EXPONENTIAL, 1, TimeUnit.MINUTES)
+        .build()
+    // Append preserves a new request arriving while the previous worker finishes.
+    val operation = WorkManager.getInstance(context).enqueueUniqueWork(
+        "file-sync-capability-cleanup-v2", ExistingWorkPolicy.APPEND_OR_REPLACE, request,
+    )
+    // This boundary runs on the owned IO path, never the Activity result callback.
+    runBlocking { withTimeout(30_000L) { operation.await() } }
+}
+
+internal class AndroidFileSyncCapabilityRecoveryWorker(context: Context, parameters: WorkerParameters) :
+    CoroutineWorker(context, parameters) {
+    override suspend fun doWork(): Result = withContext(Dispatchers.IO) {
+        try {
+            val capabilities = AndroidFileSyncCapabilityLifecycle(applicationContext)
+            val store = AndroidFileSyncStore(applicationContext)
+            // A worker may start the process before the activity restores its draft.
+            reconcileFileSyncCapabilitiesAfterRestoration(
+                AndroidFileSyncEngine.ENGINE_LOCK, store::loadAndReconcileUploadCleanups, capabilities,
+                onFailure = { throw it },
+            )
+            AndroidFileSyncEngine.ENGINE_LOCK.withLock {
+                if (capabilities.hasRecoveryWork()) Result.retry() else Result.success()
+            }
+        } catch (cancelled: CancellationException) {
+            throw cancelled
+        } catch (_: Exception) {
+            Result.retry()
+        }
+    }
+}

androidApp/src/main/kotlin/dev/obiente/nextcloudnative/AndroidFileSyncEngine.kt

@@ -91,6 +91,9 @@ internal class AndroidFileSyncEngine(context: Context) {
     private val scheduledMediaReconciliations = ConcurrentHashMap.newKeySet<String>()
     private val scheduledPairScheduling = DeferredFileSyncPairSchedulingRegistry()
     private val stagingRoot = File(appContext.cacheDir, "file-sync-staging")
+    private val capabilities = AndroidFileSyncCapabilityLifecycle(appContext)
+    private val loadCapabilityState = store::loadAndReconcileUploadCleanups
+    init { startAndroidFileSyncCapabilityRecovery(appContext, reconciliationScope, loadCapabilityState, capabilities) }
 
     suspend fun loadCenter(
         session: NextcloudSession,
@@ -257,14 +260,9 @@ internal class AndroidFileSyncEngine(context: Context) {
         val normalizedRemote = normalizeRemoteRoot(remoteRootPath)
         val accountId = NextcloudDocumentIds.accountKey(session)
         val current = store.load()
-        if (current.coordinator.pairs.any {
-                it.accountId == accountId &&
-                    it.localRootId == localRoot.localRootId &&
-                    it.remoteRootPath == normalizedRemote
-            }
-        ) {
+        if (hasDuplicateAndroidFileSyncRoot(current.coordinator.pairs, accountId, localRoot.localRootId, normalizedRemote)) {
             return@withLock FileSyncCenterActionResult.Rejected(
-                "That local and Nextcloud folder pair already exists.",
+                "That local folder already belongs to a folder sync pair.",
             )
         }
         val pair = FileSyncPair(
@@ -274,14 +272,22 @@ internal class AndroidFileSyncEngine(context: Context) {
             remoteRootPath = normalizedRemote,
             configuration = configuration,
         )
-        store.save(
-            current.copy(
-                coordinator = addFileSyncPair(current.coordinator, pair),
-                localDisplayNames = current.localDisplayNames + (pair.id to localRoot.displayName),
-            ),
+        val updated = current.copy(
+            coordinator = addFileSyncPair(current.coordinator, pair),
+            localDisplayNames = current.localDisplayNames + (pair.id to localRoot.displayName),
         )
-        scheduler.schedule(pair.id, accountId, userId, pair.configuration)
-        FileSyncCenterActionResult.Completed("Folder sync pair added. Run it to review the first sync.")
+        if (localRoot.localRootId.startsWith("content://")) {
+            bindAndPersistFileSyncPair(
+                pairId = pair.id,
+                bindReady = { capabilities.bindReady(AndroidFileSyncCapabilityAccountId(accountId), localRoot.localRootId, pair.id) },
+                persist = { store.save(updated) },
+                load = store::load,
+                abandonUncommittedPair = capabilities::abandonUncommittedPair,
+            )
+        } else {
+            store.save(updated)
+        }
+        committedFileSyncPairResult { scheduler.schedule(pair.id, accountId, userId, pair.configuration) }
     }
 
     private fun FileSyncConfiguration.scheduleDescription(): String {
@@ -312,8 +318,7 @@ internal class AndroidFileSyncEngine(context: Context) {
                     "This folder sync pair belongs to another account.",
                 )
             }
-            val releasesLocalGrant = pair.localRootId.startsWith("content://") &&
-                current.coordinator.pairs.none { it.id != pairId && it.localRootId == pair.localRootId }
+            capabilities.reconcile(current)
             var cleanedCoordinator: FileSyncCoordinatorState? = null
             var remoteCleanupRejected = false
             val removed = removeConfiguredFileSyncPair(
@@ -351,18 +356,14 @@ internal class AndroidFileSyncEngine(context: Context) {
                     }
                 },
                 persistRemoval = {
+                    capabilities.preparePairCleanup(pairId)
                     val remaining = removeFileSyncPair(requireNotNull(cleanedCoordinator), pairId)
-                    store.save(
-                        current.copy(
-                            coordinator = remaining,
-                            localDisplayNames = current.localDisplayNames - pairId,
-                        ),
-                    )
+                    capabilities.persistPairRemoval(pairId, store::loadAndReconcileUploadCleanups) {
+                        store.save(current.copy(coordinator = remaining, localDisplayNames = current.localDisplayNames - pairId))
+                    }
                 },
                 cancelSchedule = { scheduler.cancel(pairId) },
-                releaseLocalGrant = {
-                    releaseSafGrantAfterPairRemoval(appContext, pair.localRootId, releasesLocalGrant)
-                },
+                releaseLocalGrant = { capabilities.finishPairCleanupOrRetry(pairId, allowDeferredCleanup = true, load = store::load) },
             )
             if (!removed) {
                 return@withLock FileSyncCenterActionResult.Rejected(if (remoteCleanupRejected) {