libp2r2p 0.11.17 → 0.11.19

package/private-messenger/index.js

@@ -48,7 +48,8 @@ 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 { createSendRelayRouting, normalizeFallbackRelays } from './helpers/send-routing.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'
 import { normalizeRelayUrl } from '../url/index.js'
@@ -212,6 +213,7 @@ export class PrivateMessenger {
 
   constructor ({
     fallbackRelays = [],
+    fallbackDelayMs = null,
     offlineRecoverySeconds = DEFAULT_OFFLINE_RECOVERY_SECONDS,
     staleChannelSeconds = DEFAULT_STALE_CHANNEL_SECONDS,
     identityStorageRetentionSeconds = DEFAULT_IDENTITY_STORAGE_RETENTION_SECONDS,
@@ -242,6 +244,7 @@ export class PrivateMessenger {
     _pickRelaysForPubkeys = pickRelaysForPubkeys,
     _subscribeRelayListUpdates = subscribeRelayListUpdates,
     _isOnline = isOnline,
+    _waitForForeground,
     _onOnline = onOnline,
     _random = Math.random,
     _setTimeout = globalThis.setTimeout.bind(globalThis),
@@ -254,6 +257,7 @@ export class PrivateMessenger {
   } = {}) {
     if (onStateChanged != null && typeof onStateChanged !== 'function') throw new ValidationError('INVALID_ON_STATE_CHANGED')
     this.fallbackRelays = normalizeFallbackRelays(fallbackRelays)
+    this.fallbackDelayMs = normalizeFallbackDelay(fallbackDelayMs)
     this.offlineRecoverySeconds = normalizeOfflineRecoverySeconds(offlineRecoverySeconds)
     this.staleChannelSeconds = normalizeStaleChannelSeconds(staleChannelSeconds)
     this.identityStorageRetentionSeconds = normalizeIdentityStorageRetentionSeconds(identityStorageRetentionSeconds)
@@ -302,8 +306,10 @@ 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()
     this._setTimeout = _setTimeout
     this._clearTimeout = _clearTimeout
     this._setInterval = _setInterval
@@ -338,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
@@ -347,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
@@ -432,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()
@@ -670,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,
@@ -689,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))
@@ -706,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()
@@ -740,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) {
@@ -769,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)
@@ -801,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' }))
@@ -820,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))
   }
 
@@ -841,6 +883,8 @@ export class PrivateMessenger {
       peers: fixed && !recipients.length ? [this.userPubkey] : recipients, relaysByPubkey, recoveryRelays, primaryRelays: fixed?.map(normalizeRelayUrl), primaryRelayToReceivers: relayToReceivers, fallbackRelays: this.fallbackRelays,
       signal: signal ? AbortSignal.any([this.sendRoutingLifetime.signal, signal]) : this.sendRoutingLifetime.signal,
       exclusions: this.sendRelayExclusions.get(key).exclusions,
+      fallbackDelayMs: this.fallbackDelayMs, pauseSignal: this.sendRoutingPause.signal,
+      setTimer: this._setTimeout, clearTimer: this._clearTimeout,
       pickRelays: this._pickRelaysForPubkeys,
       publish: this._privateChannel.publish || privateChannel.publish,
       publishNymEvent: this._privateChannel.publishNymEvent || privateChannel.publishNymEvent,
@@ -1119,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) {
@@ -1143,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,
@@ -1169,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
@@ -1650,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)
@@ -1780,6 +1829,8 @@ 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?.()
     this.recordInterruption(this.desiredChannels)
@@ -1787,45 +1838,94 @@ 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()
     this.notifyStatus()
     if (reason === 'capacity' && removed) {
       clearInterval(this.capacityTimer)
       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 = {}) {
@@ -2329,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,
@@ -2355,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)
@@ -2451,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()
@@ -2477,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)
     })
   }
 
@@ -3063,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:
@@ -110,7 +135,7 @@ const session = createPrivateMessageSession({
 })
 ```
 
-Automatic sends try each recipient's NIP-65 read relays first, at most two per
+By default, automatic sends try each recipient's NIP-65 read relays first, at most two per
 recipient per attempt, then the configured fallbacks in pairs. Explicit
 per-call `relays`, channel `sendRelays`/`relays` and global `relays` remain primary
 and also support configured fallbacks, including fixed multi-recipient sends.
@@ -122,6 +147,19 @@ and encrypted recipient subsets, without consulting recipient NIP-65 lists.
 The session coordinator remains a DM API; multi-recipient channels use
 `createPrivateMessenger` directly.
 
+Optional `fallbackDelayMs` defaults to `null` (sequential primary exhaustion).
+A nonnegative integer up to 2147483647 opts automatic NIP-65 routing into early
+fallback; explicit relay lists/maps retain the sequential policy. With `3000`,
+start at most two eligible fallback relays after three seconds without complete
+acceptance, or immediately after primary exhaustion. The deadline belongs to
+one signed outer event; later batches do not renew it. Primary operations retain
+their deadlines and can still win. Failed fallback operations leave primary
+alternatives available; no relay is tried twice. Multiple recipients require
+accepted coverage of every encrypted recipient subset. No wrapper, ID, recipient
+tag or deletion capability is recreated. Confirmed connectivity, exclusions and
+connection cooldowns remain authoritative; a waiting primary is not penalized
+merely because fallback started. Late native failures may inform later sends.
+
 On `blocked`, `restricted`, `auth-required`, `pow`, `rate-limited`, or `error`
 rejections, or connection/transport/timeout failures, replacement requires
 `isOnline` to confirm connectivity. Invalid messages, local signer/authentication
@@ -141,7 +179,8 @@ publication report. A shared relay's first ACK covers all members assigned to
 that publication batch. If replacements use different relays for different
 members, every pending member must be covered before the outer event succeeds;
 a partial ACK cannot hide another member's failure. Remaining primary routes are
-exhausted before configured fallbacks. Redundant acknowledgements may update
+exhausted before configured fallbacks with the default null delay or explicit
+routes. Redundant acknowledgements may update
 future routing preferences without delaying a successfully covered send. Preferences are channel/recipient-scoped, in-memory,
 expire after five minutes, and never alter receive subscriptions. A fresh attempt
 can recheck an exhausted list. Additional fallback relays come only from the
@@ -159,3 +198,12 @@ relays. Validation/authorization failures are terminal without relay rotation.
 `broadcastRumor`/`broadcastEvent` accept a `signal` to stop further replacement
 publications; the session supplies it and aborts it on cancel/close. An already
 published event cannot be recalled by cancellation.
+
+`RelayPool.sendEvent(event, relays, { signal })` supports optional cancellation.
+It returns the existing result/report envelopes with the original abort reason
+for unfinished relays, preserving partial acceptance and avoiding synthetic
+timeouts. Cancellation releases publication waiters and deferred sends without
+closing shared sockets or cancelling another subscriber for the same event ID.
+Operations already transmitted cannot be recalled from relays. A messenger pause
+cancels its outstanding publication work and leaves the outbox pending; resume
+creates a fresh publication lifetime, without treating the pause as a user abort.

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() }
+  }
+}