libp2r2p 0.11.18 → 0.11.19

package/README.md

@@ -535,7 +535,8 @@ new channels are watched unless paused. Applications may explicitly watch again.
 
 Pauses, unwatch and close record the start of the gap, even for channels that
 have never received a message. Rewatch/resume uses live delivery plus historical
-recovery with overlap. A failed resume remains retryable under its pause reason.
+recovery with overlap. Remote recovery failures never restore the caller's pause
+reason: signer availability belongs exclusively to the account owner.
 Before opening a watch, the messenger persists a pending recovery interval.
 A first watch scans the configured recovery window (seven days by default),
 including messages sent before this identity first opened the channel. Successful
@@ -546,6 +547,24 @@ This also covers abrupt termination without `close()` and channels with no
 messages. Applications still supply signers and desired channels on reopening;
 storage is scoped by origin and user pubkey, not the transient session ID.
 Failed ingestion or incomplete relay fetch reports never complete the gap.
+
+`init()` and `createPrivateMessenger()` resolve after local preparation. Likewise,
+`update(options, { waitForBackground = false })` and
+`resume(reason, { waitForBackground = false })` wait for valid local channel
+configuration and mandatory durable writes, allowing sends independently of
+subscriptions, presence and history. Set `waitForBackground: true` to also await
+the initial background tasks associated with that call, not every future retry.
+Both modes share tasks; unchanged configuration does not recreate subscriptions.
+Later errors reach `onError` with the original error as `cause` and
+`operation: 'private-messenger.background'` plus a `phase`. Cancelled or obsolete
+tasks cannot deliver into a new channel generation. Mandatory persistence still
+owns its storage pause; incomplete history remains a pending recovery interval.
+Subscription setup is bounded separately from presence, so a slow announcement
+does not hold the other channels' readers. Sessions prioritize user persistence
+and publication before the next background presence signer call. Signing an outer
+envelope can overlap recovery-seed persistence, but no envelope is yielded for
+publication unless both succeed; only one outer is prepared at a time.
+
 `private-channel.fetch` reports incomplete reads as an `AggregateError` with
 stable `code: 'PRIVATE_CHANNEL_FETCH_INCOMPLETE'`. Its message names relays,
 completion statuses and native failure messages, including status-only failures.

package/helpers/abortable-semaphore.js

@@ -1,6 +1,6 @@
 // A bounded FIFO for asynchronous work. Acquired leases release explicitly;
 // queued cancellations never consume capacity or keep idle keyed gates alive.
