@decentnetwork/peer 0.1.79 → 0.1.82

package/dist/peer.js

@@ -1,11 +1,11 @@
 import { EventEmitter } from "node:events";
 import { mkdir, readFile, writeFile, rename } from "node:fs/promises";
 import { networkInterfaces } from "node:os";
-import { dirname } from "node:path";
+import { dirname, join } from "node:path";
 import nacl from "tweetnacl";
 import { carrierAddressFromPublicKey, carrierIdFromAddress, carrierIdFromPublicKey, parseCarrierAddress } from "./compat/address.js";
 import { LegacyBootstrapClient } from "./compat/bootstrap.js";
-import { PACKET_TYPE_MESSAGE, PACKET_TYPE_FRIEND_REQUEST, PACKET_TYPE_USERINFO, encodeUserInfoPacket, decodeCarrierPacket, encodeFriendMessagePacket, encodeFriendRequestPacket } from "./compat/packet.js";
+import { PACKET_TYPE_MESSAGE, PACKET_TYPE_FRIEND_REQUEST, PACKET_TYPE_USERINFO, PACKET_TYPE_BULKMSG, CARRIER_MAX_APP_MESSAGE_LEN, CARRIER_MAX_APP_BULKMSG_LEN, encodeUserInfoPacket, decodeCarrierPacket, encodeFriendMessagePacket, encodeFriendRequestPacket, encodeBulkMsgPacket } from "./compat/packet.js";
 import { NET_PACKET_ONION_ANNOUNCE_RESPONSE, NET_PACKET_ONION_DATA_RESPONSE, ONION_FRIEND_REQUEST_ID, createOnionAnnounceRequest, createOnionDataPacket, createOnionDataRequest, createOnionRequest0, openOnionAnnounceResponse, openOnionDataPacket, openOnionDataResponse } from "./compat/tox-onion.js";
 import { CRYPTO_PACKET_DHTPK, CRYPTO_PACKET_FRIEND_REQ, NET_PACKET_CRYPTO, createToxDhtCryptoRequest, openToxDhtCryptoRequest } from "./compat/tox-dht-crypto.js";
 import { NET_PACKET_PING_REQUEST, NET_PACKET_PING_RESPONSE, NET_PACKET_GET_NODES, NET_PACKET_SEND_NODES, encodeDhtRpc, decodeDhtRpc, buildPingPlain, parsePingPlain, buildGetNodesPlain, parseGetNodesPlain, buildSendNodesPlain, parseSendNodesNodeBytes, packUdpNodeV4 } from "./compat/dht-rpc.js";
@@ -255,6 +255,22 @@ export class Peer {
     // unconnected friend (the "accepted friend that never connects" wedge —
     // requestRoute only fired once at startup and was never retried).
     #routeRequestCooldown = new Map();
+    // The onion route that carried the last successful announce exchange with
+    // each announce node ("host:port" -> path | "direct"). A node's ping_id is
+    // bound to the SOURCE ip:port it saw the request arrive from (the path's
+    // exit hop, or us when direct). Step2 of a self-announce must therefore
+    // travel the exact route step1 used — re-selecting a path (scores mutate
+    // between calls) or falling back direct changes the source, the node
+    // rejects the ping_id, and the announce NEVER stores (observed: zero
+    // isStored=2 across an entire run — nobody could find us to learn our
+    // announce data key).
+    #announceRouteUsed = new Map();
+    // Last-known DHT pubkey per friend (identity id -> dht pk). Sessions get
+    // deleted on timeout, but relay ROUTING_REQUESTs must keep using the key
+    // the friend handshakes relays with — for native peers that's the DHT key,
+    // not the identity key. Without this survives-teardown copy, every re-link
+    // attempt after a session teardown silently used the wrong key.
+    #friendDhtKeys = new Map();
     // Per-friend cooldown for RE-SENDING the friend-request to a friend that's
     // never been accepted (still "requested"). On reconnect / restart we must
     // re-offer — the original request can be lost while the friend was offline.
@@ -290,6 +306,16 @@ export class Peer {
     // #initiateSession every few seconds for every friend; without this
     // dedupe, lower-pubkey side floods the log with "deferring to peer".
     #initiateSkipLogged = new Set();
+    // In-flight Carrier BULKMSG reassemblies, keyed `${friendId}:${tid}`.
+    // Fragments are appended in arrival order (the lossless stream keeps
+    // them ordered) and the message completes when totalsz bytes arrived.
+    // Mirrors the C SDK's bulkmsgs hashtable with its 60s assembly timeout.
+    #bulkAssembly = new Map();
+    // When we FIRST deferred initiation to a higher-pubkey peer (per friend).
+    // If the peer hasn't established within the grace window we break the
+    // defer and initiate ourselves (see #initiateSession). Cleared whenever a
+    // session establishes so each outage gets a fresh window.
+    #initiateDeferSinceMs = new Map();
     // Per-friend last time we deleted a desynced session (rate-limit; survives the
     // session deletion, unlike a field on the session object itself).
     #lastDesyncDeleteMs = new Map();
@@ -336,11 +362,19 @@ export class Peer {
             keyPair: this.#keyPair,
             transport: this.#udp
         });
-        const announceGenerated = createEphemeralKeyPair();
-        this.#announceDataKey = {
-            publicKey: announceGenerated.publicKey,
-            secretKey: announceGenerated.secretKey
-        };
+        // The announce data key MUST survive restarts. Native toxcore peers cache
+        // our last-known data pk and keep encrypting onion data (DHT-PK announces,
+        // friend requests) to it until they re-discover our announce on the DHT —
+        // which can take a long time when our self-announce store rate is weak.
+        // With an ephemeral per-run key, every restart silently invalidated every
+        // friend's cached key: 100% of inbound onion data failed to decrypt
+        // ("onion data response decrypt failed"), so we never learned a native
+        // friend's UDP endpoint or current relay list, and a dropped relay route
+        // could never self-heal (the iOS online-flap bug).
+        {
+            const announceKeyPath = join(dirname(this.#opts.keyFile), "announce-data-key.json");
+            this.#announceDataKey = await loadOrCreateKeyPair(announceKeyPath);
+        }
         this.#cookieSymmetricKey = randomBytes(32);
         await this.#loadPersistedFriends();
         if (this.#opts.expressNodes && this.#opts.expressNodes.length > 0) {
@@ -390,15 +424,23 @@ export class Peer {
                 this.#handleTcpDatagram(friendKey, payload);
             });
             this.#tcpRelays.on("friendOnline", (friendKey) => {
-                const friendId = carrierIdFromPublicKey(friendKey);
-                this.#debugLog(`tcp_relay friend_online ${friendId}`);
+                // The pool reports the key the peer handshook the relay with — for
+                // native peers that's the DHT key. Map it to the real friend id so
+                // route state + session kick land on the REAL session, not a ghost.
+                const friendId = this.#friendIdForPoolKey(friendKey);
+                this.#debugLog(`tcp_relay friend_online ${carrierIdFromPublicKey(friendKey)} (friend=${friendId})`);
                 // Mark the (existing or new) session as having a TCP route so
                 // outbound goes through the relay even if no UDP endpoint is
                 // known. Then kick #initiateSession — this issues a cookie
                 // request that will travel via TCP if no UDP path exists.
                 const session = this.#friendSessions.get(friendId) ?? this.#newSessionShell();
                 session.hasTcpRoute = true;
-                session.friendRealPublicKey ??= new Uint8Array(friendKey);
+                if (friendId === carrierIdFromPublicKey(friendKey)) {
+                    session.friendRealPublicKey ??= new Uint8Array(friendKey);
+                }
+                else {
+                    session.friendDhtPublicKey ??= new Uint8Array(friendKey);
+                }
                 this.#friendSessions.set(friendId, session);
                 if (!session.established) {
                     // A fresh relay-online signal means the peer just (re)connected —
@@ -413,12 +455,18 @@ export class Peer {
                 }
             });
             this.#tcpRelays.on("friendOffline", (friendKey) => {
-                const friendId = carrierIdFromPublicKey(friendKey);
+                const friendId = this.#friendIdForPoolKey(friendKey);
                 const session = this.#friendSessions.get(friendId);
                 if (session) {
                     session.hasTcpRoute = false;
                 }
-                this.#debugLog(`tcp_relay friend_offline ${friendId}`);
+                this.#debugLog(`tcp_relay friend_offline ${carrierIdFromPublicKey(friendKey)} (friend=${friendId})`);
+                // Re-assert the route right away (idempotent). A native peer that
+                // blips off a relay (network switch, app background, relay rotation)
+                // reconnects seconds later — with our ROUTING_REQUEST already parked,
+                // the relay re-links the moment it returns and fires friendOnline,
+                // instead of the session sitting pathless until the periodic sweep.
+                this.#tcpRelays?.requestRoute(friendKey);
             });
             this.#tcpRelays.on("status", (connected, total) => {
                 this.#debugLog(`tcp_pool ${connected}/${total} relays connected`);
