ThePalaceProject
diff --git a/‎Palace/Audiobooks/NowPlayingCoordinator.swift‎
Lines changed: 11 additions & 0 deletions b/‎Palace/Audiobooks/NowPlayingCoordinator.swift‎
Lines changed: 11 additions & 0 deletions
diff --git a/‎Palace/CatalogUI/ViewModels/CatalogViewModel.swift‎
Lines changed: 18 additions & 0 deletions b/‎Palace/CatalogUI/ViewModels/CatalogViewModel.swift‎
Lines changed: 18 additions & 0 deletions
diff --git a/‎Palace/MyBooks/BorrowErrorPresenter.swift‎
Lines changed: 63 additions & 48 deletions b/‎Palace/MyBooks/BorrowErrorPresenter.swift‎
Lines changed: 63 additions & 48 deletions
diff --git a/‎Palace/MyBooks/DownloadCancellationHandler.swift‎
Lines changed: 12 additions & 2 deletions b/‎Palace/MyBooks/DownloadCancellationHandler.swift‎
Lines changed: 12 additions & 2 deletions
diff --git a/‎Palace/MyBooks/DownloadQueueOrchestrator.swift‎
Lines changed: 20 additions & 9 deletions b/‎Palace/MyBooks/DownloadQueueOrchestrator.swift‎
Lines changed: 20 additions & 9 deletions
diff --git a/‎Palace/MyBooks/DownloadStartCoordinator.swift‎
Lines changed: 49 additions & 20 deletions b/‎Palace/MyBooks/DownloadStartCoordinator.swift‎
Lines changed: 49 additions & 20 deletions
@@ -359,6 +359,17 @@ public final class NowPlayingCoordinator {
     func _test_setLastIsPlaying(_ playing: Bool) {
         lastIsPlaying = playing
     }
+
+    /// Test-only join seam. Awaits the in-flight debounced update `Task`
+    /// (`pendingUpdate`) so a test can deterministically block on the actual
+    /// debounce work unit instead of polling `MPNowPlayingInfoCenter` against a
+    /// fixed wall-clock deadline (`awaitCondition(timeout:)`), which starves
+    /// under CI sim-clone oversubscription. Production behavior is unchanged —
+    /// nothing calls this outside tests. No-op when no debounced update is
+    /// pending (the immediate-apply path leaves `pendingUpdate` nil).
+    func _awaitPendingUpdateForTesting() async {
+        await pendingUpdate?.value
+    }
 }
 
 /// Nonisolated `Sendable` holder for the foreground-notification observer
 
