fix(collab): preserve presence through lease gaps

Author: lefarcen

apps/web/src/collab/collab-client.ts

@@ -73,6 +73,10 @@ export interface CollabClientOptions {
 
 const DEFAULT_HEARTBEAT_MS = 10_000;
 const DEFAULT_STATUS_POLL_MS = 5_000;
+// Vela's authoritative project-presence lease is 30 seconds from the
+// server-recorded heartbeatAt, not from when this client happens to observe
+// the roster. Using observation time can nearly double a stale lease.
+const DEFAULT_PRESENCE_ROSTER_GRACE_MS = 30_000;
 
 class CollabRequestError extends Error {
   constructor(message: string, readonly status: number) {
@@ -132,8 +136,10 @@ export class CollabClient {
    */
   private presenceRequestGeneration = 0;
   private presenceAppliedRequestGeneration = 0;
-  /** First successful self-bearing response that omitted each known peer. */
-  private readonly presenceMissingSince = new Map<string, number>();
+  /** Authoritative Vela lease expiry derived from each valid heartbeatAt. */
+  private readonly presenceLeaseExpiresAt = new Map<string, number>();
+  /** Compatibility grace for legacy/local rosters without a valid heartbeatAt. */
+  private readonly presenceFallbackMissingSince = new Map<string, number>();
   /** Suppresses the status-transition echo of an optimistic Team heartbeat. */
   private presenceAttemptedForMember = false;
   /**
@@ -252,7 +258,7 @@ export class CollabClient {
         // the roster converged. This fresh read is only an extra catch-up for
         // events/timers the browser may have throttled in the background, and
         // it preserves the current roster until the response lands.
-        void this.refreshPresence();
+        void this.refreshPresenceAfterVisibility();
         void this.pollStatus();
       };
       document.addEventListener('visibilitychange', this.onVisibilityChange);
@@ -265,7 +271,8 @@ export class CollabClient {
     this.lifecycleGeneration += 1;
     this.presenceRequestGeneration += 1;
     this.presenceAppliedRequestGeneration = this.presenceRequestGeneration;
-    this.presenceMissingSince.clear();
+    this.presenceLeaseExpiresAt.clear();
+    this.presenceFallbackMissingSince.clear();
     for (const timer of this.timers) clearInterval(timer);
     this.timers.length = 0;
     if (this.onVisibilityChange && typeof document !== 'undefined') {
@@ -353,6 +360,18 @@ export class CollabClient {
    * feedback loop, so push-channel consumers must use this read-only path.
    */
   async refreshPresence(): Promise<void> {
+    await this.readFreshPresence(false);
+  }
+
+  /**
+   * Visibility catch-up is not evidence of an explicit viewer-set mutation.
+   * Preserve still-live last-good peers just like a heartbeat response.
+   */
+  private async refreshPresenceAfterVisibility(): Promise<void> {
+    await this.readFreshPresence(true);
+  }
+
+  private async readFreshPresence(preserveMissingPeers: boolean): Promise<void> {
     const requestGeneration = ++this.presenceRequestGeneration;
     try {
       // A hub presence event marks the daemon's short-lived roster cache stale.
@@ -365,6 +384,7 @@ export class CollabClient {
         this.applyPresenceResponse(
           requestGeneration,
           body.present as CollabPresenceMember[],
+          preserveMissingPeers,
         );
       }
     } catch (error) {
@@ -562,10 +582,13 @@ export class CollabClient {
   private applyPresenceResponse(
     requestGeneration: number,
     present: CollabPresenceMember[],
+    preserveMissingPeers = true,
   ): void {
     if (requestGeneration <= this.presenceAppliedRequestGeneration) return;
     this.presenceAppliedRequestGeneration = requestGeneration;
-    this.update({ present: this.stabilizePresenceRoster(present) });
+    this.update({
+      present: this.stabilizePresenceRoster(present, preserveMissingPeers),
+    });
   }
 
   private applyPresenceAuthorityRevocation(requestGeneration: number): void {
@@ -575,12 +598,14 @@ export class CollabClient {
   }
 
   private clearPresenceRoster(): void {
-    this.presenceMissingSince.clear();
+    this.presenceLeaseExpiresAt.clear();
+    this.presenceFallbackMissingSince.clear();
     if (this.snapshot.present.length > 0) this.update({ present: [] });
   }
 
   private stabilizePresenceRoster(
     incoming: CollabPresenceMember[],
+    preserveMissingPeers: boolean,
   ): CollabPresenceMember[] {
     const selfMemberId = this.member?.memberId;
     const incomingIds = new Set(incoming.map((member) => member.memberId));
@@ -592,13 +617,35 @@ export class CollabClient {
       || incoming.length === 0
       || !incomingIds.has(selfMemberId)
     ) {
-      this.presenceMissingSince.clear();
+      this.presenceLeaseExpiresAt.clear();
+      this.presenceFallbackMissingSince.clear();
       return incoming;
     }
 
     const now = Date.now();
-    for (const memberId of incomingIds) {
-      this.presenceMissingSince.delete(memberId);
+    for (const member of incoming) {
+      const heartbeatAt = member.heartbeatAt?.trim();
+      const heartbeatAtMs = heartbeatAt ? Date.parse(heartbeatAt) : Number.NaN;
+      if (Number.isFinite(heartbeatAtMs)) {
+        this.presenceLeaseExpiresAt.set(
+          member.memberId,
+          heartbeatAtMs + DEFAULT_PRESENCE_ROSTER_GRACE_MS,
+        );
+      } else {
+        this.presenceLeaseExpiresAt.delete(member.memberId);
+      }
+      this.presenceFallbackMissingSince.delete(member.memberId);
+    }
+    if (!preserveMissingPeers) {
+      for (const memberId of this.presenceLeaseExpiresAt.keys()) {
+        if (!incomingIds.has(memberId)) this.presenceLeaseExpiresAt.delete(memberId);
+      }
+      for (const memberId of this.presenceFallbackMissingSince.keys()) {
+        if (!incomingIds.has(memberId)) {
+          this.presenceFallbackMissingSince.delete(memberId);
+        }
+      }
+      return incoming;
     }
 
     const retained: CollabPresenceMember[] = [];
@@ -607,18 +654,33 @@ export class CollabClient {
     );
     for (const member of this.snapshot.present) {
       if (incomingIds.has(member.memberId)) continue;
-      const missingSince = this.presenceMissingSince.get(member.memberId);
+      const leaseExpiresAt = this.presenceLeaseExpiresAt.get(member.memberId);
+      if (leaseExpiresAt !== undefined) {
+        if (now < leaseExpiresAt) retained.push(member);
+        else this.presenceLeaseExpiresAt.delete(member.memberId);
+        this.presenceFallbackMissingSince.delete(member.memberId);
+        continue;
+      }
+
+      const missingSince = this.presenceFallbackMissingSince.get(member.memberId);
       if (missingSince === undefined) {
-        this.presenceMissingSince.set(member.memberId, now);
+        this.presenceFallbackMissingSince.set(member.memberId, now);
         retained.push(member);
       } else if (now - missingSince < this.heartbeatMs) {
         retained.push(member);
       } else {
-        this.presenceMissingSince.delete(member.memberId);
+        this.presenceFallbackMissingSince.delete(member.memberId);
       }
     }
-    for (const memberId of this.presenceMissingSince.keys()) {
-      if (!previousIds.has(memberId)) this.presenceMissingSince.delete(memberId);
+    for (const memberId of this.presenceLeaseExpiresAt.keys()) {
+      if (!previousIds.has(memberId) && !incomingIds.has(memberId)) {
+        this.presenceLeaseExpiresAt.delete(memberId);
+      }
+    }
+    for (const memberId of this.presenceFallbackMissingSince.keys()) {
+      if (!previousIds.has(memberId) && !incomingIds.has(memberId)) {
+        this.presenceFallbackMissingSince.delete(memberId);
+      }
     }
     return retained.length > 0 ? [...incoming, ...retained] : incoming;
   }

apps/web/tests/collab-client.test.ts

@@ -1,5 +1,9 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { CollabClient, type CollabSnapshot } from '../src/collab/collab-client.js';
+import {
+  CollabClient,
+  type CollabPresenceMember,
+  type CollabSnapshot,
+} from '../src/collab/collab-client.js';
 import { workspaceContextFixture } from './helpers/workspace-context';
 
 const TEAM_CONTEXT = workspaceContextFixture({
@@ -15,12 +19,16 @@ interface RecordedCall {
 }
 
 interface FakeFetchOptions {
-  present?: Array<{ memberId: string; name?: string }>;
+  present?: CollabPresenceMember[];
   publishedVersion?: number | null;
   syncState?: string | null;
   failPath?: string;
 }
 
+const PRESENCE_TEST_NOW = Date.parse('2026-08-05T00:00:00.000Z');
+const presenceTime = (offsetMs = 0) =>
+  new Date(PRESENCE_TEST_NOW + offsetMs).toISOString();
+
 function makeFetch(options: FakeFetchOptions = {}) {
   const calls: RecordedCall[] = [];
   const state = {
@@ -54,6 +62,7 @@ function makeFetch(options: FakeFetchOptions = {}) {
 
 beforeEach(() => {
   vi.useFakeTimers();
+  vi.setSystemTime(PRESENCE_TEST_NOW);
 });
 
 afterEach(() => {
@@ -627,11 +636,11 @@ describe('CollabClient', () => {
     client.stop();
   });
 
-  it('retains a peer for one heartbeat window when one self-bearing roster omits it', async () => {
+  it('retains a peer for the upstream lease window when self-bearing rosters briefly omit it', async () => {
     const { fetchImpl, state } = makeFetch({
       present: [
-        { memberId: 'viewer', name: 'Viewer' },
-        { memberId: 'peer', name: 'Peer' },
+        { memberId: 'viewer', name: 'Viewer', heartbeatAt: presenceTime() },
+        { memberId: 'peer', name: 'Peer', heartbeatAt: presenceTime() },
       ],
     });
     const client = new CollabClient({
@@ -646,20 +655,154 @@ describe('CollabClient', () => {
     await vi.advanceTimersByTimeAsync(0);
     expect(client.getSnapshot().present).toHaveLength(2);
 
-    state.present = [{ memberId: 'viewer', name: 'Viewer' }];
+    state.present = [{
+      memberId: 'viewer',
+      name: 'Viewer',
+      heartbeatAt: presenceTime(10_000),
+    }];
     await vi.advanceTimersByTimeAsync(10_000);
-    expect(client.getSnapshot().present).toEqual([
-      { memberId: 'viewer', name: 'Viewer' },
-      { memberId: 'peer', name: 'Peer' },
-    ]);
+    expect(client.getSnapshot().present.map(({ memberId }) => memberId))
+      .toEqual(['viewer', 'peer']);
+
+    // The Vela presence lease is authoritative for 30 seconds from the last
+    // roster that actually contained the peer. A delayed heartbeat can make
+    // the peer absent from the 10s and 20s reads without making that last-good
+    // evidence stale. Dropping it after one interval makes the non-owner side
+    // flicker while the owner's local self witness hides the same upstream gap.
+    await vi.advanceTimersByTimeAsync(19_999);
+    expect(client.getSnapshot().present.map(({ memberId }) => memberId))
+      .toEqual(['viewer', 'peer']);
+
+    // At the exact upstream TTL boundary the peer is no longer retained.
+    await vi.advanceTimersByTimeAsync(1);
+    expect(client.getSnapshot().present.map(({ memberId }) => memberId))
+      .toEqual(['viewer']);
+
+    client.stop();
+  });
+
+  it('never flashes a known peer when it returns before the upstream lease window ends', async () => {
+    const { fetchImpl, state } = makeFetch({
+      present: [
+        { memberId: 'viewer', name: 'Viewer', heartbeatAt: presenceTime() },
+        { memberId: 'owner', name: 'Owner', heartbeatAt: presenceTime() },
+      ],
+    });
+    const snapshots: CollabPresenceMember[][] = [];
+    const client = new CollabClient({
+      projectId: 'p-owner-transient-gap',
+      member: { memberId: 'viewer', name: 'Viewer' },
+      fetch: fetchImpl,
+      heartbeatMs: 10_000,
+      onUpdate: (snapshot) => snapshots.push(snapshot.present),
+    });
 
-    await vi.advanceTimersByTimeAsync(9_999);
+    client.start();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(client.getSnapshot().present.map(({ memberId }) => memberId))
+      .toEqual(['viewer', 'owner']);
+    snapshots.length = 0;
+    state.present = [{
+      memberId: 'viewer',
+      name: 'Viewer',
+      heartbeatAt: presenceTime(10_000),
+    }];
+    await vi.advanceTimersByTimeAsync(20_000);
+    state.present = [
+      { memberId: 'viewer', name: 'Viewer', heartbeatAt: presenceTime(30_000) },
+      { memberId: 'owner', name: 'Owner', heartbeatAt: presenceTime(30_000) },
+    ];
+    await vi.advanceTimersByTimeAsync(10_000);
+
+    expect(snapshots.every((present) =>
+      present.some(({ memberId }) => memberId === 'owner'))).toBe(true);
     expect(client.getSnapshot().present).toHaveLength(2);
+    client.stop();
+  });
+
+  it('does not extend a nearly expired backend lease from the local observation time', async () => {
+    vi.setSystemTime(PRESENCE_TEST_NOW + 29_000);
+    const { fetchImpl, state } = makeFetch({
+      present: [
+        { memberId: 'viewer', heartbeatAt: presenceTime(29_000) },
+        { memberId: 'owner', heartbeatAt: presenceTime() },
+      ],
+    });
+    const client = new CollabClient({
+      projectId: 'p-nearly-expired-owner',
+      member: { memberId: 'viewer' },
+      fetch: fetchImpl,
+      heartbeatMs: 1_000,
+    });
+
+    client.start();
+    await vi.advanceTimersByTimeAsync(0);
+    state.present = [{
+      memberId: 'viewer',
+      heartbeatAt: presenceTime(30_000),
+    }];
+    await vi.advanceTimersByTimeAsync(999);
+    expect(client.getSnapshot().present.map(({ memberId }) => memberId))
+      .toEqual(['viewer', 'owner']);
+
     await vi.advanceTimersByTimeAsync(1);
+    expect(client.getSnapshot().present.map(({ memberId }) => memberId))
+      .toEqual(['viewer']);
+    client.stop();
+  });
+
+  it.each([
+    ['missing', undefined],
+    ['invalid', 'not-a-date'],
+  ])('retains a peer with %s heartbeatAt for only one fallback heartbeat window', async (_label, heartbeatAt) => {
+    const { fetchImpl, state } = makeFetch({
+      present: [
+        { memberId: 'viewer' },
+        { memberId: 'legacy-peer', heartbeatAt },
+      ],
+    });
+    const client = new CollabClient({
+      projectId: 'p-legacy-presence',
+      member: { memberId: 'viewer' },
+      fetch: fetchImpl,
+      heartbeatMs: 10_000,
+    });
+
+    client.start();
+    await vi.advanceTimersByTimeAsync(0);
+    state.present = [{ memberId: 'viewer' }];
+    await vi.advanceTimersByTimeAsync(19_999);
+    expect(client.getSnapshot().present.map(({ memberId }) => memberId))
+      .toEqual(['viewer', 'legacy-peer']);
+
+    await vi.advanceTimersByTimeAsync(1);
+    expect(client.getSnapshot().present.map(({ memberId }) => memberId))
+      .toEqual(['viewer']);
+    client.stop();
+  });
+
+  it('applies an event-driven fresh roster exactly so explicit leaves stay immediate', async () => {
+    const { fetchImpl, state } = makeFetch({
+      present: [
+        { memberId: 'viewer', name: 'Viewer' },
+        { memberId: 'peer', name: 'Peer' },
+      ],
+    });
+    const client = new CollabClient({
+      projectId: 'p-explicit-leave',
+      member: { memberId: 'viewer', name: 'Viewer' },
+      fetch: fetchImpl,
+      heartbeatMs: 10_000,
+    });
+
+    client.start();
+    await vi.advanceTimersByTimeAsync(0);
+    state.present = [{ memberId: 'viewer', name: 'Viewer' }];
+    await client.refreshPresence();
+
     expect(client.getSnapshot().present).toEqual([
       { memberId: 'viewer', name: 'Viewer' },
     ]);
-
     client.stop();
   });