-export function createAbortableSemaphore (capacity, onIdle = () => {}) {
+export function createAbortableSemaphore (capacity, onIdle = () => {}, { maxQueued = 256 } = {}) {
   const queue = []
   let active = 0
   const drain = () => {
@@ -21,7 +21,7 @@ export function createAbortableSemaphore (capacity, onIdle = () => {}) {
   return {
     acquire (signal) {
       signal?.throwIfAborted()
-      if (queue.length >= 256) return Promise.reject(Object.assign(new Error('PRIVATE_CHANNEL_HISTORY_QUEUE_FULL'), { code: 'PRIVATE_CHANNEL_HISTORY_QUEUE_FULL' }))
+      if (queue.length >= maxQueued) return Promise.reject(Object.assign(new Error('PRIVATE_CHANNEL_HISTORY_QUEUE_FULL'), { code: 'PRIVATE_CHANNEL_HISTORY_QUEUE_FULL' }))
       return new Promise((resolve, reject) => {
         const job = {
           signal, resolve, abort: () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libp2r2p",
-  "version": "0.11.18",
+  "version": "0.11.19",
   "description": "Peer-to-relay-to-peer",
   "keywords": [
     "p2r2p",

package/private-channel/index.js

@@ -158,7 +158,8 @@ async function * wrapPreparedEvents ({ privateChannelSigner, receivers, receiver
   const routerReceiverTag = receiverTag ?? (receiverPubkeyList.length === 1 ? receiverPubkeyList[0] : '')
   const rowIndexes = preparedRowIndexesForReceivers(context.preparedRows, receivers)
   const total = preparedChunkCount(context.preparedRows, rowIndexes)
-  if (onPreparedSeed) {
+  const persistSeeds = async () => {
+    if (!onPreparedSeed) return
     const router = makeRouterEvent({ pubkey: routerPubkey, senderPubkey: context.senderPubkey, imkcPubkey: context.imkcPubkey, imkcProof: context.imkcProof, receiverPubkey: routerReceiverTag, chunkIndex: 0, chunkTotal: 1, fileChunkIndex, content: '' })
     const payloadRow = readPreparedRow(context.preparedRows, 0)
     for (const rowIndex of rowIndexes) {
@@ -179,12 +180,18 @@ async function * wrapPreparedEvents ({ privateChannelSigner, receivers, receiver
       content
     }), routerSeckey)
     const createdAt = nowSeconds()
-    const outer = await privateChannelSigner.signEvent({
+    const prepareOuter = async () => privateChannelSigner.signEvent({
       kind: PRIVATE_BROADCAST_KIND,
       created_at: createdAt,
       tags: privateBroadcastTags({ deletionPubkey, createdAt, expirationSeconds }),
       content: await nip44v3EncryptText(privateChannelSigner, context.channelReaderPubkey, PRIVATE_BROADCAST_KIND, JSON.stringify(router))
     })
+    // These independent steps may run together, but no envelope is yielded
+    // until every seed is durable. Settle both before releasing prepared rows.
+    const [persistence, prepared] = await Promise.allSettled([index === 1 ? persistSeeds() : undefined, prepareOuter()])
+    if (persistence.status === 'rejected') throw persistence.reason
+    if (prepared.status === 'rejected') throw prepared.reason
+    const outer = prepared.value
     if (eventByteLength(outer) > MAX_EVENT_BYTES) throw new ValidationError('EVENT_TOO_LARGE')
     yield outer
   }

package/private-messenger/helpers/background-signer.js

@@ -0,0 +1,16 @@
+// Keep actual permissions and cryptography in the signer. Background presence
+// only yields before its next RPC, without interrupting an operation in flight.
+export function backgroundSigner (signer, wait, signal) {
+  if (!signer || !wait) return signer
+  return new Proxy(signer, {
+    get (target, key) {
+      const value = Reflect.get(target, key, target)
+      if (typeof value !== 'function') return value
+      return async (...args) => {
+        await wait(signal)
+        signal?.throwIfAborted()
+        return value.apply(target, args)
+      }
+    }
+  })
+}

package/private-messenger/index.js

@@ -48,6 +48,7 @@ import * as privateMessage from '../private-message/index.js'
 import { isOnline, onOnline } from '../network/index.js'
 import { isRetryableRelayFailure, isReplaceableRelayFailure } from '../relay/index.js'
 import { createPauseRecovery, isRecoverableStorageFailure } from './helpers/pause-recovery.js'
+import { backgroundSigner } from './helpers/background-signer.js'
 import { createSendRelayRouting, normalizeFallbackRelays, normalizeFallbackDelay } from './helpers/send-routing.js'
 import { incompleteFetchError } from '../private-channel/helpers/fetch-error.js'
 import { recoveryRetryDelay, isPermanentRecoveryError } from './helpers/recovery-retry.js'
@@ -243,6 +244,7 @@ export class PrivateMessenger {
     _pickRelaysForPubkeys = pickRelaysForPubkeys,
     _subscribeRelayListUpdates = subscribeRelayListUpdates,
     _isOnline = isOnline,
+    _waitForForeground,
     _onOnline = onOnline,
     _random = Math.random,
     _setTimeout = globalThis.setTimeout.bind(globalThis),
@@ -304,6 +306,7 @@ export class PrivateMessenger {
     this._pickRelaysForPubkeys = _pickRelaysForPubkeys
     this._subscribeRelayListUpdates = _subscribeRelayListUpdates
     this._isOnline = _isOnline
+    this._waitForForeground = _waitForForeground
     this.sendRelayExclusions = new Map()
     this.sendRoutingLifetime = new AbortController()
     this.sendRoutingPause = new AbortController()
@@ -341,7 +344,13 @@ export class PrivateMessenger {
     this.recoveryRanges = new Map()
     this.recoveryPriority = new Map()
     this.recoveryOnline = { at: 0, value: true }
-    this.resumeWork = null
+    this.channelBackground = new Map()
+    // At most one queued job exists per configured channel. Keep setup below
+    // foreground demand; history has its own independent admission limits.
+    this.channelSetupAdmission = createAbortableSemaphore(3, () => {}, { maxQueued: Infinity })
+    this.presenceAdmission = createAbortableSemaphore(1, () => {}, { maxQueued: Infinity })
+    this.updateTail = Promise.resolve()
+    this.pauseRevisions = new Map()
     this.capacityTimer = null
     this.capacityCheck = null
     this.capacityRequiredBytes = 0
@@ -350,6 +359,7 @@ export class PrivateMessenger {
     this.liveRecoveryTimers = new Map()
     this.watchRevisionByChannel = new Map()
     this.presenceTimers = new Map()
+    this.presenceJobs = new Map()
     this.stopRelayListWatcher = null
     this.relayListWatcherPubkey = ''
     this.relayListRefreshPromise = null
@@ -435,7 +445,6 @@ export class PrivateMessenger {
       this.startStorageMaintenance()
       this.state = { channels: await this.stateStore.load() }
       await this.update({ userSigner, contentKeySigner, nymSigner: this.nymSigner, channels, relays, mode })
-      await this.pruneStoredSeeds()
       this.initialized = true
       await this.refreshAndApplyStoragePolicy()
       this.broadcastStoragePolicyChange()
@@ -673,7 +682,16 @@ export class PrivateMessenger {
     })
   }
 
-  async update (options = {}) {
+  async update (options = {}, { waitForBackground = false } = {}) {
+    if (typeof waitForBackground !== 'boolean') throw new ValidationError('INVALID_WAIT_FOR_BACKGROUND')
+    const work = this.updateTail.catch(() => {}).then(() => this.applyUpdate(options))
+    this.updateTail = work
+    const background = await work
+    if (waitForBackground) await Promise.all(background)
+    return this
+  }
+
+  async applyUpdate (options) {
     this.assertOpen()
     const {
       userSigner = this.userSigner,
@@ -692,15 +710,17 @@ export class PrivateMessenger {
     let nextIdentityStorageRetentionSeconds = updatesIdentityPolicy
       ? normalizeIdentityStorageRetentionSeconds(options.identityStorageRetentionSeconds)
       : this.identityStorageRetentionSeconds
-    if (userSigner) {
+    if (userSigner && (userSigner !== this.userSigner || !this.userPubkey)) {
       const userPubkey = await userSigner.getPublicKey?.()
       if (!userPubkey) throw new ValidationError('USER_SIGNER_REQUIRED')
       if (this.userPubkey && userPubkey !== this.userPubkey) throw new ValidationError('USER_SIGNER_MISMATCH')
       this.userSigner = userSigner
     }
+    if (contentKeySigner !== this.contentKeySigner || (!this.contentKeyPubkey && contentKeySigner)) {
+      this.contentKeyPubkey = await contentKeySigner?.getPublicKey?.() || ''
+    }
     this.contentKeySigner = contentKeySigner || null
     this.nymSigner = nymSigner || null
-    this.contentKeyPubkey = await this.contentKeySigner?.getPublicKey?.() || ''
     const nextChannels = await this.normalizeChannels(channels, { relays, mode })
     this.assertOpen()
     const nextPubkeys = new Set(nextChannels.map(channel => channel.pubkey))
@@ -709,9 +729,11 @@ export class PrivateMessenger {
       return !previous || ['signer', 'readerSigner', 'readerPubkey', 'nymSigner', 'mode', 'usesNip65WatchRelays', 'offlineRecoverySeconds', 'autoDeletionCapability'].some(key => previous[key] !== channel[key]) ||
         ['relays', 'sendRelays', 'seeders'].some(key => JSON.stringify(previous[key]) !== JSON.stringify(channel[key]))
     }
-    const watchPubkeys = nextChannels.filter(channel => !this.channels.has(channel.pubkey) || (this.desiredChannels.has(channel.pubkey) && (readerIdentityChanged || Object.hasOwn(options, 'staleChannelSeconds') || Object.hasOwn(options, 'identityStorageRetentionSeconds') || changedChannel(channel) || !this.stopByChannel.has(channel.pubkey)))).map(channel => channel.pubkey)
+    const changed = nextChannels.filter(channel => readerIdentityChanged || updatesStalePolicy || updatesIdentityPolicy || changedChannel(channel))
+    const watchPubkeys = changed.filter(channel => !this.channels.has(channel.pubkey) || this.desiredChannels.has(channel.pubkey)).map(channel => channel.pubkey)
     const removedPubkeys = [...this.channels.keys()].filter(pubkey => !nextPubkeys.has(pubkey))
     const updatesStoragePolicy = updatesStalePolicy || updatesIdentityPolicy
+    if (!changed.length && !removedPubkeys.length && !updatesStoragePolicy) return [...this.channelBackground.values()].map(job => job.work)
 
     if (updatesStoragePolicy) {
       const currentPolicy = await this.readStoragePolicySnapshot()
@@ -743,18 +765,35 @@ export class PrivateMessenger {
     if (updatesStoragePolicy) this.broadcastStoragePolicyChange()
 
     await this.unwatch(removedPubkeys)
+    // Keep an established reader alive until private-message atomically
+    // replaces it. Only obsolete setup/presence work is retired here.
+    for (const pubkey of watchPubkeys) {
+      this.cancelReloadGap(pubkey)
+      this.cancelLiveRecovery(pubkey)
+      this.channelBackground.get(pubkey)?.controller.abort()
+      this.channelBackground.delete(pubkey)
+      this.watchRevisionByChannel.set(pubkey, (this.watchRevisionByChannel.get(pubkey) || 0) + 1)
+      this.stopPresencePublisher(pubkey)
+    }
     for (const pubkey of removedPubkeys) this.channels.delete(pubkey)
     for (const [key, value] of this.sendRelayExclusions) if (removedPubkeys.includes(value.channelPubkey)) this.sendRelayExclusions.delete(key)
-    for (const channel of nextChannels) this.channels.set(channel.pubkey, channel)
+    for (const channel of changed) this.channels.set(channel.pubkey, channel)
 
-    await this.cleanupStaleChannels({ storageSnapshot })
-    await this.applyRecoveryPolicies(nextChannels)
-    await this.watch(watchPubkeys)
-    await this.reconcilePresencePublishers()
+    // Incremental registration must not prune persisted channels whose signers
+    // are still being prepared. Retention cleanup belongs to maintenance.
+    await this.applyRecoveryPolicies(changed, { prune: !this.seedStorage })
+    this.assertOpen()
+    for (const pubkey of watchPubkeys) {
+      this.desiredChannels.add(pubkey)
+      this.recordRecoveryWindow(pubkey)
+    }
+    if (this.pauseReasons.size) this.recordInterruption(watchPubkeys)
+    await this.flushStateWrites()
+    this.ensureNetworkWatchers()
     if (this.storagePolicyRevision === storageSnapshot.policyRevision) {
       this.storagePolicyNeedsApply = false
     }
-    return this
+    return this.startChannelBackground(watchPubkeys)
   }
 
   async normalizeChannels (channels, defaults) {
@@ -772,7 +811,7 @@ export class PrivateMessenger {
       if (!signer && !readerSigner) throw new ValidationError('CHANNEL_SIGNER_REQUIRED')
       const mode = channel.mode || defaults.mode || 'leecher'
       if (!signer && doesModeStoreRecoverySeeds(mode)) throw new ValidationError('PRIVATE_CHANNEL_WRITER_REQUIRED')
-      const readerPubkey = channel.readerPubkey || channel.privateChannelReaderPubkey || await readerSigner?.getPublicKey?.() || pubkey
+      const readerPubkey = channel.readerPubkey || channel.privateChannelReaderPubkey || (readerSigner === signer ? pubkey : await readerSigner?.getPublicKey?.()) || pubkey
       const autoDeletionCapability = channel.autoDeletionCapability === undefined
         ? undefined
         : normalizeAutoDeletionCapability(channel.autoDeletionCapability)
@@ -804,8 +843,8 @@ export class PrivateMessenger {
     return this._pickRelaysForPubkeys(pubkeys, relaysByPubkey, { relayType: 'read' })
   }
 
-  async readRelaysForPubkey (pubkey) {
-    const relaysByPubkey = await this._getRelaysByPubkey([pubkey])
+  async readRelaysForPubkey (pubkey, options) {
+    const relaysByPubkey = await this._getRelaysByPubkey([pubkey], options)
     const readRelays = uniq(relaysByPubkey?.[pubkey]?.read)
     if (readRelays.length) return readRelays
     return relayMapRelays(this._pickRelaysForPubkeys([pubkey], relaysByPubkey, { relayType: 'read' }))
@@ -823,8 +862,8 @@ export class PrivateMessenger {
     }
   }
 
-  async resolveWatchRelays (channel) {
-    const primary = !channel.usesNip65WatchRelays && channel.relays.length ? channel.relays : await this.readRelaysForPubkey(this.userPubkey)
+  async resolveWatchRelays (channel, options) {
+    const primary = !channel.usesNip65WatchRelays && channel.relays.length ? channel.relays : await this.readRelaysForPubkey(this.userPubkey, options)
     return uniq([...primary, ...this.fallbackRelays].map(normalizeRelayUrl))
   }
 
@@ -1124,7 +1163,7 @@ export class PrivateMessenger {
     this.writeState(state)
   }
 
-  async watch (channels = [...this.channels.keys()], { scheduleReloadGap = true } = {}) {
+  async watch (channels = [...this.channels.keys()], { scheduleReloadGap = true, signal } = {}) {
     this.assertOpen()
     const channelPubkeys = uniq(channels)
     for (const pubkey of channelPubkeys) {
@@ -1148,13 +1187,15 @@ export class PrivateMessenger {
       await this.flushStateWrites()
       let stop; let watchRelays
       try {
-        watchRelays = await this.resolveWatchRelays(channel)
+        signal?.throwIfAborted()
+        watchRelays = await this.resolveWatchRelays(channel, { signal })
         this.assertOpen()
         if (this.pauseReasons.size || !this.desiredChannels.has(pubkey) || revision !== (this.watchRevisionByChannel.get(pubkey) || 0)) continue
         stop = await this._privateMessage.watch({
           channels: [pubkey],
           relays: watchRelays,
           receiverSigner: this.userSigner,
+          receiverPubkey: this.userPubkey,
           iykcSigner: this.contentKeySigner,
           privateChannelSigner: channel.signer,
           privateChannelReaderSigner: channel.readerSigner,
@@ -1174,6 +1215,7 @@ export class PrivateMessenger {
           onError: err => this.onError?.(err)
         })
       } catch (error) {
+        if (signal?.aborted) continue
         const transient = isRetryableRelayFailure(error)
         const remote = error?.name !== 'Nip42AuthenticationError' && (error?.category === 'relay' || isReplaceableRelayFailure(error))
         if (!transient && !remote) throw error
@@ -1655,6 +1697,8 @@ export class PrivateMessenger {
   stopWatches (channels = [...this.stopByChannel.keys()]) {
     const closing = []
     for (const pubkey of channels) {
+      this.channelBackground.get(pubkey)?.controller.abort()
+      this.channelBackground.delete(pubkey)
       this.cancelReloadGap(pubkey)
       this.cancelLiveRecovery(pubkey)
       this.liveInterruptions.delete(pubkey)
@@ -1785,6 +1829,7 @@ export class PrivateMessenger {
     if (typeof reason !== 'string' || !reason.trim()) throw new ValidationError('PAUSE_REASON_REQUIRED')
     this.assertOpen()
     this.pauseReasons.add(reason)
+    this.pauseRevisions.set(reason, (this.pauseRevisions.get(reason) || 0) + 1)
     this.sendRoutingPause.abort(this.pausedError())
     this.notifyStatus()
     for (const extension of this.extensions) extension.pause?.()
@@ -1793,14 +1838,16 @@ export class PrivateMessenger {
     return Promise.all([this.stopWatches([...this.desiredChannels]), this.flushStateWrites()])
   }
 
-  async resume (reason) {
+  async resume (reason, { waitForBackground = false } = {}) {
     if (typeof reason !== 'string' || !reason.trim()) throw new ValidationError('PAUSE_REASON_REQUIRED')
+    if (typeof waitForBackground !== 'boolean') throw new ValidationError('INVALID_WAIT_FOR_BACKGROUND')
     this.assertOpen()
+    const revision = this.pauseRevisions.get(reason)
     // Repair durable state before announcing that publication can resume.
     if (reason === 'storage' && this.pendingStorageWrites.size) await this.retryStorageWrites(this.sendRoutingLifetime.signal)
     await this.flushStateWrites()
     this.assertOpen()
-    const wasAutomatic = this.automaticPauses.has(reason)
+    if (revision !== this.pauseRevisions.get(reason)) return
     const removed = this.pauseReasons.delete(reason)
     this.automaticPauses.delete(reason)
     if (!this.pauseReasons.size && this.sendRoutingPause.signal.aborted) this.sendRoutingPause = new AbortController()
@@ -1810,29 +1857,75 @@ export class PrivateMessenger {
       this.capacityTimer = null
       this.capacityRequiredBytes = 0
     }
-    if (!removed || this.pauseReasons.size) return
-    if (this.resumeWork) await this.resumeWork
-    if (this.pauseReasons.size || this.closePromise) return
-    const work = (async () => {
-      const channels = [...this.desiredChannels]
+    if (this.pauseReasons.size) return
+    const channels = [...this.desiredChannels]
+    if (removed) {
       this.closeOpenOfflineRanges(channels)
-      await this.watch(channels, { scheduleReloadGap: false })
-      if (this.pauseReasons.size || this.closePromise) return
-      await this.reconcilePresencePublishers()
-      await this.recoverOfflineRanges(channels)
-      for (const pubkey of channels) {
-        if (this.hasPendingRecovery(pubkey)) this.scheduleOfflineRecovery(pubkey, { startDelayMs: 1000 })
-      }
-      for (const extension of this.extensions) await extension.resume?.()
-    })()
-    this.resumeWork = work
-    try { await work } catch (err) {
-      if (!this.closePromise) {
-        if (wasAutomatic && (reason === 'network' ? isRetryableRelayFailure(err) : isRecoverableStorageFailure(err))) this.automaticPauses.add(reason)
-        await this.applyPause(reason)
+      await this.flushStateWrites()
+    }
+    if (this.pauseReasons.size || this.closePromise) return
+    const jobs = removed ? this.startChannelBackground(channels, { recover: true }) : [...this.channelBackground.values()].map(job => job.work)
+    if (removed) {
+      for (const extension of this.extensions) {
+        const work = Promise.resolve().then(() => { if (!this.pauseReasons.size && !this.closePromise) return extension.resume?.() })
+        work.catch(error => this.onError?.(error))
+        jobs.push(work)
       }
-      throw err
-    } finally { if (this.resumeWork === work) this.resumeWork = null }
+    }
+    if (waitForBackground) await Promise.all(jobs)
+  }
+
+  startChannelBackground (channels, { recover = false } = {}) {
+    const jobs = []
+    for (const pubkey of channels) {
+      if (this.closePromise || this.pauseReasons.size || !this.desiredChannels.has(pubkey)) continue
+      let job = this.channelBackground.get(pubkey)
+      if (job) { jobs.push(job.work); continue }
+      const controller = new AbortController()
+      const channel = this.channels.get(pubkey)
+      job = { controller, work: null }
+      this.channelBackground.set(pubkey, job)
+      const active = () => this.initialized && !controller.signal.aborted && !this.closePromise && !this.pauseReasons.size && this.channels.get(pubkey) === channel && this.desiredChannels.has(pubkey)
+      let phase = 'subscribe'
+      let stopAbort
+      const cancelled = new Promise(resolve => {
+        stopAbort = resolve
+        controller.signal.addEventListener('abort', stopAbort, { once: true })
+      })
+      const work = Promise.resolve().then(async () => {
+        if (!this.initialized) await this.initSettledPromise
+        if (!active()) return
+        const release = await this.channelSetupAdmission.acquire(controller.signal)
+        try {
+          if (!active()) return
+          await this.watch([pubkey], { scheduleReloadGap: !recover, signal: controller.signal })
+        } finally { release() }
+        if (!active()) return
+        phase = 'presence'
+        if (doesModeStoreRecoverySeeds(channel.mode)) await this.startPresencePublisher(pubkey)
+        if (!active()) return
+        phase = 'history'
+        if (recover) await this.recoverOfflineRanges([pubkey])
+        if (!active()) return
+        if (recover && this.hasPendingRecovery(pubkey)) this.scheduleOfflineRecovery(pubkey, { startDelayMs: 1000 })
+      }).catch(error => {
+        if (!active()) return
+        const diagnostic = Object.assign(new Error(error?.message || 'PRIVATE_MESSENGER_BACKGROUND_FAILED', { cause: error }), {
+          name: error?.name || 'Error', ...(error?.code ? { code: error.code } : {}),
+          ...(error?.category ? { category: error.category } : {}),
+          operation: 'private-messenger.background', phase
+        })
+        this.onError?.(diagnostic)
+        throw error
+      })
+      job.work = Promise.race([work, cancelled]).finally(() => {
+        controller.signal.removeEventListener('abort', stopAbort)
+        if (this.channelBackground.get(pubkey) === job) this.channelBackground.delete(pubkey)
+      })
+      job.work.catch(() => {})
+      jobs.push(job.work)
+    }
+    return jobs
   }
 
   receive (pubkey, operation, message = {}) {
@@ -2336,16 +2429,16 @@ export class PrivateMessenger {
     })
   }
 
-  async publishSeederPresence (channelPubkey = this.defaultChannelPubkey()) {
+  async publishSeederPresence (channelPubkey = this.defaultChannelPubkey(), { signal } = {}) {
     const channel = this.requireWritableChannel(channelPubkey)
     if (!this.offlineRecoverySecondsFor(channel)) return null
     const receiverPubkeys = uniq([...this.knownSeeders(channelPubkey), this.userPubkey])
-    const routing = await this.resolveSendRouting({ channel, receiverPubkeys })
+    const routing = await this.resolveSendRouting({ channel, receiverPubkeys, signal })
     this.debugSend('yell', channelPubkey, { code: SEEDER_PRESENCE_CODE, receiverPubkeys })
     return this._privateMessage.yell({
-      senderSigner: this.userSigner,
-      imkcSigner: this.contentKeySigner,
-      privateChannelSigner: channel.signer,
+      senderSigner: backgroundSigner(this.userSigner, this._waitForForeground, signal),
+      imkcSigner: backgroundSigner(this.contentKeySigner, this._waitForForeground, signal),
+      privateChannelSigner: backgroundSigner(channel.signer, this._waitForForeground, signal),
       privateChannelReaderPubkey: channel.readerPubkey,
       receiverPubkeys,
       ...routing,
@@ -2362,22 +2455,40 @@ export class PrivateMessenger {
   async startPresencePublisher (channelPubkey) {
     if (this.pauseReasons.size || !this.desiredChannels.has(channelPubkey) || !this.offlineRecoverySecondsFor(channelPubkey)) return
     if (this.presenceTimers.has(channelPubkey)) return
-    try {
-      await this.publishSeederPresence(channelPubkey)
-    } catch (err) {
-      console.warn('private-messenger seeder presence failed', err?.message ?? err)
+    if (this.presenceJobs.has(channelPubkey)) return this.presenceJobs.get(channelPubkey).work
+    const job = { controller: new AbortController(), work: null }
+    const active = () => this.presenceJobs.get(channelPubkey) === job && !this.pauseReasons.size && !this.closePromise && this.desiredChannels.has(channelPubkey)
+    let publishing = false
+    const publish = async () => {
+      if (!active() || publishing) return
+      publishing = true
+      let release
+      try {
+        release = await this.presenceAdmission.acquire(job.controller.signal)
+        job.controller.signal.addEventListener('abort', release, { once: true })
+        if (active()) await this.publishSeederPresence(channelPubkey, { signal: job.controller.signal })
+      } catch (error) {
+        if (active()) this.onError?.(Object.assign(new Error(error?.message, { cause: error }), { operation: 'private-messenger.background', phase: 'presence' }))
+      } finally {
+        if (release) { job.controller.signal.removeEventListener('abort', release); release() }
+        publishing = false
+      }
     }
-    if (this.pauseReasons.size || this.closePromise || !this.desiredChannels.has(channelPubkey)) return
-    const timer = this._setInterval(() => {
-      return this.publishSeederPresence(channelPubkey).catch(err => {
-        console.warn('private-messenger seeder presence failed', err?.message ?? err)
-      })
-    }, this.seederPresenceIntervalMs)
-    timer?.unref?.()
-    this.presenceTimers.set(channelPubkey, timer)
+    const work = Promise.resolve().then(async () => {
+      await publish()
+      if (!active()) return
+      const timer = this._setInterval(publish, this.seederPresenceIntervalMs)
+      timer?.unref?.()
+      this.presenceTimers.set(channelPubkey, timer)
+    })
+    job.work = work
+    this.presenceJobs.set(channelPubkey, job)
+    return work
   }
 
   stopPresencePublisher (channelPubkey) {
+    this.presenceJobs.get(channelPubkey)?.controller.abort()
+    this.presenceJobs.delete(channelPubkey)
     const timer = this.presenceTimers.get(channelPubkey)
     if (timer) this._clearInterval(timer)
     this.presenceTimers.delete(channelPubkey)
@@ -2458,7 +2569,7 @@ export class PrivateMessenger {
     return seconds ? seconds * 1000 : DEFAULT_RECEIVED_CHUNK_TTL_MS
   }
 
-  async applyRecoveryPolicies (channels) {
+  async applyRecoveryPolicies (channels, { prune = true } = {}) {
     return this.runQueueOperation(async () => {
       const state = this.readState()
       const now = nowSeconds()
@@ -2484,7 +2595,7 @@ export class PrivateMessenger {
       for (const channel of channels) {
         if (!this.offlineRecoverySecondsFor(channel)) this.dropRecoveryState(channel.pubkey)
       }
-      for (const channel of channels) await this.pruneStoredSeeds(channel.pubkey)
+      if (prune) for (const channel of channels) await this.pruneStoredSeeds(channel.pubkey)
     })
   }
 
@@ -3070,6 +3181,7 @@ export class PrivateMessenger {
       let unwatchError
       try { await unwatchPromise } catch (err) { unwatchError = err }
       await initSettledPromise
+      await this.updateTail.catch(() => {})
       await Promise.all([...this.extensions].map(extension => extension.close?.()))
       await this.stampActiveChannelActivity()
       await this.queueOperationTail

package/private-messenger/session/README.md

@@ -15,10 +15,35 @@ back to sender-content whenever a proof is missing or the lookup fails. Misses
 are cached for 5 minutes (found proofs for 40), so a later prefetch picks up a
 key published after an earlier miss. Set it to `false` when the signer owns that discovery. The DM context is `dm`; file contexts are `dm:media:<root>`.
 `createMessengerSigner` adapts this byte signer to the transport's Base64 API.
+Each adapter belongs to an immutable account/channel identity: it shares the
+first successful public-key lookup and retries failed lookups only on a new call.
+Create a new adapter when changing identity. Signing/encryption still uses the
+real signer and its current permissions on every operation.
 
-Methods: `setPeers`, `setAvailable(boolean)`, `prefetchContentKeys(peers?)`,
+Methods: `setPeers`, `setAvailable(boolean)`, `preparePeer(peer)`, `prefetchContentKeys(peers?)`,
 `prioritizeRange(peer, options)`, `enqueue`, `retry`, `cancel`, `download`,
 `cancelDownload`, and `close`.
+
+The session creates one messenger for the account, independently of contact
+revisions. `setPeers` and `setAvailable` reconcile local configuration without
+awaiting all contacts or remote recovery. Channel preparation is incremental and
+deduplicated: at most four preparations run, with at most three in the background.
+`preparePeer(peer)` promotes an existing contact and resolves when its channel is
+locally writable. Call it when opening a conversation; enqueue, retry and remote
+download also request preparation automatically. An unprepared conversation does
+not block local saves or sends to a ready contact. Resolved identities are reused.
+The session also defers the next optional presence signer call while user outbox
+writes/publications are active. Existing signer calls, subscriptions and historical
+coverage remain intact; releasing foreground work resumes the waiting presence.
+Successful sends remove the final outbox record directly instead of encrypting a
+redundant final checkpoint; intermediate context/file checkpoints remain durable.
+
+Known transient preparation failures retry with bounded offline-aware backoff;
+unknown, permission and validation failures remain isolated to that contact until
+explicit preparation/retry or a real availability transition. Removing a contact,
+locking or closing discards obsolete signer results and cancels its queued work.
+Contact changes never invent a `signer` pause; only `setAvailable` controls that
+reason. Storage, capacity, network and explicit pauses keep their own owners.
 `prefetchContentKeys` warms the content-key lookup cache for the owner and the
 given peers (default: current peers); it is best-effort and never rejects.
 `prioritizeRange` registers an in-memory priority window for a conversation:

package/private-messenger/session/helpers/foreground-work.js

@@ -0,0 +1,29 @@
+// Local outbox persistence and user publications take precedence over the next
+// optional presence signer call. Already-started signer calls are not recalled.
+export function createForegroundWork () {
+  let active = 0
+  const waiters = new Set()
+  const lifetime = new AbortController()
+  return {
+    enter () {
+      active++
+      let released = false
+      return () => {
+        if (released) return
+        released = true
+        if (--active === 0) for (const wake of [...waiters]) wake()
+      }
+    },
+    wait (signal) {
+      const combined = signal ? AbortSignal.any([signal, lifetime.signal]) : lifetime.signal
+      combined.throwIfAborted()
+      if (!active) return Promise.resolve()
+      return new Promise((resolve, reject) => {
+        const finish = () => { waiters.delete(finish); combined.removeEventListener('abort', finish); combined.aborted ? reject(combined.reason) : resolve() }
+        waiters.add(finish)
+        combined.addEventListener('abort', finish, { once: true })
+      })
+    },
+    close () { lifetime.abort(); waiters.clear() }
+  }
+}

package/private-messenger/session/helpers/peer-preparation.js

@@ -0,0 +1,111 @@
+import { createPauseRecovery } from '../../helpers/pause-recovery.js'
+
+// One account owns the queue. Background work may occupy only three of the
+// four slots so a newly opened conversation never sits behind the whole list.
+export function createPeerPreparation ({ prepare, onReady, onError, isRetryable, online, onOnline, setTimer, clearTimer, random }) {
+  const entries = new Map()
+  let enabled = false
+  let closed = false
+  let running = 0
+  let background = 0
+  const unavailable = () => new Error('CHAT_UNAVAILABLE')
+  function entryFor (peer) {
+    const deferred = Promise.withResolvers()
+    deferred.promise.catch(() => {})
+    return { peer, ...deferred, controller: new AbortController(), state: 'queued', priority: false, value: null, error: null, recovery: null }
+  }
+  const current = entry => !closed && enabled && entries.get(entry.peer) === entry && !entry.controller.signal.aborted
+  function cancel (entry) {
+    entry.recovery?.stop()
+    entry.controller.abort(unavailable())
+    entry.reject(entry.controller.signal.reason)
+    entry.retryResult?.resolve()
+    entry.retryResult = null
+  }
+  function drain () {
+    if (!enabled || closed) return
+    while (running < 4) {
+      const queued = [...entries.values()].filter(entry => entry.state === 'queued')
+      const entry = queued.find(entry => entry.priority) || (background < 3 && queued[0])
+      if (!entry) break
+      const isBackground = !entry.priority
+      entry.state = 'running'
+      running++
+      if (isBackground) background++
+      Promise.resolve().then(() => {
+        entry.controller.signal.throwIfAborted()
+        return prepare(entry.peer, entry.controller.signal)
+      }).then(value => {
+        if (!current(entry)) return
+        entry.state = 'ready'; entry.value = value
+        entry.resolve(value)
+        onReady(entry.peer, value)
+      }, error => {
+        if (!current(entry)) return
+        entry.error = error
+        onError(error)
+        if (!isRetryable(error)) {
+          entry.state = 'failed'; entry.reject(error)
+          entry.retryResult?.reject(error); entry.retryResult = null
+          onReady(entry.peer)
+          return
+        }
+        entry.state = 'waiting'
+        entry.recovery ||= createPauseRecovery({
+          attempt: async signal => {
+            signal.throwIfAborted()
+            if (!current(entry)) return
+            entry.state = 'queued'; drain()
+            // Recovery waits for the actual preparation; no slot is held
+            // during backoff or a connectivity wait.
+            await new Promise((resolve, reject) => { entry.retryResult = { resolve, reject } })
+          },
+          retryable: isRetryable, onError: () => {}, online, onOnline, setTimer, clearTimer, random
+        })
+        if (entry.retryResult) { entry.retryResult.reject(error); entry.retryResult = null } else entry.recovery.start({ retryAt: error.retryAt })
+      }).finally(() => {
+        if (entry.state === 'ready') { entry.retryResult?.resolve(); entry.retryResult = null }
+        if (!current(entry)) { entry.retryResult?.resolve(); entry.retryResult = null }
+        running--
+        if (isBackground) background--
+        drain()
+      })
+    }
+  }
+  return {
+    get: peer => entries.get(peer)?.value,
+    error: peer => entries.get(peer)?.state === 'failed' ? entries.get(peer).error : null,
+    reconcile (peers) {
+      const wanted = new Set(peers)
+      for (const [peer, entry] of entries) if (!wanted.has(peer)) { entries.delete(peer); cancel(entry) }
+      for (const peer of wanted) if (!entries.has(peer)) entries.set(peer, entryFor(peer))
+      drain()
+    },
+    setAvailable (value) {
+      enabled = value === true
+      if (!enabled) {
+        for (const [peer, entry] of entries) {
+          if (entry.state === 'ready') continue
+          cancel(entry)
+          const replacement = entryFor(peer)
+          replacement.priority = entry.priority
+          entries.set(peer, replacement)
+        }
+      }
+      drain()
+    },
+    request (peer, { retry = false } = {}) {
+      if (closed || !entries.has(peer)) return Promise.reject(unavailable())
+      let entry = entries.get(peer)
+      if (retry && entry.state === 'failed') { cancel(entry); entries.set(peer, (entry = entryFor(peer))) }
+      entry.priority = true
+      drain()
+      return entry.promise
+    },
+    close () {
+      closed = true; enabled = false
+      for (const entry of entries.values()) cancel(entry)
+      entries.clear()
+    }
+  }
+}

package/private-messenger/session/helpers/signer.js

@@ -3,8 +3,12 @@ import { base64ToBytes, bytesToBase64 } from '../../../base64/index.js'
 // The library transport uses its Base64 signer contract. Conversion stays at
 // this adapter; the injected launcher/vault channel always carries raw bytes.
 export function messengerSigner (signer) {
+  // The adapter belongs to one account/channel generation. Share both the
+  // lookup in flight and its immutable result; failed permissions are retryable
+  // only when the owning session explicitly asks again.
+  let publicKey
   const adapter = {
-    getPublicKey: () => signer.getPublicKey(),
+    getPublicKey: () => (publicKey ??= Promise.resolve().then(() => signer.getPublicKey()).catch(error => { publicKey = null; throw error })),
     getRelays: () => signer.getRelays(),
     signEvent: event => signer.signEvent(event),
     nip44v3Encrypt: (peer, kind, scope, text) => signer.nip44v3.encrypt(peer, kind, scope, base64ToBytes(text).buffer),

package/private-messenger/session/index.js

@@ -4,7 +4,10 @@ import { createPrivateMessenger } from '../index.js'
 import { getEventHash, isValidEvent, isSerializableEvent } from '../../event/index.js'
 import { decodeIrfsChunk, IRFS_CHUNK_BYTES } from '../../irfs/index.js'
 import { getIykcProofs } from '../../content-key/index.js'
-import { onOnline } from '../../network/index.js'
+import { isOnline, onOnline } from '../../network/index.js'
+import { createPeerPreparation } from './helpers/peer-preparation.js'
+import { createForegroundWork } from './helpers/foreground-work.js'
+import { isRetryableRelayFailure } from '../../relay/index.js'
 import { ValidationError } from '../../error/index.js'
 import { decodeFileMetadata } from '../../nip94/index.js'
 import { createChatOutbox } from './helpers/work-storage.js'
@@ -41,7 +44,7 @@ function messengerStatusSnapshot (value) {
   return { closed: value.closed, paused: value.paused, pauseReasons: [...value.pauseReasons] }
 }
 
-export function createPrivateMessageSession ({ owner, signer, eventStore, messageStorage, chunkStorage, recoveryStorage, fallbackRelays = [], fallbackDelayMs = null, mode = 'seeder', seedersForPeer = peer => [peer], allowedKinds = [5, 9, 1063, 34601], useContentKeys = true, onMedia = () => {}, onOutbox = () => {}, onError = () => {}, onSendError = () => {}, Messenger = createPrivateMessenger, openOutbox = createChatOutbox, FileTransfer = createPrivateFileTransfer, _onOnline = onOnline, _getIykcProofs = getIykcProofs, _setTimeout = setTimeout, _clearTimeout = clearTimeout, _random = Math.random, openDownloads = options => createChatOutbox({ ...options, namespace: 'downloads' }) }) {
+export function createPrivateMessageSession ({ owner, signer, eventStore, messageStorage, chunkStorage, recoveryStorage, fallbackRelays = [], fallbackDelayMs = null, mode = 'seeder', seedersForPeer = peer => [peer], allowedKinds = [5, 9, 1063, 34601], useContentKeys = true, onMedia = () => {}, onOutbox = () => {}, onError = () => {}, onSendError = () => {}, Messenger = createPrivateMessenger, openOutbox = createChatOutbox, FileTransfer = createPrivateFileTransfer, _onOnline = onOnline, _isOnline = isOnline, _getIykcProofs = getIykcProofs, _setTimeout = setTimeout, _clearTimeout = clearTimeout, _random = Math.random, openDownloads = options => createChatOutbox({ ...options, namespace: 'downloads' }) }) {
   fallbackRelays = normalizeFallbackRelays(fallbackRelays)
   fallbackDelayMs = normalizeFallbackDelay(fallbackDelayMs)
   const reportedErrors = new WeakSet()
@@ -53,11 +56,11 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
     onError(error)
   }
   const userSigner = messengerSigner(signer)
+  const foreground = createForegroundWork()
   messageStorage ||= createEventStoreMessageStorage({ eventStore })
   chunkStorage ||= eventStore ? createEventStoreChunkStorage({ eventStore }) : undefined
   const peers = new Set()
   const channels = new Map()
-  const deniedPeers = new Set()
   const entries = new Map()
   const cancelled = new Set()
   const sendControllers = new Map()
@@ -113,6 +116,10 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
   let lifecycle = 0
   let configuring = Promise.resolve()
   let configurationFailed = false
+  let configureQueued = false
+  let configureWork
+  let messengerWork
+  let fileSetupWork
   let sending
   let repump
   let draining
@@ -132,7 +139,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
     let candidate
     try {
       candidate = await Messenger({
-        fallbackRelays, fallbackDelayMs, seedStorage: recoveryStorage?.seeds, userSigner, channels: [], useContentKeys,
+        fallbackRelays, fallbackDelayMs, seedStorage: recoveryStorage?.seeds, userSigner, channels: [], useContentKeys, _waitForForeground: foreground.wait,
         onMessageQueued: () => { if (messengerBinding === binding) return drain() },
         onStateChanged: state => {
           if (closed || messengerBinding !== binding) return
@@ -154,28 +161,41 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
     }
   }
 
+  const preparation = createPeerPreparation({
+    prepare: async (peer, signal) => {
+      const scoped = messengerSigner(signer.withSharedKey(peer, 'dm'))
+      const pubkey = await scoped.getPublicKey()
+      signal.throwIfAborted()
+      const channel = { signer: scoped, pubkey, readerPubkey: pubkey, mode, seeders: seedersForPeer(peer) }
+      channels.set(peer, channel)
+      await schedule()
+      signal.throwIfAborted()
+      return channel
+    },
+    onReady: () => { drain(); pump() }, onError: reportError,
+    isRetryable: error => ['connection', 'transport', 'timeout'].includes(error?.category) && isRetryableRelayFailure(error),
+    online: _isOnline, onOnline: _onOnline, setTimer: _setTimeout, clearTimer: _clearTimeout, random: _random
+  })
+  async function ensureMessenger () {
+    if (!messenger && !messengerWork) {
+      const work = createMessenger()
+      messengerWork = work
+      work.finally(() => { if (messengerWork === work) messengerWork = null }).catch(() => {})
+    }
+    await messengerWork
+  }
   async function configure () {
     if (closed || !available) return
-    await ready()
     const version = lifecycle
-    const values = []
-    for (const peer of peers) {
-      if (deniedPeers.has(peer)) continue
-      let channel = channels.get(peer)
-      if (!channel) {
-        try {
-          const scoped = messengerSigner(signer.withSharedKey(peer, 'dm'))
-          channel = { signer: scoped, pubkey: await scoped.getPublicKey(), mode, seeders: seedersForPeer(peer) }
-          channels.set(peer, channel)
-        } catch (error) { if (!retryable(error)) deniedPeers.add(peer); reportError(error); continue }
-      }
-      if (closed || !available || version !== lifecycle) return
-      values.push(channel)
-    }
-    if (!messenger) await createMessenger()
+    await ready()
+    if (closed || !available || version !== lifecycle) return
+    await ensureMessenger()
     if (!messenger) return
-    if (closed || !available || version !== lifecycle) { await messenger.pause('signer'); return }
+    if (closed || !available) { await messenger.pause('signer'); return }
+    if (version !== lifecycle) { configureQueued = true; return }
+    const values = [...channels].filter(([peer]) => peers.has(peer)).map(([, channel]) => channel)
     await messenger.update({ channels: values })
+    if (closed || !available || version !== lifecycle) return
     if (pendingPriorityRanges.size && typeof messenger.prioritizeRange === 'function') {
       for (const [peer, list] of [...pendingPriorityRanges]) {
         const channel = channels.get(peer)
@@ -187,7 +207,16 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       }
     }
     await messenger.resume('signer')
+    if (closed || !available || version !== lifecycle) return
+    preparation.setAvailable(true)
     if (storageBlocked) inboxRecovery.start({ immediate: true })
+    if (!fileSetupWork) {
+      fileSetupWork = setupFiles().catch(error => { fileSetupWork = null; if (!closed) reportError(error) })
+    }
+    fileSetupWork.then(() => { if (!closed && available) restoreDownloads() }).catch(reportError)
+    drain(); pump()
+  }
+  async function setupFiles () {
     if (!fileTransfers) {
       fileTransfers = FileTransfer({
         messenger, onError: reportError,
@@ -206,9 +235,17 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
           }
         }
       })
-      downloads = await openDownloads({ owner, signer })
-      for (const entry of await downloads.list()) downloadIntents.set(entry.id, entry)
     }
+    if (!downloads) {
+      const candidate = await openDownloads({ owner, signer })
+      try {
+        const intents = await candidate.list()
+        downloads = candidate
+        for (const entry of intents) downloadIntents.set(entry.id, entry)
+      } catch (error) { await candidate.close?.(); throw error }
+    }
+  }
+  function restoreDownloads () {
     for (const entry of downloadIntents.values()) {
       if (!peers.has(entry.file.peer) || activeDownloads.has(entry.id)) continue
       const work = download(entry.file, { manual: true })
@@ -220,12 +257,37 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
         .finally(() => { if (activeDownloads.get(entry.id) === work) activeDownloads.delete(entry.id) })
       activeDownloads.set(entry.id, work)
     }
-    drain(); pump()
+    pump()
   }
   function schedule () {
-    const work = configuring.catch(() => {}).then(configure)
-    configuring = work
-    work.then(() => { if (configuring === work) configurationFailed = false }, error => { if (configuring === work) configurationFailed = true; reportError(error) })
+    configureQueued = true
+    if (configureWork) return configureWork
+    const work = Promise.resolve().then(async () => {
+      try {
+        do {
+          configureQueued = false
+          await configure()
+          if (closed || !available) break
+        } while (configureQueued)
+      } finally { if (configureWork === work) configureWork = null }
+    })
+    configureWork = configuring = work
+    work.then(() => {
+      if (configureWork === work) configureWork = null
+      configurationFailed = false
+    }, error => {
+      if (configureWork === work) configureWork = null
+      configurationFailed = true
+      if (!closed) reportError(error)
+    }).catch(() => {})
+    return work
+  }
+  async function preparePeer (peer, { retry = true } = {}) {
+    if (typeof peer !== 'string' || !/^[0-9a-f]{64}$/i.test(peer)) throw new ValidationError('INVALID_PRIVATE_PEER')
+    if (closed || !available || !peers.has(peer)) throw new Error('CHAT_UNAVAILABLE')
+    const work = preparation.request(peer, { retry })
+    work.catch(() => {})
+    if (!messenger || configurationFailed) await schedule()
     return work
   }
   async function drain () {
@@ -285,7 +347,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
     }
   }
   async function publish (peer, event, signal) {
-    if (deniedPeers.has(peer)) throw new Error('PERMISSION_DENIED')
+    if (preparation.error(peer)) throw preparation.error(peer)
     if (!available || !peers.has(peer) || !channels.has(peer)) throw unavailableError(new Error('CHAT_UNAVAILABLE'), signal)
     const options = { channelPubkey: channels.get(peer)?.pubkey, receiverPubkeys: [peer], signal }
     let report
@@ -299,6 +361,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
     await assertMessagePublished(report, event)
   }
   async function sendEntry (entry) {
+    const releaseForeground = foreground.enter()
     entry.status = 'pending'; emit()
     const controller = new AbortController()
     sendControllers.set(entry.id, controller)
@@ -321,6 +384,11 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
           await storage.put(entry, { existing: true })
         }
       }
+      if (entry.peer !== owner && !preparation.get(entry.peer)) {
+        if (preparation.error(entry.peer)) throw preparation.error(entry.peer)
+        preparation.request(entry.peer).catch(() => {})
+        return
+      }
       if (entry.peer !== owner && messengerStatus?.paused) {
         throw unavailableError(Object.assign(new Error('PRIVATE_MESSENGER_PAUSED'), { pauseReasons: [...messengerStatus.pauseReasons] }), controller.signal)
       }
@@ -356,7 +424,9 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
         const event = entry.events[entry.index]
         if (entry.peer !== owner) await publish(entry.peer, event, controller.signal)
         await active()
-        await storage.put({ ...entry, index: entry.index + 1 }, { existing: true })
+        // The final durable operation is removal. Avoid encrypting a checkpoint
+        // that would immediately be deleted; earlier context stages still checkpoint.
+        if (entry.index + 1 < entry.events.length) await storage.put({ ...entry, index: entry.index + 1 }, { existing: true })
       }
       await storage.remove(entry.id)
       entries.delete(entry.id)
@@ -368,16 +438,22 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       if (cancelled.has(entry.id)) { await storage.remove(entry.id); entries.delete(entry.id) } else {
         entry.status = error.retryWhenAvailable ? 'pending' : 'error'; entry.failed = true; entry.retryable = retryable(error)
         await storage.put(entry, { existing: true }).catch(reportError)
-        if (entry.peer !== owner && error.retryWhenAvailable && messenger.readStatus().paused) pausedSends.add(entry.id)
+        if (entry.peer !== owner && error.retryWhenAvailable && messenger?.readStatus().paused) pausedSends.add(entry.id)
+        else if (isUnavailableSend(cause) && cause.pauseReasons?.length && available && !closed) {
+          // Release can race persistence of the failed attempt. Do not lose
+          // its notification and spend a retry delay after the pause is gone.
+          entry.failed = false
+          queueMicrotask(() => pump())
+        }
         reportError(error)
         // The failed wire event may be a quote or file chunk. Report the
         // owning outbox item separately, without mutating the native error.
         if (error.retryWhenOnline) offlineSends.add(entry.id)
-        if (error.retryWhenAvailable && !pausedSends.has(entry.id)) scheduleSendRetry()
+        if (entry.failed && error.retryWhenAvailable && !pausedSends.has(entry.id)) scheduleSendRetry()
         if (!closed && !entry.deletion && !cancelled.has(entry.id) && !error.retryWhenAvailable) onSendError(error, { id: entry.id, peer: entry.peer })
       }
       emit()
-    } finally { sendControllers.delete(entry.id) }
+    } finally { sendControllers.delete(entry.id); releaseForeground() }
   }
   function stopOnlineRetry () { stopOnline?.(); stopOnline = undefined }
   // Transient availability failures without an active messenger pause retain
@@ -425,7 +501,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
     })
   }
   async function pump () {
-    if (!available || closed || !messenger || !storage) return
+    if (!available || closed || !storage) return
     // A retry that lands while a pump is already running must not be skipped
     // just because that pass already walked past the entry.
     if (sending) { repump = true; return }
@@ -436,6 +512,10 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
         for (const entry of entries.values()) {
           if (closed || !available) break
           if ((entry.peer !== owner && !peers.has(entry.peer)) || entry.failed || cancelled.has(entry.id)) continue
+          if (entry.peer !== owner && entry.localSaved.every(Boolean) && !preparation.get(entry.peer) && !preparation.error(entry.peer)) {
+            preparation.request(entry.peer).catch(() => {})
+            continue
+          }
           if (entry.peer !== owner && entry.files.length && !fileTransfers) continue
           await sendEntry(entry)
         }
@@ -450,7 +530,10 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
   const intentId = file => getEventHash({ kind: 0, pubkey: owner, created_at: 0, tags: [], content: `${file.peer}:${file.root}` })
   async function download (file, options = {}) {
     if (file.peer === owner) return file
-    if (!available || closed || !peers.has(file.peer) || !fileTransfers) throw new Error('CHAT_UNAVAILABLE')
+    if (!available || closed || !peers.has(file.peer)) throw new Error('CHAT_UNAVAILABLE')
+    await preparePeer(file.peer)
+    await fileSetupWork
+    if (!fileTransfers || !downloads) throw new Error('CHAT_UNAVAILABLE')
     const id = intentId(file)
     if (options.manual) {
       const epoch = downloadEpochs.get(id) || 0
@@ -475,7 +558,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
     await writeDownloadIntent(() => downloads?.remove(id))
   }
   return {
-    download, cancelDownload,
+    download, cancelDownload, preparePeer,
     // Peers-based so callers can prefetch as soon as a chat route opens, before
     // the shared-key channel exists. When group chats get real membership, add
     // a thin prefetchChannelContentKeys(channelPubkey) wrapper that resolves
@@ -503,20 +586,28 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       if (type === 'unread-page' && since === undefined) throw new TypeError('PRIORITY_SINCE_REQUIRED')
       const request = { since, until, type }
       const channel = channels.get(peer)
-      if (channel && typeof messenger?.prioritizeRange === 'function') {
+      if (channel && preparation.get(peer) && !pendingPriorityRanges.has(peer) && typeof messenger?.prioritizeRange === 'function') {
         try { return await messenger.prioritizeRange(channel.pubkey, request) } catch (error) { reportError(error); return false }
       }
       const list = pendingPriorityRanges.get(peer) || []
       list.push(request)
       pendingPriorityRanges.set(peer, list)
+      if (channel && available) schedule().catch(() => {})
       return true
     },
     async setPeers (values) {
       const next = new Set([...values].filter(peer => peer !== owner))
       if (next.size === peers.size && [...next].every(peer => peers.has(peer))) return configuring
       peers.clear(); for (const peer of next) peers.add(peer)
-      for (const peer of deniedPeers) if (!peers.has(peer)) deniedPeers.delete(peer)
-      lifecycle++
+      preparation.reconcile(peers)
+      for (const peer of channels.keys()) {
+        if (!peers.has(peer)) {
+          channels.delete(peer); pendingPriorityRanges.delete(peer)
+          for (const entry of entries.values()) {
+            if (entry.peer === peer) sendControllers.get(entry.id)?.abort()
+          }
+        }
+      }
       return schedule()
     },
     async setAvailable (value) {
@@ -527,31 +618,39 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       if (available) resetSendRetry()
       else clearSendRetry()
       if (changed) lifecycle++
-      if (!available) { inboxRecovery.stop(); await messenger?.pause('signer'); return }
+      if (!available) {
+        preparation.setAvailable(false)
+        for (const peer of channels.keys()) if (!preparation.get(peer)) channels.delete(peer)
+        inboxRecovery.stop(); await messenger?.pause('signer'); return
+      }
       await ready()
       for (const entry of entries.values()) if (pendingRetryable(entry)) entry.failed = false
       if (storageBlocked) inboxRecovery.start({ immediate: true })
-      if (!changed && messenger && !configurationFailed) return pump()
+      if (!changed && messenger && !configurationFailed) { preparation.setAvailable(true); pump(); return configuring }
       return schedule()
     },
     async enqueue ({ peer, event, context = [], requiredFiles = [], deletion = false }) {
       if (closed || !available || (peer !== owner && !peers.has(peer))) throw new Error('CHAT_UNAVAILABLE')
-      await ready()
-      const main = wireEvent(event, owner)
-      const id = getEventHash(main)
-      const events = [...context.map(value => wireEvent(value, owner)), main]
-      const files = events.filter(value => value.kind === 1063).map(value => ({ ...decodeFileMetadata(value), optional: !requiredFiles.includes(getEventHash(value)) })).filter(file => file.service === 'irfs').flatMap(file => [file, ...(file.thumbnail?.root ? [{ ...file.thumbnail, optional: file.optional }] : [])])
-      const entry = { id, peer, event: { ...main, id }, events, files, index: 0, fileIndex: 0, chunkIndex: 0, localSaved: context.map(() => true).concat(false), status: 'pending', deletion }
-      await storage.put(entry)
-      entries.set(id, entry); emit(); pump()
-      return id
+      const releaseForeground = foreground.enter()
+      try {
+        await ready()
+        const main = wireEvent(event, owner)
+        const id = getEventHash(main)
+        const events = [...context.map(value => wireEvent(value, owner)), main]
+        const files = events.filter(value => value.kind === 1063).map(value => ({ ...decodeFileMetadata(value), optional: !requiredFiles.includes(getEventHash(value)) })).filter(file => file.service === 'irfs').flatMap(file => [file, ...(file.thumbnail?.root ? [{ ...file.thumbnail, optional: file.optional }] : [])])
+        const entry = { id, peer, event: { ...main, id }, events, files, index: 0, fileIndex: 0, chunkIndex: 0, localSaved: context.map(() => true).concat(false), status: 'pending', deletion }
+        await storage.put(entry)
+        entries.set(id, entry); emit(); pump()
+        if (peer !== owner) preparePeer(peer).catch(() => {})
+        return id
+      } finally { releaseForeground() }
     },
     async retry (id) {
       offlineSends.delete(id); pausedSends.delete(id); watchOfflineSends()
       if (storageBlocked) inboxRecovery.start({ immediate: true })
       await ready()
       const entry = entries.get(id)
-      if (entry) { entry.failed = false; resetSendRetry(); if (deniedPeers.delete(entry.peer)) await schedule(); return pump() }
+      if (entry) { entry.failed = false; resetSendRetry(); if (entry.peer !== owner) preparePeer(entry.peer).catch(() => {}); return pump() }
     },
     async cancel (id) {
       cancelled.add(id)
@@ -566,9 +665,9 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       return (closeWork ??= (async () => {
         closed = true; available = false; lifecycle++
         stopOnlineRetry(); offlineSends.clear(); activeDownloads.clear(); pendingPriorityRanges.clear()
-        clearSendRetry(); inboxRecovery.stop(); pausedSends.clear()
+        clearSendRetry(); inboxRecovery.stop(); preparation.close(); foreground.close(); pausedSends.clear()
         for (const controller of sendControllers.values()) controller.abort()
-        await Promise.allSettled([configuring, initialized])
+        await Promise.allSettled([configuring, initialized, messengerWork, fileSetupWork])
         await messenger?.pause('closed')
         if (sending || draining) await new Promise(resolve => idleWaiters.add(resolve))
         await messenger?.close()