libp2r2p 0.11.2 → 0.11.4

package/README.md

@@ -912,4 +912,14 @@ Private-message consumers can now substitute recovery persistence through
 [`private-messenger/event-store`](private-messenger/event-store/README.md), or use
 local defaults, including a bounded streaming file cache. The optional
 [`private-messenger/session`](private-messenger/session/README.md) coordinator
-provides reusable DM inbox/outbox and attachment lifecycle without UI coupling.
+provides reusable DM inbox/outbox and attachment lifecycle without UI coupling,
+including an optional `onSendError` callback identifying the failed outbox message.
+
+Single-recipient private messages now retry NIP-65 read relays in pairs when
+selected relays reject publication or become unreachable while connectivity is
+confirmed. The exact encrypted outer events are reused; explicit per-call and
+channel relay overrides remain authoritative. Successful sends keep first-ACK
+latency, and short-lived channel/recipient preferences avoid recently refused
+relays without changing receive subscriptions. See the
+[session coordinator](private-messenger/session/README.md) for deferred offline
+attempts and final failure notifications.

package/package.json

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

package/private-messenger/file/README.md

@@ -21,8 +21,10 @@ append it to the thumbnail URL. This is not a group-key derivation scheme.
   The application calls it for an explicit share, using its persisted message
   timestamp (standalone 1063 uses its own timestamp). Registration, cache hits
   and incoming requests never grant access. Missing router `p` is not a wildcard.
-- `publishChunk(descriptor, event)` checks a 34601 proof and the descriptor,
+- `publishChunk(descriptor, event, { signal } = {})` checks a 34601 proof and the descriptor,
   captures ciphertext only in watchtower mode, and publishes to the recipient's relays.
+  It shares the parent channel's automatic relay fallback and full publication
+  diagnostics; `signal` stops further replacement attempts.
   Every wrapper must receive at least one relay acceptance. Yield between calls
   so text/control sends can run. Publish all file chunks before announcing 1063/9.
 - `download(descriptor, { manual, thumbnail, signal })` returns the verified,

package/private-messenger/file/index.js

@@ -3,6 +3,7 @@ import { chunkStream } from './helpers/stream.js'
 import { createFileCache } from './helpers/cache.js'
 export { createFileCache, DEFAULT_FILE_CACHE_BYTES } from './helpers/cache.js'
 import { createFileCatalog } from './helpers/catalog.js'
+import { assertMessagePublished } from '../helpers/publication.js'
 import { ValidationError } from '../../error/index.js'
 import { IRFS_CHUNK_BYTES, decodeIrfsChunk } from '../../irfs/index.js'
 import { createQueue } from '../../idb-queue/index.js'
@@ -48,11 +49,6 @@ function rangesFor (indices) {
   return ranges
 }
 