@@ -122,6 +122,24 @@ final class CatalogViewModel: ObservableObject {
   func appendPrefetchTaskForTesting(_ task: Task<Void, Never>) { prefetchTasks.append(task) }
   func cancelPrefetchForTesting() { cancelPrefetch() }
 
+  /// Test seam — deterministically join the in-flight load. `load()` /
+  /// `forceRefresh()` / `reload()` spawn `currentLoadTask` (repo fetch →
+  /// off-actor `mapFeed` → image-cache warming) and return WITHOUT awaiting it,
+  /// so the `.loaded`/`.error`/`.offline` transition lands asynchronously. A
+  /// test that asserts the terminal state must otherwise wait on the `$state`
+  /// publisher against a fixed wall-clock deadline (`fulfillment(timeout:)`),
+  /// which STARVES under CI sim-clone oversubscription — the `.userInitiated`
+  /// map hop and cache warming get deferred past the deadline even though the
+  /// code is correct. Awaiting the retained Task handle blocks EXACTLY until the
+  /// load finishes, removing the pool/wall-clock dependence entirely.
+  ///
+  /// Changes NO production behavior: this only reads a handle the view model
+  /// already retains; `load()` still spawns the task and returns immediately.
+  /// Returns at once if no load is in flight.
+  func _awaitLoadForTesting() async {
+    await currentLoadTask?.value
+  }
+
   // MARK: - Connectivity
 
   /// Auto-reload the catalog when connectivity returns while we are showing the
 
@@ -122,6 +122,32 @@ final class BorrowErrorPresenter: @unchecked Sendable {
     /// path. Called from MBDC's borrow flow on every problem-document
     /// failure.
     func process(error: [String: Any]?, for book: TPPBook) {
+        // `book` (non-Sendable `TPPBook`) and `error` (`Any`-valued dict) ride
+        // whole into the `@MainActor @Sendable` Task via read-only carrier
+        // boxes; the boxed values are only touched on the main actor inside
+        // `processAsync`.
+        let bookBox = BorrowBookBox(book)
+        let errorBox = BorrowErrorDictBox(error)
+        Task { @MainActor [weak self] in
+            await self?.processAsync(error: errorBox.error, for: bookBox.book)
+        }
+    }
+
+    /// Behavior-identical `async` sibling of `process`. Fire-and-forget
+    /// `process` is `Task { await processAsync(...) }`; callers already inside
+    /// an `async @MainActor` context (and tests) can `await` it directly to
+    /// JOIN every branch's side effects — the alert publish, the re-auth
+    /// dispatch, and the post-reauth `startDownload` retry — instead of
+    /// polling a wall-clock deadline for a fire-and-forget hop to settle.
+    ///
+    /// Structurally identical to the previous `process` body: the branch-1/2/4
+    /// publishes happen on the main actor (previously via `runOnMainAsync`,
+    /// now directly — we are already on `@MainActor`, same thread, same
+    /// order), and the invalid-credentials branch keeps the same guard order,
+    /// the same one-shot latch, the same shared-flag set, and the same
+    /// fire-and-forget 2s `isRequestingCredentials` reset Task.
+    @MainActor
+    func processAsync(error: [String: Any]?, for book: TPPBook) async {
         guard let errorType = error?["type"] as? String else {
             showGenericBorrowFailedAlert(for: book)
             return
@@ -132,49 +158,30 @@ final class BorrowErrorPresenter: @unchecked Sendable {
         switch errorType {
         case TPPProblemDocument.TypeLoanAlreadyExists:
             let alertMessage = DisplayStrings.loanAlreadyExistsAlertMessage
-            // Snapshot the Sendable identifier so the non-Sendable `book` does
-            // not cross into the `@MainActor @Sendable` closure.
-            let bookId = book.identifier
-            runOnMainAsync { [weak self] in
-                self?.progressReporter.publishAndAnnounceError(
-                    DownloadErrorInfo(bookId: bookId, title: alertTitle, message: alertMessage, kind: .borrow)
-                )
-            }
+            progressReporter.publishAndAnnounceError(
+                DownloadErrorInfo(bookId: book.identifier, title: alertTitle, message: alertMessage, kind: .borrow)
+            )
 
         case TPPProblemDocument.TypeInvalidCredentials:
-            // `book` (non-Sendable `TPPBook`) and `error` (`[String: Any]?`,
-            // `Any` is non-Sendable) both need to ride whole into the
-            // `@MainActor @Sendable` re-auth Task. Thread them through
-            // read-only carrier boxes; the boxed values are only touched on
-            // the main actor inside the Task.
-            let bookBox = BorrowBookBox(book)
-            let errorBox = BorrowErrorDictBox(error)
-            Task { @MainActor [weak self] in
-                guard let self else { return }
-                let book = bookBox.book
-                let error = errorBox.error
-
-                guard !self.hasAttemptedAuthentication else {
-                    self.showAlert(for: book, with: error, alertTitle: alertTitle)
-                    return
-                }
-
-                guard !self.credentialRequestState.isRequestingCredentials else {
-                    NSLog("Already requesting credentials, skipping re-authentication for: \(book.title)")
-                    return
-                }
+            guard !self.hasAttemptedAuthentication else {
+                self.showAlert(for: book, with: error, alertTitle: alertTitle)
+                return
+            }
 
-                self.hasAttemptedAuthentication = true
-                self.credentialRequestState.isRequestingCredentials = true
+            guard !self.credentialRequestState.isRequestingCredentials else {
+                NSLog("Already requesting credentials, skipping re-authentication for: \(book.title)")
+                return
+            }
 
-                Task { @MainActor [weak self] in
-                    try? await Task.sleep(nanoseconds: 2_000_000_000)
-                    self?.credentialRequestState.isRequestingCredentials = false
-                }
+            self.hasAttemptedAuthentication = true
+            self.credentialRequestState.isRequestingCredentials = true
 
-                await self.handleInvalidCredentials(for: book)
+            Task { @MainActor [weak self] in
+                try? await Task.sleep(nanoseconds: 2_000_000_000)
+                self?.credentialRequestState.isRequestingCredentials = false
             }
-            return
+
+            await self.handleInvalidCredentials(for: book)
 
         default:
             showAlert(for: book, with: error, alertTitle: alertTitle)
@@ -184,21 +191,29 @@ final class BorrowErrorPresenter: @unchecked Sendable {
     // MARK: - Invalid-credentials → reauth + retry
 
     @MainActor
-    private func handleInvalidCredentials(for book: TPPBook) {
+    private func handleInvalidCredentials(for book: TPPBook) async {
         let userAccount = userAccountProvider()
-        reauthenticator.authenticateIfNeeded(userAccount, usingExistingCredentials: false) { [weak self] in
-            guard let self = self else { return }
 
-            Task { @MainActor [weak self] in
-                self?.credentialRequestState.isRequestingCredentials = false
-
-                if self?.userAccountProvider().hasCredentials() == true {
-                    self?.delegate?.startDownload(for: book, withRequest: nil)
-                } else {
-                    NSLog("Authentication completed but no credentials present, user may have cancelled")
-                }
+        // Bridge the completion-handler reauthenticator API to `async` so the
+        // caller (`processAsync`) can JOIN the retry. The post-reauth body runs
+        // on the main actor exactly as before — previously it hopped through
+        // `Task { @MainActor }` from the (possibly-nonisolated) completion; now
+        // we resume back onto the main actor via the continuation and run it
+        // inline. Same thread, same order, same observable effects
+        // (`isRequestingCredentials` reset → conditional `startDownload`).
+        await withCheckedContinuation { (continuation: CheckedContinuation<Void, Never>) in
+            reauthenticator.authenticateIfNeeded(userAccount, usingExistingCredentials: false) {
+                continuation.resume()
             }
         }
+
+        credentialRequestState.isRequestingCredentials = false
+
+        if userAccountProvider().hasCredentials() {
+            delegate?.startDownload(for: book, withRequest: nil)
+        } else {
+            NSLog("Authentication completed but no credentials present, user may have cancelled")
+        }
     }
 
     // MARK: - Generic + problem-doc alerts
 
@@ -55,6 +55,16 @@ final class DownloadCancellationHandler: @unchecked Sendable {
 
     weak var delegate: DownloadCancellationHandlerDelegate?
 
+    /// Handle to the most recently spawned cancel-teardown `Task`. The cancel
+    /// paths do their coordinator/map teardown inside a fire-and-forget
+    /// `Task { }` (spawned either from the no-task branch or from the
+    /// URLSession `cancel` completion). Retaining the handle lets callers —
+    /// and tests — `await lastCancelTeardownTask?.value` to join that teardown
+    /// deterministically instead of polling for the resulting state. Behavior
+    /// is unchanged: the same Task is created and runs exactly as before; only
+    /// a reference to it is now kept.
+    private(set) var lastCancelTeardownTask: Task<Void, Never>?
+
     private let stateManager: DownloadStateManager
     private let bookRegistry: TPPBookRegistryProvider
     #if FEATURE_DRM_CONNECTOR
@@ -94,7 +104,7 @@ final class DownloadCancellationHandler: @unchecked Sendable {
                 bookRegistry.setState(.downloadNeeded, for: identifier)
                 delegate?.broadcastUpdate()
 
-                Task { [weak self] in
+                lastCancelTeardownTask = Task { [weak self] in
                     guard let self else { return }
                     await self.stateManager.downloadCoordinator.removeCachedDownloadInfo(for: identifier)
                     await self.stateManager.downloadCoordinator.registerCompletion(identifier: identifier)
@@ -128,7 +138,7 @@ final class DownloadCancellationHandler: @unchecked Sendable {
         info.downloadTask.cancel { [weak self] _ in
             guard let self else { return }
 
-            Task { [weak self] in
+            self.lastCancelTeardownTask = Task { [weak self] in
                 guard let self else { return }
                 // Clear both maps so retry isn't blocked by stale entries.
                 _ = await self.stateManager.bookIdentifierToDownloadInfo.remove(identifier)
 
@@ -91,15 +91,26 @@ final class DownloadQueueOrchestrator: @unchecked Sendable {
         bookRegistry.setState(.downloading, for: book.identifier)
 
         Task { [weak self] in
-            guard let self else { return }
-            await self.downloadCoordinator.enqueuePending(book)
-            let queueSize = await self.downloadCoordinator.queueCount
-            Log.debug(#file, "📋 Enqueued '\(book.title)' for download, queue size: \(queueSize)")
-
-            // Notify UI to refresh
-            runOnMainAsync {
-                self.notificationCenter.post(name: .TPPMyBooksDownloadCenterDidChange, object: nil)
-            }
+            await self?.enqueuePendingAsync(book)
+        }
+    }
+
+    /// Async body of `enqueuePending`: the actor-hopping portion (coordinator
+    /// enqueue + DidChange broadcast) that `enqueuePending` fires as a
+    /// detached `Task`. Exposed so callers already inside an `async` context
+    /// — and tests — can `await` the enqueue to completion deterministically
+    /// instead of polling for the resulting queue/notification state. Mirrors
+    /// the `schedulePendingStartsIfPossible()` → `schedulePendingStartsAsync()`
+    /// split. The synchronous `.downloading` state broadcast stays in
+    /// `enqueuePending` (it runs before the Task hop, same as before).
+    func enqueuePendingAsync(_ book: TPPBook) async {
+        await self.downloadCoordinator.enqueuePending(book)
+        let queueSize = await self.downloadCoordinator.queueCount
+        Log.debug(#file, "📋 Enqueued '\(book.title)' for download, queue size: \(queueSize)")
+
+        // Notify UI to refresh
+        runOnMainAsync {
+            self.notificationCenter.post(name: .TPPMyBooksDownloadCenterDidChange, object: nil)
         }
     }
 
 
@@ -71,9 +71,15 @@ protocol DownloadStartCoordinatorDelegate: AnyObject {
 /// `DownloadAuthRetryHandler`) that captures `[weak delegate]`/`[weak self]`
 /// and mutates non-Sendable state.
 /// INVARIANT — the boxed closure is invoked at most once, inside the single
-/// `startBorrow` `Task` (both the success and `catch` terminal paths), never
-/// concurrently; its own thread-affinity is the caller's contract (unchanged).
-private final class BorrowCompletionBox: @unchecked Sendable {
+/// `startBorrow` `Task` (both the success and `catch` terminal paths of
+/// `startBorrowAsync`), never concurrently; its own thread-affinity is the
+/// caller's contract (unchanged).
+///
+/// `internal` (not `private`) so the joinable `startBorrowAsync` seam — which
+/// takes the box rather than the raw closure to preserve the single boxing at
+/// the `Task` boundary — is `await`-able from the test target under
+/// `@testable import`. No production behavior depends on the access level.
+final class BorrowCompletionBox: @unchecked Sendable {
     let call: (() -> Void)?
     init(_ call: (() -> Void)?) { self.call = call }
 }
@@ -193,27 +199,50 @@ final class DownloadStartCoordinator: @unchecked Sendable {
         // `@Sendable`-ing the param, which would ripple to the caller closures.
         let borrowCompletionBox = BorrowCompletionBox(borrowCompletion)
         Task { [weak self] in
-            guard let self else { return }
-            do {
-                _ = try await self.delegate?.borrowAsync(book, attemptDownload: shouldAttemptDownload)
-
-                let newState = self.bookRegistry.state(for: book.identifier)
-                if newState == .holding {
-                    await self.stateManager.downloadCoordinator.registerCompletion(identifier: book.identifier)
-                    let remainingCount = await self.stateManager.downloadCoordinator.activeCount
-                    Log.info(#file, "📊 Borrow resulted in hold for '\(book.title)', released slot, remaining active: \(remainingCount)")
-                    self.delegate?.schedulePendingStartsIfPossible()
-                }
-
-                borrowCompletionBox.call?()
-            } catch {
-                Log.error(#file, "Borrow failed: \(error.localizedDescription)")
+            await self?.startBorrowAsync(
+                for: book,
+                attemptDownload: shouldAttemptDownload,
+                borrowCompletionBox: borrowCompletionBox
+            )
+        }
+    }
+
+    /// Behavior-identical `async` body of `startBorrow`. The fire-and-forget
+    /// entry point above is `Task { await startBorrowAsync(...) }`; callers
+    /// already inside an `async` context (and tests) can `await` it directly
+    /// to JOIN the slot-release + reschedule + completion side effects instead
+    /// of polling a wall-clock deadline for the detached Task to settle (which
+    /// starves under CI oversubscription and blows the executionTimeAllowance).
+    ///
+    /// Takes the `BorrowCompletionBox` (not the raw closure) so the sole
+    /// caller keeps its single boxing at the `Task` boundary; the ordered
+    /// side effects — borrowAsync → post-state read → registerCompletion →
+    /// activeCount → schedulePendingStartsIfPossible → completion — are
+    /// verbatim what the previous inline Task ran.
+    func startBorrowAsync(
+        for book: TPPBook,
+        attemptDownload shouldAttemptDownload: Bool,
+        borrowCompletionBox: BorrowCompletionBox
+    ) async {
+        do {
+            _ = try await self.delegate?.borrowAsync(book, attemptDownload: shouldAttemptDownload)
+
+            let newState = self.bookRegistry.state(for: book.identifier)
+            if newState == .holding {
                 await self.stateManager.downloadCoordinator.registerCompletion(identifier: book.identifier)
                 let remainingCount = await self.stateManager.downloadCoordinator.activeCount
-                Log.info(#file, "📊 Borrow failed for '\(book.title)', released slot, remaining active: \(remainingCount)")
+                Log.info(#file, "📊 Borrow resulted in hold for '\(book.title)', released slot, remaining active: \(remainingCount)")
                 self.delegate?.schedulePendingStartsIfPossible()
-                borrowCompletionBox.call?()
             }
+
+            borrowCompletionBox.call?()
+        } catch {
+            Log.error(#file, "Borrow failed: \(error.localizedDescription)")
+            await self.stateManager.downloadCoordinator.registerCompletion(identifier: book.identifier)
+            let remainingCount = await self.stateManager.downloadCoordinator.activeCount
+            Log.info(#file, "📊 Borrow failed for '\(book.title)', released slot, remaining active: \(remainingCount)")
+            self.delegate?.schedulePendingStartsIfPossible()
+            borrowCompletionBox.call?()
         }
     }