@@ -465,14 +513,25 @@ export class Peer {
                 this.#debugLog(`tcp pool initial start failed: ${error.message}`);
             });
             // Pre-route every persisted friend so the pool watches for them
-            // the moment a relay is up.
-            for (const friend of this.#friends.values()) {
+            // the moment a relay is up — under BOTH keys: identity (JS peers)
+            // and the persisted DHT key (native peers handshake relays with it).
+            for (const [friendId, friend] of this.#friends.entries()) {
                 try {
                     const pk = base58ToBytes(friend.pubkey);
                     if (pk.length === 32)
                         this.#tcpRelays.requestRoute(pk);
                 }
                 catch { /* skip malformed */ }
+                if (friend.dhtPubkey && friend.dhtPubkey !== friend.pubkey) {
+                    try {
+                        const dhtPk = base58ToBytes(friend.dhtPubkey);
+                        if (dhtPk.length === 32) {
+                            this.#friendDhtKeys.set(friendId, dhtPk);
+                            this.#tcpRelays.requestRoute(dhtPk);
+                        }
+                    }
+                    catch { /* skip malformed */ }
+                }
             }
         }
         this.#started = true;
@@ -901,17 +960,58 @@ export class Peer {
             }
         }
         const packet = encodeFriendMessagePacket(text);
+        // Carrier C peers accept at most 1024 raw bytes per friendmsg; larger
+        // messages MUST be split into BULKMSG fragments (shared tid, totalsz on
+        // the first fragment) or a native receiver drops them. The express
+        // fallback below still posts the single big MESSAGE packet — that's
+        // what the C SDK does offline too.
+        const rawText = new TextEncoder().encode(text);
+        let livePackets;
+        if (rawText.length > CARRIER_MAX_APP_MESSAGE_LEN) {
+            if (rawText.length > CARRIER_MAX_APP_BULKMSG_LEN) {
+                throw new Error(`message exceeds bulk limit (${rawText.length} > ${CARRIER_MAX_APP_BULKMSG_LEN})`);
+            }
+            const tid = (BigInt(Date.now()) << 20n) ^ BigInt(Math.floor(Math.random() * 0xfffff));
+            livePackets = [];
+            for (let off = 0; off < rawText.length; off += CARRIER_MAX_APP_MESSAGE_LEN) {
+                livePackets.push(encodeBulkMsgPacket({
+                    totalsz: off === 0 ? rawText.length : 0,
+                    tid,
+                    data: rawText.subarray(off, Math.min(off + CARRIER_MAX_APP_MESSAGE_LEN, rawText.length))
+                }));
+            }
+        }
+        else {
+            livePackets = [packet];
+        }
         // Try the live in-session path first when any transport is up
         // (UDP via session.remote, or TCP relay via session.hasTcpRoute).
         // #sendMessengerPacket internally fans out to both transports and
         // returns true if at least one accepted; throws only if zero did.
+        //
+        // CRUCIAL: also require the session to be PROVEN — we've decrypted a real
+        // packet from the peer within FRIEND_TIMEOUT_MS. `established` alone can be a
+        // half-open / key-desynced session (common JS<->native case): our transport
+        // ACCEPTS the encrypted packet (so #sendMessengerPacket returns success, no
+        // throw) but the peer can't decrypt it, so the message is silently swallowed
+        // — and because the direct send "succeeded", the express fallback below never
+        // runs. Observed: an offline message to a desynced iOS peer showed "sent"
+        // yet never reached the peer OR the express relay (0 rows). Gating on recent
+        // inbound routes such sends to express store-and-forward instead of losing
+        // them. A genuinely-healthy session proves itself within a ping RTT (~4-8s),
+        // so at most the first message of a cold conversation takes the express path.
+        const provenInbound = session?.lastPingRecvMs !== undefined &&
+            Date.now() - session.lastPingRecvMs < FRIEND_TIMEOUT_MS;
         const liveSession = session?.established
             && session.sessionSharedKey
             && session.ourBaseNonce
-            && (session.remote || session.hasTcpRoute);
+            && (session.remote || session.hasTcpRoute)
+            && provenInbound;
         if (liveSession) {
             try {
-                await this.#sendMessengerPacket(pubkey, PACKET_ID_MESSAGE, packet);
+                for (const p of livePackets) {
+                    await this.#sendMessengerPacket(pubkey, PACKET_ID_MESSAGE, p);
+                }
                 return;
             }
             catch (error) {
@@ -991,6 +1091,40 @@ export class Peer {
     onText(cb) {
         this.#events.on("text", cb);
     }
+    /** Files received inline over (bulk)messages — the iOS/C Carrier apps'
+     *  native way of sending images/audio online (FileModel JSON envelope). */
+    onInlineFile(cb) {
+        this.#events.on("inlineFile", cb);
+    }
+    /**
+     * Send a file INLINE over the message channel the way iOS/C Carrier apps
+     * do: a FileModel JSON envelope ({data: base64, fileExtension, fileName,
+     * type}) carried as a (bulk)message. This is the ONLY file path a native
+     * Beagle client can receive online — the toxcore file transfer (80-82)
+     * used by sendFile() is invisible to the Carrier C SDK. Best for images
+     * and small files; the hard protocol cap is ~5MB (base64-inflated), keep
+     * real use well below it.
+     */
+    async sendInlineFile(pubkey, opts) {
+        const dot = opts.name.lastIndexOf(".");
+        const ext = dot > 0 ? opts.name.slice(dot).toLowerCase() : "";
+        const base = dot > 0 ? opts.name.slice(0, dot) : opts.name;
+        const type = opts.fileType ?? ([".png", ".jpg", ".jpeg", ".gif", ".webp", ".heic"].includes(ext) ? "image" :
+            [".m4a", ".mp3", ".aac", ".wav", ".ogg"].includes(ext) ? "audio" :
+                [".txt", ".md", ".log"].includes(ext) ? "text" : "unknown");
+        // Key order matters for byte-identical envelopes with iOS (JSONEncoder
+        // .sortedKeys): data, fileExtension, fileName, type — alphabetical.
+        const envelope = JSON.stringify({
+            data: Buffer.from(opts.data).toString("base64"),
+            fileExtension: ext,
+            fileName: base,
+            type
+        });
+        if (envelope.length > CARRIER_MAX_APP_BULKMSG_LEN) {
+            throw new Error(`inline file too large for the message channel (${envelope.length} bytes encoded, max ${CARRIER_MAX_APP_BULKMSG_LEN})`);
+        }
+        await this.sendText(pubkey, envelope);
+    }
     /**
      * Send an application-defined custom packet to a friend. `id` selects the
      * channel and its delivery class by toxcore range: **160–191 lossless**
@@ -1136,21 +1270,61 @@ export class Peer {
      * starts with `tcp:` so downstream code can recognize the origin
      * and avoid setting `session.remote` to a UDP-shaped value.
      */
+    /** Record a friend's DHT pubkey: in-memory (survives session teardown) and
+     *  persisted on the friend record (survives restarts, so start() can park
+     *  relay routes under the right key before the friend announces again). */
+    #learnFriendDhtKey(friendId, dhtPublicKey) {
+        if (dhtPublicKey.length !== 32)
+            return;
+        this.#friendDhtKeys.set(friendId, new Uint8Array(dhtPublicKey));
+        const friend = this.#friends.get(friendId);
+        if (friend) {
+            const b58 = carrierIdFromPublicKey(dhtPublicKey);
+            if (friend.dhtPubkey !== b58) {
+                this.#friends.set(friendId, { ...friend, dhtPubkey: b58 });
+                this.#persistFriends();
+            }
+        }
+    }
+    /** Resolve a TCP-relay-pool key (the key the peer handshook the relay
+     *  with) to OUR friend id. For JS peers the two coincide; native peers
+     *  (iOS/Android) sit on relays under their DHT key — without this
+     *  mapping, every pool event (friendOnline/friendOffline/inbound data
+     *  bookkeeping) landed on a GHOST session keyed by the DHT key while the
+     *  real session (keyed by identity) never saw route state change. */
+    #friendIdForPoolKey(poolKey) {
+        const asId = carrierIdFromPublicKey(poolKey);
+        if (this.#friends.has(asId))
+            return asId;
+        for (const [friendId, dhtPk] of this.#friendDhtKeys) {
+            if (bytesEqual(dhtPk, poolKey))
+                return friendId;
+        }
+        return asId;
+    }
     #handleTcpDatagram(friendKey, payload) {
-        const friendId = carrierIdFromPublicKey(friendKey);
-        // Mark the session as TCP-routed if we don't have it yet.
+        const poolId = carrierIdFromPublicKey(friendKey);
+        // Route-state bookkeeping belongs on the REAL friend's session (mapped
+        // via the DHT key for native peers), not a ghost keyed by the pool key.
+        const friendId = this.#friendIdForPoolKey(friendKey);
         let session = this.#friendSessions.get(friendId);
         if (!session) {
             session = this.#newSessionShell();
-            session.friendRealPublicKey = new Uint8Array(friendKey);
             this.#friendSessions.set(friendId, session);
         }
         session.hasTcpRoute = true;
-        session.friendRealPublicKey ??= new Uint8Array(friendKey);
-        // Feed through the regular dispatcher with synthetic remote.
+        if (friendId !== poolId) {
+            session.friendDhtPublicKey ??= new Uint8Array(friendKey);
+        }
+        else {
+            session.friendRealPublicKey ??= new Uint8Array(friendKey);
+        }
+        // Feed through the regular dispatcher with synthetic remote. Keep the
+        // POOL key in the remote tag: the crypto layer matched sessions by this
+        // exact string during the (proven-working) handshake flow.
         this.#onDatagram({
             data: Buffer.from(payload),
-            remote: { address: `tcp:${friendId}`, port: 0 }
+            remote: { address: `tcp:${poolId}`, port: 0 }
         });
     }
     /** True when the synthetic remote was constructed by #handleTcpDatagram. */
