@agentunion/fastaun 0.5.24 → 0.5.26

package/dist/client/delivery.js

@@ -149,6 +149,7 @@ export class MessageDeliveryEngine {
     peerPageChains = new Map();
     automaticPullFailures = new Map();
     terminalGroupPulls = new Map();
+    groupPullVersions = new Map();
     automaticPullOperations = new WeakSet();
     automaticPullContext = new AsyncLocalStorage();
     automaticPullAbort = new AbortController();
@@ -160,6 +161,7 @@ export class MessageDeliveryEngine {
         this.automaticPullAbort = new AbortController();
         this.automaticPullFailures.clear();
         this.terminalGroupPulls.clear();
+        this.groupPullVersions.clear();
     }
     groupPullNamespace(namespace) {
         const groupId = namespace.startsWith('group_event:') ? namespace.slice('group_event:'.length)
@@ -173,15 +175,43 @@ export class MessageDeliveryEngine {
         if (!this.automaticPullContext.getStore())
             this.terminalGroupPulls.delete(this.groupPullNamespace(namespace));
     }
+    observeGroupUnblocked(groupId) {
+        const normalized = normalizeGroupAid(groupId);
+        if (!normalized)
+            return;
+        const canonical = `group:${normalized}`;
+        this.groupPullVersions.set(canonical, {});
+        const stopped = this.terminalGroupPulls.get(canonical);
+        if (!stopped)
+            return;
+        this.terminalGroupPulls.delete(canonical);
+        const client = this.runtime.client;
+        if (client._sessionOptions?.background_sync === false || client._closing || client.state !== ConnectionState.READY)
+            return;
+        const namespaces = [...stopped.namespaces, ...Object.keys(client._seqTracker.exportSyncState?.() ?? client._seqTracker.exportState())];
+        for (const prefix of ['group:', 'group_event:']) {
+            const ns = namespaces.find((candidate) => candidate.startsWith(prefix) && this.groupPullNamespace(candidate) === canonical) ?? `${prefix}${groupId}`;
+            this.recordBackgroundPullNeed(ns, client._seqTracker.getMaxSeenSeq(ns), true, true);
+        }
+        this.requestBackgroundPullRecovery();
+    }
     stopAutomaticGroupPull(namespace, error) {
         const canonical = this.groupPullNamespace(namespace);
         if (!canonical)
             return;
-        this.terminalGroupPulls.set(canonical, error);
+        const namespaces = this.terminalGroupPulls.get(canonical)?.namespaces ?? new Set();
+        namespaces.add(namespace);
+        for (const ns of [...this.backgroundPullTasks, ...(this.realtimeSyncing ?? []), ...(this.onlineUnreadHintTasks?.keys() ?? [])]) {
+            if (this.groupPullNamespace(ns) === canonical)
+                namespaces.add(ns);
+        }
+        this.terminalGroupPulls.set(canonical, { error, namespaces });
         for (const pending of [this.automaticPullFailures, this.backgroundPullNeeds, this.pendingGroupPullUpper, this.onlineUnreadHintTargets]) {
             for (const ns of pending?.keys() ?? []) {
-                if (this.groupPullNamespace(ns) === canonical)
+                if (this.groupPullNamespace(ns) === canonical) {
+                    namespaces.add(ns);
                     pending.delete(ns);
+                }
             }
         }
     }
@@ -194,10 +224,13 @@ export class MessageDeliveryEngine {
     async runAutomaticPull(namespace, operation, schedule) {
         this.ensurePeerContext();
         if (this.automaticGroupPullStopped(namespace))
-            throw this.terminalGroupPulls.get(this.groupPullNamespace(namespace));
+            throw this.terminalGroupPulls.get(this.groupPullNamespace(namespace)).error;
         const nested = this.automaticPullContext.getStore() === namespace;
         const generation = this.captureInlineAckGeneration();
         const signal = this.automaticPullAbort.signal;
+        const groupNamespace = this.groupPullNamespace(namespace);
+        const groupVersion = this.groupPullVersions.get(groupNamespace);
+        const groupCurrent = () => this.groupPullVersions.get(groupNamespace) === groupVersion;
         const client = this.runtime.client;
         while ((this.automaticPullFailures.get(namespace)?.retryAt ?? 0) > Date.now()) {
             const delay = this.automaticPullFailures.get(namespace).retryAt - Date.now();
@@ -210,20 +243,26 @@ export class MessageDeliveryEngine {
                 signal.addEventListener('abort', abort, { once: true });
             });
         }
-        if (signal.aborted || generation !== this.captureInlineAckGeneration() || client._closing || client.state !== ConnectionState.READY) {
+        if (signal.aborted || generation !== this.captureInlineAckGeneration() || !groupCurrent() || client._closing || client.state !== ConnectionState.READY) {
             throw new Error('pull invalidated');
         }
         const attempt = async () => {
+            if (!groupCurrent())
+                throw new Error('pull invalidated');
             if (this.automaticGroupPullStopped(namespace))
-                throw this.terminalGroupPulls.get(this.groupPullNamespace(namespace));
+                throw this.terminalGroupPulls.get(this.groupPullNamespace(namespace)).error;
             const previousFailure = this.automaticPullFailures.get(namespace);
             try {
                 const result = await this.automaticPullContext.run(namespace, operation);
+                if (!groupCurrent())
+                    throw new Error('pull invalidated');
                 if (!nested && !signal.aborted && generation === this.captureInlineAckGeneration())
                     this.automaticPullFailures.delete(namespace);
                 return result;
             }
             catch (error) {
+                if (!groupCurrent())
+                    throw new Error('pull invalidated');
                 if (!signal.aborted && generation === this.captureInlineAckGeneration()
                     && this.groupPullNamespace(namespace) && isTerminalGroupPullError(error)) {
                     this.stopAutomaticGroupPull(namespace, error);
@@ -627,6 +666,11 @@ export class MessageDeliveryEngine {
             && this.peerCatalogVersion === version.catalog && this.runtime.client._seqTracker.getMaxSeenSeq(namespace) <= committedAck
             && this.peerPullPriority(namespace) <= committedAck && this.syncState(namespace).head <= committedAck;
     }
+    isPeerHeadCovered(namespace, head) {
+        const committedAck = this.peerCommittedAck(namespace);
+        return Number.isSafeInteger(head) && head > 0 && head <= committedAck
+            && (this.peerServerConfirmedAcks.get(namespace) ?? 0) >= committedAck;
+    }
     shouldTailPeer(namespace, head, limit, expectedForwardNeed) {
         const state = this.syncState(namespace);
         const knownHead = Math.max(head, state.head, this.runtime.client._seqTracker.getMaxSeenSeq(namespace), this.peerPullPriority(namespace));
@@ -644,7 +688,7 @@ export class MessageDeliveryEngine {
             && this.peerPullPriority(namespace) <= committedAck
             && this.peerPushVersions.get(namespace) === pushVersion
             && this.peerCatalogVersion === catalogVersion
-            && (!need || (need === expectedNeed && !need.pending && need.head <= committedAck));
+            && (!need || (need === expectedNeed && need.head <= committedAck));
     }
     async pullPeers(params = {}, background = false) {
         const client = this.runtime.client;
@@ -794,12 +838,16 @@ export class MessageDeliveryEngine {
             }
         }
         const namespace = this.peerNamespace(sender);
-        this.peerPushVersions.set(namespace, {});
+        if (!Number.isSafeInteger(head) || head <= 0 || volatile)
+            this.peerPushVersions.set(namespace, {});
+        else if (this.initializedPeers.has(namespace) && client._seqTracker.snapshotNamespace(namespace) !== null)
+            client._seqTracker.updateMaxSeen(namespace, head);
         if (!this.hasP2pApplicationSubscription() || client._sessionOptions?.background_sync === false) {
             this.peerForwardNeeds.set(namespace, {});
             return;
         }
         const need = this.peerRecoveryNeeds.get(sender) ?? { head: 0, volatile: false, pending: false };
+        need.paused = false;
         need.head = Math.max(need.head, head);
         need.volatile ||= volatile;
         need.pending = true;
@@ -812,6 +860,8 @@ export class MessageDeliveryEngine {
             if (!this.hasP2pApplicationSubscription())
                 return;
             const namespace = this.peerNamespace(sender);
+            if (Number.isSafeInteger(need.head) && need.head > 0)
+                client._seqTracker.updateMaxSeen(namespace, need.head);
             if (this.shouldTailPeer(namespace, need.head, _INTERNAL_MESSAGE_FLOW_LIMITS.pullPageSize)) {
                 const forwardNeed = {};
                 this.peerForwardNeeds.set(namespace, forwardNeed);
@@ -822,19 +872,28 @@ export class MessageDeliveryEngine {
                 const tail = await this.runAutomaticPull(namespace, async () => {
                     const beforeAck = this.peerCommittedAck(namespace);
                     const beforeVolatile = this.peerVolatilePullCursor(sender);
+                    const beforeWindow = this.syncState(namespace);
                     const result = await client._v2E2EE.pullPeerV2(sender, { window_mode: 'tail', background: true, retainMessages: false, budget: { remaining: 1 }, autoTail });
-                    if (autoTail.forward && !result.complete && this.peerCommittedAck(namespace) <= beforeAck && this.peerVolatilePullCursor(sender) === beforeVolatile) {
-                        throw new Error('peer recovery made no progress');
+                    need.volatile ||= result.volatile_has_more === true;
+                    const afterWindow = this.syncState(namespace);
+                    if (autoTail.forward && (!result.complete || Number(result.ack_seq) < need.head) && this.peerCommittedAck(namespace) <= beforeAck && this.peerVolatilePullCursor(sender) === beforeVolatile
+                        && afterWindow.tail === beforeWindow.tail && afterWindow.head === beforeWindow.head) {
+                        if (!result.pending_ack_seq && !need.pending && this.peerPushVersions.get(namespace) === pushVersion && this.peerCatalogVersion === catalogVersion)
+                            need.paused = true;
+                        else if (result.pending_ack_seq)
+                            throw new Error('peer recovery made no progress');
                     }
                     return result;
                 });
                 if (generation !== this.captureInlineAckGeneration() || this.peerRecoveryNeeds.get(sender) !== need)
                     return;
+                if (need.paused)
+                    return;
                 if (autoTail.forward) {
                     if (tail.complete && this.peerForwardNeeds.get(namespace) === forwardNeed
                         && this.peerPushVersions.get(namespace) === pushVersion && this.peerCatalogVersion === catalogVersion)
                         this.peerForwardNeeds.delete(namespace);
-                    if (tail.complete && Number(tail.ack_seq) >= need.head && !need.pending
+                    if (tail.complete && Number(tail.ack_seq) >= need.head
                         && this.peerPushVersions.get(namespace) === pushVersion && this.peerCatalogVersion === catalogVersion) {
                         this.peerRecoveryNeeds.delete(sender);
                         return;
@@ -856,18 +915,27 @@ export class MessageDeliveryEngine {
                 const result = await this.runAutomaticPull(namespace, async () => {
                     const beforeAck = this.peerCommittedAck(namespace);
                     const beforeVolatile = this.peerVolatilePullCursor(sender);
+                    const beforeWindow = this.syncState(namespace);
                     const result = await client._v2E2EE.pullPeerV2(sender, { background: true, retainMessages: false, budget: { remaining: 100 } });
-                    if (!result.complete && this.peerCommittedAck(namespace) <= beforeAck && this.peerVolatilePullCursor(sender) === beforeVolatile) {
-                        throw new Error('peer recovery made no progress');
+                    need.volatile ||= result.volatile_has_more === true;
+                    const afterWindow = this.syncState(namespace);
+                    if ((!result.complete || result.ack_seq < need.head) && this.peerCommittedAck(namespace) <= beforeAck && this.peerVolatilePullCursor(sender) === beforeVolatile
+                        && afterWindow.tail === beforeWindow.tail && afterWindow.head === beforeWindow.head) {
+                        if (!result.pending_ack_seq && !need.pending && this.peerPushVersions.get(namespace) === pushVersion && this.peerCatalogVersion === catalogVersion)
+                            need.paused = true;
+                        else if (result.pending_ack_seq)
+                            throw new Error('peer recovery made no progress');
                     }
                     return result;
                 });
                 if (generation !== this.captureInlineAckGeneration() || this.peerRecoveryNeeds.get(sender) !== need)
                     return;
+                if (need.paused)
+                    return;
                 if (result.complete && this.peerForwardNeeds.get(namespace) === forwardNeed
                     && this.peerPushVersions.get(namespace) === pushVersion && this.peerCatalogVersion === catalogVersion)
                     this.peerForwardNeeds.delete(namespace);
-                if (result.complete && result.ack_seq >= need.head && !need.pending
+                if (result.complete && result.ack_seq >= need.head
                     && this.peerPushVersions.get(namespace) === pushVersion && this.peerCatalogVersion === catalogVersion) {
                     this.peerRecoveryNeeds.delete(sender);
                     break;
@@ -879,12 +947,18 @@ export class MessageDeliveryEngine {
         client._safeAsync(task.catch(() => {
             if (generation !== this.captureInlineAckGeneration())
                 return;
-            const timer = setTimeout(() => { if (generation === this.captureInlineAckGeneration())
-                this.schedulePeerRecovery(sender, need.head, need.volatile); }, BACKGROUND_PULL_RETRY_DELAY_MS);
+            const timer = setTimeout(() => {
+                if (generation === this.captureInlineAckGeneration() && this.peerRecoveryNeeds.get(sender) === need
+                    && !need.paused && !this.peerRecoveryTasks.has(sender))
+                    this.schedulePeerRecovery(sender, need.head, need.volatile);
+            }, BACKGROUND_PULL_RETRY_DELAY_MS);
             timer.unref?.();
         }).finally(() => {
             if (generation === this.captureInlineAckGeneration()) {
                 this.peerRecoveryTasks.delete(sender);
+                const pending = this.peerRecoveryNeeds.get(sender);
+                if (pending?.pending && !pending.paused)
+                    this.requestBackgroundPullRecovery();
                 if (this.peerCatalogDirty && this.peerRecoveryTasks.size === 0)
                     this.refreshPendingPeers();
             }
@@ -1587,9 +1661,9 @@ export class MessageDeliveryEngine {
         return this.pendingGroupPullUpper?.get(ns) ?? 0;
     }
     hasAnyPendingPull() {
-        return this.peerCatalogDirty || this.peerRecoveryNeeds.size > 0 || this.peerRecoveryTasks.size > 0 || Boolean(this.peerCatalogTask)
+        return this.peerCatalogDirty || [...this.peerRecoveryNeeds.values()].some((need) => !need.paused) || this.peerRecoveryTasks.size > 0 || Boolean(this.peerCatalogTask)
             || [...(this.pendingGroupPullUpper?.values() ?? [])].some((seq) => seq > 0)
-            || this.backgroundPullNeeds.size > 0
+            || [...this.backgroundPullNeeds.values()].some((need) => need.retryAt !== Infinity)
             || Boolean(this.onlineUnreadHintTasks?.size)
             || Boolean(this.realtimeSyncing?.size)
             || Boolean(this.runtime.client._v2E2EE?.hasPendingSenderIKWork?.());
@@ -1604,7 +1678,7 @@ export class MessageDeliveryEngine {
         }
         this.schedulePendingGroupPullIfNeeded(ns, 'pull-gate-idle');
     }
-    recordBackgroundPullNeed(ns, throughSeq = 0, probe = false) {
+    recordBackgroundPullNeed(ns, throughSeq = 0, probe = false, restart = false) {
         if (this.automaticGroupPullStopped(ns))
             return;
         const client = this.runtime.client;
@@ -1612,8 +1686,14 @@ export class MessageDeliveryEngine {
             || !(ns === `p2p:${client._aid}` || ns.startsWith('group:') || ns.startsWith('group_event:')))
             return;
         const need = this.backgroundPullNeeds.get(ns) ?? {
-            throughSeq: 0, hasMore: false, probe, lastAfter: -1, retryAt: 0,
+            throughSeq: 0, hasMore: false, probe, lastAfter: -1, retryAt: 0, empty: false, trigger: {},
         };
+        if (restart) {
+            need.trigger = {};
+            need.retryAt = 0;
+            need.empty = false;
+            need.progress = undefined;
+        }
         need.throughSeq = Math.max(need.throughSeq, throughSeq);
         need.probe ||= probe;
         this.backgroundPullNeeds.set(ns, need);
@@ -1627,30 +1707,46 @@ export class MessageDeliveryEngine {
             return;
         const cursor = isJsonObject(response.cursor)
             ? response.cursor : null;
-        const throughSeq = Math.max(positiveSafeSequenceHint(cursor?.latest_seq), positiveSafeSequenceHint(response.latest_seq), positiveSafeSequenceHint(response.latest_message_seq), positiveSafeSequenceHint(response.latest_event_seq), ...rows.map((row) => row && typeof row === 'object' && row.storage !== 'volatile'
+        const serverHead = Math.max(positiveSafeSequenceHint(cursor?.latest_seq), positiveSafeSequenceHint(response.latest_seq), positiveSafeSequenceHint(response.latest_message_seq), positiveSafeSequenceHint(response.latest_event_seq));
+        const throughSeq = Math.max(serverHead, ...rows.map((row) => row && typeof row === 'object' && row.storage !== 'volatile'
             ? positiveSafeSequenceHint(row.seq ?? row.event_seq) : 0));
         this.recordBackgroundPullNeed(ns, throughSeq);
         const need = this.backgroundPullNeeds.get(ns);
         if (!need || afterSeq < need.lastAfter)
             return;
         need.lastAfter = afterSeq;
+        need.progress = { ...this.syncState(ns), volatile: this.volatilePullCursor() };
+        need.empty = rows.length === 0;
         need.hasMore = response.has_more === true || positiveSafeSequenceHint(response.remaining) > 0
-            || (!('has_more' in response) && limit > 0 && rows.length >= limit);
+            || (!('has_more' in response) && serverHead === 0 && limit > 0 && rows.length >= limit);
         need.probe = false;
     }
-    finishBackgroundPull(ns, generation, afterSeq, failed) {
+    finishBackgroundPull(ns, generation, afterSeq, failed, trigger) {
         if (generation !== this.captureInlineAckGeneration())
             return;
         if (this.automaticGroupPullStopped(ns))
             return;
         const need = this.backgroundPullNeeds.get(ns);
+        if (need && trigger && need.trigger !== trigger) {
+            need.retryAt = Date.now() + BACKGROUND_PULL_RETRY_DELAY_MS;
+            this.requestBackgroundPullRecovery();
+            return;
+        }
         if (need) {
             if (failed)
                 need.probe = true;
             else
                 need.probe = false;
-            need.retryAt = failed || this.syncState(ns).ack <= afterSeq
-                ? Date.now() + BACKGROUND_PULL_RETRY_DELAY_MS : 0;
+            const client = this.runtime.client;
+            const state = this.syncState(ns);
+            const ack = state.ack;
+            const coordinator = client._v2E2EE;
+            const pendingAck = coordinator?.pendingForwardAck?.(ns, ack) ?? 0;
+            const noProgress = need.progress ? ack <= need.progress.ack && state.tail === need.progress.tail && state.head === need.progress.head
+                && this.volatilePullCursor() === need.progress.volatile : need.empty && ack <= Math.max(afterSeq, need.lastAfter);
+            need.retryAt = !failed && noProgress && trigger === need.trigger
+                && !pendingAck && !this.pendingP2PInlineAcks?.has(ns) && !this.pendingGroupInlineAcks?.has(ns)
+                ? Infinity : failed || ack <= afterSeq ? Date.now() + BACKGROUND_PULL_RETRY_DELAY_MS : 0;
         }
         this.requestBackgroundPullRecovery();
     }
@@ -1670,7 +1766,7 @@ export class MessageDeliveryEngine {
                 if (this.peerCatalogDirty && !this.peerCatalogTask)
                     this.refreshPendingPeers();
                 for (const [sender, need] of this.peerRecoveryNeeds) {
-                    if (!this.peerRecoveryTasks.has(sender))
+                    if (!need.paused && !this.peerRecoveryTasks.has(sender))
                         this.schedulePeerRecovery(sender, need.head, need.volatile);
                 }
             }
@@ -1741,6 +1837,8 @@ export class MessageDeliveryEngine {
             || client.state !== ConnectionState.READY || client._closing)
             return;
         const ns = `p2p:${client._aid}`;
+        if (this.backgroundPullNeeds.get(ns)?.retryAt === Infinity)
+            return;
         const state = this.syncState(ns);
         const maxSeen = client._seqTracker.getMaxSeenSeq(ns);
         if (maxSeen <= state.ack && state.ack >= state.tail - 1)
@@ -2930,6 +3028,7 @@ export class MessageDeliveryEngine {
             return;
         client._gapFillDone.set(dedupKey, Date.now());
         this.recordBackgroundPullNeed(ns, 0, true);
+        const pullTrigger = this.backgroundPullNeeds.get(ns)?.trigger;
         client._clientLog.debug(`P2P message gap fill start: after_seq=${afterSeq}`);
         let filled = 0;
         let failed = false;
@@ -2953,7 +3052,7 @@ export class MessageDeliveryEngine {
                 return;
             client._gapFillDone.delete(dedupKey);
             client._schedulePendingP2pPullIfNeeded?.(ns, 'gap-fill-complete');
-            this.finishBackgroundPull(ns, generation, afterSeq, failed);
+            this.finishBackgroundPull(ns, generation, afterSeq, failed, pullTrigger);
         }
     }
     async fillGroupGap(groupId) {
@@ -2973,6 +3072,7 @@ export class MessageDeliveryEngine {
             return;
         client._gapFillDone.set(dedupKey, Date.now());
         this.recordBackgroundPullNeed(ns, 0, true);
+        const pullTrigger = this.backgroundPullNeeds.get(ns)?.trigger;
         client._clientLog.debug(`group message gap fill start: group=${groupId}, after_seq=${afterSeq}`);
         let filled = 0;
         let failed = false;
@@ -2994,7 +3094,7 @@ export class MessageDeliveryEngine {
                 return;
             client._gapFillDone.delete(dedupKey);
             this.schedulePendingGroupPullIfNeeded(ns, 'gap-fill-complete');
-            this.finishBackgroundPull(ns, generation, afterSeq, failed);
+            this.finishBackgroundPull(ns, generation, afterSeq, failed, pullTrigger);
         }
     }
     scheduleRealtimeWindowForward(ns, groupId = '') {
@@ -3058,6 +3158,7 @@ export class MessageDeliveryEngine {
         }
         client._gapFillDone.set(dedupKey, Date.now());
         this.recordBackgroundPullNeed(ns, client._seqTracker.getMaxSeenSeq(ns), true);
+        const pullTrigger = this.backgroundPullNeeds.get(ns)?.trigger;
         this.syncStarted(ns);
         let filled = 0;
         let continuationAfterSeq = 0;
@@ -3245,7 +3346,7 @@ export class MessageDeliveryEngine {
                     _online_hint_after_event_seq: continuationAfterSeq,
                 });
             }
-            this.finishBackgroundPull(ns, generation, afterSeq, failed);
+            this.finishBackgroundPull(ns, generation, afterSeq, failed, pullTrigger);
             if (!client._rpcPipeline)
                 this.syncStopped(failed ? 'aborted' : 'pull_drained');
         }
@@ -3257,7 +3358,7 @@ export class MessageDeliveryEngine {
             return;
         if (!groupId || client._sessionOptions?.background_sync === false)
             return;
-        this.recordBackgroundPullNeed(`group_event:${groupId}`, positiveSafeSequenceHint(data.event_seq), true);
+        this.recordBackgroundPullNeed(`group_event:${groupId}`, positiveSafeSequenceHint(data.event_seq), true, true);
         const rawAfter = Number(data._online_hint_after_event_seq ?? 0);
         const afterSeq = Number.isSafeInteger(rawAfter) && rawAfter > 0 ? rawAfter : 0;
         client._safeAsync(this.fillGroupEventGap(groupId, {
@@ -4341,17 +4442,36 @@ export class MessageDeliveryEngine {
         if (!isJsonObject(data) || !client._aid || !this.messageTargetsCurrentInstance(data))
             return;
         const head = data;
-        if (String(head.kind ?? '') === 'message.online_unread_hint' || !head.sender_aid) {
+        const legacy = isJsonObject(head.legacy_v1) ? head.legacy_v1 : null;
+        const completeVolatile = this.isVolatileMessage(head) && (head.payload != null || legacy?.payload != null
+            || (typeof head.envelope_json === 'string' && head.envelope_json.trim()));
+        const sender = String(head.sender_aid ?? (completeVolatile ? head.from_aid ?? head.from : undefined) ?? '');
+        if (String(head.kind ?? '') === 'message.online_unread_hint' || !sender) {
             this.refreshPendingPeers();
             return;
         }
-        if (head.cursor_scope !== 'peer') {
+        if (head.cursor_scope !== 'peer' && (head.cursor_scope !== undefined || !completeVolatile)) {
             this.refreshPendingPeers();
             return;
         }
-        const sender = String(head.sender_aid);
         this.ensurePeerContext();
-        this.peerPushVersions.set(this.peerNamespace(sender), {});
+        if (completeVolatile) {
+            await client._v2E2EE.publishV2VolatileMessages([head], 'push', false);
+            return;
+        }
+        const namespace = this.peerNamespace(sender);
+        const seq = positiveSafeSequenceHint(head.seq);
+        const committedAck = this.peerCommittedAck(namespace);
+        if (seq > 0 && !this.isVolatileMessage(head) && !this.isVolatileMessage(head.inline_message)
+            && head.volatile_has_more !== true && seq <= committedAck
+            && !this.peerRecoveryNeeds.get(sender)?.volatile
+            && (this.peerServerConfirmedAcks.get(namespace) ?? 0) >= committedAck)
+            return;
+        const unbounded = !seq || this.isVolatileMessage(head) || this.isVolatileMessage(head.inline_message)
+            || head.volatile_has_more === true || this.peerRecoveryNeeds.get(sender)?.volatile === true;
+        if (unbounded)
+            this.peerPushVersions.set(namespace, {});
+        const peerPullVersion = this.capturePeerTailVersion(sender);
         if (!hasNonEmptyInlineMessage(head.inline_message) && !this.isVolatileMessage(head) && !this.hasP2pApplicationSubscription())
             return;
         const generation = this.captureInlineAckGeneration();
@@ -4364,7 +4484,6 @@ export class MessageDeliveryEngine {
                 this.schedulePeerRecovery(sender, positiveSafeSequenceHint(head.seq) ?? 0, this.isVolatileMessage(head));
             throw error;
         }
-        const seq = positiveSafeSequenceHint(head.seq);
         if (this.isVolatileMessage(head)) {
             await client._v2E2EE.publishV2VolatileMessages([head], 'push', false);
             return;
@@ -4410,16 +4529,20 @@ export class MessageDeliveryEngine {
                     this.schedulePeerRecovery(sender, seq);
                 throw error;
             });
-            if (consumed?.acquired && consumed.value)
+            if (consumed?.acquired && consumed.value && !unbounded)
                 return;
         }
-        if (seq <= this.syncState(ns).ack || !this.hasP2pApplicationSubscription())
+        if ((!unbounded && this.isPeerHeadCovered(ns, seq)) || !this.hasP2pApplicationSubscription())
             return;
         if (client._sessionOptions?.background_sync !== false) {
-            this.schedulePeerRecovery(sender, seq);
+            if (unbounded)
+                this.schedulePeerRecovery(sender, seq, true);
+            else
+                this.schedulePeerRecovery(sender, seq);
         }
         else {
             await this.runAutomaticPull(ns, () => client._v2E2EE.pullPeerV2(sender, { limit: _INTERNAL_MESSAGE_FLOW_LIMITS.pullPageSize, budget: { remaining: 1 },
+                ...(!unbounded ? { autoPeerHead: seq, peerPullVersion } : {}),
                 ...(this.shouldTailPeer(ns, seq, _INTERNAL_MESSAGE_FLOW_LIMITS.pullPageSize) ? { window_mode: 'tail', autoTail: { head: seq, forward: false } } : {}) }));
         }
     }
@@ -4486,13 +4609,15 @@ export class MessageDeliveryEngine {
         }
         if (!this.hasP2pApplicationSubscription())
             return;
-        this.recordBackgroundPullNeed(ns, pushSeq);
+        this.recordBackgroundPullNeed(ns, pushSeq, false, true);
+        const pullTrigger = this.backgroundPullNeeds.get(ns)?.trigger;
         const pullActive = client._rpcPipeline?.hasPullActivity?.(ns) === true;
         if (pullActive || !this.beginRealtimeSync(ns)) {
             client._recordPendingP2pPull(ns, pushSeq);
             client._clientLog.debug(`V2 P2P push queued behind in-flight realtime sync: ns=${ns} seq=${pushSeq}`);
             return;
         }
+        let pullFailed = false;
         try {
             await this.runP2PRealtimeSync(ns, pushSeq, 50, false);
             if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
@@ -4500,12 +4625,13 @@ export class MessageDeliveryEngine {
             // Tail 期间新到达的 Push 已由 realtime sync 在同一周期内补至多一页 Forward。
         }
         catch (exc) {
+            pullFailed = true;
             client._clientLog.warn(`V2 P2P push auto-sync failed: ${formatDeliveryError(exc)}`);
         }
         finally {
             if (syncGeneration === this.captureInlineAckGeneration()
                 && (inlineGeneration === undefined || this.inlineGenerationIsCurrent(inlineGeneration))) {
-                this.finishBackgroundPull(ns, syncGeneration, this.syncState(ns).ack, false);
+                this.finishBackgroundPull(ns, syncGeneration, this.syncState(ns).ack, pullFailed, pullTrigger);
                 this.endRealtimeSync(ns);
                 client._schedulePendingP2pPullIfNeeded?.(ns, 'push-auto-pull-complete');
             }
@@ -4519,14 +4645,34 @@ export class MessageDeliveryEngine {
         const ns = `group:${groupId}`;
         if (this.automaticGroupPullStopped(ns))
             return;
+        this.rememberCommittedSeqState(ns);
         const generation = this.captureInlineAckGeneration();
-        const afterSeq = this.syncState(ns).ack;
-        this.recordBackgroundPullNeed(ns, positiveSafeSequenceHint(data.seq));
+        const state = this.syncState(ns);
+        const afterSeq = state.ack;
+        const hintSeq = positiveSafeSequenceHint(data.seq);
+        const committedAck = Math.min(afterSeq, this.committedSeqTrackerStates.get(ns)?.ack ?? afterSeq);
+        if (hintSeq > 0 && committedAck >= Math.max(hintSeq, state.head, Number(client._seqTracker.getMaxSeenSeq?.(ns) ?? 0), this.pendingPullUpper(ns))
+            && !client._pendingOrderedMsgs.get(ns)?.size) {
+            const coordinator = client._v2E2EE;
+            const pendingAckSeq = Number(coordinator.pendingForwardAck?.(ns, committedAck) ?? 0);
+            if (pendingAckSeq > 0) {
+                client._safeAsync(coordinator.confirmForwardGroupAck(groupId, pendingAckSeq, String(data.group_aid ?? '').trim() || undefined, true));
+            }
+            else {
+                const pendingNs = this.resolvePendingGroupInlineAckNamespace(ns);
+                const pending = this.pendingGroupInlineAcks?.get(pendingNs);
+                if (pending)
+                    this.retryPendingGroupInlineAck(pendingNs, pending.seq, 'covered online hint', committedAck);
+            }
+            return;
+        }
+        this.recordBackgroundPullNeed(ns, hintSeq, false, true);
+        const pullTrigger = this.backgroundPullNeeds.get(ns)?.trigger;
         const targets = this.onlineUnreadHintTargets ?? new Map();
         const tasks = this.onlineUnreadHintTasks ?? new Map();
         this.onlineUnreadHintTargets = targets;
         this.onlineUnreadHintTasks = tasks;
-        targets.set(ns, Math.max(targets.get(ns) ?? 0, positiveSafeSequenceHint(data.seq)));
+        targets.set(ns, Math.max(targets.get(ns) ?? 0, hintSeq));
         if (tasks.has(ns))
             return;
         let attemptAfterSeq = afterSeq;
@@ -4550,7 +4696,7 @@ export class MessageDeliveryEngine {
                 targets.delete(ns);
                 if (tasks.get(ns) === task)
                     tasks.delete(ns);
-                this.finishBackgroundPull(ns, generation, attemptAfterSeq, failed);
+                this.finishBackgroundPull(ns, generation, attemptAfterSeq, failed, pullTrigger);
                 client._rpcPipeline?.requestPullDrainedCheck?.();
             }
         });
@@ -4624,25 +4770,28 @@ export class MessageDeliveryEngine {
             }
             return;
         }
-        this.recordBackgroundPullNeed(ns, seq);
+        this.recordBackgroundPullNeed(ns, seq, false, true);
+        const pullTrigger = this.backgroundPullNeeds.get(ns)?.trigger;
         const pullActive = client._rpcPipeline?.hasPullActivity?.(ns) === true;
         if (pullActive || !this.beginRealtimeSync(ns)) {
             this.recordPendingGroupPull(ns, seq);
             client._clientLog.debug(`V2 group push queued behind in-flight realtime sync: ns=${ns} seq=${seq}`);
             return;
         }
+        let pullFailed = false;
         void this.runGroupRealtimeSync(groupId, ns, seq, 50, false).then(async () => {
             if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
                 return;
             // Tail 期间新到达的 Push 已由 realtime sync 在同一周期内补至多一页 Forward。
         }).catch((exc) => {
+            pullFailed = true;
             if (inlineGeneration !== undefined && !this.inlineGenerationIsCurrent(inlineGeneration))
                 return;
             client._clientLog.warn(`V2 group push auto-sync failed: group=${groupId} err=${formatDeliveryError(exc)}`);
         }).finally(() => {
             if (syncGeneration === this.captureInlineAckGeneration()
                 && (inlineGeneration === undefined || this.inlineGenerationIsCurrent(inlineGeneration))) {
-                this.finishBackgroundPull(ns, syncGeneration, this.syncState(ns).ack, false);
+                this.finishBackgroundPull(ns, syncGeneration, this.syncState(ns).ack, pullFailed, pullTrigger);
                 this.endRealtimeSync(ns);
                 this.schedulePendingGroupPullIfNeeded(ns, 'push-auto-pull-complete');
             }
@@ -4721,12 +4870,13 @@ export class MessageDeliveryEngine {
         const ns = `p2p:${client._aid}`;
         const generation = this.captureInlineAckGeneration();
         const afterSeq = this.syncState(ns).ack;
-        this.recordBackgroundPullNeed(ns, positiveSafeSequenceHint(data.seq), true);
+        this.recordBackgroundPullNeed(ns, positiveSafeSequenceHint(data.seq), true, true);
+        const pullTrigger = this.backgroundPullNeeds.get(ns)?.trigger;
         let failed = false;
         client._safeAsync(this.runP2PForwardRecovery(ns, 50, true).catch((exc) => {
             failed = true;
             client._clientLog.debug(`P2P online unread hint background Forward failed: ns=${ns} err=${formatDeliveryError(exc)}`);
-        }).finally(() => this.finishBackgroundPull(ns, generation, afterSeq, failed)));
+        }).finally(() => this.finishBackgroundPull(ns, generation, afterSeq, failed, pullTrigger)));
     }
     async saveSeqTrackerState() {
         const client = this.runtime.client;