@agentunion/fastaun 0.5.20 → 0.5.22

package/dist/client/v2-e2ee.js

@@ -1,4 +1,5 @@
 import * as crypto from 'node:crypto';
+import { _INTERNAL_MESSAGE_FLOW_LIMITS } from '../config.js';
 import { E2EEError, StateError, ValidationError } from '../errors.js';
 import { decryptMessage, encryptGroupMessage, encryptP2PMessage, } from '../v2/e2ee/index.js';
 import { V2Session } from '../v2/session/index.js';
@@ -349,6 +350,13 @@ export class V2E2EECoordinator {
     get client() {
         return this.runtime.client;
     }
+    async withApplicationPage(ns, source, operation, reservation, handlers) {
+        const delivery = this.client._delivery;
+        return typeof delivery.runApplicationPage === 'function'
+            ? await (handlers ? delivery.runApplicationPage(ns, source, operation, reservation, handlers)
+                : reservation ? delivery.runApplicationPage(ns, source, operation, reservation) : delivery.runApplicationPage(ns, source, operation))
+            : await operation();
+    }
     resetForwardCursorState() {
         this.pendingForwardCursors.clear();
         this.pendingForwardAcks.clear();
@@ -621,11 +629,13 @@ export class V2E2EECoordinator {
             return null;
         }
     }
-    pendingSenderIKMessageKey(msg, groupId) {
+    pendingSenderIKMessageKey(msg, groupId, fromAid = '') {
         const client = this.client;
         const messageId = String(msg.message_id ?? '').trim();
         const seq = String(msg.seq ?? '').trim();
-        const prefix = groupId ? `group:${groupId}` : `p2p:${client._aid ?? ''}`;
+        const prefix = groupId ? `group:${groupId}` : client._p2pPeerPullEnabled
+            ? client._delivery.peerNamespace(fromAid || String(msg.sender_aid ?? msg.from_aid ?? msg.from ?? ''))
+            : `p2p:${client._aid ?? ''}`;
         return `${prefix}:${messageId || seq || Math.random().toString(36).slice(2)}`;
     }
     pendingSenderIKFetchKey(fromAid, senderDeviceId, groupId) {
@@ -717,7 +727,7 @@ export class V2E2EECoordinator {
             return;
         const senderDeviceId = String(args.senderDeviceId ?? '');
         const groupId = String(args.groupId ?? '').trim();
-        const messageKey = this.pendingSenderIKMessageKey(args.msg, groupId);
+        const messageKey = this.pendingSenderIKMessageKey(args.msg, groupId, fromAid);
         client._v2SenderIKPending.set(messageKey, {
             msg: { ...args.msg },
             fromAid,
@@ -833,10 +843,19 @@ export class V2E2EECoordinator {
                     }
                     plaintext = normalizeGroupMentionMode(plaintext, entry.msg, entry.msg.envelope_json);
                     plaintext.group_id = entry.groupId;
+                    plaintext.need_render = typeof entry.msg.need_render === 'boolean' ? entry.msg.need_render : plaintext.need_render !== false;
                     await client._publishPulledMessage('group.message_created', `group:${entry.groupId}`, seq, plaintext, false, 'pending_retry');
                 }
                 else {
-                    await client._publishPulledMessage('message.received', `p2p:${client._aid ?? ''}`, seq, plaintext, false, 'pending_retry');
+                    const ns = client._p2pPeerPullEnabled
+                        ? await client._delivery.initializePeer(entry.fromAid) : `p2p:${client._aid ?? ''}`;
+                    if (!generationIsCurrent())
+                        return;
+                    plaintext.sender_aid = entry.fromAid;
+                    plaintext.need_render = typeof entry.msg.need_render === 'boolean' ? entry.msg.need_render : plaintext.need_render !== false;
+                    await client._publishPulledMessage('message.received', ns, seq, plaintext, false, 'pending_retry');
+                    if (client._p2pPeerPullEnabled && generationIsCurrent())
+                        client._delivery.schedulePeerRecovery(entry.fromAid, seq);
                 }
                 if (generationIsCurrent())
                     pending.delete(key);
@@ -852,6 +871,8 @@ export class V2E2EECoordinator {
     }
     async publishPendingV2VolatileMessage(rawMessage, plaintext, source) {
         const delivery = this.client._delivery;
+        const generation = Number(this.client._v2RuntimeGeneration ?? 0);
+        const context = JSON.stringify([this.client._aid, this.client._deviceId, this.client._slotId]);
         const claim = delivery.beginVolatileDelivery(rawMessage);
         if (claim === 'inflight')
             return;
@@ -865,8 +886,14 @@ export class V2E2EECoordinator {
                 if (Object.prototype.hasOwnProperty.call(rawMessage, key))
                     publicMessage[key] = rawMessage[key];
             }
+            publicMessage.need_render = typeof rawMessage.need_render === 'boolean' ? rawMessage.need_render : plaintext.need_render !== false;
             const appEvent = delivery.p2pAppEventForMessage(publicMessage);
             await this.client._publishAppEvent(appEvent.event, appEvent.payload, source);
+            if (this.client._p2pPeerPullEnabled) {
+                if (context !== JSON.stringify([this.client._aid, this.client._deviceId, this.client._slotId]))
+                    throw new StateError('delivery invalidated');
+                this.ensureDeliveryCurrent(delivery.peerNamespace(String(rawMessage.sender_aid ?? rawMessage.from_aid ?? rawMessage.from ?? '')), generation);
+            }
             delivery.markVolatileSeen(rawMessage);
         }
         finally {
@@ -1040,6 +1067,7 @@ export class V2E2EECoordinator {
             timestamp: opts.timestamp,
             protectedHeaders: opts.protectedHeaders,
             context: opts.context,
+            needRender: opts.needRender,
         });
         client._logMessageDebug('send-envelope', 'message.send.v2', 'message.send', {
             message_id: envelope.message_id,
@@ -1084,6 +1112,7 @@ export class V2E2EECoordinator {
                 deviceId: targetDeviceId || undefined,
                 protectedHeaders: opts?.protectedHeaders,
                 context: opts?.context,
+                needRender: opts?.needRender,
                 useCache,
             });
             const result = await client.call('message.send', {
@@ -1093,6 +1122,7 @@ export class V2E2EECoordinator {
                 ...(targetDeviceId ? { device_id: targetDeviceId } : {}),
                 ...(opts?.ttl !== undefined ? { ttl: opts.ttl } : {}),
                 encrypt: false,
+                need_render: opts?.needRender ?? true,
                 _skip_send_result_envelope: true,
             });
             client._clientLog.debug(`message.v2.send ok: to=${toAid}, use_cache=${useCache}, seq=${String((isJsonObject(result) ? result.seq : '') ?? '')}`);
@@ -1106,6 +1136,7 @@ export class V2E2EECoordinator {
                 message_id: messageId,
                 timestamp: opts?.timestamp,
                 ttl: opts?.ttl,
+                need_render: opts?.needRender ?? true,
                 protected_headers: opts?.protectedHeaders,
                 context: opts?.context,
             }, result, true);
@@ -1122,6 +1153,7 @@ export class V2E2EECoordinator {
                     message_id: messageId,
                     timestamp: opts?.timestamp,
                     ttl: opts?.ttl,
+                    need_render: opts?.needRender ?? true,
                     protected_headers: opts?.protectedHeaders,
                     context: opts?.context,
                 }, result, true);
@@ -1137,12 +1169,13 @@ export class V2E2EECoordinator {
             history_error: { code: 'decrypt_failed', message: reason },
         };
     }
-    ensureDeliveryCurrent(ns, generation) {
+    ensureDeliveryCurrent(ns, generation, inlineGeneration) {
         if (Number(this.client._v2RuntimeGeneration ?? 0) !== generation
+            || (inlineGeneration !== undefined && this.client._delivery.captureInlineAckGeneration() !== inlineGeneration)
             || this.client._rpcPipeline?.isPullNamespaceCurrent?.(ns) === false)
             throw new StateError('pull invalidated');
     }
-    async decodeP2PWindowMessage(msg, publish, history, source, orderedPublish = false) {
+    async decodeP2PWindowMessage(msg, publish, history, source, orderedPublish = false, deferredEffects) {
         const client = this.client;
         const seq = strictWindowSeq(msg.seq, 'messages[].seq', true);
         let plaintext = null;
@@ -1173,11 +1206,11 @@ export class V2E2EECoordinator {
             else if (isJsonObject(payload)
                 && ['e2ee.p2p_encrypted', 'e2ee.encrypted'].includes(payloadType)) {
                 msg = { ...msg, envelope_json: JSON.stringify(payload) };
-                plaintext = await client._decryptV2Message(msg, false, !history, true, true, undefined, false, source);
+                plaintext = await client._decryptV2Message(msg, false, !history, true, true, undefined, false, source, ...(deferredEffects ? [deferredEffects] : []));
             }
         }
         else {
-            plaintext = await client._decryptV2Message(msg, false, !history, true, true, undefined, false, source);
+            plaintext = await client._decryptV2Message(msg, false, !history, true, true, undefined, false, source, ...(deferredEffects ? [deferredEffects] : []));
         }
         if (!plaintext) {
             if (history)
@@ -1260,6 +1293,7 @@ export class V2E2EECoordinator {
             client._clientLog.warn(`Group Tail 单条消息解密失败，连续性证明仍保留: group=${groupId}, seq=${seq}`);
             return null;
         }
+        plaintext.need_render = typeof msg.need_render === 'boolean' ? msg.need_render : plaintext.need_render !== false;
         if (publish && !history && client._delivery.isSelfSentGroupMessage?.(msg)) {
             return plaintext;
         }
@@ -1268,6 +1302,415 @@ export class V2E2EECoordinator {
         }
         return plaintext;
     }
+    async pullPeerV2(senderAid, opts = {}) {
+        const client = this.client;
+        const generation = Number(client._v2RuntimeGeneration ?? 0);
+        const inlineGeneration = client._delivery.captureInlineAckGeneration?.();
+        const pullVersion = opts.peerPullVersion ?? client._delivery.capturePeerTailVersion(senderAid);
+        await client._ensureV2SessionReady('message.pull');
+        this.ensureDeliveryCurrent(client._delivery.peerNamespace(senderAid), generation, inlineGeneration);
+        const ns = await client._delivery.initializePeer(senderAid);
+        this.ensureDeliveryCurrent(ns, generation, inlineGeneration);
+        const limit = Number(opts.limit ?? _INTERNAL_MESSAGE_FLOW_LIMITS.pullPageSize);
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 200)
+            throw new ValidationError('peer limit must be between 1 and 200');
+        let mode = opts.window_mode === 'tail' ? 'tail' : 'forward';
+        let source = mode === 'tail' ? 'tail' : 'pull';
+        if (mode === 'tail' && (opts.force === true || 'ack_up_to_seq' in opts))
+            throw new ValidationError('Tail does not accept force or ACK');
+        const budget = opts.budget ?? { remaining: Math.max(1, Number(opts.max_pages ?? 100)) };
+        let after = opts.after_seq === undefined ? client._seqTracker.getContiguousSeq(ns) : strictWindowSeq(opts.after_seq, 'after_seq');
+        if (mode !== 'tail' && opts.force !== true && after > client._seqTracker.getContiguousSeq(ns))
+            throw new ValidationError('after_seq cannot exceed the peer delivery cursor');
+        let volatileCursor = String(opts.after_volatile_cursor ?? client._delivery.peerVolatilePullCursor(senderAid));
+        const decoded = [];
+        let complete = false;
+        let head = after;
+        let tailVolatileHasMore;
+        let tailServerAck = null;
+        let pages = 0;
+        let durableAck = 0;
+        let initializedAck = false;
+        let confirmedAck = 0;
+        const confirmAck = (seq) => {
+            confirmedAck = Math.max(confirmedAck, Math.min(seq, durableAck));
+            this.clearForwardAck(ns, confirmedAck);
+        };
+        const prefetched = [];
+        const stopping = new AbortController();
+        const canPull = () => !opts.background || client._delivery.hasP2pApplicationSubscription();
+        const validatePage = (response, requestAfter, committedAck, preparing = false) => {
+            this.ensureDeliveryCurrent(ns, generation, inlineGeneration);
+            this.validatePeerResponse(response, senderAid);
+            const rows = Array.isArray(response.messages) ? response.messages : null;
+            if (!rows || rows.length > limit)
+                throw new ValidationError('invalid peer messages page');
+            const persistent = rows.filter((row) => row.storage !== 'volatile');
+            const volatile = rows.filter((row) => row.storage === 'volatile');
+            const end = strictWindowSeq(response.covered_through_seq, 'covered_through_seq');
+            const pageHead = strictWindowSeq(response.head_seq, 'head_seq');
+            let start;
+            if (mode === 'tail') {
+                if (response.window_mode !== 'tail')
+                    throw new ValidationError('peer Tail response mode mismatch');
+                start = strictWindowSeq(response.window_start_seq, 'window_start_seq');
+                if (volatile.length > 0 || start > end || end !== pageHead || (pageHead <= requestAfter
+                    ? start !== pageHead || persistent.length > 0
+                    : start <= requestAfter))
+                    throw new ValidationError('invalid peer Tail proof');
+                if (response.volatile_has_more !== undefined && typeof response.volatile_has_more !== 'boolean')
+                    throw new ValidationError('invalid peer Tail volatile proof');
+            }
+            else {
+                start = strictWindowSeq(response.scan_after_seq, 'scan_after_seq');
+                const retention = safeNonNegativeSeq(response.retention_floor_seq) ?? 0;
+                if (start < requestAfter || (!preparing && start > Math.max(requestAfter, retention, opts.force === true ? 0 : committedAck))
+                    || end < start || end > pageHead || response.next_after_seq !== end)
+                    throw new ValidationError('invalid peer Forward proof');
+                if (typeof response.persistent_has_more !== 'boolean' || typeof response.volatile_has_more !== 'boolean'
+                    || response.has_more !== (response.persistent_has_more || response.volatile_has_more)
+                    || (!response.persistent_has_more && end < pageHead))
+                    throw new ValidationError('invalid peer continuation proof');
+            }
+            let previous = mode === 'tail' ? start - 1 : start;
+            for (const row of persistent) {
+                const seq = strictWindowSeq(row.seq, 'messages[].seq', true);
+                if (seq <= previous || seq > end || String(row.sender_aid ?? row.from_aid ?? row.from ?? '') !== senderAid)
+                    throw new ValidationError('peer message is outside proof or sender');
+                previous = seq;
+            }
+            if (mode === 'forward' && opts.force !== true) {
+                const serverAck = safeNonNegativeSeq(response.server_ack_seq);
+                if (serverAck !== null)
+                    client._delivery.observePeerServerAck(ns, serverAck);
+                confirmAck(serverAck ?? 0);
+            }
+            return { persistent, volatile, end, pageHead, start };
+        };
+        const decodeRows = async (rows) => {
+            const prepared = { messages: [], effects: [] };
+            try {
+                for (const row of rows) {
+                    if (stopping.signal.aborted)
+                        throw new StateError('pull invalidated');
+                    const plaintext = await this.decodeP2PWindowMessage(row, false, false, source, false, prepared.effects);
+                    this.ensureDeliveryCurrent(ns, generation, inlineGeneration);
+                    if (!plaintext)
+                        throw new E2EEError('peer message could not be decrypted');
+                    plaintext.sender_aid = senderAid;
+                    plaintext.need_render = typeof row.need_render === 'boolean' ? row.need_render : plaintext.need_render !== false;
+                    prepared.messages.push(plaintext);
+                }
+            }
+            catch (error) {
+                prepared.error = error;
+            }
+            return prepared;
+        };
+        const fetchPage = async (requestAfter, requestCursor) => {
+            const key = `${ns}|mode=${mode}|after=${requestAfter}|volatile=${requestCursor}|force=${Boolean(opts.force)}|limit=${limit}`;
+            const request = (cursor) => {
+                const operation = async () => {
+                    if (!canPull()) {
+                        reservation?.release();
+                        return null;
+                    }
+                    return { response: await client._callRawV2Rpc('message.v2.pull', {
+                            cursor_scope: 'peer', sender_aid: senderAid, device_id: client._deviceId, slot_id: client._slotId,
+                            after_seq: requestAfter, limit,
+                            ...(mode === 'forward' && opts.force !== true && durableAck > 0 ? { ack_up_to_seq: durableAck } : {}),
+                            ...(mode === 'tail' ? { window_mode: 'tail' } : {}),
+                            ...(opts.force === true ? { force: true } : {}),
+                            ...(cursor ? { after_volatile_cursor: cursor } : {}),
+                            ...(opts.background ? { _rpc_background: true } : { _rpc_foreground: true }),
+                        }, key), reservation };
+                };
+                const schedule = (attempt) => client._runPullSerialized(key, attempt, Boolean(opts.background));
+                return client._delivery.runPeerPullAttempt?.(ns, operation, schedule) ?? schedule(operation);
+            };
+            const reservation = await client._dispatcher?._reserveMessageCapacity?.(limit, stopping.signal);
+            try {
+                if (stopping.signal.aborted)
+                    throw new StateError('pull invalidated');
+                try {
+                    return await request(requestCursor);
+                }
+                catch (error) {
+                    this.ensureDeliveryCurrent(ns, generation, inlineGeneration);
+                    if (!requestCursor || !String(error instanceof Error ? error.message : error).toLowerCase().includes('volatile cursor epoch mismatch'))
+                        throw error;
+                    client._delivery.setPeerVolatilePullCursor(senderAid, '');
+                    return await request('');
+                }
+            }
+            catch (error) {
+                reservation?.release();
+                throw error;
+            }
+        };
+        const prefetchPage = (requestAfter, cursor) => {
+            const existing = prefetched.find((page) => page.after === requestAfter && page.cursor === cursor);
+            if (existing)
+                return existing;
+            if (prefetched.length >= 2 || budget.remaining <= 0 || stopping.signal.aborted || !canPull())
+                return undefined;
+            budget.remaining -= 1;
+            const page = { after: requestAfter, cursor, response: fetchPage(requestAfter, cursor) };
+            void page.response.catch(() => undefined);
+            prefetched.push(page);
+            return page;
+        };
+        const preparePage = (page) => {
+            if (page.prepared)
+                return;
+            page.prepared = page.response.then(async (fetched) => {
+                if (!fetched)
+                    return null;
+                try {
+                    const proof = validatePage(fetched.response, page.after, durableAck, true);
+                    const handlers = client._delivery.snapshotApplicationHandlers?.();
+                    if (proof.volatile.length === 0 && proof.end > page.after && fetched.response.persistent_has_more === true) {
+                        prefetchPage(proof.end, page.cursor);
+                    }
+                    return { ...fetched, handlers, prepared: await decodeRows(proof.persistent) };
+                }
+                catch (error) {
+                    fetched.reservation?.release();
+                    throw error;
+                }
+            });
+            void page.prepared.catch(() => undefined);
+        };
+        client._delivery.syncStarted(ns);
+        let failed = false;
+        try {
+            while (budget.remaining > 0 || prefetched.length > 0) {
+                if (prefetched.length === 0 && !canPull())
+                    break;
+                const cached = prefetched.shift();
+                if (!cached)
+                    budget.remaining -= 1;
+                pages += 1;
+                let requestedAfter = cached ? cached.after : after;
+                const requestedVolatile = cached ? cached.cursor : volatileCursor;
+                const page = await client._delivery.runPeerPageSerialized(ns, async () => {
+                    const committedAck = client._delivery.peerCommittedAck(ns);
+                    if (!initializedAck) {
+                        durableAck = committedAck;
+                        initializedAck = true;
+                    }
+                    if (!cached && mode === 'tail' && opts.autoTail
+                        && !client._delivery.shouldTailPeer(ns, opts.autoTail.head, limit, opts.autoTail.forwardNeed)) {
+                        mode = 'forward';
+                        source = 'pull';
+                        opts.autoTail.forward = true;
+                    }
+                    if (!cached && mode === 'forward' && opts.force !== true)
+                        requestedAfter = Math.max(requestedAfter, committedAck);
+                    if (!cached)
+                        this.ensureDeliveryCurrent(ns, generation, inlineGeneration);
+                    const fetched = await (cached ? cached.prepared ?? cached.response : fetchPage(requestedAfter, requestedVolatile));
+                    if (!fetched)
+                        return null;
+                    const { response, reservation } = fetched;
+                    try {
+                        this.ensureDeliveryCurrent(ns, generation, inlineGeneration);
+                        const { persistent, volatile, end, pageHead, start } = validatePage(response, requestedAfter, committedAck);
+                        const handlers = fetched.handlers ?? client._delivery.snapshotApplicationHandlers?.();
+                        if (mode === 'forward' && opts.force !== true && volatile.length === 0 && end > requestedAfter
+                            && (response.persistent_has_more === true || response.has_more === true)) {
+                            const pending = prefetchPage(end, requestedVolatile);
+                            if (pending)
+                                preparePage(pending);
+                        }
+                        const messages = [];
+                        const prepared = fetched.prepared ?? await decodeRows(persistent);
+                        this.ensureDeliveryCurrent(ns, generation, inlineGeneration);
+                        for (const effect of prepared.effects)
+                            effect();
+                        if ('error' in prepared)
+                            throw prepared.error;
+                        await this.withApplicationPage(ns, source, async () => {
+                            for (let index = 0; index < persistent.length; index += 1) {
+                                const row = persistent[index], plaintext = prepared.messages[index];
+                                const event = client._delivery.p2pAppEventForMessage(plaintext);
+                                await client._delivery.publishPulledMessage(event.event, ns, row.seq, event.payload, false, source);
+                                this.ensureDeliveryCurrent(ns, generation, inlineGeneration);
+                                messages.push(plaintext);
+                            }
+                            if (volatile.length > 0) {
+                                for (const row of volatile)
+                                    if (String(row.sender_aid ?? row.from_aid ?? row.from ?? '') !== senderAid)
+                                        throw new ValidationError('volatile peer sender mismatch');
+                                messages.push(...await this.publishV2VolatileMessages(volatile, source, true));
+                                this.ensureDeliveryCurrent(ns, generation, inlineGeneration);
+                            }
+                        }, reservation, handlers);
+                        this.ensureDeliveryCurrent(ns, generation, inlineGeneration);
+                        if (!volatile.every((row) => client._delivery.isVolatileSeen(row)))
+                            throw new E2EEError('volatile peer delivery remains pending');
+                        const before = client._seqTracker.snapshotNamespace(ns);
+                        try {
+                            if (mode === 'tail') {
+                                if (pageHead > requestedAfter)
+                                    client._seqTracker.commitTailWindow(ns, { windowStartSeq: start, headSeq: pageHead, coveredThroughSeq: end, pageLimit: limit, sparse: true });
+                            }
+                            else if (opts.force !== true) {
+                                client._seqTracker.onPullResult(ns, persistent, requestedAfter, end);
+                            }
+                            if (opts.force !== true) {
+                                await client._commitSeqTrackerState(ns);
+                                durableAck = Math.max(durableAck, client._seqTracker.getContiguousSeq(ns));
+                            }
+                            this.ensureDeliveryCurrent(ns, generation, inlineGeneration);
+                        }
+                        catch (error) {
+                            if (Number(client._v2RuntimeGeneration ?? 0) === generation
+                                && (inlineGeneration === undefined || client._delivery.captureInlineAckGeneration() === inlineGeneration)
+                                && client._rpcPipeline?.isPullNamespaceCurrent?.(ns) !== false)
+                                client._seqTracker._restoreNamespaceSnapshotPreservingPush(ns, before);
+                            throw error;
+                        }
+                        const ack = client._seqTracker.getContiguousSeq(ns);
+                        if (mode === 'forward' && opts.force !== true) {
+                            this.ensureDeliveryCurrent(ns, generation, inlineGeneration);
+                            const next = safeNonNegativeSeq(response.next_pending_seq);
+                            client._delivery.consumePeerPullHint(ns, end, response.persistent_has_more === true && next !== null && next > end && next <= pageHead ? next : undefined);
+                            confirmAck(Math.max(confirmedAck, safeNonNegativeSeq(response.server_ack_seq) ?? 0));
+                            if (ack > confirmedAck)
+                                this.recordForwardAck(ns, ack);
+                        }
+                        return { response, messages, end, head: pageHead };
+                    }
+                    finally {
+                        reservation?.release();
+                    }
+                });
+                if (!page)
+                    break;
+                this.ensureDeliveryCurrent(ns, generation, inlineGeneration);
+                if (opts.retainMessages !== false)
+                    decoded.push(...page.messages);
+                head = page.head;
+                if (mode === 'tail') {
+                    tailVolatileHasMore = page.response.volatile_has_more;
+                    tailServerAck = safeNonNegativeSeq(page.response.server_ack_seq);
+                    if (tailServerAck !== null)
+                        client._delivery.observePeerServerAck(ns, tailServerAck);
+                }
+                volatileCursor = client._delivery.peerVolatilePullCursor(senderAid);
+                const more = page.response.persistent_has_more === true || page.response.volatile_has_more === true || page.response.has_more === true;
+                complete = !more;
+                client._delivery.syncProgress(ns, { rawCount: page.response.messages.length, pulledCount: page.messages.length, hasMore: more,
+                    currentSeq: client._seqTracker.getContiguousSeq(ns), targetSeq: head });
+                after = page.end;
+                if (mode === 'tail' || complete || (after <= requestedAfter && volatileCursor === requestedVolatile))
+                    break;
+            }
+        }
+        catch (error) {
+            failed = true;
+            throw error;
+        }
+        finally {
+            stopping.abort();
+            for (const pending of prefetched) {
+                try {
+                    (await (pending.prepared ?? pending.response))?.reservation?.release();
+                }
+                catch { }
+            }
+            if (mode === 'forward' && opts.force !== true) {
+                try {
+                    this.ensureDeliveryCurrent(ns, generation, inlineGeneration);
+                    const pending = this.pendingForwardAck(ns, durableAck);
+                    if (pending > 0) {
+                        await this.ackPeerV2(senderAid, pending);
+                        this.ensureDeliveryCurrent(ns, generation, inlineGeneration);
+                        confirmAck(pending);
+                    }
+                }
+                catch (error) {
+                    if (!failed)
+                        throw error;
+                }
+            }
+        }
+        const ack = client._seqTracker.getContiguousSeq(ns);
+        if (mode === 'tail')
+            complete = ack >= head && durableAck >= head && tailVolatileHasMore === false
+                && tailServerAck !== null && tailServerAck >= durableAck && this.pendingForwardAck(ns, durableAck) === 0;
+        if (opts.force !== true && complete)
+            complete = client._delivery.isPeerTailCurrent(senderAid, pullVersion, Math.min(ack, durableAck));
+        if (!opts.background && opts.force !== true && !complete)
+            client._delivery.schedulePeerRecovery(senderAid, head, true);
+        return { sender_aid: senderAid, messages: decoded, complete,
+            ack_seq: ack, head_seq: head, pages,
+            ...(mode === 'tail' ? { ...(tailVolatileHasMore === undefined ? {} : { volatile_has_more: tailVolatileHasMore }),
+                ...(tailServerAck === null ? {} : { server_ack_seq: tailServerAck }), pending_ack_seq: this.pendingForwardAck(ns, durableAck) } : {}) };
+    }
+    validatePeerResponse(response, senderAid) {
+        const client = this.client;
+        if (!response || response.cursor_scope !== 'peer' || response.sender_aid !== senderAid
+            || (response.device_id !== undefined && response.device_id !== client._deviceId)
+            || (response.slot_id !== undefined && response.slot_id !== client._slotId))
+            throw new ValidationError('peer response scope mismatch');
+    }
+    async ackPeerV2(senderAid, upToSeq, volatileCursors = [], volatileIds = []) {
+        const client = this.client;
+        const generation = Number(client._v2RuntimeGeneration ?? 0);
+        const inlineGeneration = client._delivery.captureInlineAckGeneration?.();
+        const ns = await client._delivery.initializePeer(senderAid);
+        this.ensureDeliveryCurrent(ns, generation, inlineGeneration);
+        const localAck = client._delivery.peerCommittedAck(ns);
+        const requested = upToSeq === undefined ? (volatileCursors.length || volatileIds.length ? 0 : localAck) : strictWindowSeq(upToSeq, 'up_to_seq');
+        const seq = Math.min(requested, localAck);
+        if (!seq && !volatileCursors.length && !volatileIds.length)
+            return { cursor_scope: 'peer', sender_aid: senderAid, peer_ack_seq: 0 };
+        const result = await client._callRawV2Rpc('message.v2.ack', { cursor_scope: 'peer', sender_aid: senderAid,
+            device_id: client._deviceId, slot_id: client._slotId,
+            ...(seq ? { up_to_seq: seq } : {}), ...(volatileCursors.length ? { volatile_cursors: volatileCursors } : {}),
+            ...(volatileIds.length ? { volatile_ids: volatileIds } : {}), _rpc_background: true });
+        this.ensureDeliveryCurrent(ns, generation, inlineGeneration);
+        this.validatePeerResponse(result, senderAid);
+        const actual = safeNonNegativeSeq(result.peer_ack_seq ?? result.effective_ack_seq ?? result.up_to_seq);
+        if (seq > 0 && (actual === null || actual < seq))
+            throw new E2EEError('peer ACK watermark is below requested');
+        if (actual !== null)
+            client._delivery.observePeerServerAck(ns, actual);
+        client._delivery.peerAckChanged();
+        return result;
+    }
+    async peerHistoryV2(params) {
+        const sender = String(params.sender_aid ?? '').trim();
+        if (!sender)
+            throw new ValidationError('peer History requires sender_aid');
+        const client = this.client;
+        const ns = await client._delivery.initializePeer(sender);
+        const generation = Number(client._v2RuntimeGeneration ?? 0);
+        const before = strictWindowSeq(params.before_seq, 'before_seq', true);
+        const limit = Number(params.limit ?? _INTERNAL_MESSAGE_FLOW_LIMITS.pullPageSize);
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 200)
+            throw new ValidationError('peer limit must be between 1 and 200');
+        const key = pullGateKeyForClient(client, 'message.history', { ...params, sender_aid: sender, before_seq: before, limit }, `${ns}|history|before=${before}|limit=${limit}`);
+        const result = await client._runPullSerialized(key, () => client._callRawV2Rpc('message.history', { ...params, cursor_scope: 'peer', sender_aid: sender,
+            before_seq: before, limit, device_id: client._deviceId, slot_id: client._slotId, _rpc_foreground: true }, key), false);
+        this.ensureDeliveryCurrent(ns, generation);
+        this.validatePeerResponse(result, sender);
+        const rows = validateHistoryPage(result, before);
+        if (rows.length > limit)
+            throw new ValidationError('peer History exceeds limit');
+        const messages = [];
+        for (const row of rows) {
+            if (String(row.sender_aid ?? row.from_aid ?? row.from ?? '') !== sender)
+                throw new ValidationError('peer History sender mismatch');
+            const plaintext = await this.decodeP2PWindowMessage(row, false, true, 'history');
+            this.ensureDeliveryCurrent(ns, generation);
+            if (plaintext)
+                messages.push({ ...plaintext, need_render: typeof row.need_render === 'boolean' ? row.need_render : plaintext.need_render !== false });
+        }
+        return { ...result, messages };
+    }
     async pullV2TailInternal(params, deferPublish = false) {
         const client = this.client;
         const generation = Number(client._v2RuntimeGeneration ?? 0);
@@ -1278,28 +1721,47 @@ export class V2E2EECoordinator {
         const afterSeq = strictWindowSeq(params.after_seq ?? 0, 'after_seq');
         const limit = strictWindowLimit(params.limit ?? V2_PULL_DEFAULT_PAGE_LIMIT);
         const ns = client._aid ? `p2p:${client._aid}` : '';
+        const volatileCursor = String(params.after_volatile_cursor ?? client._delivery.volatilePullCursor?.(ns) ?? '');
         if (ns)
             client._delivery.syncStarted(ns);
-        const pullGateKey = pullGateKeyForClient(client, 'message.v2.pull', {
-            window_mode: 'tail', after_seq: afterSeq, limit,
-        }, `${ns}|tail|after=${afterSeq}|limit=${limit}`);
-        const result = await client._callRawV2Rpc('message.v2.pull', { window_mode: 'tail', after_seq: afterSeq, limit, _rpc_foreground: true }, pullGateKey);
-        const page = validateTailPage(result, afterSeq, limit);
-        const decoded = [];
-        for (const msg of page.messages) {
+        const request = (cursor) => {
+            const tailParams = { window_mode: 'tail', after_seq: afterSeq, limit,
+                ...(cursor ? { after_volatile_cursor: cursor } : {}) };
+            const pullGateKey = pullGateKeyForClient(client, 'message.v2.pull', tailParams, `${ns}|tail|after=${afterSeq}|limit=${limit}${cursor ? `|volatile=${cursor}` : ''}`);
+            return client._callRawV2Rpc('message.v2.pull', { ...tailParams, _rpc_foreground: true }, pullGateKey);
+        };
+        let result;
+        try {
+            result = await request(volatileCursor);
+        }
+        catch (error) {
             this.ensureDeliveryCurrent(ns, generation);
-            const plaintext = await this.decodeP2PWindowMessage(msg, true, false, 'tail', deferPublish);
-            if (plaintext)
-                decoded.push(plaintext);
+            if (!volatileCursor || !String(error instanceof Error ? error.message : error).toLowerCase().includes('volatile cursor epoch mismatch'))
+                throw error;
+            client._delivery.resetVolatilePullCursor?.();
+            result = await request('');
         }
+        if (Array.isArray(result?.messages) && result.messages.some((row) => row?.storage === 'volatile'))
+            throw new ValidationError('Tail cannot return volatile messages');
+        const page = validateTailPage(result, afterSeq, limit);
+        const decoded = [];
+        await this.withApplicationPage(ns, 'tail', async () => {
+            for (const msg of page.messages) {
+                this.ensureDeliveryCurrent(ns, generation);
+                const plaintext = await this.decodeP2PWindowMessage(msg, true, false, 'tail', deferPublish);
+                if (plaintext)
+                    decoded.push(plaintext);
+            }
+        });
         this.ensureDeliveryCurrent(ns, generation);
         if (ns) {
-            client._seqTracker.commitTailWindow(ns, {
-                windowStartSeq: page.windowStart,
-                headSeq: page.head,
-                coveredThroughSeq: page.head,
-                pageLimit: limit,
-            });
+            if (page.head > afterSeq)
+                client._seqTracker.commitTailWindow(ns, {
+                    windowStartSeq: page.windowStart,
+                    headSeq: page.head,
+                    coveredThroughSeq: page.head,
+                    pageLimit: limit,
+                });
             client._persistSeq(ns);
             await client._saveSeqTrackerState?.();
             this.ensureDeliveryCurrent(ns, generation);
@@ -1522,10 +1984,6 @@ export class V2E2EECoordinator {
                     pipelineRunning = false;
                     pipelineQueue = new V2PullPageQueue(V2_PULL_PIPELINE_QUEUE_CAPACITY);
                 }
-                if (volatileMessages.length > 0) {
-                    decrypted.push(...await this.publishV2VolatileMessages(volatileMessages, 'pull', true));
-                    volatileCursor = String(client._delivery.volatilePullCursor?.() ?? '').trim();
-                }
                 const messages = deduplicateForwardPageMessages(pageMessages, nextAfterSeq);
                 const cursor = isJsonObject(result.cursor) ? result.cursor : null;
                 const hasMoreField = Object.prototype.hasOwnProperty.call(result, 'has_more');
@@ -1556,116 +2014,119 @@ export class V2E2EECoordinator {
                     startPipeline(pageMaxSeq, volatileCursor);
                 const deferredKeyFetches = new Map();
                 let blockedSeq = 0;
-                const pageDecryptedBefore = decrypted.length;
-                for (const msg of messages) {
-                    const seq = Number(msg.seq ?? 0);
-                    if (!Number.isFinite(seq) || seq <= 0)
-                        continue;
-                    const version = String(msg.version ?? 'v2');
-                    if (version === 'v1') {
-                        const legacy = isJsonObject(msg.legacy_v1) ? msg.legacy_v1 : {};
-                        const legacyPayload = legacy.payload !== undefined ? legacy.payload : msg.payload;
-                        const payloadType = isJsonObject(legacyPayload)
-                            ? String(legacyPayload.type ?? '').trim()
-                            : '';
-                        if (legacyPayload !== undefined && legacyPayload !== null
-                            && !['e2ee.encrypted', 'e2ee.group_encrypted', 'e2ee.p2p_encrypted'].includes(payloadType)) {
-                            const v1Msg = {
-                                message_id: String(msg.message_id ?? ''),
-                                from: String(msg.from_aid ?? ''),
-                                to: String(legacy.to ?? client._aid ?? ''),
-                                seq: msg.seq,
-                                type: String(msg.type ?? ''),
-                                timestamp: msg.t_server,
-                                payload: legacyPayload,
-                                encrypted: false,
-                            };
-                            const direction = String(msg.direction ?? '').trim();
-                            if (direction)
-                                v1Msg.direction = direction;
-                            else if (String(msg.from_aid ?? '').trim() && String(msg.from_aid ?? '').trim() !== String(client._aid ?? '').trim()) {
-                                v1Msg.direction = 'inbound';
+                let pageDecryptedBefore = decrypted.length;
+                const hasServerAckSeq = Object.prototype.hasOwnProperty.call(result, 'server_ack_seq');
+                const parsedServerAckSeq = hasServerAckSeq ? safeNonNegativeSeq(result.server_ack_seq) : null;
+                const serverAckSeq = parsedServerAckSeq ?? 0;
+                const retentionFloor = Math.max(0, Number(result.retention_floor_seq ?? 0));
+                let commitTarget = pageContigBefore;
+                await this.withApplicationPage(ns, 'pull', async () => {
+                    if (volatileMessages.length > 0) {
+                        decrypted.push(...await this.publishV2VolatileMessages(volatileMessages, 'pull', true));
+                        pageDecryptedBefore = decrypted.length;
+                    }
+                    for (const msg of messages) {
+                        const seq = Number(msg.seq ?? 0);
+                        if (!Number.isFinite(seq) || seq <= 0)
+                            continue;
+                        const version = String(msg.version ?? 'v2');
+                        if (version === 'v1') {
+                            const legacy = isJsonObject(msg.legacy_v1) ? msg.legacy_v1 : {};
+                            const legacyPayload = legacy.payload !== undefined ? legacy.payload : msg.payload;
+                            const payloadType = isJsonObject(legacyPayload)
+                                ? String(legacyPayload.type ?? '').trim()
+                                : '';
+                            if (legacyPayload !== undefined && legacyPayload !== null
+                                && !['e2ee.encrypted', 'e2ee.group_encrypted', 'e2ee.p2p_encrypted'].includes(payloadType)) {
+                                const v1Msg = {
+                                    message_id: String(msg.message_id ?? ''),
+                                    from: String(msg.from_aid ?? ''),
+                                    to: String(legacy.to ?? client._aid ?? ''),
+                                    seq: msg.seq,
+                                    type: String(msg.type ?? ''),
+                                    timestamp: msg.t_server,
+                                    payload: legacyPayload,
+                                    encrypted: false,
+                                };
+                                const direction = String(msg.direction ?? '').trim();
+                                if (direction)
+                                    v1Msg.direction = direction;
+                                else if (String(msg.from_aid ?? '').trim() && String(msg.from_aid ?? '').trim() !== String(client._aid ?? '').trim()) {
+                                    v1Msg.direction = 'inbound';
+                                }
+                                if (msg.sender_device_id !== undefined)
+                                    v1Msg.sender_device_id = msg.sender_device_id;
+                                attachGatewayProximity(v1Msg, msg);
+                                const appEvent = client._delivery.p2pAppEventForMessage(v1Msg);
+                                if (ns) {
+                                    await client._publishPulledMessage(appEvent.event, ns, seq, appEvent.payload, false);
+                                }
+                                else {
+                                    await client._publishAppEvent(appEvent.event, appEvent.payload, 'pull');
+                                }
+                                decrypted.push(v1Msg);
+                                client._clientLog.debug(`message.v2.pull plaintext V1 delivered: seq=${seq}, ns=${ns || '<none>'}`);
                             }
-                            if (msg.sender_device_id !== undefined)
-                                v1Msg.sender_device_id = msg.sender_device_id;
-                            attachGatewayProximity(v1Msg, msg);
-                            const appEvent = client._delivery.p2pAppEventForMessage(v1Msg);
-                            if (ns) {
-                                await client._publishPulledMessage(appEvent.event, ns, seq, appEvent.payload, false);
+                            else if (isJsonObject(legacyPayload)
+                                && ['e2ee.p2p_encrypted', 'e2ee.encrypted'].includes(payloadType)) {
+                                const deferStatus = {};
+                                const plaintext = await client._decryptV2Message({ ...msg, envelope_json: JSON.stringify(legacyPayload) }, true, true, true, true, deferStatus, true, 'pull');
+                                if (deferStatus.deferred) {
+                                    blockedSeq = blockedSeq > 0 ? Math.min(blockedSeq, seq) : seq;
+                                    if (deferStatus.fromAid) {
+                                        const key = `${deferStatus.fromAid}\u0000${deferStatus.senderDeviceId ?? ''}\u0000${deferStatus.groupId ?? ''}`;
+                                        deferredKeyFetches.set(key, { fromAid: deferStatus.fromAid, senderDeviceId: deferStatus.senderDeviceId ?? '', groupId: deferStatus.groupId ?? '' });
+                                    }
+                                }
+                                if (plaintext) {
+                                    if (ns)
+                                        await client._publishPulledMessage('message.received', ns, seq, plaintext, false);
+                                    else
+                                        await client._publishAppEvent('message.received', plaintext, 'pull');
+                                    decrypted.push(plaintext);
+                                }
                             }
                             else {
-                                await client._publishAppEvent(appEvent.event, appEvent.payload, 'pull');
+                                client._clientLog.debug(`message.v2.pull skipping V1 envelope seq=${seq} payload_type=${payloadType || '<none>'} (V1 E2EE removed)`);
                             }
-                            decrypted.push(v1Msg);
-                            client._clientLog.debug(`message.v2.pull plaintext V1 delivered: seq=${seq}, ns=${ns || '<none>'}`);
+                            continue;
                         }
-                        else if (isJsonObject(legacyPayload)
-                            && ['e2ee.p2p_encrypted', 'e2ee.encrypted'].includes(payloadType)) {
-                            const deferStatus = {};
-                            const plaintext = await client._decryptV2Message({ ...msg, envelope_json: JSON.stringify(legacyPayload) }, true, true, true, true, deferStatus, true, 'pull');
-                            if (deferStatus.deferred) {
-                                blockedSeq = blockedSeq > 0 ? Math.min(blockedSeq, seq) : seq;
-                                if (deferStatus.fromAid) {
-                                    const key = `${deferStatus.fromAid}\u0000${deferStatus.senderDeviceId ?? ''}\u0000${deferStatus.groupId ?? ''}`;
-                                    deferredKeyFetches.set(key, { fromAid: deferStatus.fromAid, senderDeviceId: deferStatus.senderDeviceId ?? '', groupId: deferStatus.groupId ?? '' });
-                                }
-                            }
-                            if (plaintext) {
-                                if (ns)
-                                    await client._publishPulledMessage('message.received', ns, seq, plaintext, false);
-                                else
-                                    await client._publishAppEvent('message.received', plaintext, 'pull');
-                                decrypted.push(plaintext);
-                            }
+                        if (version !== 'v2') {
+                            client._clientLog.debug(`message.v2.pull skipping non-V2 row seq=${seq} version=${String(msg.version ?? '')}`);
+                            continue;
+                        }
+                        const spkId = String(msg.spk_id ?? '');
+                        if (spkId && client._v2Session && !client._v2Session.isCurrentSPK(spkId)) {
+                            client._v2Session.trackOldSPKMaxSeq(spkId, seq);
+                        }
+                        const deferStatus = {};
+                        const plaintext = await client._decryptV2Message(msg, true, true, true, true, deferStatus, true, 'pull');
+                        if (deferStatus.deferred) {
+                            blockedSeq = blockedSeq > 0 ? Math.min(blockedSeq, seq) : seq;
+                        }
+                        if (deferStatus.deferred && deferStatus.fromAid) {
+                            const key = `${deferStatus.fromAid}\u0000${deferStatus.senderDeviceId ?? ''}\u0000${deferStatus.groupId ?? ''}`;
+                            deferredKeyFetches.set(key, {
+                                fromAid: deferStatus.fromAid,
+                                senderDeviceId: deferStatus.senderDeviceId ?? '',
+                                groupId: deferStatus.groupId ?? '',
+                            });
+                        }
+                        if (plaintext === null) {
+                            client._clientLog.debug(`message.v2.pull decrypt returned null: seq=${seq}, ns=${ns || '<none>'}`);
+                            continue;
+                        }
+                        if (ns) {
+                            await client._publishPulledMessage('message.received', ns, seq, plaintext, false);
                         }
                         else {
-                            client._clientLog.debug(`message.v2.pull skipping V1 envelope seq=${seq} payload_type=${payloadType || '<none>'} (V1 E2EE removed)`);
+                            await client._publishAppEvent('message.received', plaintext, 'pull');
                         }
-                        continue;
-                    }
-                    if (version !== 'v2') {
-                        client._clientLog.debug(`message.v2.pull skipping non-V2 row seq=${seq} version=${String(msg.version ?? '')}`);
-                        continue;
-                    }
-                    const spkId = String(msg.spk_id ?? '');
-                    if (spkId && client._v2Session && !client._v2Session.isCurrentSPK(spkId)) {
-                        client._v2Session.trackOldSPKMaxSeq(spkId, seq);
-                    }
-                    const deferStatus = {};
-                    const plaintext = await client._decryptV2Message(msg, true, true, true, true, deferStatus, true, 'pull');
-                    if (deferStatus.deferred) {
-                        blockedSeq = blockedSeq > 0 ? Math.min(blockedSeq, seq) : seq;
-                    }
-                    if (deferStatus.deferred && deferStatus.fromAid) {
-                        const key = `${deferStatus.fromAid}\u0000${deferStatus.senderDeviceId ?? ''}\u0000${deferStatus.groupId ?? ''}`;
-                        deferredKeyFetches.set(key, {
-                            fromAid: deferStatus.fromAid,
-                            senderDeviceId: deferStatus.senderDeviceId ?? '',
-                            groupId: deferStatus.groupId ?? '',
-                        });
-                    }
-                    if (plaintext === null) {
-                        client._clientLog.debug(`message.v2.pull decrypt returned null: seq=${seq}, ns=${ns || '<none>'}`);
-                        continue;
+                        decrypted.push(plaintext);
+                        client._logMessageDebug('decrypt-ok', 'message.v2.pull', 'message.received', plaintext);
                     }
                     if (ns) {
-                        await client._publishPulledMessage('message.received', ns, seq, plaintext, false);
-                    }
-                    else {
-                        await client._publishAppEvent('message.received', plaintext, 'pull');
-                    }
-                    decrypted.push(plaintext);
-                    client._logMessageDebug('decrypt-ok', 'message.v2.pull', 'message.received', plaintext);
-                }
-                const hasServerAckSeq = Object.prototype.hasOwnProperty.call(result, 'server_ack_seq');
-                const parsedServerAckSeq = hasServerAckSeq ? safeNonNegativeSeq(result.server_ack_seq) : null;
-                const serverAckSeq = parsedServerAckSeq ?? 0;
-                const retentionFloor = Math.max(0, Number(result.retention_floor_seq ?? 0));
-                if (ns) {
-                    const commitTarget = Math.max(pageContigBefore, Number.isFinite(retentionFloor) ? retentionFloor : 0, pageCount === 1 ? deferredServerCursor : 0, serverAckSeq, blockedSeq > 0 ? blockedSeq - 1 : pageContiguousSeq);
-                    let ackSeq = pageContigBefore;
-                    let contigAdvanced = false;
-                    try {
+                        commitTarget = Math.max(pageContigBefore, Number.isFinite(retentionFloor) ? retentionFloor : 0, pageCount === 1 ? deferredServerCursor : 0, serverAckSeq, blockedSeq > 0 ? blockedSeq - 1 : pageContiguousSeq);
                         this.ensureDeliveryCurrent(ns, generation);
                         const window = client._seqTracker.getSyncState?.(ns);
                         const deliveryTarget = window && commitTarget >= window.tail - 1
@@ -1674,6 +2135,15 @@ export class V2E2EECoordinator {
                             await client._drainOrderedMessages(ns, undefined, false, false, 'pull', deliveryTarget);
                         }
                         this.ensureDeliveryCurrent(ns, generation);
+                    }
+                });
+                if (volatileMessages.length > 0)
+                    volatileCursor = String(client._delivery.volatilePullCursor?.() ?? '').trim();
+                if (ns) {
+                    let ackSeq = pageContigBefore;
+                    let contigAdvanced = false;
+                    try {
+                        this.ensureDeliveryCurrent(ns, generation);
                         pageTrackerSnapshot = client._seqTracker.snapshotNamespace?.(ns) ?? null;
                         if (commitTarget > pageContigBefore) {
                             trackerMutated = true;
@@ -1824,11 +2294,27 @@ export class V2E2EECoordinator {
         const client = this.client;
         if (!client._v2Session)
             return [];
+        const generation = Number(client._v2RuntimeGeneration ?? 0);
+        const context = JSON.stringify([client._aid, client._deviceId, client._slotId]);
+        const ensureCurrent = () => {
+            if (!client._p2pPeerPullEnabled)
+                return;
+            if (context !== JSON.stringify([client._aid, client._deviceId, client._slotId]))
+                throw new StateError('delivery invalidated');
+            const sender = String(messages[0]?.sender_aid ?? messages[0]?.from_aid ?? messages[0]?.from ?? '').trim();
+            if (sender)
+                this.ensureDeliveryCurrent(client._delivery.peerNamespace(sender), generation);
+        };
         const processed = [];
         const plaintextMessages = [];
         let complete = true;
         for (const rawMessage of messages) {
-            const claim = client._delivery.beginVolatileDelivery(rawMessage);
+            let claim = client._delivery.beginVolatileDelivery(rawMessage);
+            if (claim === 'inflight' && typeof client._delivery.waitVolatileDelivery === 'function') {
+                await client._delivery.waitVolatileDelivery(rawMessage);
+                ensureCurrent();
+                claim = client._delivery.beginVolatileDelivery(rawMessage);
+            }
             if (claim === 'seen') {
                 processed.push(rawMessage);
                 continue;
@@ -1867,13 +2353,16 @@ export class V2E2EECoordinator {
                     complete = false;
                     continue;
                 }
+                ensureCurrent();
                 const publicMessage = client._delivery.publicVolatileMessage(plaintext);
                 for (const key of ['storage', 'volatile_cursor', 'created_at', 'expires_at', 'persist']) {
                     if (Object.prototype.hasOwnProperty.call(rawMessage, key))
                         publicMessage[key] = rawMessage[key];
                 }
+                publicMessage.need_render = typeof rawMessage.need_render === 'boolean' ? rawMessage.need_render : publicMessage.need_render !== false;
                 const appEvent = client._delivery.p2pAppEventForMessage(publicMessage);
                 await client._publishAppEvent(appEvent.event, appEvent.payload, source);
+                ensureCurrent();
                 client._delivery.markVolatileSeen(rawMessage);
                 processed.push(rawMessage);
                 plaintextMessages.push(publicMessage);
@@ -1883,6 +2372,7 @@ export class V2E2EECoordinator {
             }
         }
         if (processed.length > 0) {
+            ensureCurrent();
             await client._delivery.ackVolatileMessages(processed, true, advanceCursor && complete && processed.length === messages.length);
         }
         return plaintextMessages;
@@ -1997,6 +2487,7 @@ export class V2E2EECoordinator {
                 timestamp: opts?.timestamp,
                 protectedHeaders: opts?.protectedHeaders,
                 context: opts?.context,
+                needRender: opts?.needRender,
                 useCache,
             });
             const result = await client.call('group.v2.send', withExplicitGroupAid({
@@ -2013,6 +2504,7 @@ export class V2E2EECoordinator {
                 payload,
                 message_id: messageId,
                 timestamp: opts?.timestamp,
+                need_render: opts?.needRender ?? true,
                 protected_headers: opts?.protectedHeaders,
                 context: opts?.context,
             }, groupAid), result, true);
@@ -2028,6 +2520,7 @@ export class V2E2EECoordinator {
                     payload,
                     message_id: messageId,
                     timestamp: opts?.timestamp,
+                    need_render: opts?.needRender ?? true,
                     protected_headers: opts?.protectedHeaders,
                     context: opts?.context,
                 }, groupAid), result, true);
@@ -2152,6 +2645,7 @@ export class V2E2EECoordinator {
             timestamp: opts.timestamp,
             protectedHeaders: opts.protectedHeaders,
             context: opts.context,
+            needRender: opts.needRender,
         }, stateCommitment);
         client._logMessageDebug('send-envelope', 'group.send.v2', 'group.send', {
             group_id: groupId,
@@ -2173,7 +2667,7 @@ export class V2E2EECoordinator {
         });
         return envelope;
     }
-    async pullGroupV2TailInternal(params, deferPublish = false) {
+    async pullGroupV2TailInternal(params, deferPublish = false, namespaceLocked = false) {
         const client = this.client;
         const generation = Number(client._v2RuntimeGeneration ?? 0);
         if (params.window_mode !== 'tail')
@@ -2187,6 +2681,7 @@ export class V2E2EECoordinator {
         const afterSeq = strictWindowSeq(params.after_seq ?? 0, 'after_seq');
         const limit = strictWindowLimit(params.limit ?? V2_PULL_DEFAULT_PAGE_LIMIT);
         const ns = `group:${groupId}`;
+        const namespaceGeneration = client._delivery.captureSeqNamespaceGeneration?.(ns);
         const explicitCursorParams = isJsonObject(params._group_cursor_params)
             ? params._group_cursor_params : {};
         const cursorParams = Object.keys(explicitCursorParams).length > 0 ? explicitCursorParams : params;
@@ -2203,35 +2698,56 @@ export class V2E2EECoordinator {
             limit,
             _group_cursor_params: explicitCursorParams,
         }, `${ns}|tail|after=${afterSeq}|limit=${limit}`);
-        const result = await client._callRawV2Rpc('group.v2.pull', withExplicitGroupAid({
+        if (!namespaceLocked)
+            return await client._rpcPipeline.runPullNamespaceSerialized(pullGateKey, () => this.pullGroupV2TailInternal(params, deferPublish, true), false);
+        const result = await client._runPullSerialized(pullGateKey, () => client._callRawV2Rpc('group.v2.pull', withExplicitGroupAid({
             group_id: groupId,
             window_mode: 'tail',
             after_seq: afterSeq,
             limit,
             _group_cursor_params: explicitCursorParams,
             _rpc_foreground: true,
-        }, groupAid), pullGateKey);
+        }, groupAid), pullGateKey), false);
         const resultAid = String(result.group_aid ?? result.groupAid ?? '').trim();
         if (resultAid)
             groupAid = resultAid;
         const page = validateTailPage(result, afterSeq, limit);
         const decoded = [];
-        for (const msg of page.messages) {
-            this.ensureDeliveryCurrent(ns, generation);
-            client._logMessageDebug('tail-raw', 'group.v2.pull', 'group.message_created', msg);
-            const plaintext = await this.decodeGroupWindowMessage(msg, groupId, groupAid, true, false, 'tail', deferPublish);
-            if (plaintext)
-                decoded.push(plaintext);
-        }
-        this.ensureDeliveryCurrent(ns, generation);
-        client._seqTracker.commitTailWindow(ns, {
-            windowStartSeq: page.windowStart,
-            headSeq: page.head,
-            coveredThroughSeq: page.head,
-            pageLimit: limit,
+        await this.withApplicationPage(ns, 'tail', async () => {
+            for (const msg of page.messages) {
+                this.ensureDeliveryCurrent(ns, generation);
+                client._logMessageDebug('tail-raw', 'group.v2.pull', 'group.message_created', msg);
+                const plaintext = await this.decodeGroupWindowMessage(msg, groupId, groupAid, true, false, 'tail', deferPublish);
+                if (plaintext)
+                    decoded.push(plaintext);
+            }
         });
-        client._persistSeq(ns);
-        await client._saveSeqTrackerState?.();
+        this.ensureDeliveryCurrent(ns, generation);
+        if (client._delivery.isSeqNamespaceGenerationCurrent?.(ns, namespaceGeneration) === false)
+            throw new Error('pull invalidated');
+        client._delivery.rememberCommittedSeqState?.(ns);
+        const snapshot = client._seqTracker.snapshotNamespace?.(ns) ?? null;
+        try {
+            if (page.head > afterSeq)
+                client._seqTracker.commitTailWindow(ns, {
+                    windowStartSeq: page.windowStart,
+                    headSeq: page.head,
+                    coveredThroughSeq: page.head,
+                    pageLimit: limit,
+                });
+            await client._commitSeqTrackerState(ns);
+            if (client._delivery.isSeqNamespaceGenerationCurrent?.(ns, namespaceGeneration) === false)
+                throw new Error('pull invalidated');
+        }
+        catch (error) {
+            if (Number(client._v2RuntimeGeneration ?? 0) === generation
+                && client._delivery.isSeqNamespaceGenerationCurrent?.(ns, namespaceGeneration) !== false
+                && client._rpcPipeline?.isPullNamespaceCurrent?.(ns) !== false) {
+                (client._seqTracker._restoreNamespaceSnapshotPreservingPush ?? client._seqTracker.restoreNamespaceSnapshot)
+                    .call(client._seqTracker, ns, snapshot);
+            }
+            throw error;
+        }
         this.ensureDeliveryCurrent(ns, generation);
         const ack = client._seqTracker.getContiguousSeq(ns);
         if (ownsCursor)
@@ -2253,12 +2769,13 @@ export class V2E2EECoordinator {
         let groupAid = String(params.group_aid ?? '').trim();
         const beforeSeq = strictWindowSeq(params.before_seq, 'before_seq', true);
         const limit = strictWindowLimit(params.limit ?? V2_PULL_DEFAULT_PAGE_LIMIT);
-        const result = await client._callRawV2Rpc('group.history', withExplicitGroupAid({
+        const key = pullGateKeyForClient(client, 'group.history', { group_id: groupId, before_seq: beforeSeq, limit }, `group:${groupId}|history|before=${beforeSeq}|limit=${limit}`);
+        const result = await client._runPullSerialized(key, () => client._callRawV2Rpc('group.history', withExplicitGroupAid({
             group_id: groupId,
             before_seq: beforeSeq,
             limit,
             _rpc_foreground: true,
-        }, groupAid));
+        }, groupAid), key), false);
         const resultAid = String(result.group_aid ?? result.groupAid ?? '').trim();
         if (resultAid)
             groupAid = resultAid;
@@ -2295,7 +2812,7 @@ export class V2E2EECoordinator {
                     group_id: gid, window_mode: 'tail', after_seq: afterSeq, limit,
                     _group_cursor_params: opts?.cursorParams,
                 }, `${ns}|tail|after=${afterSeq}|limit=${limit}`);
-                return (await client._runPullSerialized(key, () => this.pullGroupV2Impl(gid, afterSeq, limit, {
+                return (await client._rpcPipeline.runPullNamespaceSerialized(key, () => this.pullGroupV2Impl(gid, afterSeq, limit, {
                     ...opts,
                     gateLocked: true,
                 }), false));
@@ -2308,7 +2825,7 @@ export class V2E2EECoordinator {
                 window_mode: 'tail',
                 after_seq: afterSeq,
                 limit,
-            });
+            }, false, true);
             return (Array.isArray(result.messages) ? result.messages : []);
         }
         if (!opts?.gateLocked) {
@@ -2316,20 +2833,17 @@ export class V2E2EECoordinator {
                 group_id: gid, after_seq: afterSeq, force: opts?.force === true, limit,
                 _group_cursor_params: opts?.cursorParams,
             }, `${ns}|forward|after=${afterSeq}|force=${opts?.force === true}|limit=${limit}`);
-            return await client._runPullSerialized(key, async () => this.pullGroupV2Impl(gid, afterSeq, limit, {
+            return await client._rpcPipeline.runPullNamespaceSerialized(key, async () => this.pullGroupV2Impl(gid, afterSeq, limit, {
                 ...(opts ?? {}),
                 gateLocked: true,
                 scheduleFollowup: true,
-            }), true);
+            }), opts?.background !== false);
         }
         const decrypted = [];
         const wireGroupId = String(opts?.wireGroupId ?? groupId ?? '').trim() || gid;
         const cursorParams = opts?.cursorParams ?? {};
         const ownsCursor = opts?.ownsCursor !== false;
-        let pullGateKey = pullGateKeyForClient(client, 'group.v2.pull', {
-            group_id: gid, after_seq: afterSeq, force: opts?.force === true, limit,
-            _group_cursor_params: cursorParams,
-        }, `${ns}|forward|after=${afterSeq}|force=${String(Boolean(opts?.force))}|limit=${limit}`);
+        const background = opts?.background !== false;
         let nextAfterSeq = (opts?.explicitAfterSeq || opts?.force)
             ? afterSeq
             : (afterSeq || client._seqTracker.getContiguousSeq(ns));
@@ -2340,6 +2854,21 @@ export class V2E2EECoordinator {
         let pageCount = 0;
         let lastAutoAckSeq = 0;
         let pendingAckSeq = deferredForwardAck;
+        let committedAckSeq = ownsCursor ? client._seqTracker.getContiguousSeq(ns) : 0;
+        const fetchPage = async (after, ack) => {
+            const key = pullGateKeyForClient(client, 'group.v2.pull', {
+                group_id: gid, after_seq: after, force: opts?.force === true, limit, _group_cursor_params: cursorParams,
+            }, `${ns}|forward|after=${after}|force=${String(Boolean(opts?.force))}|limit=${limit}`);
+            return await client._runPullSerialized(key, async () => {
+                this.ensureDeliveryCurrent(ns, generation);
+                return await client._callRawV2Rpc('group.v2.pull', withExplicitGroupAid({
+                    group_id: wireGroupId, after_seq: after, limit, ...cursorParams,
+                    ...(opts?.force ? { force: true } : {}),
+                    ...(ack > 0 ? { ack_up_to_seq: Math.min(ack, committedAckSeq) } : {}),
+                    _rpc_background: background, _rpc_foreground: !background,
+                }, groupAid), key);
+            }, background);
+        };
         const maxPages = Math.max(1, Math.min(100, Math.trunc(Number(opts?.maxPages ?? 100) || 100)));
         let pipelineRunning = false;
         let pipelineError = null;
@@ -2356,16 +2885,9 @@ export class V2E2EECoordinator {
                     if (pipelineStopped)
                         break;
                     this.ensureDeliveryCurrent(ns, generation);
-                    const ackUpToSeq = pendingAckSeq;
+                    const ackUpToSeq = Math.min(pendingAckSeq, committedAckSeq);
                     const inlineAckGeneration = ackUpToSeq > 0 ? client._delivery.captureGroupInlineAckGeneration() : null;
-                    const result = await client._callRawV2Rpc('group.v2.pull', withExplicitGroupAid({
-                        group_id: wireGroupId,
-                        after_seq: producerAfterSeq,
-                        limit,
-                        ...cursorParams,
-                        ...(opts?.force ? { force: true } : {}),
-                        ...(ackUpToSeq > 0 ? { ack_up_to_seq: ackUpToSeq } : {}),
-                    }, groupAid), pullGateKey);
+                    const result = await fetchPage(producerAfterSeq, ackUpToSeq);
                     if (pipelineStopped)
                         break;
                     this.ensureDeliveryCurrent(ns, generation);
@@ -2442,14 +2964,7 @@ export class V2E2EECoordinator {
                     result = pipelinePage.result;
                 }
                 else {
-                    result = await client._callRawV2Rpc('group.v2.pull', withExplicitGroupAid({
-                        group_id: wireGroupId,
-                        after_seq: nextAfterSeq,
-                        limit,
-                        ...cursorParams,
-                        ...(opts?.force ? { force: true } : {}),
-                        ...(ackUpToSeq > 0 ? { ack_up_to_seq: ackUpToSeq } : {}),
-                    }, groupAid), pullGateKey);
+                    result = await fetchPage(nextAfterSeq, ackUpToSeq);
                 }
                 if (ownsCursor)
                     this.ensureDeliveryCurrent(ns, generation);
@@ -2486,6 +3001,7 @@ export class V2E2EECoordinator {
                     .map((msg) => Number(msg.seq ?? 0))
                     .filter((seq) => Number.isFinite(seq) && seq > 0);
                 const pageContigBefore = client._seqTracker.getContiguousSeq(ns);
+                const namespaceGeneration = client._delivery.captureSeqNamespaceGeneration?.(ns);
                 let pageTrackerSnapshot = null;
                 let trackerMutated = false;
                 let pageMaxSeq = nextAfterSeq;
@@ -2503,30 +3019,66 @@ export class V2E2EECoordinator {
                 const deferredKeyFetches = new Map();
                 let blockedSeq = 0;
                 const pageDecryptedBefore = decrypted.length;
-                for (const msg of messages) {
-                    const seq = Number(msg.seq ?? 0);
-                    if (!Number.isFinite(seq) || seq <= 0)
-                        continue;
-                    const version = String(msg.version ?? 'v2');
-                    if (version === 'v1') {
-                        const legacy = isJsonObject(msg.legacy_v1) ? msg.legacy_v1 : {};
-                        const payload = msg.payload !== undefined ? msg.payload : legacy.payload;
-                        const payloadObj = isJsonObject(payload) ? payload : null;
-                        const payloadType = payloadObj ? String(payloadObj.type ?? '').trim() : '';
-                        // 群撤回 tombstone（占位 / 通知）：归一化为 group.message_recalled 事件，仍占 seq。
-                        if (typeof client._delivery?.recallEventFromGroupMessage === 'function'
-                            && client._delivery.recallEventFromGroupMessage(msg)) {
-                            await client._delivery.publishGroupRecallTombstone(gid, seq, {
-                                ...msg,
-                                group_id: gid,
-                                group_aid: eventGroupAid,
-                            }, 'pull');
-                            client._markPublishedSeq(ns, seq);
-                            client._clientLog.debug(`group.v2.pull recall tombstone delivered: group=${gid}, seq=${seq}`);
+                const hasServerCursor = cursor !== null && Object.prototype.hasOwnProperty.call(cursor, 'current_seq');
+                const parsedCursorCurrentSeq = hasServerCursor ? safeNonNegativeSeq(cursor?.current_seq) : null;
+                const cursorCurrentSeq = parsedCursorCurrentSeq ?? 0;
+                const retentionFloor = Math.max(client._pullRetentionFloor(result, 'retention_floor_message_seq', 'retention_floor_message_seq'));
+                const visibilityFloor = Math.max(0, Math.max(0, Number(result.earliest_available_message_seq ?? 1) - 1), Number(cursor?.join_seq ?? 0));
+                const effectiveFloor = Math.max(retentionFloor, visibilityFloor);
+                let commitTarget = pageContigBefore;
+                await this.withApplicationPage(ns, 'pull', async () => {
+                    for (const msg of messages) {
+                        const seq = Number(msg.seq ?? 0);
+                        if (!Number.isFinite(seq) || seq <= 0)
                             continue;
-                        }
-                        if (payloadObj) {
-                            if (!['e2ee.encrypted', 'e2ee.group_encrypted', 'e2ee.p2p_encrypted'].includes(payloadType)) {
+                        const version = String(msg.version ?? 'v2');
+                        if (version === 'v1') {
+                            const legacy = isJsonObject(msg.legacy_v1) ? msg.legacy_v1 : {};
+                            const payload = msg.payload !== undefined ? msg.payload : legacy.payload;
+                            const payloadObj = isJsonObject(payload) ? payload : null;
+                            const payloadType = payloadObj ? String(payloadObj.type ?? '').trim() : '';
+                            // 群撤回 tombstone（占位 / 通知）：归一化为 group.message_recalled 事件，仍占 seq。
+                            if (typeof client._delivery?.recallEventFromGroupMessage === 'function'
+                                && client._delivery.recallEventFromGroupMessage(msg)) {
+                                await client._delivery.publishGroupRecallTombstone(gid, seq, {
+                                    ...msg,
+                                    group_id: gid,
+                                    group_aid: eventGroupAid,
+                                }, 'pull');
+                                client._markPublishedSeq(ns, seq);
+                                client._clientLog.debug(`group.v2.pull recall tombstone delivered: group=${gid}, seq=${seq}`);
+                                continue;
+                            }
+                            if (payloadObj) {
+                                if (!['e2ee.encrypted', 'e2ee.group_encrypted', 'e2ee.p2p_encrypted'].includes(payloadType)) {
+                                    let v1Msg = {
+                                        message_id: String(msg.message_id ?? ''),
+                                        from: String(msg.from_aid ?? ''),
+                                        group_id: gid,
+                                        group_aid: eventGroupAid,
+                                        seq: msg.seq,
+                                        type: String(msg.type ?? ''),
+                                        timestamp: msg.t_server,
+                                        payload,
+                                        encrypted: false,
+                                        need_render: msg.need_render !== false,
+                                    };
+                                    if (msg.sender_device_id !== undefined)
+                                        v1Msg.sender_device_id = msg.sender_device_id;
+                                    v1Msg = normalizeGroupMentionMode(v1Msg, msg, msg.envelope_json);
+                                    attachGatewayProximity(v1Msg, msg);
+                                    if (!client._delivery.isSelfSentGroupMessage?.(msg)) {
+                                        await client._publishPulledMessage('group.message_created', ns, seq, v1Msg, false);
+                                    }
+                                    else {
+                                        client._markPublishedSeq(ns, seq);
+                                    }
+                                    decrypted.push(v1Msg);
+                                    client._clientLog.debug(`group.v2.pull plaintext V1 delivered: group=${gid}, seq=${seq}`);
+                                    continue;
+                                }
+                            }
+                            else if (payload !== undefined && payload !== null) {
                                 let v1Msg = {
                                     message_id: String(msg.message_id ?? ''),
                                     from: String(msg.from_aid ?? ''),
@@ -2537,114 +3089,81 @@ export class V2E2EECoordinator {
                                     timestamp: msg.t_server,
                                     payload,
                                     encrypted: false,
+                                    need_render: msg.need_render !== false,
                                 };
                                 if (msg.sender_device_id !== undefined)
                                     v1Msg.sender_device_id = msg.sender_device_id;
                                 v1Msg = normalizeGroupMentionMode(v1Msg, msg, msg.envelope_json);
                                 attachGatewayProximity(v1Msg, msg);
-                                if (!client._delivery.isSelfSentGroupMessage?.(msg)) {
-                                    await client._publishPulledMessage('group.message_created', ns, seq, v1Msg, false);
-                                }
-                                else {
-                                    client._markPublishedSeq(ns, seq);
-                                }
+                                await client._publishPulledMessage('group.message_created', ns, seq, v1Msg, false);
                                 decrypted.push(v1Msg);
                                 client._clientLog.debug(`group.v2.pull plaintext V1 delivered: group=${gid}, seq=${seq}`);
                                 continue;
                             }
-                        }
-                        else if (payload !== undefined && payload !== null) {
-                            let v1Msg = {
-                                message_id: String(msg.message_id ?? ''),
-                                from: String(msg.from_aid ?? ''),
-                                group_id: gid,
-                                group_aid: eventGroupAid,
-                                seq: msg.seq,
-                                type: String(msg.type ?? ''),
-                                timestamp: msg.t_server,
-                                payload,
-                                encrypted: false,
-                            };
-                            if (msg.sender_device_id !== undefined)
-                                v1Msg.sender_device_id = msg.sender_device_id;
-                            v1Msg = normalizeGroupMentionMode(v1Msg, msg, msg.envelope_json);
-                            attachGatewayProximity(v1Msg, msg);
-                            await client._publishPulledMessage('group.message_created', ns, seq, v1Msg, false);
-                            decrypted.push(v1Msg);
-                            client._clientLog.debug(`group.v2.pull plaintext V1 delivered: group=${gid}, seq=${seq}`);
-                            continue;
-                        }
-                        if (payloadObj && ['e2ee.group_encrypted', 'e2ee.p2p_encrypted', 'e2ee.encrypted'].includes(payloadType)) {
-                            const deferStatus = {};
-                            const plaintext = await client._decryptV2Message({ ...msg, envelope_json: JSON.stringify(payloadObj) }, true, true, true, true, deferStatus, true, 'pull');
-                            if (deferStatus.deferred) {
-                                blockedSeq = blockedSeq > 0 ? Math.min(blockedSeq, seq) : seq;
-                                if (deferStatus.fromAid) {
-                                    const key = `${deferStatus.fromAid}\u0000${deferStatus.senderDeviceId ?? ''}\u0000${deferStatus.groupId ?? ''}`;
-                                    deferredKeyFetches.set(key, { fromAid: deferStatus.fromAid, senderDeviceId: deferStatus.senderDeviceId ?? '', groupId: deferStatus.groupId ?? '' });
+                            if (payloadObj && ['e2ee.group_encrypted', 'e2ee.p2p_encrypted', 'e2ee.encrypted'].includes(payloadType)) {
+                                const deferStatus = {};
+                                const plaintext = await client._decryptV2Message({ ...msg, envelope_json: JSON.stringify(payloadObj) }, true, true, true, true, deferStatus, true, 'pull');
+                                if (deferStatus.deferred) {
+                                    blockedSeq = blockedSeq > 0 ? Math.min(blockedSeq, seq) : seq;
+                                    if (deferStatus.fromAid) {
+                                        const key = `${deferStatus.fromAid}\u0000${deferStatus.senderDeviceId ?? ''}\u0000${deferStatus.groupId ?? ''}`;
+                                        deferredKeyFetches.set(key, { fromAid: deferStatus.fromAid, senderDeviceId: deferStatus.senderDeviceId ?? '', groupId: deferStatus.groupId ?? '' });
+                                    }
                                 }
-                            }
-                            if (plaintext) {
-                                plaintext.group_id = gid;
-                                plaintext.group_aid = eventGroupAid;
-                                if (!client._delivery.isSelfSentGroupMessage?.(msg)) {
-                                    await client._publishPulledMessage('group.message_created', ns, seq, plaintext, false);
-                                }
-                                else {
-                                    client._markPublishedSeq(ns, seq);
+                                if (plaintext) {
+                                    plaintext.group_id = gid;
+                                    plaintext.group_aid = eventGroupAid;
+                                    plaintext.need_render = typeof msg.need_render === 'boolean' ? msg.need_render : plaintext.need_render !== false;
+                                    if (!client._delivery.isSelfSentGroupMessage?.(msg)) {
+                                        await client._publishPulledMessage('group.message_created', ns, seq, plaintext, false);
+                                    }
+                                    else {
+                                        client._markPublishedSeq(ns, seq);
+                                    }
+                                    decrypted.push(plaintext);
                                 }
-                                decrypted.push(plaintext);
                             }
+                            else {
+                                client._clientLog.debug(`group.v2.pull skipping V1 envelope group=${gid} seq=${seq} payload_type=${payloadObj ? String(payloadObj.type ?? '') : '<none>'} (V1 E2EE removed)`);
+                            }
+                            continue;
+                        }
+                        if (version !== 'v2') {
+                            client._clientLog.debug(`group.v2.pull skipping non-V2 row group=${gid} seq=${seq} version=${String(msg.version ?? '')}`);
+                            continue;
+                        }
+                        const deferStatus = {};
+                        let plaintext = await client._decryptV2Message(msg, true, true, true, true, deferStatus, true, 'pull');
+                        if (deferStatus.deferred) {
+                            blockedSeq = blockedSeq > 0 ? Math.min(blockedSeq, seq) : seq;
+                        }
+                        if (deferStatus.deferred && deferStatus.fromAid) {
+                            const key = `${deferStatus.fromAid}\u0000${deferStatus.senderDeviceId ?? ''}\u0000${deferStatus.groupId ?? ''}`;
+                            deferredKeyFetches.set(key, {
+                                fromAid: deferStatus.fromAid,
+                                senderDeviceId: deferStatus.senderDeviceId ?? '',
+                                groupId: deferStatus.groupId ?? '',
+                            });
+                        }
+                        if (plaintext === null) {
+                            client._clientLog.debug(`group.v2.pull decrypt returned null: group=${gid}, seq=${seq}`);
+                            continue;
+                        }
+                        plaintext = normalizeGroupMentionMode(plaintext, msg, msg.envelope_json);
+                        plaintext.group_id = gid;
+                        plaintext.group_aid = eventGroupAid;
+                        plaintext.need_render = typeof msg.need_render === 'boolean' ? msg.need_render : plaintext.need_render !== false;
+                        if (!client._delivery.isSelfSentGroupMessage?.(msg)) {
+                            await client._publishPulledMessage('group.message_created', ns, seq, plaintext, false);
                         }
                         else {
-                            client._clientLog.debug(`group.v2.pull skipping V1 envelope group=${gid} seq=${seq} payload_type=${payloadObj ? String(payloadObj.type ?? '') : '<none>'} (V1 E2EE removed)`);
+                            client._markPublishedSeq(ns, seq);
                         }
-                        continue;
-                    }
-                    if (version !== 'v2') {
-                        client._clientLog.debug(`group.v2.pull skipping non-V2 row group=${gid} seq=${seq} version=${String(msg.version ?? '')}`);
-                        continue;
-                    }
-                    const deferStatus = {};
-                    let plaintext = await client._decryptV2Message(msg, true, true, true, true, deferStatus, true, 'pull');
-                    if (deferStatus.deferred) {
-                        blockedSeq = blockedSeq > 0 ? Math.min(blockedSeq, seq) : seq;
-                    }
-                    if (deferStatus.deferred && deferStatus.fromAid) {
-                        const key = `${deferStatus.fromAid}\u0000${deferStatus.senderDeviceId ?? ''}\u0000${deferStatus.groupId ?? ''}`;
-                        deferredKeyFetches.set(key, {
-                            fromAid: deferStatus.fromAid,
-                            senderDeviceId: deferStatus.senderDeviceId ?? '',
-                            groupId: deferStatus.groupId ?? '',
-                        });
-                    }
-                    if (plaintext === null) {
-                        client._clientLog.debug(`group.v2.pull decrypt returned null: group=${gid}, seq=${seq}`);
-                        continue;
-                    }
-                    plaintext = normalizeGroupMentionMode(plaintext, msg, msg.envelope_json);
-                    plaintext.group_id = gid;
-                    plaintext.group_aid = eventGroupAid;
-                    if (!client._delivery.isSelfSentGroupMessage?.(msg)) {
-                        await client._publishPulledMessage('group.message_created', ns, seq, plaintext, false);
+                        decrypted.push(plaintext);
+                        client._logMessageDebug('decrypt-ok', 'group.v2.pull', 'group.message_created', plaintext);
                     }
-                    else {
-                        client._markPublishedSeq(ns, seq);
-                    }
-                    decrypted.push(plaintext);
-                    client._logMessageDebug('decrypt-ok', 'group.v2.pull', 'group.message_created', plaintext);
-                }
-                const hasServerCursor = cursor !== null && Object.prototype.hasOwnProperty.call(cursor, 'current_seq');
-                const parsedCursorCurrentSeq = hasServerCursor ? safeNonNegativeSeq(cursor?.current_seq) : null;
-                const cursorCurrentSeq = parsedCursorCurrentSeq ?? 0;
-                const retentionFloor = Math.max(client._pullRetentionFloor(result, 'retention_floor_message_seq', 'retention_floor_message_seq'));
-                const visibilityFloor = Math.max(0, Math.max(0, Number(result.earliest_available_message_seq ?? 1) - 1), Number(cursor?.join_seq ?? 0));
-                const effectiveFloor = Math.max(retentionFloor, visibilityFloor);
-                const commitTarget = Math.max(pageContigBefore, effectiveFloor, ownsCursor && pageCount === 1 ? deferredServerCursor : 0, ownsCursor ? cursorCurrentSeq : 0, blockedSeq > 0 ? blockedSeq - 1 : pageContiguousSeq);
-                let ackSeq = pageContigBefore;
-                let contigAdvanced = false;
-                if (ownsCursor) {
-                    try {
+                    commitTarget = Math.max(pageContigBefore, effectiveFloor, ownsCursor && pageCount === 1 ? deferredServerCursor : 0, ownsCursor ? cursorCurrentSeq : 0, blockedSeq > 0 ? blockedSeq - 1 : pageContiguousSeq);
+                    if (ownsCursor) {
                         this.ensureDeliveryCurrent(ns, generation);
                         const window = client._seqTracker.getSyncState?.(ns);
                         const deliveryTarget = window && commitTarget >= window.tail - 1
@@ -2653,6 +3172,16 @@ export class V2E2EECoordinator {
                             await client._drainOrderedMessages(ns, undefined, false, false, 'pull', deliveryTarget);
                         }
                         this.ensureDeliveryCurrent(ns, generation);
+                    }
+                });
+                let ackSeq = pageContigBefore;
+                let contigAdvanced = false;
+                if (ownsCursor) {
+                    try {
+                        this.ensureDeliveryCurrent(ns, generation);
+                        if (client._delivery.isSeqNamespaceGenerationCurrent?.(ns, namespaceGeneration) === false)
+                            throw new Error('pull invalidated');
+                        client._delivery.rememberCommittedSeqState?.(ns);
                         pageTrackerSnapshot = client._seqTracker.snapshotNamespace?.(ns) ?? null;
                         if (commitTarget > pageContigBefore) {
                             trackerMutated = true;
@@ -2672,12 +3201,16 @@ export class V2E2EECoordinator {
                         if (contigAdvanced) {
                             await client._commitSeqTrackerState(ns);
                             this.ensureDeliveryCurrent(ns, generation);
+                            if (client._delivery.isSeqNamespaceGenerationCurrent?.(ns, namespaceGeneration) === false)
+                                throw new Error('pull invalidated');
                             if (pageCount === 1 && deferredServerCursor > 0)
                                 this.clearForwardCursor(ns, ackSeq);
                         }
+                        committedAckSeq = ackSeq;
                     }
                     catch (exc) {
                         if (trackerMutated && Number(client._v2RuntimeGeneration ?? 0) === generation
+                            && client._delivery.isSeqNamespaceGenerationCurrent?.(ns, namespaceGeneration) !== false
                             && client._rpcPipeline?.isPullNamespaceCurrent?.(ns) !== false
                             && typeof client._seqTracker.restoreNamespaceSnapshot === 'function') {
                             (client._seqTracker._restoreNamespaceSnapshotPreservingPush ?? client._seqTracker.restoreNamespaceSnapshot)
@@ -2749,14 +3282,6 @@ export class V2E2EECoordinator {
                 if (shouldContinueForPipeline && !pipelineRunning && limit >= V2_PULL_MAX_PAGE_LIMIT) {
                     startPipeline(nextAfter);
                 }
-                if (!pipelineRunning && pullGateKey && opts?.gateLocked && client._rpcPipeline?.yieldPullGate) {
-                    const nextKey = pullGateKeyForClient(client, 'group.v2.pull', {
-                        group_id: gid, after_seq: nextAfter, force: opts?.force === true, limit,
-                        _group_cursor_params: cursorParams,
-                    }, `${ns}|forward|after=${nextAfter}|force=${String(Boolean(opts?.force))}|limit=${limit}`);
-                    await client._rpcPipeline.yieldPullGate(pullGateKey, nextKey, true);
-                    pullGateKey = nextKey;
-                }
                 const tailDelayMs = pipelineRunning ? 0 : v2PullTailDelayMs(rawCount, limit);
                 if (tailDelayMs > 0)
                     await v2Sleep(tailDelayMs);
@@ -2773,7 +3298,7 @@ export class V2E2EECoordinator {
             this.ensureDeliveryCurrent(ns, generation);
             client._clientLog.debug(`group.v2.pull flushing pending auto-ack: group=${gid}, ns=${ns}, ack_seq=${pendingAckSeq}`);
             const ackToFlush = pendingAckSeq;
-            await this.confirmForwardGroupAck(gid, ackToFlush, groupAid);
+            await this.confirmForwardGroupAck(gid, ackToFlush, groupAid, background);
             if (pendingAckSeq <= ackToFlush)
                 pendingAckSeq = 0;
         }
@@ -2794,11 +3319,11 @@ export class V2E2EECoordinator {
             throw error;
         }
     }
-    async confirmForwardGroupAck(groupId, upToSeq, groupAid) {
+    async confirmForwardGroupAck(groupId, upToSeq, groupAid, background = false) {
         const ns = `group:${String(groupId ?? '').trim()}`;
         const generation = Number(this.client._v2RuntimeGeneration ?? 0);
         try {
-            const result = await this.ackGroupV2ForForward(groupId, upToSeq, groupAid);
+            const result = await this.ackGroupV2ForForward(groupId, upToSeq, groupAid, background);
             this.ensureDeliveryCurrent(ns, generation);
             const actualAckSeq = this.client._delivery.resolveForwardAckSeq(result, upToSeq);
             if (actualAckSeq < upToSeq) {
@@ -2816,10 +3341,10 @@ export class V2E2EECoordinator {
     async ackGroupV2(groupId, upToSeq, groupAid) {
         return this.ackGroupV2WithConfirmation(groupId, upToSeq, groupAid, false);
     }
-    async ackGroupV2ForForward(groupId, upToSeq, groupAid) {
-        return this.ackGroupV2WithConfirmation(groupId, upToSeq, groupAid, true);
+    async ackGroupV2ForForward(groupId, upToSeq, groupAid, background = false) {
+        return this.ackGroupV2WithConfirmation(groupId, upToSeq, groupAid, true, background);
     }
-    async ackGroupV2WithConfirmation(groupId, upToSeq, groupAid, requireServerWatermark) {
+    async ackGroupV2WithConfirmation(groupId, upToSeq, groupAid, requireServerWatermark, background) {
         const client = this.client;
         const gid = String(groupId ?? '').trim();
         if (!gid)
@@ -2837,7 +3362,9 @@ export class V2E2EECoordinator {
             return { acked: 0 };
         const inlineAckGeneration = client._delivery.captureGroupInlineAckGeneration();
         client._clientLog.debug(`group.v2.ack send: group=${gid}, ns=${ns}, up_to_seq=${seq}`);
-        const result = await client._callRawV2Rpc('group.v2.ack', withExplicitGroupAid({ group_id: gid, up_to_seq: seq }, explicitGroupAid));
+        const result = await client._callRawV2Rpc('group.v2.ack', withExplicitGroupAid({ group_id: gid, up_to_seq: seq,
+            ...(background === undefined ? {} : { _rpc_background: background, _rpc_foreground: !background }),
+        }, explicitGroupAid));
         const actualAckSeq = requireServerWatermark
             ? client._delivery.resolveForwardAckSeq(result, seq)
             : client._delivery.resolveActualAckSeq(result, seq);