-function assertPublished (result) {
-  const reports = result?.delivery?.reports
-  if (!Array.isArray(reports) || !reports.length || !reports.every(report => report?.success === true)) throw Object.assign(new Error('FILE_NOT_PUBLISHED'), { code: 'MESSAGE_NOT_PUBLISHED' })
-}
-
 function waitForTransfer (promise, signal) {
   signal?.throwIfAborted()
   if (!signal) return promise
@@ -148,14 +144,14 @@ export function createPrivateFileTransfer ({ messenger, resolveChannel, storage,
     if (decoded.root !== file.root || (index !== undefined && decoded.index !== index) || (file.size !== undefined && (decoded.total !== Math.ceil(file.size / IRFS_CHUNK_BYTES) || (decoded.index === decoded.total - 1 && decoded.contentBytes.length !== file.size - decoded.index * IRFS_CHUNK_BYTES)))) throw new ValidationError('FILE_CHUNK_DESCRIPTOR_MISMATCH')
     return decoded
   }
-  async function routing (file, receiverPubkey) {
+  async function routing (file, receiverPubkey, signal) {
     const parent = messenger.requireWritableChannel(file.controlChannelPubkey)
-    return messenger.resolveSendRouting({ channel: parent, receiverPubkeys: [receiverPubkey] })
+    return messenger.resolveSendRouting({ channel: parent, receiverPubkeys: [receiverPubkey], signal })
   }
   function sendOptions (file, routes) {
     return { senderSigner: messenger.userSigner, imkcSigner: messenger.contentKeySigner, privateChannelSigner: file.signer, ...routes, temporaryStorageArea: messenger.temporaryStorageArea, expirationSeconds: messenger.eventExpirationSecondsFor(file.controlChannelPubkey), _getIykcProofs: messenger.contentKeyLookup() }
   }
-  async function publishChunk (descriptor, event) {
+  async function publishChunk (descriptor, event, { signal } = {}) {
     const file = await register(descriptor)
     usable(file)
     const decoded = checked(file, event)
@@ -166,9 +162,9 @@ export function createPrivateFileTransfer ({ messenger, resolveChannel, storage,
     }
     let result
     try {
-      const options = { ...sendOptions(file, await routing(file, file.peerPubkey)), receiverPubkeys: [file.peerPubkey], fileChunkIndex: decoded.index, ...(messenger.channels.get(file.controlChannelPubkey)?.mode === 'watchtower' ? { onPreparedSeed: seed => saveSeed(file, seed) } : {}) }
+      const options = { ...sendOptions(file, await routing(file, file.peerPubkey, signal)), receiverPubkeys: [file.peerPubkey], fileChunkIndex: decoded.index, ...(messenger.channels.get(file.controlChannelPubkey)?.mode === 'watchtower' ? { onPreparedSeed: seed => saveSeed(file, seed) } : {}) }
       result = event.sig ? await _messages.broadcastEvent({ ...options, event }) : await _messages.broadcastRumor({ ...options, rumor: event })
-      assertPublished(result)
+      await assertMessagePublished(result, result?.rumor || result?.event || { ...event, pubkey: event.pubkey || messenger.userPubkey })
     } catch (error) { await uploadLeases.get(file.root)?.(); uploadLeases.delete(file.root); throw error }
     if (decoded.index === decoded.total - 1) { await uploadLeases.get(file.root)?.(); uploadLeases.delete(file.root) }
     // A scheduler turn between chunks lets queued text/control publications run.

package/private-messenger/{session/helpers → helpers}/publication.js

@@ -1,4 +1,4 @@
-import { getEventHash } from '../../../event/index.js'
+import { getEventHash } from '../../event/index.js'
 
 // A report describes one outer event, not one relay. Each outer event needs
 // at least one relay acknowledgement. Keep the successful fast path immediate.
@@ -17,6 +17,8 @@ export async function assertMessagePublished (result, event) {
       return {
         index,
         total: settled?.total ?? report?.total,
+        ...(report?.retryWhenAvailable ? { retryWhenAvailable: true } : {}),
+        ...(report?.retryWhenOnline ? { retryWhenOnline: true } : {}),
         fulfilled: settled?.fulfilled,
         errors: (settled?.errors || []).map(({ relay, reason }) => ({ relay, reason }))
       }
@@ -32,6 +34,7 @@ export async function assertMessagePublished (result, event) {
   })
   throw Object.assign(new Error(`MESSAGE_NOT_PUBLISHED: ${details.join(' | ') || reason}`), {
     code: 'MESSAGE_NOT_PUBLISHED',
+    ...(failures.length && failures.every(report => report.retryWhenAvailable) ? { retryWhenAvailable: true, ...(failures.some(report => report.retryWhenOnline) ? { retryWhenOnline: true } : {}) } : {}),
     reason,
     eventId: getEventHash(event),
     eventKind: event.kind,

package/private-messenger/helpers/send-routing.js

@@ -0,0 +1,90 @@
+import { normalizeRelayUrl } from '../../url/index.js'
+
+const REJECTION_PREFIXES = new Set(['blocked', 'restricted', 'auth-required', 'pow', 'rate-limited', 'error'])
+const TRANSPORT_CATEGORIES = new Set(['connection', 'transport', 'timeout'])
+const EXCLUSION_MS = 5 * 60 * 1000
+const normalized = relay => { try { return normalizeRelayUrl(relay) } catch { return '' } }
+
+// Only machine-readable relay policy/server failures qualify. Invalid events,
+// local signer denials and unknown prose must not rotate relays.
+export function isReplaceableRelayFailure (error) {
+  if (error?.name === 'Nip42AuthenticationError') return false
+  if (TRANSPORT_CATEGORIES.has(error?.category)) return true
+  if (error?.category && error.category !== 'relay') return false
+  return REJECTION_PREFIXES.has(/^([a-z-]+):/.exec(error?.message || '')?.[1])
+}
+
+export function createSendRelayRouting ({ peer, relaysByPubkey, exclusions, pickRelays, recoveryRelays, publish, publishNymEvent, sendEvent, isOnline, isCurrent, signal, now = Date.now }) {
+  // One finite snapshot, including the existing default pair if NIP-65 is
+  // unavailable. Never invent additional fallback relays.
+  const candidates = [...pickRelays([peer], relaysByPubkey, { relayType: 'read', maxPerPubkey: Infinity }).keys()]
+  const candidateSet = new Set(candidates)
+  for (const [relay, expires] of exclusions) if (expires <= now() || !candidateSet.has(relay)) exclusions.delete(relay)
+  // New attempts may recheck an exhausted list. Each in-flight outer event has
+  // its own tried set, preventing loops during concurrent sends.
+  if (candidates.length && candidates.every(relay => exclusions.has(relay))) exclusions.clear()
+  const select = excluded => pickRelays([peer], relaysByPubkey, { relayType: 'read', excludeRelaysByPubkey: new Map([[peer, [...excluded]]]) })
+  const relayToReceivers = select(exclusions.keys())
+  const current = () => !signal?.aborted && isCurrent()
+  const rejected = report => (report?.errors || []).filter(item => candidateSet.has(normalized(item.relay)) && isReplaceableRelayFailure(item.reason))
+  const remember = errors => { for (const item of errors) exclusions.set(normalized(item.relay), now() + EXCLUSION_MS) }
+  const online = async () => {
+    if (!current()) return false
+    try { return await isOnline({ signal }) && current() } catch { return false }
+  }
+
+  async function send (event, initialRelays) {
+    const mirrors = initialRelays.filter(relay => !candidateSet.has(normalized(relay)))
+    let relays = [...new Set([...select(exclusions.keys()).keys(), ...mirrors])]
+    const tried = new Set()
+    const errors = []
+    const summaries = []
+    const finish = result => {
+      if (summaries.length === 1) return result
+      return {
+        ...result,
+        total: tried.size,
+        promise: Promise.all(summaries).then(reports => ({
+          total: tried.size,
+          success: reports.some(report => report.success),
+          fulfilled: reports.reduce((total, report) => total + (report.fulfilled || 0), 0),
+          succeededRelays: [...new Set(reports.flatMap(report => report.succeededRelays || []))],
+          errors: reports.flatMap(report => report.errors || [])
+        }))
+      }
+    }
+    while (true) {
+      signal?.throwIfAborted()
+      for (const relay of relays) tried.add(normalized(relay))
+      // Republish the exact signed outer event, preserving encryption,
+      // fragments, timestamps and deletion capabilities.
+      const result = await sendEvent(event, relays)
+      const settled = Promise.resolve(result.promise)
+      summaries.push(settled)
+      if (result.success) {
+        // Keep the first ACK immediate; learn about redundant failures later.
+        settled.then(async report => {
+          const failed = rejected(report)
+          if (failed.length && await online()) remember(failed)
+        }).catch(() => {})
+        return finish(result)
+      }
+      const report = await settled
+      const failed = rejected(report)
+      errors.push(...(report?.errors || []))
+      if (!failed.length || errors.some(item => !isReplaceableRelayFailure(item.reason))) return finish(result)
+      const next = [...select(new Set([...exclusions.keys(), ...tried])).keys()]
+      if (!next.length) { exclusions.clear(); return finish(result) }
+      if (!await online()) return { ...finish(result), retryWhenAvailable: !signal?.aborted, retryWhenOnline: current() }
+      remember(failed)
+      relays = next
+    }
+  }
+
+  return {
+    relayToReceivers,
+    // A recovery mirror must not reintroduce the recipient's refused relays.
+    recoveryRelays: recoveryRelays.filter(relay => !candidateSet.has(relay) || !exclusions.has(relay)),
+    _publish: options => (options.nymSigner ? publishNymEvent : publish)({ ...options, _publish: send })
+  }
+}

package/private-messenger/index.js

@@ -43,10 +43,12 @@
 // - For other event-list replies, use createEventReplyPacker({ messenger, question, code }).update(event).
 
 import * as privateMessage from '../private-message/index.js'
+import { isOnline } from '../network/index.js'
+import { createSendRelayRouting } from './helpers/send-routing.js'
 import { deliveryInfo } from '../private-channel/helpers/rumor.js'
 import { bytesToBase64 } from '../base64/index.js'
 import { ValidationError } from '../error/index.js'
-import { getRelaysByPubkey, pickRelaysForPubkeys, subscribeRelayListUpdates } from '../relay/index.js'
+import { getRelaysByPubkey, pickRelaysForPubkeys, subscribeRelayListUpdates, relayPool } from '../relay/index.js'
 import * as privateChannel from '../private-channel/index.js'
 import { DEFAULT_RECEIVED_CHUNK_TTL_MS } from '../private-channel/services/received-chunks.js'
 import { createQueue } from '../idb-queue/index.js'
@@ -215,6 +217,7 @@ export class PrivateMessenger {
     _getRelaysByPubkey = getRelaysByPubkey,
     _pickRelaysForPubkeys = pickRelaysForPubkeys,
     _subscribeRelayListUpdates = subscribeRelayListUpdates,
+    _isOnline = isOnline,
     _setTimeout = globalThis.setTimeout.bind(globalThis),
     _clearTimeout = globalThis.clearTimeout.bind(globalThis),
     _setInterval = globalThis.setInterval.bind(globalThis),
@@ -247,6 +250,9 @@ export class PrivateMessenger {
     this._getRelaysByPubkey = _getRelaysByPubkey
     this._pickRelaysForPubkeys = _pickRelaysForPubkeys
     this._subscribeRelayListUpdates = _subscribeRelayListUpdates
+    this._isOnline = _isOnline
+    this.sendRelayExclusions = new Map()
+    this.sendRoutingLifetime = new AbortController()
     this._setTimeout = _setTimeout
     this._clearTimeout = _clearTimeout
     this._setInterval = _setInterval
@@ -670,6 +676,7 @@ export class PrivateMessenger {
 
     await this.unwatch(removedPubkeys)
     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)
 
     await this.cleanupStaleChannels({ storageSnapshot })
@@ -753,13 +760,36 @@ export class PrivateMessenger {
     return this.readRelaysForPubkey(this.userPubkey)
   }
 
-  async resolveSendRouting ({ channel, receiverPubkeys, relays, relayToReceivers }) {
+  async resolveSendRouting ({ channel, receiverPubkeys, relays, relayToReceivers, signal }) {
     const recoveryRelays = await this.recoveryMirrorRelays(channel.pubkey)
     if (relayToReceivers) return { relayToReceivers, recoveryRelays }
     if (relays?.length) return { relays: uniq(relays), recoveryRelays }
     if (channel.sendRelays.length) return { relays: channel.sendRelays, recoveryRelays }
     if (channel.relays.length) return { relays: channel.relays, recoveryRelays }
-    const derived = await this.readRelayToReceivers(receiverPubkeys)
+    const recipients = uniq(receiverPubkeys)
+    if (recipients.length === 1) {
+      const peer = recipients[0]
+      const relaysByPubkey = await this._getRelaysByPubkey(recipients)
+      const key = `${channel.pubkey}:${peer}`
+      if (!this.sendRelayExclusions.has(key)) {
+        if (this.sendRelayExclusions.size >= 256) this.sendRelayExclusions.delete(this.sendRelayExclusions.keys().next().value)
+        this.sendRelayExclusions.set(key, { channelPubkey: channel.pubkey, exclusions: new Map() })
+      }
+      const routing = createSendRelayRouting({
+        peer, relaysByPubkey, recoveryRelays,
+        signal: signal ? AbortSignal.any([this.sendRoutingLifetime.signal, signal]) : this.sendRoutingLifetime.signal,
+        exclusions: this.sendRelayExclusions.get(key).exclusions,
+        pickRelays: this._pickRelaysForPubkeys,
+        publish: this._privateChannel.publish || privateChannel.publish,
+        publishNymEvent: this._privateChannel.publishNymEvent || privateChannel.publishNymEvent,
+        sendEvent: (...args) => relayPool.sendEvent(...args),
+        isOnline: this._isOnline,
+        isCurrent: () => !this.closePromise && !this.pauseReasons.size && this.channels.has(channel.pubkey)
+      })
+      if (!relayMapRelays(routing.relayToReceivers).length) throw new ValidationError('NO_RELAYS')
+      return routing
+    }
+    const derived = await this.readRelayToReceivers(recipients)
     if (!relayMapRelays(derived).length) throw new ValidationError('NO_RELAYS')
     return { relayToReceivers: derived, recoveryRelays }
   }
@@ -1600,9 +1630,9 @@ export class PrivateMessenger {
     })
   }
 
-  async broadcastRumor ({ channelPubkey = this.defaultChannelPubkey(), receiverPubkeys, relays, relayToReceivers, rumor, deletionPubkey }) {
+  async broadcastRumor ({ channelPubkey = this.defaultChannelPubkey(), receiverPubkeys, relays, relayToReceivers, rumor, deletionPubkey, signal }) {
     const channel = this.requireWritableChannel(channelPubkey)
-    const routing = await this.resolveSendRouting({ channel, receiverPubkeys, relays, relayToReceivers })
+    const routing = await this.resolveSendRouting({ channel, receiverPubkeys, relays, relayToReceivers, signal })
     this.debugSend('broadcastRumor', channelPubkey, { receiverPubkeys })
     return this._privateMessage.broadcastRumor({
       senderSigner: this.userSigner,
@@ -1621,9 +1651,9 @@ export class PrivateMessenger {
     })
   }
 
-  async broadcastEvent ({ channelPubkey = this.defaultChannelPubkey(), receiverPubkeys, relays, relayToReceivers, event, deletionPubkey }) {
+  async broadcastEvent ({ channelPubkey = this.defaultChannelPubkey(), receiverPubkeys, relays, relayToReceivers, event, deletionPubkey, signal }) {
     const channel = this.requireWritableChannel(channelPubkey)
-    const routing = await this.resolveSendRouting({ channel, receiverPubkeys, relays, relayToReceivers })
+    const routing = await this.resolveSendRouting({ channel, receiverPubkeys, relays, relayToReceivers, signal })
     this.debugSend('broadcastEvent', channelPubkey, { receiverPubkeys })
     return this._privateMessage.broadcastEvent({
       senderSigner: this.userSigner,
@@ -2187,6 +2217,8 @@ export class PrivateMessenger {
   close () {
     if (this.closePromise) return this.closePromise
     const initSettledPromise = this.initSettledPromise
+    this.sendRoutingLifetime.abort()
+    this.sendRelayExclusions.clear()
     let unwatchPromise
     try {
       unwatchPromise = Promise.resolve(this.unwatch())

package/private-messenger/session/README.md

@@ -14,8 +14,16 @@ persistence; absent file storage uses the library cache. `mode` defaults to
 
 Methods: `setPeers`, `setAvailable(boolean)`, `enqueue`, `retry`, `cancel`,
 `download`, `cancelDownload`, and `close`. Callbacks are `onOutbox`, `onMedia`,
-and `onError`. The caller maps its account permissions/connectivity/lock state
-to availability and owns view subscriptions. There are no DOM or UI imports.
+`onError`, and optional `onSendError(error, { id, peer })`. The caller maps its
+account permissions/connectivity/lock state to availability and owns view subscriptions. There are no DOM or UI imports.
+
+`onSendError` identifies the main outbox message even when its quote, metadata,
+file chunks, or local persistence failed. The original error is also reported to
+`onError` unchanged. It fires once per failed send attempt (including retries),
+not when persisted failures are read, nor for inbox/download/deletion operations
+or cancelled/closed sends. Apps own route visibility and user-intent filtering;
+automatic retries may also fail. Callbacks must not throw. Errors are not copied
+into persisted outbox records.
 
 `enqueue({ peer, event, context, requiredFiles, deletion })` preserves prepared
 identities. Local message commits and remote stages have independent checkpoints.
@@ -37,3 +45,34 @@ passing their established factories, as Zillion does.
 External recovery factories are owned by their caller and must be closed after
 the session. Work storage opened by the session is closed by the session.
 This is a DM profile; group membership/key derivation is not implemented.
+
+## Relay fallback
+
+Automatic single-recipient routing uses the recipient's NIP-65 read relays, at
+most two per attempt. On `blocked`, `restricted`, `auth-required`, `pow`,
+`rate-limited`, or `error` rejections, or connection/transport/timeout failures,
+it can try remaining read relays after `isOnline` confirms connectivity. Invalid
+messages, local signer/authentication failures and unknown error text retain their
+original diagnosis. Explicit per-call `relays`/`relayToReceivers`, channel
+`sendRelays`/`relays`, and multi-recipient sends do not enable automatic fallback.
+
+Each signed outer event is reused verbatim, including router/carrier fragments
+and deletion capabilities. Native errors from exhausted attempts remain in its
+publication report. One successful relay acknowledgement completes that outer
+event immediately; other acknowledgements may update future routing preferences
+without delaying the 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. No additional public fallback relays are invented.
+
+When offline/interrupted with alternatives remaining, reports carry
+`retryWhenAvailable: true`. The outbox remains pending and emits no `onSendError`.
+Offline reports also carry `retryWhenOnline: true`: the session owns a temporary
+`onOnline` subscription to retry those entries after confirmed connectivity,
+including brief outages the app's existing monitor might have missed. Cancel,
+close and signer unavailability release the subscription. Account recovery still
+uses `setAvailable(true)`; network recovery never overrides signer availability.
+`onSendError` is emitted only after final failure, including exhausted eligible
+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.

package/private-messenger/session/index.js

@@ -3,10 +3,11 @@ import { createPrivateFileTransfer } from '../file/index.js'
 import { createPrivateMessenger } from '../index.js'
 import { getEventHash, isValidEvent, isSerializableEvent } from '../../event/index.js'
 import { decodeIrfsChunk, IRFS_CHUNK_BYTES } from '../../irfs/index.js'
+import { onOnline } from '../../network/index.js'
 import { decodeFileMetadata } from '../../nip94/index.js'
 import { createChatOutbox } from './helpers/work-storage.js'
 import { messengerSigner } from './helpers/signer.js'
-import { assertMessagePublished } from './helpers/publication.js'
+import { assertMessagePublished } from '../helpers/publication.js'
 
 export function wireEvent (value, owner) {
   const event = { kind: value.kind, created_at: value.created_at, tags: structuredClone(value.tags), content: value.content, pubkey: value.pubkey || owner }
@@ -16,7 +17,7 @@ export function wireEvent (value, owner) {
 // Relay rejection text must not be interpreted as a local signer denial.
 const retryable = error => error?.code === 'MESSAGE_NOT_PUBLISHED' || !/DENIED|PERMISSION|REVOKED|READ_ONLY|INVALID|BLOCKED|EXPIRED|NOT_IN_PERSONA/i.test(`${error?.code || ''} ${error?.message || ''}`)
 
-export function createPrivateMessageSession ({ owner, signer, eventStore, messageStorage, chunkStorage, recoveryStorage, mode = 'seeder', seedersForPeer = peer => [peer], allowedKinds = [5, 9, 1063, 34601], onMedia = () => {}, onOutbox = () => {}, onError = () => {}, Messenger = createPrivateMessenger, openOutbox = createChatOutbox, FileTransfer = createPrivateFileTransfer, openDownloads = options => createChatOutbox({ ...options, namespace: 'downloads' }) }) {
+export function createPrivateMessageSession ({ owner, signer, eventStore, messageStorage, chunkStorage, recoveryStorage, mode = 'seeder', seedersForPeer = peer => [peer], allowedKinds = [5, 9, 1063, 34601], onMedia = () => {}, onOutbox = () => {}, onError = () => {}, onSendError = () => {}, Messenger = createPrivateMessenger, openOutbox = createChatOutbox, FileTransfer = createPrivateFileTransfer, _onOnline = onOnline, openDownloads = options => createChatOutbox({ ...options, namespace: 'downloads' }) }) {
   const userSigner = messengerSigner(signer)
   messageStorage ||= createEventStoreMessageStorage({ eventStore })
   chunkStorage ||= eventStore ? createEventStoreChunkStorage({ eventStore }) : undefined
@@ -25,6 +26,9 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
   const deniedPeers = new Set()
   const entries = new Map()
   const cancelled = new Set()
+  const sendControllers = new Map()
+  const offlineSends = new Set()
+  let stopOnline
   let messenger
   let fileTransfers
   let downloads
@@ -140,16 +144,18 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       }
     } finally { await Promise.all(deferred.map(nack => nack())); draining = false; settled() }
   }
-  async function publish (peer, event) {
+  async function publish (peer, event, signal) {
     if (deniedPeers.has(peer)) throw new Error('PERMISSION_DENIED')
     if (!available || !peers.has(peer) || !channels.has(peer)) throw new Error('CHAT_UNAVAILABLE')
-    const options = { channelPubkey: channels.get(peer)?.pubkey, receiverPubkeys: [peer] }
+    const options = { channelPubkey: channels.get(peer)?.pubkey, receiverPubkeys: [peer], signal }
     const report = event.sig ? await messenger.broadcastEvent({ ...options, event }) : await messenger.broadcastRumor({ ...options, rumor: event })
     // Published is relay acceptance, never a peer receipt.
     await assertMessagePublished(report, event)
   }
   async function sendEntry (entry) {
     entry.status = 'pending'; emit()
+    const controller = new AbortController()
+    sendControllers.set(entry.id, controller)
     try {
       const active = async () => {
         if (storage.has && !await storage.has(entry.id)) cancelled.add(entry.id)
@@ -180,7 +186,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
           const chunk = chunkStorage ? await chunkStorage.read(file.root, entry.chunkIndex, file) : await fileTransfers.readChunk(file.root, entry.chunkIndex)
           if (!chunk || decodeIrfsChunk(chunk).root !== file.root) { if (file.optional) break; throw new Error('FILE_UNAVAILABLE') }
           if (!fileTransfers) throw new Error('FILE_TRANSFER_UNAVAILABLE')
-          await fileTransfers.publishChunk({ controlChannelPubkey: channels.get(entry.peer).pubkey, peerPubkey: entry.peer, root: file.root, size: file.size }, wireEvent(chunk, owner))
+          await fileTransfers.publishChunk({ controlChannelPubkey: channels.get(entry.peer).pubkey, peerPubkey: entry.peer, root: file.root, size: file.size }, wireEvent(chunk, owner), { signal: controller.signal })
           const completed = entry.files.slice(0, entry.fileIndex).reduce((sum, value) => sum + value.size, 0) + Math.min(file.size, (entry.chunkIndex + 1) * IRFS_CHUNK_BYTES)
           entry.uploadProgress = { completed, total: entry.files.reduce((sum, value) => sum + value.size, 0) }
           emit()
@@ -199,7 +205,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       for (; entry.index < entry.events.length; entry.index++) {
         await active()
         const event = entry.events[entry.index]
-        if (entry.peer !== owner) await publish(entry.peer, event)
+        if (entry.peer !== owner) await publish(entry.peer, event, controller.signal)
         await active()
         await storage.put({ ...entry, index: entry.index + 1 }, { existing: true })
       }
@@ -207,9 +213,34 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       entries.delete(entry.id)
       emit()
     } catch (error) {
-      if (cancelled.has(entry.id)) { await storage.remove(entry.id); entries.delete(entry.id) } else { entry.status = 'error'; entry.failed = true; entry.retryable = retryable(error); await storage.put(entry, { existing: true }).catch(onError); onError(error) }
+      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(onError)
+        onError(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 (!closed && !entry.deletion && !cancelled.has(entry.id) && !error.retryWhenAvailable) onSendError(error, { id: entry.id, peer: entry.peer })
+      }
       emit()
-    }
+    } finally { sendControllers.delete(entry.id) }
+  }
+  function stopOnlineRetry () { stopOnline?.(); stopOnline = undefined }
+  function watchOfflineSends () {
+    if (closed || !available || !offlineSends.size) { stopOnlineRetry(); return }
+    if (stopOnline) return
+    // A fresh listener receives confirmed connectivity even when a brief outage
+    // occurred between the app's long-lived monitor checks.
+    stopOnline = _onOnline(() => {
+      stopOnlineRetry()
+      if (closed || !available) return
+      for (const id of offlineSends) {
+        const entry = entries.get(id)
+        if (entry?.retryable) entry.failed = false
+      }
+      offlineSends.clear()
+      return schedule()
+    })
   }
   async function pump () {
     if (sending || !available || closed || !messenger || !storage) return
@@ -220,7 +251,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
         if ((entry.peer !== owner && !peers.has(entry.peer)) || entry.failed || cancelled.has(entry.id)) continue
         await sendEntry(entry)
       }
-    } finally { sending = false; settled() }
+    } finally { sending = false; watchOfflineSends(); settled() }
   }
   const intentId = file => getEventHash({ kind: 0, pubkey: owner, created_at: 0, tags: [], content: `${file.peer}:${file.root}` })
   async function download (file, options = {}) {
@@ -259,6 +290,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
     },
     async setAvailable (value) {
       available = value === true
+      stopOnlineRetry(); offlineSends.clear()
       lifecycle++
       if (!available) { await messenger?.pause('signer'); return }
       await ready()
@@ -279,12 +311,15 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       return id
     },
     async retry (id) {
+      offlineSends.delete(id); watchOfflineSends()
       await ready()
       const entry = entries.get(id)
       if (entry) { entry.failed = false; if (deniedPeers.delete(entry.peer)) await schedule(); return pump() }
     },
     async cancel (id) {
       cancelled.add(id)
+      sendControllers.get(id)?.abort()
+      offlineSends.delete(id); watchOfflineSends()
       await ready()
       entries.delete(id)
       await storage.remove(id)
@@ -292,6 +327,8 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
     },
     async close () {
       closed = true; available = false; lifecycle++
+      stopOnlineRetry(); offlineSends.clear()
+      for (const controller of sendControllers.values()) controller.abort()
       await Promise.allSettled([configuring, initialized])
       await messenger?.pause('closed')
       if (sending || draining) await new Promise(resolve => idleWaiters.add(resolve))