@agentunion/fastaun-browser 0.5.6 → 0.5.9

package/dist/client/delivery.js

@@ -57,6 +57,25 @@ function positiveSafeSequenceHint(value) {
     const parsed = Number(value);
     return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : 0;
 }
+function nonNegativeSafeSequenceHint(value) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0)
+        return null;
+    return value;
+}
+function deduplicatePlainForwardPageMessages(value, afterSeq) {
+    if (!Array.isArray(value))
+        return [];
+    const bySeq = new Map();
+    for (const raw of value) {
+        if (!isJsonObject(raw))
+            continue;
+        const seq = positiveSafeSequenceHint(raw.seq);
+        if (seq <= afterSeq || bySeq.has(seq))
+            continue;
+        bySeq.set(seq, { ...raw, seq });
+    }
+    return [...bySeq.entries()].sort(([left], [right]) => left - right).map(([, message]) => message);
+}
 function p2pAppEventFromPlainPullMessage(message) {
     const payload = message.payload;
     const payloadType = isJsonObject(payload)
@@ -77,18 +96,31 @@ export class MessageDeliveryEngine {
     runtime;
     realtimeTailResults = null;
     realtimeSyncing = null;
+    pendingP2pPullUpper = null;
+    pendingGroupPullUpper = null;
+    pendingPullNoProgressAcks = null;
+    onlineUnreadHintTargets = null;
+    onlineUnreadHintOwners = null;
     realtimeAcking = null;
     pendingP2PInlineAcks = null;
     pendingGroupInlineAcks = null;
     pendingGroupInlineAckNamespaces = null;
     // reset 后旧 inline Promise 只能自行结束，不能触碰新身份上下文的状态。
     inlineGeneration = 0;
+    // 同一实例的 tracker 写入必须串行，避免旧的延迟 flush 覆盖新的 Forward 提交。
+    seqTrackerWriteChain = Promise.resolve();
     constructor(runtime) {
         this.runtime = runtime;
     }
     resetInlineAckState() {
         this.inlineGeneration += 1;
+        void this.runtime.client._rpcPipeline?.invalidatePulls?.();
         this.realtimeSyncing = null;
+        this.pendingP2pPullUpper = null;
+        this.pendingGroupPullUpper = null;
+        this.pendingPullNoProgressAcks = null;
+        this.onlineUnreadHintTargets = null;
+        this.onlineUnreadHintOwners = null;
         this.realtimeTailResults = null;
         this.realtimeAcking = null;
         this.pendingP2PInlineAcks = null;
@@ -98,6 +130,20 @@ export class MessageDeliveryEngine {
     isInlineGenerationCurrent(generation) {
         return generation === this.inlineGeneration;
     }
+    isPullOperationCurrent() {
+        const client = this.runtime.client;
+        const generation = client._pullOperationGeneration;
+        if (generation === undefined)
+            return true;
+        const pipeline = client._rpcPipeline;
+        return typeof pipeline?.isPullGenerationCurrent === 'function'
+            ? pipeline.isPullGenerationCurrent(generation)
+            : true;
+    }
+    ensurePullOperationCurrent() {
+        if (!this.isPullOperationCurrent())
+            throw new Error('pull invalidated');
+    }
     captureInlineGeneration() {
         return this.inlineGeneration;
     }
@@ -112,6 +158,74 @@ export class MessageDeliveryEngine {
     endRealtimeSync(ns) {
         this.realtimeSyncing?.delete(ns);
     }
+    hasPendingPull(ns) {
+        const pending = ns.startsWith('p2p:') ? this.pendingP2pPullUpper : this.pendingGroupPullUpper;
+        return (pending?.get(ns) ?? 0) > 0;
+    }
+    onPullGateIdle(ns) {
+        if (!ns)
+            return;
+        this.schedulePendingPullIfNeeded(ns, 'pull-gate-idle');
+    }
+    recordPendingPull(ns, seq) {
+        if (!ns || !Number.isSafeInteger(seq) || seq <= 0)
+            return;
+        const pending = ns.startsWith('p2p:')
+            ? (this.pendingP2pPullUpper ?? new Map())
+            : (this.pendingGroupPullUpper ?? new Map());
+        if (ns.startsWith('p2p:'))
+            this.pendingP2pPullUpper = pending;
+        else
+            this.pendingGroupPullUpper = pending;
+        pending.set(ns, Math.max(pending.get(ns) ?? 0, seq));
+    }
+    consumePendingPull(ns, throughSeq) {
+        const pending = ns.startsWith('p2p:') ? this.pendingP2pPullUpper : this.pendingGroupPullUpper;
+        if ((pending?.get(ns) ?? 0) <= throughSeq) {
+            pending?.delete(ns);
+            this.pendingPullNoProgressAcks?.delete(ns);
+        }
+    }
+    markPendingPullNoProgress(ns, ack) {
+        const blocked = this.pendingPullNoProgressAcks ?? new Map();
+        this.pendingPullNoProgressAcks = blocked;
+        blocked.set(ns, ack);
+    }
+    schedulePendingPullIfNeeded(ns, reason) {
+        const pending = ns.startsWith('p2p:') ? this.pendingP2pPullUpper : this.pendingGroupPullUpper;
+        if (!pending)
+            return false;
+        const upper = pending.get(ns) ?? 0;
+        if (upper <= 0) {
+            pending.delete(ns);
+            this.pendingPullNoProgressAcks?.delete(ns);
+            return false;
+        }
+        const client = this.runtime.client;
+        const contiguous = client._seqTracker.getContiguousSeq(ns);
+        if (upper <= contiguous) {
+            pending.delete(ns);
+            this.pendingPullNoProgressAcks?.delete(ns);
+            client._clientLog?.debug(`pending pull upper already covered: ns=${ns}, upper_seq=${upper}, contiguous=${contiguous}, reason=${reason}`);
+            return false;
+        }
+        const blockedAck = this.pendingPullNoProgressAcks?.get(ns);
+        if (blockedAck !== undefined && contiguous <= blockedAck)
+            return false;
+        this.pendingPullNoProgressAcks?.delete(ns);
+        if (client.state !== ConnectionState.READY || client._closing || this.realtimeSyncing?.has(ns)
+            || client._rpcPipeline?.hasPullActivity?.(ns, false))
+            return false;
+        pending.delete(ns);
+        client._clientLog?.debug(`pending push follow-up pull scheduled: ns=${ns}, upper_seq=${upper}, reason=${reason}`);
+        if (ns.startsWith('p2p:')) {
+            client._safeAsync(this.onV2PushNotification({ seq: upper }));
+        }
+        else {
+            client._safeAsync(this.onRawGroupV2MessageCreated({ group_id: ns.slice('group:'.length), seq: upper }));
+        }
+        return true;
+    }
     beginRealtimeAck(ns, seq) {
         if (!ns || !Number.isSafeInteger(seq) || seq <= 0)
             return false;
@@ -499,6 +613,230 @@ export class MessageDeliveryEngine {
         }
         return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0;
     }
+    resolveP2PPullAckSeq(result, requestedSeq) {
+        if (!Number.isSafeInteger(requestedSeq) || requestedSeq <= 0)
+            return 0;
+        if (isJsonObject(result)
+            && Object.prototype.hasOwnProperty.call(result, 'server_ack_seq')) {
+            const value = result.server_ack_seq;
+            return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+        }
+        return 0;
+    }
+    resolveGroupPullAckSeq(result, requestedSeq) {
+        if (!Number.isSafeInteger(requestedSeq) || requestedSeq <= 0)
+            return 0;
+        if (!isJsonObject(result))
+            return 0;
+        const row = result;
+        if (!Object.prototype.hasOwnProperty.call(row, 'cursor'))
+            return 0;
+        const cursor = row.cursor;
+        if (!isJsonObject(cursor))
+            return 0;
+        const cursorRow = cursor;
+        if (!Object.prototype.hasOwnProperty.call(cursorRow, 'current_seq'))
+            return 0;
+        const value = cursorRow.current_seq;
+        return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+    }
+    resolveForwardAckSeq(result, requestedSeq) {
+        if (!Number.isSafeInteger(requestedSeq) || requestedSeq <= 0)
+            return 0;
+        // 旧服务端成功响应可能不带累计水位字段；RPC 已成功，兼容按请求水位处理。
+        if (!isJsonObject(result))
+            return requestedSeq;
+        const row = result;
+        let value;
+        if (Object.prototype.hasOwnProperty.call(row, 'effective_ack_seq')) {
+            value = row.effective_ack_seq;
+        }
+        else if (Object.prototype.hasOwnProperty.call(row, 'ack_seq')) {
+            value = row.ack_seq;
+        }
+        else if (Object.prototype.hasOwnProperty.call(row, 'cursor')) {
+            const cursor = row.cursor;
+            const cursorRow = isJsonObject(cursor)
+                ? cursor
+                : null;
+            if (cursorRow) {
+                if (!Object.prototype.hasOwnProperty.call(cursorRow, 'current_seq'))
+                    return 0;
+                value = cursorRow.current_seq;
+            }
+            else {
+                value = cursor;
+            }
+        }
+        else {
+            return requestedSeq;
+        }
+        return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+    }
+    forwardCoordinator() {
+        const coordinator = this.runtime.client._v2E2EE;
+        if (!coordinator
+            || typeof coordinator.pendingForwardCursor !== 'function'
+            || typeof coordinator.recordForwardCursor !== 'function'
+            || typeof coordinator.clearForwardCursor !== 'function'
+            || typeof coordinator.pendingForwardAck !== 'function'
+            || typeof coordinator.recordForwardAck !== 'function'
+            || typeof coordinator.clearForwardAck !== 'function') {
+            throw new Error('Forward cursor coordinator is unavailable');
+        }
+        return coordinator;
+    }
+    async confirmPlainForwardAck(ns, method, ackSeq, groupId = '') {
+        const client = this.runtime.client;
+        this.ensurePullOperationCurrent();
+        const coordinator = this.forwardCoordinator();
+        const generation = this.captureInlineGeneration();
+        coordinator.recordForwardAck(ns, ackSeq);
+        const params = method === 'message.ack'
+            ? {
+                seq: ackSeq,
+                device_id: client._deviceId,
+                slot_id: client._slotId,
+                _rpc_background: true,
+            }
+            : {
+                group_id: groupId,
+                msg_seq: ackSeq,
+                device_id: client._deviceId,
+                slot_id: client._slotId,
+                _rpc_background: true,
+            };
+        const result = await client._rpcPipeline.rawCall(method, params, { background: true });
+        this.ensurePullOperationCurrent();
+        const actualAckSeq = this.resolveForwardAckSeq(result, ackSeq);
+        if (actualAckSeq < ackSeq) {
+            throw new Error(`${method} server ACK watermark ${actualAckSeq} is below requested ${ackSeq}`);
+        }
+        coordinator.clearForwardAck(ns, actualAckSeq);
+        if (method === 'message.ack') {
+            this.completePendingP2PInlineAckUpTo(ns, actualAckSeq, generation);
+        }
+        else {
+            this.completePendingGroupInlineAckUpTo(ns, actualAckSeq, generation);
+        }
+    }
+    async commitPlainForwardPage(ns, afterSeq, method, result, groupId = '') {
+        if (!isJsonObject(result)) {
+            throw new Error(`${method} response must be an object`);
+        }
+        const client = this.runtime.client;
+        this.ensurePullOperationCurrent();
+        const response = result;
+        const messages = deduplicatePlainForwardPageMessages(response.messages, afterSeq);
+        const coordinator = this.forwardCoordinator();
+        const pageContigBefore = client._seqTracker.getContiguousSeq(ns);
+        const pageInlineGeneration = this.captureInlineGeneration();
+        const deferredServerCursor = Number(coordinator.pendingForwardCursor(ns, pageContigBefore) ?? 0);
+        const deferredForwardAck = Number(coordinator.pendingForwardAck(ns, pageContigBefore) ?? 0);
+        const pageTrackerSnapshot = typeof client._seqTracker.snapshotNamespace === 'function'
+            ? client._seqTracker.snapshotNamespace(ns)
+            : null;
+        response._contig_before = pageContigBefore;
+        const cursor = isJsonObject(response.cursor)
+            ? response.cursor
+            : null;
+        const serverAckRaw = method === 'message.pull' ? response.server_ack_seq : cursor?.current_seq;
+        const hasServerAck = method === 'message.pull'
+            ? Object.prototype.hasOwnProperty.call(response, 'server_ack_seq')
+            : Boolean(cursor && Object.prototype.hasOwnProperty.call(cursor, 'current_seq'));
+        const parsedServerAck = hasServerAck ? nonNegativeSafeSequenceHint(serverAckRaw) : null;
+        const serverAckSeq = parsedServerAck ?? 0;
+        const retentionFloor = method === 'message.pull'
+            ? positiveSafeSequenceHint(response.retention_floor_seq)
+            : Math.max(positiveSafeSequenceHint(response.retention_floor_message_seq), positiveSafeSequenceHint(response.retention_floor_seq), positiveSafeSequenceHint(cursor?.retention_floor_seq));
+        const visibilityFloor = method === 'group.pull'
+            ? Math.max(positiveSafeSequenceHint(cursor?.join_seq), Math.max(0, positiveSafeSequenceHint(response.earliest_available_message_seq) - 1))
+            : 0;
+        let publishedCount = 0;
+        let committed = false;
+        try {
+            for (const rawMessage of messages) {
+                this.ensurePullOperationCurrent();
+                const seq = positiveSafeSequenceHint(rawMessage.seq);
+                if (method === 'message.pull') {
+                    const appEvent = p2pAppEventFromPlainPullMessage(rawMessage);
+                    if (await this.publishPulledMessage(appEvent.event, ns, seq, appEvent.payload, false)) {
+                        publishedCount += 1;
+                    }
+                    this.ensurePullOperationCurrent();
+                    continue;
+                }
+                const message = normalizeGroupMentionMode(rawMessage);
+                if (this.recallEventFromGroupMessage(message)) {
+                    if (await this.publishGroupRecallTombstone(groupId, seq, message)) {
+                        this.ensurePullOperationCurrent();
+                        this.markPublishedSeq(ns, seq);
+                        publishedCount += 1;
+                    }
+                }
+                else if (await this.publishPulledMessage('group.message_created', ns, seq, message, false)) {
+                    this.ensurePullOperationCurrent();
+                    publishedCount += 1;
+                }
+            }
+            this.ensurePullOperationCurrent();
+            if (messages.length > 0)
+                client._seqTracker.onPullResult(ns, messages, afterSeq);
+            const commitTarget = Math.max(client._seqTracker.getContiguousSeq(ns), retentionFloor, visibilityFloor, deferredServerCursor);
+            if (commitTarget > client._seqTracker.getContiguousSeq(ns)) {
+                client._seqTracker.forceContiguousSeq(ns, commitTarget);
+            }
+            if (client._seqTracker.getContiguousSeq(ns) !== pageContigBefore) {
+                this.ensurePullOperationCurrent();
+                await this.drainOrderedMessages(ns, undefined, false, false);
+                this.ensurePullOperationCurrent();
+                await client._commitSeqTrackerState(ns);
+            }
+            committed = true;
+        }
+        catch (exc) {
+            if (this.isPullOperationCurrent() && !committed && typeof client._seqTracker.restoreNamespaceSnapshot === 'function') {
+                client._seqTracker.restoreNamespaceSnapshot(ns, pageTrackerSnapshot);
+                this.dropSeqTrackerPending(ns);
+            }
+            throw exc;
+        }
+        this.ensurePullOperationCurrent();
+        const committedAck = client._seqTracker.getContiguousSeq(ns);
+        if (deferredServerCursor > 0 && committedAck >= deferredServerCursor) {
+            coordinator.clearForwardCursor(ns, committedAck);
+        }
+        if (hasServerAck && parsedServerAck !== null && serverAckSeq > committedAck) {
+            coordinator.recordForwardCursor(ns, serverAckSeq, committedAck);
+        }
+        if (hasServerAck && parsedServerAck !== null && serverAckSeq >= deferredForwardAck) {
+            coordinator.clearForwardAck(ns, serverAckSeq);
+            if (method === 'message.pull') {
+                this.completePendingP2PInlineAckUpTo(ns, serverAckSeq, pageInlineGeneration);
+            }
+            else {
+                this.completePendingGroupInlineAckUpTo(ns, serverAckSeq, pageInlineGeneration);
+            }
+        }
+        const contigAdvanced = committedAck > pageContigBefore;
+        const knownServerAck = hasServerAck ? serverAckSeq : deferredServerCursor;
+        if (committedAck > 0
+            && ((hasServerAck && committedAck > serverAckSeq)
+                || (contigAdvanced && committedAck > knownServerAck))) {
+            coordinator.recordForwardAck(ns, committedAck);
+        }
+        const pendingAckSeq = Number(coordinator.pendingForwardAck(ns, committedAck) ?? 0);
+        if (pendingAckSeq > 0) {
+            const ackMethod = method === 'message.pull' ? 'message.ack' : 'group.ack_messages';
+            const clampedAckSeq = this.clampAckSeq(ackMethod, ackMethod === 'message.ack' ? 'seq' : 'msg_seq', ns, pendingAckSeq);
+            if (clampedAckSeq < pendingAckSeq) {
+                throw new Error(`${ackMethod} cannot confirm pending Forward watermark ${pendingAckSeq}`);
+            }
+            this.ensurePullOperationCurrent();
+            await this.confirmPlainForwardAck(ns, ackMethod, pendingAckSeq, groupId);
+        }
+        return { rawCount: messages.length, publishedCount };
+    }
     enqueueOrderedMessage(ns, event, seq, payload) {
         const client = this.runtime.client;
         let queue = client._pendingOrderedMsgs.get(ns);
@@ -1432,55 +1770,47 @@ export class MessageDeliveryEngine {
         }
         const ns = this.resolvePendingGroupInlineAckNamespace(`group:${groupId}`);
         const afterSeq = client._seqTracker.getContiguousSeq(ns);
-        try {
-            if (client._v2Session) {
+        if (client._v2Session) {
+            try {
                 const key = client._rpcPipeline.pullGateKeyForCall('group.pull', { group_id: groupId, after_seq: afterSeq, limit: 50 });
                 await client._rpcPipeline.runPullSerialized(key, () => client._pullGroupV2(groupId, afterSeq, 50, { gateLocked: true }), true);
                 return;
             }
-            const result = await client.call('group.pull', {
+            catch (exc) {
+                client._clientLog.warn(`auto pull group message failed:${String(exc)}`);
+                await client._publishAppEvent('group.message_created', notification);
+                return;
+            }
+        }
+        let rawCompleted = false;
+        try {
+            const key = client._rpcPipeline.pullGateKeyForCall('group.pull', {
                 group_id: groupId,
                 after_message_seq: afterSeq,
-                device_id: client._deviceId,
                 limit: 50,
-                _rpc_background: true,
             });
-            if (isJsonObject(result)) {
-                const messages = result.messages;
-                if (Array.isArray(messages)) {
-                    const pushed = client._pushedSeqs.get(ns);
-                    for (const msg of messages) {
-                        if (isJsonObject(msg)) {
-                            const s = msg.seq;
-                            if (pushed && s !== undefined && s !== null && pushed.has(s)) {
-                                continue;
-                            }
-                            // 群撤回 tombstone（占位 / 通知）：归一化为 group.message_recalled 事件，仍占 seq。
-                            // 与 V2 pull 路径（v2-e2ee.ts pullGroupV2）对齐，避免 legacy 回退路径把撤回
-                            // tombstone 当普通 group.message_created 投递给应用层。
-                            if (s !== undefined && s !== null
-                                && this.recallEventFromGroupMessage(msg)) {
-                                await this.publishGroupRecallTombstone(groupId, s, msg);
-                                this.markPublishedSeq(ns, Number(s));
-                                continue;
-                            }
-                            if (s !== undefined && s !== null) {
-                                await client._publishPulledMessage('group.message_created', ns, s, msg);
-                            }
-                            else {
-                                await client._publishAppEvent('group.message_created', msg);
-                            }
-                        }
-                    }
-                    this.prunePushedSeqs(ns);
-                    return;
-                }
-            }
+            await client._rpcPipeline.runPullSerialized(key, async () => {
+                const result = await client._rpcPipeline.rawCall('group.pull', {
+                    group_id: groupId,
+                    after_message_seq: afterSeq,
+                    device_id: client._deviceId,
+                    slot_id: client._slotId,
+                    limit: 50,
+                    _rpc_background: true,
+                }, { background: true });
+                rawCompleted = true;
+                await this.commitPlainForwardPage(ns, afterSeq, 'group.pull', result, groupId);
+                this.prunePushedSeqs(ns);
+            }, true);
         }
         catch (exc) {
-            client._clientLog.warn(`auto pull group message failed:${String(exc)}`);
+            // 页发布或本地提交失败不能 ACK；提交后 ACK 失败则保留 pending。
+            // 两种情况都不能再把原始通知当作第二条业务消息发布。
+            client._clientLog.warn(`auto pull group message commit/ack failed:${String(exc)}`);
+            if (!rawCompleted) {
+                await client._publishAppEvent('group.message_created', notification);
+            }
         }
-        await client._publishAppEvent('group.message_created', notification);
     }
     scheduleP2pGapRetry(ns, retryAttempt) {
         const client = this.runtime.client;
@@ -1541,6 +1871,7 @@ export class MessageDeliveryEngine {
         finally {
             client._gapFillDone.delete(dedupKey);
             this.runtime.delivery.setGapFillActive(false);
+            this.schedulePendingPullIfNeeded(ns, 'gap-fill-complete');
         }
     }
     async fillP2pGapWithPlainPull(ns, afterSeq) {
@@ -1552,25 +1883,9 @@ export class MessageDeliveryEngine {
             slot_id: client._slotId,
             _rpc_background: true,
         };
-        const raw = await client._transport.call('message.pull', params, undefined, undefined, true);
-        const result = typeof client._rpcPipeline?.postprocessResult === 'function'
-            ? await client._rpcPipeline.postprocessResult('message.pull', params, raw)
-            : raw;
-        const messages = (isJsonObject(result) && Array.isArray(result.messages))
-            ? result.messages
-            : [];
-        let published = 0;
-        for (const item of messages) {
-            if (!isJsonObject(item))
-                continue;
-            const msg = item;
-            const seq = Number(msg.seq ?? 0);
-            const appEvent = p2pAppEventFromPlainPullMessage(msg);
-            if (await this.publishPulledMessage(appEvent.event, ns, seq, appEvent.payload)) {
-                published += 1;
-            }
-        }
-        return published;
+        const raw = await client._rpcPipeline.rawCall('message.pull', params, { background: true });
+        const page = await this.commitPlainForwardPage(ns, afterSeq, 'message.pull', raw);
+        return page.publishedCount;
     }
     async fillGroupGap(groupId) {
         const client = this.runtime.client;
@@ -1604,9 +1919,10 @@ export class MessageDeliveryEngine {
             if (filled > 0 && client._seqTracker.getContiguousSeq(ns) > afterSeq) {
                 client._safeAsync(this.fillGroupGap(groupId));
             }
+            this.schedulePendingPullIfNeeded(ns, 'gap-fill-complete');
         }
     }
-    async fillGroupEventGap(groupId) {
+    async fillGroupEventGap(groupId, options) {
         const client = this.runtime.client;
         if (client._sessionOptions?.background_sync === false)
             return;
@@ -1616,25 +1932,31 @@ export class MessageDeliveryEngine {
         if (!groupId)
             return;
         const ns = `group_event:${groupId}`;
-        const afterSeq = client._seqTracker.getContiguousSeq(ns);
+        const requestedAfterSeq = Number(options?.afterSeq ?? 0);
+        const afterSeq = Number.isSafeInteger(requestedAfterSeq) && requestedAfterSeq > 0
+            ? requestedAfterSeq
+            : client._seqTracker.getContiguousSeq(ns);
+        const singlePage = options?.singlePage === true;
         const dedupKey = `group_event_pull:${ns}`;
         if (client._gapFillDone.has(dedupKey))
             return;
         client._gapFillDone.add(dedupKey);
         this.runtime.delivery.setGapFillActive(true);
+        let continuationAfterSeq = 0;
         try {
             let nextAfterSeq = afterSeq;
-            const maxPages = 100;
+            const maxPages = singlePage ? 1 : 100;
             let pageCount = 0;
             while (pageCount < maxPages) {
                 pageCount += 1;
-                const result = await client.call('group.pull_events', {
+                const request = {
                     group_id: groupId,
                     after_event_seq: nextAfterSeq,
                     device_id: client._deviceId,
                     limit: 50,
                     _rpc_background: true,
-                });
+                };
+                const result = await client.call('group.pull_events', request);
                 if (!isJsonObject(result))
                     return;
                 const events = result.events;
@@ -1690,16 +2012,28 @@ export class MessageDeliveryEngine {
                     this.persistSeq(ns);
                 }
                 if (eventObjects.length > 0 && ackContig > 0 && ackContig !== pageContigBefore) {
-                    client._transport.call('group.ack_events', {
-                        group_id: groupId,
-                        event_seq: ackContig,
-                        device_id: client._deviceId,
-                        slot_id: client._slotId,
-                        _rpc_background: true,
-                    }).catch((e) => { client._clientLog.warn('group event auto-ack failed: group=' + groupId, e); });
+                    try {
+                        const ackPromise = client._transport.call('group.ack_events', {
+                            group_id: groupId,
+                            event_seq: ackContig,
+                            device_id: client._deviceId,
+                            slot_id: client._slotId,
+                            _rpc_background: true,
+                        });
+                        if (singlePage)
+                            await ackPromise;
+                        else
+                            ackPromise.catch((e) => { client._clientLog.warn('group event auto-ack failed: group=' + groupId, e); });
+                    }
+                    catch (e) {
+                        client._clientLog.warn('group event auto-ack failed: group=' + groupId, e);
+                    }
                 }
                 const nextAfter = Math.max(eventSeqs.length > 0 ? Math.max(...eventSeqs) : nextAfterSeq, nextAfterSeq);
-                if (eventObjects.length === 0 || nextAfter <= nextAfterSeq || result.has_more === false)
+                if (singlePage && result.has_more === true && nextAfter > nextAfterSeq) {
+                    continuationAfterSeq = nextAfter;
+                }
+                if (eventObjects.length === 0 || nextAfter <= nextAfterSeq || result.has_more !== true)
                     break;
                 nextAfterSeq = nextAfter;
             }
@@ -1713,6 +2047,12 @@ export class MessageDeliveryEngine {
         finally {
             client._gapFillDone.delete(dedupKey);
             this.runtime.delivery.setGapFillActive(false);
+            if (singlePage && continuationAfterSeq > afterSeq) {
+                this.enqueueOnlineUnreadEventHint({
+                    group_id: groupId,
+                    _online_hint_after_event_seq: continuationAfterSeq,
+                });
+            }
         }
     }
     async handleGroupChangedEventSeq(data, groupId) {
@@ -1731,8 +2071,8 @@ export class MessageDeliveryEngine {
                 client._clientLog.debug(`group.changed online unread hint skipped: group=${groupId} background_sync=false`);
                 return;
             }
-            client._clientLog.debug(`group.changed online unread hint triggering gap fill: group=${groupId}, event_seq=${eventSeq}`);
-            client._safeAsync(this.fillGroupEventGap(groupId));
+            client._clientLog.debug(`group.changed online unread hint triggering event Forward: group=${groupId}, event_seq=${eventSeq}`);
+            this.enqueueOnlineUnreadEventHint(data);
             return;
         }
         if (this.isSelfJoinGroupChanged(data)) {
@@ -1794,50 +2134,88 @@ export class MessageDeliveryEngine {
         const groupId = String(data.group_id ?? '').trim();
         if (!groupId)
             return;
-        client._onlineUnreadHintQueue.set(groupId, { ...data });
-        if (client._onlineUnreadHintTimer || client._onlineUnreadHintDrainActive)
-            return;
-        const delayMs = Math.max(0, Number(client._onlineUnreadHintInitialDelayMs ?? 750) || 0);
-        this.runtime.delivery.setOnlineUnreadHintTimer(setTimeout(() => {
-            this.runtime.delivery.setOnlineUnreadHintTimer(null);
-            client._safeAsync(this.drainOnlineUnreadHints());
-        }, delayMs));
+        const ns = `group:${groupId}`;
+        const targets = this.onlineUnreadHintTargets ?? new Map();
+        const owners = this.onlineUnreadHintOwners ?? new Set();
+        this.onlineUnreadHintTargets = targets;
+        this.onlineUnreadHintOwners = owners;
+        targets.set(ns, Math.max(targets.get(ns) ?? 0, positiveSafeSequenceHint(data.seq)));
+        if (owners.has(ns))
+            return;
+        owners.add(ns);
+        client._safeAsync((async () => {
+            try {
+                while (true) {
+                    const throughSeq = targets.get(ns) ?? 0;
+                    const ackBefore = this.syncState(ns).ack;
+                    await this.runGroupForwardRecovery(groupId, ns, 50, true, throughSeq);
+                    const ackAfter = this.syncState(ns).ack;
+                    const target = targets.get(ns) ?? 0;
+                    if (ackAfter >= target || ackAfter <= ackBefore)
+                        return;
+                }
+            }
+            catch (exc) {
+                client._clientLog?.debug(`online unread hint background Forward failed: ns=${ns} err=${formatDeliveryError(exc)}`);
+            }
+            finally {
+                if (this.onlineUnreadHintTargets === targets)
+                    targets.delete(ns);
+                if (this.onlineUnreadHintOwners === owners)
+                    owners.delete(ns);
+            }
+        })());
     }
-    async drainOnlineUnreadHints() {
+    enqueueOnlineUnreadEventHint(data) {
         const client = this.runtime.client;
-        if (client._onlineUnreadHintDrainActive)
+        const groupId = String(data.group_id ?? '').trim();
+        if (!groupId || client._sessionOptions?.background_sync === false)
             return;
-        this.runtime.delivery.setOnlineUnreadHintDrainActive(true);
-        const attemptedAckByGroup = new Map();
-        try {
-            while (client._onlineUnreadHintQueue.size > 0) {
-                if (client.state !== ConnectionState.READY)
-                    return;
-                const groupId = client._onlineUnreadHintQueue.keys().next().value;
-                if (!groupId)
-                    return;
-                const payload = client._onlineUnreadHintQueue.get(groupId);
-                client._onlineUnreadHintQueue.delete(groupId);
-                if (!payload)
-                    continue;
-                const currentAck = this.syncState(`group:${groupId}`).ack;
-                const attemptedAck = attemptedAckByGroup.get(groupId);
-                if (attemptedAck !== undefined && currentAck <= attemptedAck)
-                    continue;
-                attemptedAckByGroup.set(groupId, currentAck);
-                await this.onRawGroupV2MessageCreated({ ...payload, _online_hint_drained: true });
-                const intervalMs = Math.max(0, Number(client._onlineUnreadHintIntervalMs ?? 50) || 0);
-                if (intervalMs > 0 && client._onlineUnreadHintQueue.size > 0) {
-                    await new Promise((resolve) => setTimeout(resolve, intervalMs));
-                }
-            }
-        }
-        catch (exc) {
-            client._clientLog.debug(`online unread hint drain failed: ${formatDeliveryError(exc)}`);
-        }
-        finally {
-            this.runtime.delivery.setOnlineUnreadHintDrainActive(false);
-        }
+        const rawAfter = Number(data._online_hint_after_event_seq ?? 0);
+        const afterSeq = Number.isSafeInteger(rawAfter) && rawAfter > 0 ? rawAfter : 0;
+        client._safeAsync(this.fillGroupEventGap(groupId, {
+            afterSeq,
+            singlePage: true,
+        }));
+    }
+    async runP2PForwardRecovery(ns, pageLimit, background = false) {
+        const client = this.runtime.client;
+        const request = {
+            after_seq: this.syncState(ns).ack,
+            limit: pageLimit,
+            max_pages: 1,
+        };
+        const invoke = async () => {
+            const after = this.syncState(ns).ack;
+            const messages = await client._pullV2(after, pageLimit, { gateLocked: true, maxPages: 1 });
+            return { messages, raw_count: messages.length };
+        };
+        const pipeline = client._rpcPipeline;
+        if (!pipeline)
+            return await invoke();
+        const key = pipeline.pullGateKeyForCall('message.pull', request);
+        return await pipeline.runPullSerialized(key, invoke, background);
+    }
+    async runGroupForwardRecovery(groupId, ns, pageLimit, background = false, throughSeq = 0) {
+        const client = this.runtime.client;
+        const state = this.syncState(ns);
+        const maxPages = this.forwardMaxPages(state.ack, throughSeq, pageLimit);
+        const request = {
+            group_id: groupId,
+            after_seq: state.ack,
+            limit: pageLimit,
+            max_pages: maxPages,
+        };
+        const invoke = async () => {
+            const after = this.syncState(ns).ack;
+            const messages = await client._pullGroupV2(groupId, after, pageLimit, { gateLocked: true, maxPages });
+            return { messages, raw_count: messages.length };
+        };
+        const pipeline = client._rpcPipeline;
+        if (!pipeline)
+            return await invoke();
+        const key = pipeline.pullGateKeyForCall('group.pull', request);
+        return await pipeline.runPullSerialized(key, invoke, background);
     }
     syncState(ns) {
         const tracker = this.runtime.client._seqTracker;
@@ -1846,6 +2224,10 @@ export class MessageDeliveryEngine {
         const ack = Number(tracker.getContiguousSeq(ns) || 0);
         return { ack, tail: ack, head: Math.max(ack, Number(tracker.getMaxSeenSeq?.(ns) || 0)) };
     }
+    forwardMaxPages(ack, throughSeq, pageLimit) {
+        const limit = Number.isSafeInteger(pageLimit) && pageLimit > 0 ? pageLimit : 1;
+        return Math.max(1, Math.ceil(Math.max(0, throughSeq - ack) / limit));
+    }
     inlineMessage(data) {
         if (!isJsonObject(data))
             return null;
@@ -2253,8 +2635,10 @@ export class MessageDeliveryEngine {
         }
     }
     hasOutstandingRealtimeGap(ns) {
-        const maxSeenSeq = this.runtime.client._seqTracker.getMaxSeenSeq(ns);
-        return Number.isSafeInteger(maxSeenSeq) && maxSeenSeq > this.syncState(ns).ack;
+        const state = this.syncState(ns);
+        // Tail 已建立可靠后缀窗口；后台续拉只针对尚未接上窗口的真实缺口。
+        // maxSeen 可能只是 Tail 期间到达的通知，不能单独据此启动全量补洞。
+        return state.ack < state.tail - 1;
     }
     scheduleP2PRealtimeFullGapFill(ns) {
         const client = this.runtime.client;
@@ -2307,7 +2691,17 @@ export class MessageDeliveryEngine {
     }
     async runP2PRealtimeSync(ns, pushSeq, pageLimit = 50, forceTail = false) {
         const client = this.runtime.client;
-        const order = client._seqTracker.planRealtimeSync(ns, pushSeq, pageLimit);
+        const before = this.syncState(ns);
+        const order = forceTail ? ['tail'] : typeof client._seqTracker.planRealtimeSync === 'function'
+            ? client._seqTracker.planRealtimeSync(ns, pushSeq, pageLimit)
+            : (() => {
+                const gap = pushSeq - before.ack;
+                if (gap <= 0)
+                    return before.ack < before.tail - 1 ? ['forward'] : [];
+                return gap <= pageLimit * 2 ? ['forward'] : ['tail'];
+            })();
+        // Planner 依据 S-A 选路；H 已覆盖 S 也不代表 A 已连续提交，仍需前台 Forward。
+        const headForward = order[0] === 'forward' && pushSeq > before.ack;
         let result = { messages: [], raw_count: 0 };
         let tailCompleted = false;
         const run = async (tail, background, maxPages, forceForward = false, bypassCoveredHead = false) => {
@@ -2322,7 +2716,7 @@ export class MessageDeliveryEngine {
                 if (tail) {
                     const tailResult = await client._v2E2EE.pullV2TailInternal({
                         window_mode: 'tail', after_seq: live.ack, limit: pageLimit,
-                    });
+                    }, true);
                     tailCompleted = true;
                     return tailResult;
                 }
@@ -2341,22 +2735,46 @@ export class MessageDeliveryEngine {
         // 落盘的 ack 为起点，至多补一页普通 Forward 即可恢复该小窗口。
         const tailMissedDuringPull = tailCompleted
             && Number(client._seqTracker.getMaxSeenSeq(ns) || 0) > state.head;
-        let boundedForwardForMissedHead = false;
-        if (client._sessionOptions?.background_sync !== false
-            && (order[0] === 'forward'
-                || (tailCompleted && (state.ack < state.tail - 1 || tailMissedDuringPull)))) {
-            result = await run(false, true, order[0] === 'tail' ? 1 : undefined, tailMissedDuringPull);
-            boundedForwardForMissedHead = order[0] === 'tail' && tailMissedDuringPull;
-        }
-        if (boundedForwardForMissedHead)
+        const maxSeen = Number(client._seqTracker.getMaxSeenSeq(ns) || 0);
+        const pendingThroughSeq = tailMissedDuringPull
+            ? maxSeen
+            : 0;
+        const tailForward = tailCompleted && (state.ack < state.tail - 1 || tailMissedDuringPull);
+        const backgroundWindowForward = order[0] === 'forward' && !headForward;
+        if (headForward || tailForward
+            || (client._sessionOptions?.background_sync !== false && backgroundWindowForward)) {
+            const forwardTarget = Math.max(headForward ? Math.max(pushSeq, maxSeen) : 0, (tailForward || backgroundWindowForward) ? state.tail - 1 : 0, tailMissedDuringPull ? maxSeen : 0);
+            const forwardMaxPages = this.forwardMaxPages(state.ack, forwardTarget, pageLimit);
+            result = await run(false, !(headForward || tailForward), forwardMaxPages, headForward || tailMissedDuringPull);
+            if (pendingThroughSeq > 0) {
+                const committedAck = this.syncState(ns).ack;
+                if (committedAck >= pendingThroughSeq)
+                    this.consumePendingPull(ns, pendingThroughSeq);
+                else if (committedAck <= state.ack)
+                    this.markPendingPullNoProgress(ns, committedAck);
+            }
+        }
+        const finalState = this.syncState(ns);
+        if (tailCompleted && finalState.ack < finalState.tail - 1) {
             this.scheduleP2PRealtimeFullGapFill(ns);
+        }
         if (tailCompleted)
             this.markRealtimeTailCompleted(result);
         return result;
     }
     async runGroupRealtimeSync(groupId, ns, pushSeq, pageLimit = 50, forceTail = false) {
         const client = this.runtime.client;
-        const order = client._seqTracker.planRealtimeSync(ns, pushSeq, pageLimit);
+        const before = this.syncState(ns);
+        const order = forceTail ? ['tail'] : typeof client._seqTracker.planRealtimeSync === 'function'
+            ? client._seqTracker.planRealtimeSync(ns, pushSeq, pageLimit)
+            : (() => {
+                const gap = pushSeq - before.ack;
+                if (gap <= 0)
+                    return before.ack < before.tail - 1 ? ['forward'] : [];
+                return gap <= pageLimit * 2 ? ['forward'] : ['tail'];
+            })();
+        // Planner 依据 S-A 选路；H 已覆盖 S 也不代表 A 已连续提交，仍需前台 Forward。
+        const headForward = order[0] === 'forward' && pushSeq > before.ack;
         let result = { messages: [], raw_count: 0 };
         let tailCompleted = false;
         const run = async (tail, background, maxPages, forceForward = false, bypassCoveredHead = false) => {
@@ -2371,7 +2789,7 @@ export class MessageDeliveryEngine {
                 if (tail) {
                     const tailResult = await client._v2E2EE.pullGroupV2TailInternal({
                         group_id: groupId, window_mode: 'tail', after_seq: live.ack, limit: pageLimit,
-                    });
+                    }, true);
                     tailCompleted = true;
                     return tailResult;
                 }
@@ -2389,31 +2807,33 @@ export class MessageDeliveryEngine {
         // 期间新到达的序号；绝不重新规划或再执行 Tail。
         const tailMissedDuringPull = tailCompleted
             && Number(client._seqTracker.getMaxSeenSeq(ns) || 0) > state.head;
-        let boundedForwardForMissedHead = false;
-        if (client._sessionOptions?.background_sync !== false
-            && (order[0] === 'forward'
-                || (tailCompleted && (state.ack < state.tail - 1 || tailMissedDuringPull)))) {
-            result = await run(false, true, order[0] === 'tail' ? 1 : undefined, tailMissedDuringPull);
-            boundedForwardForMissedHead = order[0] === 'tail' && tailMissedDuringPull;
-        }
-        if (boundedForwardForMissedHead)
+        const maxSeen = Number(client._seqTracker.getMaxSeenSeq(ns) || 0);
+        const pendingThroughSeq = tailMissedDuringPull
+            ? maxSeen
+            : 0;
+        const tailForward = tailCompleted && (state.ack < state.tail - 1 || tailMissedDuringPull);
+        const backgroundWindowForward = order[0] === 'forward' && !headForward;
+        if (headForward || tailForward
+            || (client._sessionOptions?.background_sync !== false && backgroundWindowForward)) {
+            const forwardTarget = Math.max(headForward ? Math.max(pushSeq, maxSeen) : 0, (tailForward || backgroundWindowForward) ? state.tail - 1 : 0, tailMissedDuringPull ? maxSeen : 0);
+            const forwardMaxPages = this.forwardMaxPages(state.ack, forwardTarget, pageLimit);
+            result = await run(false, !(headForward || tailForward), forwardMaxPages, headForward || tailMissedDuringPull);
+            if (pendingThroughSeq > 0) {
+                const committedAck = this.syncState(ns).ack;
+                if (committedAck >= pendingThroughSeq)
+                    this.consumePendingPull(ns, pendingThroughSeq);
+                else if (committedAck <= state.ack)
+                    this.markPendingPullNoProgress(ns, committedAck);
+            }
+        }
+        const finalState = this.syncState(ns);
+        if (tailCompleted && finalState.ack < finalState.tail - 1) {
             this.scheduleGroupRealtimeFullGapFill(groupId, ns);
+        }
         if (tailCompleted)
             this.markRealtimeTailCompleted(result);
         return result;
     }
-    async runGroupOnlineUnreadHintForward(groupId, ns, pageLimit = 50) {
-        const client = this.runtime.client;
-        const request = { group_id: groupId, after_seq: this.syncState(ns).ack, limit: pageLimit, max_pages: 1 };
-        const key = client._rpcPipeline.pullGateKeyForCall('group.pull', request);
-        return await client._rpcPipeline.runPullSerialized(key, async () => {
-            const live = this.syncState(ns);
-            const messages = await client._pullGroupV2(groupId, live.ack, pageLimit, {
-                gateLocked: true, maxPages: 1,
-            });
-            return { messages, raw_count: messages.length };
-        }, true);
-    }
     async recoverInvalidP2PRealtimeHead(ns, rawSeq) {
         const client = this.runtime.client;
         client._clientLog.warn(`V2 P2P inline Head has invalid seq; forcing authoritative Tail: seq=${String(rawSeq)}`);
@@ -2483,21 +2903,9 @@ export class MessageDeliveryEngine {
         const eventKind = String(data.kind ?? '').trim();
         // Hint 是恢复信号而不是消息 Head：不得消费 inline、推进水位或直接 ACK。
         if (eventKind === 'group.online_unread_hint') {
-            if (!data._online_hint_drained) {
-                if (client._sessionOptions?.background_sync === false)
-                    return;
-                this.enqueueOnlineUnreadHint(data);
-                return;
-            }
             if (client._sessionOptions?.background_sync === false)
                 return;
-            try {
-                // 只从已提交 Ack 做一页普通 Forward，不能由 planner 把 hint 当 Tail 证据。
-                await this.runGroupOnlineUnreadHintForward(groupId, `group:${groupId}`);
-            }
-            catch (exc) {
-                client._clientLog.warn(`group online unread hint recovery pull failed: group=${groupId} err=${formatDeliveryError(exc)}`);
-            }
+            this.enqueueOnlineUnreadHint(data);
             return;
         }
         const ns = this.resolvePendingGroupInlineAckNamespace(`group:${groupId}`);
@@ -2527,30 +2935,33 @@ export class MessageDeliveryEngine {
         // inline 绑定仍要求原始 seq 是严格 number，避免类型归一化后消费正文。
         if (strictSeq || !inlinePresent)
             client._seqTracker.updateMaxSeen(ns, seq);
-        if ((!inlinePresent || inlineMatches) && !pendingConflict) {
-            if (seq <= before.head && before.ack >= before.tail - 1) {
-                const canonicalNs = this.resolvePendingGroupInlineAckNamespace(ns);
-                const pending = this.pendingGroupInlineAcks?.get(canonicalNs);
-                if (pending && seq >= pending.seq) {
-                    this.retryPendingGroupInlineAck(canonicalNs, pending.seq, 'covered inline Group ack', seq);
-                }
-                else {
-                    this.fireGroupV2Ack(groupId, ns, seq, 'group v2 covered push ack', inlineMatches ? inlineGeneration : null);
-                }
-                return;
+        if (seq <= before.ack && before.ack >= before.tail - 1) {
+            const canonicalNs = this.resolvePendingGroupInlineAckNamespace(ns);
+            const pending = this.pendingGroupInlineAcks?.get(canonicalNs);
+            if (pending && seq >= pending.seq) {
+                this.retryPendingGroupInlineAck(canonicalNs, pending.seq, 'covered inline Group ack', seq);
+            }
+            else if (!inlinePresent || inlineMatches) {
+                this.fireGroupV2Ack(groupId, ns, seq, 'group v2 covered push ack', inlineMatches ? inlineGeneration : null);
             }
+            return;
         }
-        if (!this.beginRealtimeSync(ns))
+        const pullActive = client._rpcPipeline?.hasPullActivity?.(ns) === true;
+        if (pullActive || !this.beginRealtimeSync(ns)) {
+            this.recordPendingPull(ns, seq);
+            client._clientLog?.debug(`V2 group push queued behind in-flight realtime sync: ns=${ns} seq=${seq}`);
             return;
+        }
         try {
             // namespace 串行区必须覆盖 Tail 与其后至多一次 Forward 的完整周期。
-            await this.runGroupRealtimeSync(groupId, ns, seq, 50, inlinePresent && (!inlineMatches || pendingConflict));
+            await this.runGroupRealtimeSync(groupId, ns, seq, 50, false);
         }
         catch (exc) {
             client._clientLog.warn(`V2 group push auto-sync failed: group=${groupId} err=${formatDeliveryError(exc)}`);
         }
         finally {
             this.endRealtimeSync(ns);
+            this.schedulePendingPullIfNeeded(ns, 'push-auto-pull-complete');
         }
     }
     async onV2PushNotification(data) {
@@ -2558,6 +2969,12 @@ export class MessageDeliveryEngine {
         const ns = client._aid ? `p2p:${client._aid}` : '';
         if (!ns)
             return;
+        if (isJsonObject(data) && String(data.kind ?? '').trim() === 'message.online_unread_hint') {
+            if (client._sessionOptions?.background_sync === false)
+                return;
+            this.enqueueOnlineUnreadP2pHint(data);
+            return;
+        }
         const pushSeq = isJsonObject(data) && typeof data.seq === 'number' ? data.seq : 0;
         if (client._v2Session && Number.isSafeInteger(pushSeq) && pushSeq > 0) {
             // 与 Group 相同，在排队前暴露更高 Head 给当前在途 Tail。
@@ -2606,30 +3023,42 @@ export class MessageDeliveryEngine {
         const before = this.syncState(ns);
         if (strictSeq || !inlinePresent)
             client._seqTracker.updateMaxSeen(ns, pushSeq);
-        if ((!inlinePresent || inlineMatches) && !pendingConflict) {
-            if (pushSeq <= before.head && before.ack >= before.tail - 1) {
-                const pending = this.pendingP2PInlineAcks?.get(ns);
-                if (pending && pushSeq >= pending.seq) {
-                    this.retryPendingP2PInlineAck(ns, pending.seq, 'covered inline P2P ack', pushSeq);
-                }
-                else if (inlineMatches) {
-                    this.fireP2PV2Ack(pushSeq, 'P2P inline covered push ack', inlineGeneration);
-                }
-                return;
+        if (pushSeq <= before.ack && before.ack >= before.tail - 1) {
+            const pending = this.pendingP2PInlineAcks?.get(ns);
+            if (pending && pushSeq >= pending.seq) {
+                this.retryPendingP2PInlineAck(ns, pending.seq, 'covered inline P2P ack', pushSeq);
             }
+            else if (inlineMatches) {
+                this.fireP2PV2Ack(pushSeq, 'P2P inline covered push ack', inlineGeneration);
+            }
+            return;
         }
-        if (!this.beginRealtimeSync(ns))
+        const pullActive = client._rpcPipeline?.hasPullActivity?.(ns) === true;
+        if (pullActive || !this.beginRealtimeSync(ns)) {
+            this.recordPendingPull(ns, pushSeq);
+            client._clientLog?.debug(`V2 P2P push queued behind in-flight realtime sync: ns=${ns} seq=${pushSeq}`);
             return;
+        }
         try {
-            await this.runP2PRealtimeSync(ns, pushSeq, 50, inlinePresent && (!inlineMatches || pendingConflict));
+            await this.runP2PRealtimeSync(ns, pushSeq, 50, false);
         }
         catch (exc) {
             client._clientLog.warn(`V2 P2P push auto-sync failed: ${formatDeliveryError(exc)}`);
         }
         finally {
             this.endRealtimeSync(ns);
+            this.schedulePendingPullIfNeeded(ns, 'push-auto-pull-complete');
         }
     }
+    enqueueOnlineUnreadP2pHint(data) {
+        const client = this.runtime.client;
+        if (!client._aid || !client._v2Session)
+            return;
+        const ns = `p2p:${client._aid}`;
+        client._safeAsync(this.runP2PForwardRecovery(ns, 50, true).catch((exc) => {
+            client._clientLog?.debug(`P2P online unread hint background Forward failed: ns=${ns} err=${formatDeliveryError(exc)}`);
+        }));
+    }
     async restoreSeqTrackerState() {
         const client = this.runtime.client;
         if (!client._aid)
@@ -2745,8 +3174,14 @@ export class MessageDeliveryEngine {
         if (![state.ack, state.tail, state.head].some((value) => Number(value) > 0))
             return;
         const [aid, deviceId, slotId] = JSON.parse(context);
-        await this.writeSeqTrackerState(aid, deviceId, slotId, { [ns]: state }, true);
-        this.dropSeqTrackerPending(ns);
+        const pendingBeforeCommit = this.takeSeqTrackerPending(context, ns);
+        try {
+            await this.writeSeqTrackerState(aid, deviceId, slotId, { [ns]: state }, true);
+        }
+        catch (exc) {
+            this.restoreSeqTrackerPending(context, ns, pendingBeforeCommit);
+            throw exc;
+        }
         client._clientLog.debug(`seq_tracker atomic commit: ns=${ns} A/T/H=${JSON.stringify(state)} context=${context}`);
     }
     async flushSeqTrackerPending() {
@@ -2773,6 +3208,34 @@ export class MessageDeliveryEngine {
             this.cancelSeqTrackerFlushTimer();
         }
     }
+    takeSeqTrackerPending(context, ns) {
+        const client = this.runtime.client;
+        if (client._seqTrackerPendingPersistContext !== context)
+            return null;
+        const pending = this.seqTrackerPending();
+        const state = pending.get(ns);
+        if (!state)
+            return null;
+        pending.delete(ns);
+        if (pending.size === 0) {
+            client._seqTrackerPendingPersistContext = null;
+            this.cancelSeqTrackerFlushTimer();
+        }
+        return { ...state };
+    }
+    restoreSeqTrackerPending(context, ns, state) {
+        if (!state || this.currentSeqTrackerContext() !== context)
+            return;
+        const client = this.runtime.client;
+        const pendingContext = client._seqTrackerPendingPersistContext;
+        if (pendingContext && pendingContext !== context)
+            return;
+        const pending = this.seqTrackerPending();
+        if (!pending.has(ns))
+            pending.set(ns, state);
+        client._seqTrackerPendingPersistContext = context;
+        this.scheduleSeqTrackerFlush();
+    }
     currentSeqTrackerContext() {
         const client = this.runtime.client;
         if (!client._aid)
@@ -2823,6 +3286,14 @@ export class MessageDeliveryEngine {
         }
     }
     async writeSeqTrackerState(aid, deviceId, slotId, state, throwOnError = false) {
+        await this.enqueueSeqTrackerWrite(() => this.writeSeqTrackerStateNow(aid, deviceId, slotId, state, throwOnError));
+    }
+    enqueueSeqTrackerWrite(operation) {
+        const run = this.seqTrackerWriteChain.then(operation, operation);
+        this.seqTrackerWriteChain = run.catch(() => { });
+        return run;
+    }
+    async writeSeqTrackerStateNow(aid, deviceId, slotId, state, throwOnError = false) {
         const client = this.runtime.client;
         if (!aid || Object.keys(state).length === 0)
             return;
@@ -2865,41 +3336,56 @@ export class MessageDeliveryEngine {
         const client = this.runtime.client;
         if (!client._aid || !ns)
             return;
+        const aid = client._aid;
+        const deviceId = client._deviceId;
+        const slotId = client._slotId;
         const seq = client._seqTracker.getContiguousSeq(ns);
         this.dropSeqTrackerPending(ns);
-        try {
-            if (seq > 0 && typeof client._tokenStore.saveSeq === 'function') {
-                client._tokenStore.saveSeq(client._aid, client._deviceId, client._slotId, ns, seq).catch((exc) => {
+        const saveSeq = client._tokenStore.saveSeq;
+        if (seq > 0 && typeof saveSeq === 'function') {
+            void this.enqueueSeqTrackerWrite(async () => {
+                try {
+                    await saveSeq.call(client._tokenStore, aid, deviceId, slotId, ns, seq);
+                }
+                catch (exc) {
                     client._clientLog.debug(`persist repaired seq failed: ns=${ns} err=${formatDeliveryError(exc)}`);
-                });
-                return;
-            }
-            const deleteSeq = client._tokenStore.deleteSeq;
-            if (seq <= 0 && typeof deleteSeq === 'function') {
-                deleteSeq.call(client._tokenStore, client._aid, client._deviceId, client._slotId, ns).catch((exc) => {
+                }
+            });
+            return;
+        }
+        const deleteSeq = client._tokenStore.deleteSeq;
+        if (seq <= 0 && typeof deleteSeq === 'function') {
+            void this.enqueueSeqTrackerWrite(async () => {
+                try {
+                    await deleteSeq.call(client._tokenStore, aid, deviceId, slotId, ns);
+                }
+                catch (exc) {
                     client._clientLog.debug(`delete repaired seq failed: ns=${ns} err=${formatDeliveryError(exc)}`);
-                });
-                return;
-            }
-            if (seq <= 0 && typeof client._tokenStore.updateInstanceState === 'function') {
-                Promise.resolve(client._tokenStore.updateInstanceState(client._aid, client._deviceId, client._slotId, (current) => {
-                    if (isJsonObject(current.seq_tracker_state)) {
-                        const next = { ...current.seq_tracker_state };
-                        delete next[ns];
-                        current.seq_tracker_state = next;
-                    }
-                    return current;
-                })).catch((exc) => {
+                }
+            });
+            return;
+        }
+        const updater = client._tokenStore.updateInstanceState;
+        if (seq <= 0 && typeof updater === 'function') {
+            void this.enqueueSeqTrackerWrite(async () => {
+                try {
+                    await updater.call(client._tokenStore, aid, deviceId, slotId, (current) => {
+                        if (isJsonObject(current.seq_tracker_state)) {
+                            const next = { ...current.seq_tracker_state };
+                            delete next[ns];
+                            current.seq_tracker_state = next;
+                        }
+                        return current;
+                    });
+                }
+                catch (exc) {
                     client._clientLog.debug(`delete repaired seq failed: ns=${ns} err=${formatDeliveryError(exc)}`);
-                });
-                return;
-            }
-            if (seq > 0) {
-                void this.saveSeqTrackerState();
-            }
+                }
+            });
+            return;
         }
-        catch (exc) {
-            client._clientLog.debug(`persist repaired seq failed: ns=${ns} err=${formatDeliveryError(exc)}`);
+        if (seq > 0) {
+            void this.saveSeqTrackerState();
         }
     }
     clampAckSeq(method, field, ns, seq) {
@@ -2960,8 +3446,9 @@ export class MessageDeliveryEngine {
         }
         return params;
     }
-    async drainOrderedMessages(ns, beforeSeq, pullResponse = false) {
+    async drainOrderedMessages(ns, beforeSeq, pullResponse = false, persist = true) {
         const client = this.runtime.client;
+        this.ensurePullOperationCurrent();
         const queue = client._pendingOrderedMsgs.get(ns);
         if (!queue || queue.size === 0)
             return;
@@ -2971,18 +3458,22 @@ export class MessageDeliveryEngine {
             .sort((a, b) => a - b);
         let delivered = false;
         for (const seq of ready) {
+            this.ensurePullOperationCurrent();
             const item = queue.get(seq);
             queue.delete(seq);
             if (!item || client._pushedSeqs.get(ns)?.has(seq))
                 continue;
             await this.publishOrderedQueueItem(ns, item.event, seq, item.payload, pullResponse);
+            this.ensurePullOperationCurrent();
             this.markPublishedSeq(ns, seq);
             delivered = true;
         }
         if (queue.size === 0) {
             client._pendingOrderedMsgs.delete(ns);
-            if (delivered)
+            if (delivered && persist) {
+                this.ensurePullOperationCurrent();
                 await this.saveSeqTrackerState();
+            }
         }
     }
     async publishOrderedMessage(event, ns, seq, payload) {
@@ -3018,14 +3509,18 @@ export class MessageDeliveryEngine {
             await this.saveSeqTrackerState();
         return true;
     }
-    async publishPulledMessage(event, ns, seq, payload) {
+    async publishPulledMessage(event, ns, seq, payload, persist = true) {
         const client = this.runtime.client;
+        this.ensurePullOperationCurrent();
         const seqNum = Number(seq);
         if (!Number.isFinite(seqNum) || !Number.isInteger(seqNum) || seqNum <= 0 || !ns) {
             if (event === 'message.recalled') {
-                return await client._withPullResponseProcessing(ns, () => this.publishMessageRecallTombstone(seq, payload));
+                const published = await client._withPullResponseProcessing(ns, () => this.publishMessageRecallTombstone(seq, payload));
+                this.ensurePullOperationCurrent();
+                return published;
             }
             await client._withPullResponseProcessing(ns, () => client._publishAppEvent(event, payload));
+            this.ensurePullOperationCurrent();
             return true;
         }
         const queue = client._pendingOrderedMsgs.get(ns);
@@ -3035,16 +3530,19 @@ export class MessageDeliveryEngine {
                 client._pendingOrderedMsgs.delete(ns);
             return false;
         }
-        await this.drainOrderedMessages(ns, seqNum);
+        await this.drainOrderedMessages(ns, seqNum, false, persist);
+        this.ensurePullOperationCurrent();
         queue?.delete(seqNum);
         if (queue && queue.size === 0)
             client._pendingOrderedMsgs.delete(ns);
         if (event === 'message.recalled') {
             const published = await client._withPullResponseProcessing(ns, () => this.publishMessageRecallTombstone(seqNum, payload));
+            this.ensurePullOperationCurrent();
             this.markPublishedSeq(ns, seqNum);
             return published;
         }
         await client._withPullResponseProcessing(ns, () => client._publishAppEvent(event, payload));
+        this.ensurePullOperationCurrent();
         this.markPublishedSeq(ns, seqNum);
         return true;
     }