@@ -1250,6 +1424,15 @@ export class Peer {
                     this.#debugLog(`cookie response: no tcp relay accepted oob send for ${senderId}`);
                 }
             }
+            else if (this.#isUnroutableSelfSource(remote.address, remote.port)) {
+                // The request arrived sourced from our own TUN address (or our own
+                // socket) — an overlay routing artifact. Replying there loops into
+                // ourselves and dies. Answer over the relay OOB path instead, which
+                // the peer reliably receives. (A self PHYSICAL address with a
+                // different port is a same-host peer and gets the normal UDP reply.)
+                const sent = this.#tcpRelays?.sendOobToFriend(request.senderDhtPublicKey, response) ?? 0;
+                this.#debugLog(`cookie response: source ${remote.address}:${remote.port} is an unroutable self-source — replied via tcp_oob instead (relays=${sent})`);
+            }
             else {
                 void this.#sendPacket(response, { host: remote.address, port: remote.port })
                     .then(() => {
@@ -1431,6 +1614,9 @@ export class Peer {
                 if (!state.friendDhtPublicKey)
                     state.friendDhtPublicKey = hs.senderDhtPublicKey;
             }
+            if (hs.senderDhtPublicKey && hs.senderDhtPublicKey.length === 32) {
+                this.#learnFriendDhtKey(friendId, hs.senderDhtPublicKey);
+            }
             const wasEstablished = state.established === true;
             // Detect a real session reset: the peer is offering NEW session
             // keys (different ephemeral session pubkey from before). When
@@ -1479,14 +1665,25 @@ export class Peer {
                 // the current session is dead — fall through and accept the new one.
                 const lastAlive = state.lastPingRecvMs ?? state.sessionEstablishedAtMs;
                 const currentSessionAlive = Date.now() - lastAlive < FRIEND_TIMEOUT_MS;
-                if (sinceEstablished > 1000 && currentSessionAlive) {
-                    // Reject a new-key handshake while our session is alive — toxcore does
-                    // the same. (The "half-open breaker" that accepted these after N tries
-                    // was reverted: accepting a new key ROTATES the session, which churned
-                    // healthy sessions; the real fix was the TURN-crash fix, not this.)
+                // The peer has RE-KEYED if it's sending us crypto data we can't decrypt
+                // more recently than the last packet we could — our "alive" signal above
+                // is stale (it counts packets from just before the peer flapped). This is
+                // the flapping iOS/native case: iOS drops, re-handshakes with a fresh
+                // session key, then sends online messages we can't decrypt because we're
+                // still holding the dead keys and rejecting its fix-up handshake for the
+                // whole 32s timeout. Accept the fresh handshake NOW to resync. Safe: a
+                // healthy session never produces undecryptable data, so peerReKeyed stays
+                // false for it — this can't churn a live session (the reverted "half-open
+                // breaker" churned because it accepted new keys with NO such evidence).
+                const peerReKeyed = state.undecryptableRecvMs !== undefined &&
+                    state.undecryptableRecvMs > (state.lastPingRecvMs ?? 0);
+                if (sinceEstablished > 1000 && currentSessionAlive && !peerReKeyed) {
                     this.#debugVerboseLog(`hs_recv ignored friend=${friendId} (new session pubkey on live established session, ${sinceEstablished}ms after establish)`);
                     return;
                 }
+                if (peerReKeyed) {
+                    this.#debugLog(`hs_recv accepting re-handshake friend=${friendId} (peer re-keyed: undecryptable data since last good packet)`);
+                }
                 this.#debugLog(`hs_recv accepting re-handshake friend=${friendId} (current session wedged/dead, ` +
                     `lastPingRecv=${state.lastPingRecvMs ? Date.now() - state.lastPingRecvMs + "ms ago" : "never"})`);
             }
@@ -1495,6 +1692,10 @@ export class Peer {
             state.sessionSharedKey = nacl.box.before(hs.sessionPublicKey, state.ourSessionKeyPair.secretKey);
             state.established = true;
             state.sessionEstablishedAtMs = Date.now();
+            // Fresh session up — reset the higher-pubkey defer window for the
+            // next outage (see #initiateSession).
+            this.#initiateDeferSinceMs.delete(friendId);
+            this.#initiateSkipLogged.delete(friendId);
             if (this.#remoteIsTcp(remote)) {
                 state.hasTcpRoute = true;
                 // Don't set state.remote — there's no UDP endpoint for this peer.
@@ -1505,6 +1706,11 @@ export class Peer {
             if (isNewSession) {
                 state.sendPacketNumber = 0;
                 state.receiveBufferStart = 0;
+                // Packet numbers restart at 0 — parked retransmit payloads from
+                // the previous session are meaningless (and would resend under
+                // colliding numbers). Drop them.
+                state.sendArray = undefined;
+                state.sendBufferStartNum = undefined;
             }
             else {
                 state.sendPacketNumber ??= 0;
@@ -1670,6 +1876,13 @@ export class Peer {
                     }
                     state.lastRelayRecvMs = Date.now();
                 }
+                else if (this.#isUnroutableSelfSource(remote.address, remote.port)) {
+                    // Sourced from our own TUN address / own socket (overlay routing
+                    // artifact): the payload is real — deliver it — but this is NOT a
+                    // usable bidirectional UDP path. Don't adopt it (replies loop into
+                    // our own interface) and don't mark UDP-confirmed, or the punch
+                    // machinery stops trying to establish a REAL direct path.
+                }
                 else {
                     // Adopt the source as our send endpoint — via #adoptRemote, which
                     // refuses to downgrade off a locked physical-LAN path to a public /
@@ -1688,12 +1901,44 @@ export class Peer {
                 if (!isSingleTransportKind && opened.packetNumber < (state.receiveBufferStart ?? 0)) {
                     continue;
                 }
-                state.peerBaseNonce[state.peerBaseNonce.length - 2] = packet[1];
-                state.peerBaseNonce[state.peerBaseNonce.length - 1] = packet[2];
-                incrementNonce(state.peerBaseNonce);
-                state.receiveBufferStart = Math.max(state.receiveBufferStart ?? 0, (opened.packetNumber + 1) >>> 0);
+                // Track the receive nonce from the EXACT nonce this packet used
+                // (openCryptoDataPacket reconstructs it with full carry/borrow).
+                // The old two-byte overwrite dropped the carry into byte 21 when
+                // loss spanned a 64k counter wrap, permanently desyncing the
+                // session. Only move FORWARD — a late reordered packet must not
+                // drag the tracked nonce backward.
+                {
+                    const trackedLow = ((state.peerBaseNonce[state.peerBaseNonce.length - 2] << 8) | state.peerBaseNonce[state.peerBaseNonce.length - 1]) >>> 0;
+                    const fwd = ((opened.nonceLast2 - trackedLow) & 0xffff) < 0x8000;
+                    if (fwd) {
+                        state.peerBaseNonce = opened.usedNonce.slice();
+                        incrementNonce(state.peerBaseNonce);
+                    }
+                }
                 const kind = opened.payload[0];
                 const inner = opened.payload.slice(1);
+                // Advance our ack point ONLY for kinds that actually consume a
+                // reliable packet number on the sender. Toxcore sends REQUEST(1)
+                // and lossy (>=192) packets with num = send_array.buffer_end — the
+                // NEXT UNUSED number, not stored in its send array. Counting those
+                // advanced our receiveBufferStart to buffer_end+1, i.e. we then
+                // acked one more packet than the peer ever sent — and toxcore's
+                // handle_data_packet_core REJECTS any packet whose buffer_start is
+                // out of its send window (clear_buffer_until -> return -1). Result:
+                // from the peer's FIRST retransmit request onward, every packet we
+                // sent was discarded whole (fresh and retransmitted alike) and the
+                // peer went deaf until it re-keyed — the final piece of the iOS
+                // session churn. The JS droppable bulk channel (bulkDataPacketId)
+                // reuses the current number without consuming it, so it must not
+                // advance the ack point either (also fixes reliable packets being
+                // dropped as duplicates after a droppable burst under the same
+                // number).
+                const consumesReliableNumber = kind !== PACKET_ID_REQUEST &&
+                    !(kind !== undefined && kind >= 192) &&
+                    kind !== this.#opts.bulkDataPacketId;
+                if (consumesReliableNumber) {
+                    state.receiveBufferStart = Math.max(state.receiveBufferStart ?? 0, (opened.packetNumber + 1) >>> 0);
+                }
                 // Toxcore file transfer (FILE_SENDREQUEST/CONTROL/DATA = 80/81/82).
                 if (this.#fileTransfer.handlePacket(friendId, kind, inner))
                     return;
@@ -1729,9 +1974,13 @@ export class Peer {
                     return;
                 }
                 if (kind === PACKET_ID_REQUEST) {
-                    // Lossless retransmission request from peer. Full reliable stream
-                    // not yet implemented in JS port, so just acknowledge by logging.
-                    this.#debugVerboseLog(`crypto request packet received from ${friendId} (no retransmit queue)`);
+                    // Lossless retransmission request (toxcore handle_request_packet).
+                    // Bytes are 1-based deltas walking our send window from
+                    // sendBufferStartNum: a matching delta marks that packet number
+                    // REQUESTED (peer is missing it — resend); every walked number
+                    // that doesn't match is implicitly ACKED (peer has it — drop from
+                    // the buffer). 0 is a +255 filler.
+                    this.#handleRetransmitRequest(friendId, state, inner);
                     return;
                 }
                 if (kind === PACKET_ID_SHARE_RELAYS) {
@@ -1810,17 +2059,44 @@ export class Peer {
                     return;
                 }
                 if (kind === PACKET_ID_MESSAGE || kind === PACKET_ID_ACTION) {
-                    // Plain text inside (no Carrier FlatBuffers wrapper). Some peers
-                    // send raw UTF-8, others send a Carrier message packet — try both.
-                    let text = tryDecodeCarrierMessagePacket(inner) ?? decodeUtf8Best(inner);
+                    this.#setFriendOnline(friendId, remote.address, remote.port);
+                    // Decode the Carrier FlatBuffers wrapper when present. A BULKMSG
+                    // fragment (Carrier C splits any message >1024 bytes this way —
+                    // e.g. iOS Beagle images, which are FileModel JSON envelopes)
+                    // goes to the reassembler and only emits once complete; before
+                    // this, every fragment surfaced as a separate garbage "text".
+                    let text;
+                    let carrier;
+                    try {
+                        carrier = decodeCarrierPacket(inner);
+                    }
+                    catch { /* raw utf-8 peer */ }
+                    if (carrier?.type === PACKET_TYPE_BULKMSG) {
+                        const complete = this.#assembleBulkMsg(friendId, carrier);
+                        if (!complete)
+                            return; // more fragments pending
+                        text = decodeUtf8Best(complete);
+                        this.#debugLog(`bulkmsg complete from ${friendId} (${complete.length} bytes)`);
+                    }
+                    else if (carrier?.type === PACKET_TYPE_MESSAGE) {
+                        text = new TextDecoder().decode(carrier.data);
+                    }
+                    else {
+                        text = decodeUtf8Best(inner);
+                    }
                     if (!text) {
                         this.#debugLog(`crypto message packet decode failed from ${friendId}`);
                         return;
                     }
-                    this.#setFriendOnline(friendId, remote.address, remote.port);
+                    // iOS Beagle sends files inline as a FileModel JSON envelope
+                    // ({data: base64, fileExtension, fileName, type}) — surface those
+                    // as files, not as a wall of base64 text.
+                    if (this.#tryEmitInlineFile(friendId, text, "online"))
+                        return;
                     this.#events.emit("text", {
                         pubkey: friendId,
-                        text
+                        text,
+                        via: "online"
                     });
                     this.#debugLog(`crypto ${kind === PACKET_ID_ACTION ? "action" : "message"} from ${friendId}: "${text}"`);
                     return;
@@ -1852,6 +2128,25 @@ export class Peer {
             // CRASH (TURN DNS); with that fixed, sessions stay converged on their own.
             // Just drop the undecryptable packet — net_crypto's normal re-handshake
             // path recovers a genuinely dead session.
+            // If this came over the TCP relay (synthetic tcp:<friendId> remote) we KNOW
+            // which friend sent it. Record the decrypt failure so the handshake path can
+            // distinguish a re-keyed peer (desync — accept its fresh handshake now) from
+            // a live one, instead of holding dead keys for the full timeout while every
+            // online message is silently dropped.
+            if (remote.address.startsWith("tcp:")) {
+                // remote carries the POOL key id (native peers: DHT key) — map to
+                // the real friend so the desync marker lands on the real session.
+                let desyncFriendId = remote.address.slice(4);
+                try {
+                    desyncFriendId = this.#friendIdForPoolKey(base58ToBytes(desyncFriendId));
+                }
+                catch { /* keep raw id */ }
+                const ds = this.#friendSessions.get(desyncFriendId);
+                if (ds?.established) {
+                    ds.undecryptableRecvMs = Date.now();
+                    this.#debugVerboseLog(`undecryptable crypto data from ${desyncFriendId} (peer likely re-keyed)`);
+                }
+            }
             this.#debugVerboseLog(`crypto data received from ${remote.address}:${remote.port} but no session matched`);
             return;
         }
@@ -1949,6 +2244,7 @@ export class Peer {
         session.lastDhtPkNoReplay = noReplay;
         session.friendRealPublicKey ??= senderPublicKey;
         session.friendDhtPublicKey = friendDhtPublicKey;
+        this.#learnFriendDhtKey(senderId, friendDhtPublicKey);
         // A DHT-PK announce from this friend IS the proof they've accepted
         // our friend request — only friends actively trying to reach us send
         // these. Mark acceptedAt so subsequent peer.sendFriendRequest calls
@@ -2165,7 +2461,11 @@ export class Peer {
                     // Malformed pubkey, fall through.
                 }
             }
-            this.#events.emit("text", { pubkey: fromUserId, text });
+            // Offline images/audio arrive as the same FileModel JSON envelope
+            // (iOS posts the whole thing as one express MESSAGE packet).
+            if (this.#tryEmitInlineFile(fromUserId, text, "offline"))
+                return;
+            this.#events.emit("text", { pubkey: fromUserId, text, via: "offline" });
         }
         catch {
             // Ignore invalid offline payloads.
@@ -2459,7 +2759,10 @@ export class Peer {
                 dataPublicKey: this.#announceDataKey.publicKey,
                 sendBack: c.sendBack,
                 allowDirectFallback: true,
-                attempts: SELF_ANNOUNCE_ATTEMPTS
+                attempts: SELF_ANNOUNCE_ATTEMPTS,
+                // ping_id is source-bound: step2 must exit from the same hop
+                // step1 did or the node rejects it and nothing ever stores.
+                reuseRoute: true
             })));
             for (let j = 0; j < step1Hits.length; j++) {
                 const { c, resp1 } = step1Hits[j];
@@ -2474,6 +2777,7 @@ export class Peer {
                     catch { /* best-effort */ }
                 if (final.isStored === 2) {
                     storedNodes.push(c.node);
+                    this.#debugLog(`self announce STORED on ${c.node.host}:${c.node.port} (total ${storedNodes.length})`);
                     // Keep dhtHealth.selfAnnounceStoredOn live within the loop,
                     // not just at the end, so we see growth in real time.
                     this.#lastSelfAnnounceStoredCount = storedNodes.length;
@@ -2564,8 +2868,17 @@ export class Peer {
                 // sessions a long grace so a blackout doesn't churn them via re-handshake;
                 // unproven sessions still time out fast to self-heal a wedged handshake.
                 const proven = session.lastPingRecvMs !== undefined;
-                const deadline = proven ? PROVEN_SESSION_HARD_TIMEOUT_MS : FRIEND_TIMEOUT_MS;
-                if (proven && silentFor > FRIEND_TIMEOUT_MS && silentFor <= deadline) {
+                // A relay-only session (synthetic tcp: remote, no UDP path) whose
+                // relay route is gone has NO transport at all — nothing can arrive
+                // and nothing we send leaves. The proven-session blackout grace
+                // exists for UDP paths that black out (GFW) while both ends keep
+                // keys; it must NOT keep a transportless relay session as a 180s
+                // zombie (iOS flap: peer sees us vanish while we still show them
+                // online and drop every send). Fast-track those to teardown.
+                const relayOnly = !session.remote || session.remote.host.startsWith("tcp:");
+                const pathless = relayOnly && !session.hasTcpRoute;
+                const deadline = proven && !pathless ? PROVEN_SESSION_HARD_TIMEOUT_MS : FRIEND_TIMEOUT_MS;
+                if (proven && !pathless && silentFor > FRIEND_TIMEOUT_MS && silentFor <= deadline) {
                     // Blackout grace: keep the proven session and keep probing (the
                     // keepalive + UDP re-punch + relay-keepalive below all still run). Do
                     // NOT delete or re-handshake — that's what desyncs and churns. The peer,
@@ -2587,6 +2900,11 @@ export class Peer {
                         const pk = base58ToBytes(friend.pubkey);
                         if (pk.length === 32)
                             this.#tcpRelays?.requestRoute(pk);
+                        // Native peers sit on relays under their DHT key — re-request
+                        // that too or the relay never re-links after this teardown.
+                        const dhtPk = this.#friendDhtKeys.get(friendId);
+                        if (dhtPk && dhtPk.length === 32)
+                            this.#tcpRelays?.requestRoute(dhtPk);
                     }
                     catch { /* skip malformed */ }
                     continue;
@@ -2774,30 +3092,46 @@ export class Peer {
             // bridged them, cookie+handshake fired once, didn't complete, and
             // nothing re-tried it. Counting the relay route lets the retry fire.
             const haveEndpoint = (friend.remoteHost && friend.remotePort) || session?.remote || session?.hasTcpRoute;
-            if (!haveEndpoint) {
-                // No UDP endpoint AND no relay route yet. For a peer whose DHT
-                // self-announce never stored (WSL2, symmetric NAT, restrictive
-                // firewall), neither onion discovery nor UDP punch can ever find
-                // them — the ONLY bootstrap is the TCP relay: ask our relays to
-                // route to the friend's pubkey, and when they're also connected to
-                // a shared relay the pool fires `friendOnline` -> #initiateSession.
-                // requestRoute was only issued once at start(); if the friend or a
-                // relay wasn't connected in that instant it was never retried, so an
-                // accepted friend could sit at "requested" forever (the WSL-client-
-                // never-gets-an-IP bug). Re-assert it here on a cooldown — cheap and
-                // idempotent — so it eventually catches once both ends share a relay.
+            // Route parking runs for EVERY non-established friend — deliberately
+            // NOT gated on haveEndpoint. A stale persisted remoteHost (e.g. a
+            // bootstrap ip:port cached by an old bug) counts as an "endpoint" and
+            // used to suppress this block entirely, so the friend was never
+            // watched on any relay and could only ever be reached by spamming
+            // cookies at the dead address (the iOS-simulator-forever-offline bug).
+            // For a peer whose DHT self-announce never stored (WSL2, symmetric
+            // NAT, restrictive firewall), the TCP relay is the ONLY bootstrap:
+            // ask our relays to route to the friend's keys; when both ends share
+            // a relay the pool fires `friendOnline` -> #initiateSession.
+            // Re-asserted on a cooldown — cheap and idempotent.
+            {
                 const lastRouteReq = this.#routeRequestCooldown.get(friendId) ?? 0;
                 if (this.#tcpRelays && now - lastRouteReq > 15_000) {
                     try {
                         const pk = base58ToBytes(friend.pubkey);
+                        // The relay routes CRYPTO_DATA by the key the peer CONNECTED to the
+                        // relay with. For a NATIVE peer (iOS/Android) that's its DHT key,
+                        // NOT its identity key — and the send path already routes by
+                        // friendDhtPublicKey. Requesting the route ONLY under the identity
+                        // key (as before) meant the relay never linked us to the peer: its
+                        // handshake arrives OOB (which needs no route), but every continuous
+                        // CRYPTO_DATA packet (chat + keepalives) was silently dropped, so the
+                        // session came up then went dead in 32s. Request the DHT key too so
+                        // the routed path actually establishes; keep the identity key for
+                        // toxcore peers where the two match.
+                        const dhtPk = this.#friendSessions.get(friendId)?.friendDhtPublicKey ?? this.#friendDhtKeys.get(friendId);
+                        if (dhtPk && dhtPk.length === 32) {
+                            this.#tcpRelays.requestRoute(dhtPk);
+                        }
                         if (pk.length === 32) {
                             this.#tcpRelays.requestRoute(pk);
                             this.#routeRequestCooldown.set(friendId, now);
-                            this.#debugLog(`re-requesting relay route for unconnected friend ${friendId}`);
+                            this.#debugVerboseLog(`re-requesting relay route for unconnected friend ${friendId}${dhtPk ? " (+dht key)" : ""}`);
                         }
                     }
                     catch { /* skip malformed pubkey */ }
                 }
+            }
+            if (!haveEndpoint) {
                 // Re-SEND the friend-request to a friend we've never had accepted
                 // (still "requested"). The original can be lost — the friend was
                 // offline/restarting, a relay blipped, or onion had no return path.
@@ -2874,6 +3208,140 @@ export class Peer {
             });
         }
     }
+    /** Append a Carrier BULKMSG fragment; returns the full reassembled
+     *  message when the last fragment lands, undefined while pending.
+     *  Mirrors the C SDK's handle_friend_bulkmsg: totalsz on the first
+     *  fragment sizes the buffer; fragments append in arrival order. */
+    #assembleBulkMsg(friendId, frag) {
+        const now = Date.now();
+        // Lazy expiry sweep (C uses a 60s assembly timeout).
+        for (const [key, entry] of this.#bulkAssembly) {
+            if (entry.expireAtMs < now)
+                this.#bulkAssembly.delete(key);
+        }
+        const key = `${friendId}:${frag.tid.toString()}`;
+        let entry = this.#bulkAssembly.get(key);
+        if (!entry) {
+            if (!frag.totalsz || frag.totalsz > CARRIER_MAX_APP_BULKMSG_LEN) {
+                this.#debugLog(`bulkmsg from ${friendId} with invalid/missing totalsz ${frag.totalsz} — dropped`);
+                return undefined;
+            }
+            entry = { total: frag.totalsz, chunks: [], got: 0, expireAtMs: now + 60_000 };
+            this.#bulkAssembly.set(key, entry);
+        }
+        if (frag.data.length === 0 || entry.got + frag.data.length > entry.total) {
+            this.#debugLog(`bulkmsg fragment from ${friendId} overflows totalsz — dropped`);
+            this.#bulkAssembly.delete(key);
+            return undefined;
+        }
+        entry.chunks.push(frag.data);
+        entry.got += frag.data.length;
+        if (entry.got < entry.total)
+            return undefined;
+        this.#bulkAssembly.delete(key);
+        return concatBytes(entry.chunks);
+    }
+    /** iOS Beagle sends files inline as a JSON envelope over (bulk)messages:
+     *  {"data":"<base64>","fileExtension":".jpg","fileName":"…","type":"image"}.
+     *  Detect it, decode, and emit an inlineFile event instead of dumping
+     *  base64 into the chat. Returns true when handled. */
+    #tryEmitInlineFile(friendId, text, via) {
+        const trimmed = text.trimStart();
+        if (!trimmed.startsWith("{") || !trimmed.includes("\"fileName\"") || !trimmed.includes("\"data\"")) {
+            return false;
+        }
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (typeof parsed.data !== "string" || typeof parsed.fileName !== "string")
+                return false;
+            const data = Uint8Array.from(Buffer.from(parsed.data, "base64"));
+            const ext = parsed.fileExtension ?? "";
+            const name = parsed.fileName.endsWith(ext) ? parsed.fileName : parsed.fileName + ext;
+            this.#events.emit("inlineFile", {
+                pubkey: friendId,
+                name,
+                fileType: parsed.type,
+                data,
+                via
+            });
+            this.#debugLog(`inline file from ${friendId}: "${name}" (${data.length} bytes, ${via})`);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Toxcore handle_request_packet: parse the peer's PACKET_ID_REQUEST and
+     *  (a) implicitly ACK every walked packet number that isn't requested,
+     *  (b) retransmit the requested ones from the send buffer. */
+    #handleRetransmitRequest(friendId, session, data) {
+        const start = session.sendBufferStartNum;
+        const end = session.sendPacketNumber;
+        if (start === undefined || end === undefined || !session.sendArray || session.sendArray.size === 0) {
+            return;
+        }
+        let cursor = 0;
+        let n = 1;
+        const requested = [];
+        for (let i = start; i !== end; i = (i + 1) >>> 0) {
+            if (cursor >= data.length)
+                break;
+            if (n === data[cursor]) {
+                requested.push(i);
+                cursor++;
+                n = 0;
+            }
+            else {
+                // Peer has this one — implicit ack, free it.
+                session.sendArray.delete(i);
+            }
+            if (n === 255) {
+                n = 1;
+                if (data[cursor] !== 0)
+                    return; // malformed filler
+                cursor++;
+            }
+            else {
+                n++;
+            }
+        }
+        // Advance the window past the acked prefix.
+        let s = start;
+        while (s !== end && !session.sendArray.has(s))
+            s = (s + 1) >>> 0;
+        session.sendBufferStartNum = s;
+        if (requested.length === 0)
+            return;
+        this.#debugLog(`retransmit request from ${friendId}: resending ${requested.length} packet(s) [${requested.slice(0, 8).join(",")}${requested.length > 8 ? ",…" : ""}]`);
+        void (async () => {
+            for (const num of requested) {
+                const payload = session.sendArray?.get(num);
+                if (!payload)
+                    continue;
+                try {
+                    await this.#resendReliablePacket(friendId, session, num, payload);
+                }
+                catch { /* transport hiccup — peer will re-request */ }
+            }
+        })();
+    }
+    /** Re-send a parked reliable packet with its ORIGINAL packet number but
+     *  the CURRENT nonce counter (toxcore retransmissions do the same — the
+     *  receiver reconstructs the nonce from the wire bytes, while the packet
+     *  number slots it into the gap in their receive window). */
+    async #resendReliablePacket(friendId, session, packetNumber, payload) {
+        if (!session.established || !session.sessionSharedKey || !session.ourBaseNonce)
+            return;
+        const encrypted = createCryptoDataPacket({
+            sessionSharedKey: session.sessionSharedKey,
+            sentNonce: session.ourBaseNonce,
+            bufferStart: session.receiveBufferStart ?? 0,
+            packetNumber,
+            payload
+        });
+        incrementNonce(session.ourBaseNonce);
+        await this.#sendToFriend(friendId, encrypted, session, false, false);
+    }
     async #sendMessengerPacket(friendId, kind, data) {
         const session = this.#friendSessions.get(friendId);
         if (!session?.established || !session.sessionSharedKey || !session.ourBaseNonce) {
@@ -2892,7 +3360,35 @@ export class Peer {
             payload
         });
         incrementNonce(session.ourBaseNonce);
-        session.sendPacketNumber = (packetNumber + 1) >>> 0;
+        // Reliable-sequence hygiene. Only packets we will actually DELIVER reliably
+        // may consume the reliable packet-number sequence. The app's high-volume bulk
+        // channel (bulkDataPacketId, e.g. decentlan IP=163) and toxcore lossy packets
+        // (192-254) are DROPPED under backpressure — if they burn a reliable number
+        // first, the drop punches a PERMANENT hole in the stream. A native (iOS/C)
+        // peer does strict in-order net_crypto delivery and stalls EVERYTHING after a
+        // hole (incl. chat 64), sending PACKET_ID_REQUEST for a retransmit we never do
+        // (no retransmit queue) — silently wedging online chat with native peers.
+        // File transfer is bulk but NEVER dropped (queued reliably), so it keeps its
+        // number. So advance the reliable number for everything EXCEPT the droppable
+        // bulk-IP channel and lossy packets; the crypto nonce still advances above so
+        // decryption stays in sync regardless.
+        const isFileTransfer = kind === PACKET_ID_FILE_SENDREQUEST || kind === PACKET_ID_FILE_CONTROL || kind === PACKET_ID_FILE_DATA || kind === PACKET_ID_FILE_FEC;
+        const isBulkData = (this.#opts.bulkDataPacketId !== undefined && kind === this.#opts.bulkDataPacketId) || isFileTransfer;
+        const isDroppable = (isBulkData && !isFileTransfer) || kind >= 192;
+        if (!isDroppable) {
+            session.sendPacketNumber = (packetNumber + 1) >>> 0;
+            // Park the plaintext for retransmission (native peers stall their
+            // whole lossless stream on a gap until we honor PACKET_ID_REQUEST).
+            session.sendArray ??= new Map();
+            session.sendBufferStartNum ??= packetNumber;
+            session.sendArray.set(packetNumber, payload);
+            // Bound the buffer: beyond this window the peer has either acked via
+            // REQUEST packets or the session is beyond saving anyway.
+            while (session.sendArray.size > 1024 && session.sendBufferStartNum !== session.sendPacketNumber) {
+                session.sendArray.delete(session.sendBufferStartNum);
+                session.sendBufferStartNum = (session.sendBufferStartNum + 1) >>> 0;
+            }
+        }
         session.lastPingSentMs = Date.now();
         // Bulk IP-forwarding data (PACKET_ID_MESSAGE) is the high-volume
         // traffic. Once UDP is established it should ride UDP exclusively and
@@ -2925,12 +3421,10 @@ export class Peer {
         // happens to finish before reordering bites. Pinning file transfer to a
         // single transport keeps the chunks in send order. (Reliability across a
         // lossy path still wants a reorder buffer + retransmit — tracked separately.)
-        const isFileTransfer = kind === PACKET_ID_FILE_SENDREQUEST || kind === PACKET_ID_FILE_CONTROL || kind === PACKET_ID_FILE_DATA || kind === PACKET_ID_FILE_FEC;
-        const isBulkData = (this.#opts.bulkDataPacketId !== undefined && kind === this.#opts.bulkDataPacketId) || isFileTransfer;
         // File transfer rides the relay RELIABLY (never dropped under backpressure):
         // a dropped IP/CCTV packet is fine (the stream moves on), but a dropped file
         // chunk corrupts the file (no retransmit). So bulk IP data stays droppable
-        // while file transfer is queued.
+        // while file transfer is queued. (isBulkData / isFileTransfer computed above.)
         await this.#sendToFriend(friendId, encrypted, session, isBulkData, isFileTransfer);
     }
     /**
@@ -3134,6 +3628,11 @@ export class Peer {
         if (!friend) {
             return;
         }
+        // An unroutable self-source is never the friend's endpoint (see
+        // #adoptRemote) — don't let it poison the in-memory record either.
+        if (this.#isUnroutableSelfSource(host, port)) {
+            return;
+        }
         // Important: do NOT persist this candidate to disk. Speculative endpoint
         // hints (from DHT-PK extras, sendnodes-derived knownNodes, etc.) are
         // frequently stale relay addresses that aren't actually the friend's
@@ -3166,6 +3665,7 @@ export class Peer {
         }
         if (dhtPublicKey) {
             session.friendDhtPublicKey = dhtPublicKey;
+            this.#learnFriendDhtKey(friendId, dhtPublicKey);
         }
     }
     /** Single choke point for setting session.remote (the direct-UDP send
@@ -3176,7 +3676,26 @@ export class Peer {
      *  is just a string compare and is safe to call from the per-packet hot path.
      *  Replacing the per-packet getPhysicalLanSubnets() call here was the fix for
      *  the CCTV CPU regression. */
+    /** True when replying to host:port would never reach a peer: the host is
+     *  one of our own TUN/overlay addresses (replies re-enter the overlay
+     *  router and loop), or it's literally our own UDP socket. A self
+     *  PHYSICAL address with a DIFFERENT port is routable — that's a
+     *  same-host peer (e.g. the iOS simulator running on this Mac). */
+    #isUnroutableSelfSource(host, port) {
+        if (isOwnVirtualAddress(host))
+            return true;
+        if (!isOwnAddress(host))
+            return false;
+        const ourPort = this.#udp?.localPort();
+        return ourPort !== undefined && port === ourPort;
+    }
     #adoptRemote(session, host, port) {
+        // NEVER adopt an unroutable self-source as a friend's remote — replies
+        // would loop into our own interface and die, the peer never hears back
+        // and re-handshakes forever.
+        if (this.#isUnroutableSelfSource(host, port)) {
+            return;
+        }
         if (session.lanRemoteHost &&
             session.remote?.host === session.lanRemoteHost &&
             host !== session.lanRemoteHost) {
@@ -3685,13 +4204,33 @@ export class Peer {
             }
         }
         if (pkCmp < 0) {
-            // We're the responder side — wait for peer's COOKIE_REQUEST.
-            // Log once per friend to avoid noise from repeated probe calls.
-            if (!this.#initiateSkipLogged.has(friendId)) {
-                this.#initiateSkipLogged.add(friendId);
-                this.#debugLog(`initiate session: deferring to higher-pubkey peer ${friendId}`);
+            // We're the responder side — wait for peer's COOKIE_REQUEST...
+            // but NOT forever. A higher-pubkey peer that still holds a proven
+            // session from before OUR restart never re-initiates (its side looks
+            // healthy; only its data — encrypted with keys we no longer have —
+            // arrives here as an endless undecryptable flood). Deferring
+            // unconditionally is a PERMANENT deadlock: observed live as a dozen
+            // fleet peers "online at the relay, spraying undecryptable data,
+            // never reconnecting" after a mac-dev restart. Toxcore's tie-break
+            // assumes both sides know the session is dead; here only WE do. So:
+            // defer for a grace window; if the peer hasn't established by then,
+            // initiate anyway — the duplicate-handshake fast path and the
+            // re-handshake acceptance rules handle the both-initiate races the
+            // defer was protecting against.
+            const firstDefer = this.#initiateDeferSinceMs.get(friendId);
+            const now = Date.now();
+            if (firstDefer === undefined) {
+                this.#initiateDeferSinceMs.set(friendId, now);
+            }
+            if (firstDefer === undefined || now - firstDefer < 30_000) {
+                // Log once per friend to avoid noise from repeated probe calls.
+                if (!this.#initiateSkipLogged.has(friendId)) {
+                    this.#initiateSkipLogged.add(friendId);
+                    this.#debugLog(`initiate session: deferring to higher-pubkey peer ${friendId}`);
+                }
+                return false;
             }
-            return false;
+            this.#debugLog(`initiate session: higher-pubkey peer ${friendId} hasn't established in ${Math.round((now - firstDefer) / 1000)}s — breaking defer, initiating`);
         }
         // Prefer DHT key learned from DHTPK updates; fallback to real key.
         const friendDhtPk = session?.friendDhtPublicKey ?? friendRealPk;
@@ -4229,26 +4768,22 @@ export class Peer {
         if (ourUdpPort && ourUdpPort > 0) {
             const ourDhtPk = this.#keyPair?.publicKey;
             if (ourDhtPk && ourDhtPk.length === 32) {
-                // Enumerate non-loopback IPv4 addresses on this host.
-                // We use os.networkInterfaces() rather than guessing — this
-                // covers a multi-homed peer with several reachable IPs.
+                // Enumerate non-loopback IPv4 addresses on this host — PHYSICAL
+                // interfaces only (getPhysicalLanAddresses applies VIRTUAL_IFACE_RE).
+                // The old raw networkInterfaces() walk also advertised our own TUN
+                // address (agentnet0's 10.86.x.y): native peers then sent their UDP
+                // cookie/handshake/session packets to our VIRTUAL ip — into the TUN
+                // maze — and we replied to that same poisoned source, so neither
+                // side's packets arrived and the peer saw us flap online/offline
+                // forever (the iOS-simulator churn).
                 try {
-                    const ifaces = (await import("os")).networkInterfaces();
                     const seenIps = new Set();
-                    for (const iface of Object.values(ifaces)) {
-                        if (!iface)
-                            continue;
-                        for (const addr of iface) {
-                            if (addr.family !== "IPv4")
-                                continue;
-                            if (addr.internal)
-                                continue;
-                            if (addr.address === "0.0.0.0")
+                    for (const address of getPhysicalLanAddresses()) {
+                        {
+                            if (seenIps.has(address))
                                 continue;
-                            if (seenIps.has(addr.address))
-                                continue;
-                            seenIps.add(addr.address);
-                            const parts = addr.address
+                            seenIps.add(address);
+                            const parts = address
                                 .split(".")
                                 .map((p) => Number.parseInt(p, 10));
                             if (parts.length !== 4 || parts.some((n) => !(n >= 0 && n <= 255)))
@@ -4429,32 +4964,53 @@ export class Peer {
             dataPublicKey: opts.dataPublicKey,
             sendBack: opts.sendBack
         });
-        const attempts = opts.attempts ?? 3;
-        for (let attempt = 0; attempt < attempts; attempt++) {
+        const nodeId = `${opts.node.host}:${opts.node.port}`;
+        const pinnedRoute = opts.reuseRoute ? this.#announceRouteUsed.get(nodeId) : undefined;
+        const exchange = async (forcedPath) => {
             const waiter = this.#waitForAnnounceResponse(opts.node, opts.sendBack, {
                 requesterSecretKey: opts.senderSecretKey,
                 nodePublicKey: opts.nodePublicKey
             });
-            await this.#sendThroughOnionPath(request, opts.node, attempt);
+            const routeUsed = await this.#sendThroughOnionPath(request, opts.node, 0, forcedPath);
             const response = await waiter;
             if (response) {
-                this.#recordNodeSuccess(`${opts.node.host}:${opts.node.port}`);
+                this.#recordNodeSuccess(nodeId);
+                this.#announceRouteUsed.set(nodeId, routeUsed);
                 return response;
             }
-            this.#recordNodeFailure(`${opts.node.host}:${opts.node.port}`);
+            this.#recordNodeFailure(nodeId);
+            return undefined;
+        };
+        if (pinnedRoute) {
+            // The pinned route is the only one whose source the node's ping_id can
+            // match — retry it rather than wandering to other paths.
+            const pinnedAttempts = Math.max(1, opts.attempts ?? 3);
+            for (let attempt = 0; attempt < pinnedAttempts; attempt++) {
+                const response = await exchange(pinnedRoute);
+                if (response)
+                    return response;
+            }
+            return undefined;
         }
-        if (opts.allowDirectFallback) {
+        const attempts = opts.attempts ?? 3;
+        for (let attempt = 0; attempt < attempts; attempt++) {
             const waiter = this.#waitForAnnounceResponse(opts.node, opts.sendBack, {
                 requesterSecretKey: opts.senderSecretKey,
                 nodePublicKey: opts.nodePublicKey
             });
-            await this.#sendPacket(request, opts.node);
+            const routeUsed = await this.#sendThroughOnionPath(request, opts.node, attempt);
             const response = await waiter;
             if (response) {
-                this.#recordNodeSuccess(`${opts.node.host}:${opts.node.port}`);
+                this.#recordNodeSuccess(nodeId);
+                this.#announceRouteUsed.set(nodeId, routeUsed);
                 return response;
             }
-            this.#recordNodeFailure(`${opts.node.host}:${opts.node.port}`);
+            this.#recordNodeFailure(nodeId);
+        }
+        if (opts.allowDirectFallback) {
+            const response = await exchange("direct");
+            if (response)
+                return response;
         }
         return undefined;
     }
@@ -4513,12 +5069,12 @@ export class Peer {
         const wrapped = concatBytes([Uint8Array.of(0x69, 0x76, 0x65, 0x67), packet]);
         await this.#udp.send(Buffer.from(wrapped), node.host, node.port);
     }
-    async #sendThroughOnionPath(payloadForNodeD, nodeD, pathOffset = 0) {
-        const path = this.#selectOnionPath(nodeD, pathOffset);
+    async #sendThroughOnionPath(payloadForNodeD, nodeD, pathOffset = 0, forcedPath) {
+        const path = forcedPath === "direct" ? undefined : forcedPath ?? this.#selectOnionPath(nodeD, pathOffset);
         if (!path) {
             this.#debugLog(`no onion path for ${nodeD.host}:${nodeD.port}, sending direct`);
             await this.#sendPacket(payloadForNodeD, nodeD);
-            return;
+            return "direct";
         }
         this.#debugLog(`sending onion initial via ${path.nodeA.node.host}:${path.nodeA.node.port} to ${nodeD.host}:${nodeD.port}`);
         const packet = createOnionRequest0({
@@ -4534,6 +5090,7 @@ export class Peer {
             payloadForNodeD
         });
         await this.#sendPacket(packet, path.nodeA.node);
+        return path;
     }
     #selectOnionPath(nodeD, pathOffset = 0) {
         const nodeDId = `${nodeD.host}:${nodeD.port}`;
@@ -4754,6 +5311,14 @@ export class Peer {
                     remotePort: undefined,
                     status: record.status === "online" ? "offline" : record.status
                 };
+                // Scrub a remoteHost on one of our own VIRTUAL/TUN interfaces (older
+                // builds could cache the self-poisoned TUN source) — sends there
+                // loop through the overlay and die. Self PHYSICAL addresses are kept:
+                // a same-host peer (iOS simulator) legitimately lives there.
+                if (trusted.remoteHost && isOwnVirtualAddress(trusted.remoteHost)) {
+                    trusted.remoteHost = undefined;
+                    trusted.remotePort = undefined;
+                }
                 this.#friends.set(record.pubkey, trusted);
             }
             this.#debugLog(`loaded ${this.#friends.size} persisted friends`);
@@ -5116,6 +5681,8 @@ function isCgnatAddress(host) {
 let _lanIfaceCacheMs = 0;
 let _lanAddrsCache = [];
 let _lanSubnetsCache = [];
+let _allOwnAddrsCache = new Set();
+let _ownVirtualAddrsCache = new Set();
 function refreshLanIfaceCache() {
     const now = Date.now();
     if (_lanIfaceCacheMs !== 0 && now - _lanIfaceCacheMs < 5000)
@@ -5123,12 +5690,22 @@ function refreshLanIfaceCache() {
     _lanIfaceCacheMs = now;
     const addrs = [];
     const subnets = [];
+    const allOwn = new Set();
+    const ownVirtual = new Set();
     try {
         for (const [name, list] of Object.entries(networkInterfaces())) {
-            if (!list || VIRTUAL_IFACE_RE.test(name))
+            if (!list)
                 continue;
+            const virtual = VIRTUAL_IFACE_RE.test(name);
             for (const info of list) {
-                if (info.family !== "IPv4" || info.internal || isCgnatAddress(info.address))
+                if (info.family !== "IPv4")
+                    continue;
+                // ALL own addresses — including virtual/TUN interfaces — feed the
+                // self-source checks (see isOwnAddress/isOwnVirtualAddress).
+                allOwn.add(info.address);
+                if (virtual)
+                    ownVirtual.add(info.address);
+                if (virtual || info.internal || isCgnatAddress(info.address))
                     continue;
                 addrs.push(info.address);
                 const addr = ipv4ToInt(info.address);
@@ -5144,6 +5721,23 @@ function refreshLanIfaceCache() {
     }
     _lanAddrsCache = addrs;
     _lanSubnetsCache = subnets;
+    _allOwnAddrsCache = allOwn;
+    _ownVirtualAddrsCache = ownVirtual;
+}
+/** True when host is one of THIS machine's own IPv4 addresses (any
+ *  interface, physical or virtual/TUN). Cached (see refreshLanIfaceCache). */
+function isOwnAddress(host) {
+    refreshLanIfaceCache();
+    return _allOwnAddrsCache.has(host);
+}
+/** True when host belongs to one of our own VIRTUAL/TUN interfaces (e.g.
+ *  agentnet0's 10.86.x.y). Packets sent there re-enter the overlay router
+ *  and loop — never a usable peer endpoint. A self PHYSICAL address with a
+ *  DIFFERENT port is fine: that's a same-host peer (e.g. the iOS simulator
+ *  on this Mac), and local delivery works. */
+function isOwnVirtualAddress(host) {
+    refreshLanIfaceCache();
+    return _ownVirtualAddrsCache.has(host);
 }
 function getPhysicalLanAddresses() {
     refreshLanIfaceCache();