@agent-native/core 0.161.10 → 0.161.12

package/dist/server/poll.d.ts

@@ -23,6 +23,8 @@ import { EventEmitter } from "node:events";
 import { type DbExec } from "../db/client.js";
 export interface ChangeEvent {
     version: number;
+    /** Stable durable-row tie-breaker for events sharing a millisecond version. */
+    cursorId?: string;
     source: string;
     type: string;
     key?: string;
@@ -53,9 +55,15 @@ export interface ChangeEvent {
 }
 export declare const DURABLE_LEGACY_DB_CHECK_INTERVAL_MS = 30000;
 export declare const POLL_CHANGE_EVENT = "poll-change";
+type SyncCursor = {
+    version: number;
+    id: string;
+};
 export type ChangeReadResult = {
     version: number;
     events: ChangeEvent[];
+    /** Composite `(version,id)` cursor for durable rows sharing a version. */
+    cursor?: string;
     /**
      * True when the returned version is an intentional cursor stop, not the
      * source high-water mark. This happens when access is still pending or when a
@@ -143,11 +151,13 @@ export declare class AppSyncState {
     private dbVersionFallbacks;
     private warnedListenerThrow;
     private version;
+    private latestCursor;
     private readonly buffer;
     private readonly pollEmitter;
     private syncEventsInitPromise;
     private lastDurablePrune;
     private durablePruneFailures;
+    private durableWriteFailures;
     /**
      * Whether we've seeded `version` from the DB. In serverless (Netlify,
      * Vercel, etc.) each invocation starts fresh — without seeding, `version`
@@ -175,8 +185,9 @@ export declare class AppSyncState {
      * after a restart (where an existing row would look like a fresh bump).
      */
     private lastScreenRefreshTs;
+    private lastScreenRefreshSessionId;
     private screenRefreshInitialized;
-    private readonly lastScreenRefreshTsBySession;
+    private screenRefreshHasMore;
     private localEmittersWired;
     /**
      * TTL'd access cache for the access-aware branch of `canSeeChangeForUser`,
@@ -232,13 +243,15 @@ export declare class AppSyncState {
      *     `sync_events_created_at_id_idx` drives the batch and the delete is a
      *     bounded index range scan.
      *
-     * The `lastDurablePrune` throttle below is per-process, so every serverless
-     * worker prunes on its first poll. Postgres workers also take a
+     * The `lastDurablePrune` throttle below is per-process and starts at process
+     * initialization, so a cold serverless worker does not run a potentially
+     * large delete during its first request. Postgres workers also take a
      * transaction-scoped advisory lease for each batch. The lease and delete
      * are one bounded statement, so a serverless worker killed after the
      * statement starts cannot leave an open transaction.
      */
     private pruneDurableEvents;
+    private reportDurableWriteFailure;
     persistSyncEvent(event: ChangeEvent, dedupeKey?: string, presetId?: string): Promise<void>;
     /**
      * Persist with a DB-allocated version (see ALLOCATING_INSERT_SQL). Returns
@@ -340,12 +353,9 @@ export declare class AppSyncState {
      * Get changes after a given version, filtered to events the caller is
      * allowed to see.
      */
-    getChangesSinceForUser(since: number, userEmail: string, orgId: string | undefined): ChangeReadResult;
-    getDurableChangesSinceForUser(since: number, userEmail: string, orgId: string | undefined): Promise<ChangeReadResult>;
-    getCombinedChangesSinceForUser(since: number, userEmail: string, orgId: string | undefined, useDurableEvents: boolean): Promise<{
-        version: number;
-        events: ChangeEvent[];
-    }>;
+    getChangesSinceForUser(since: number, userEmail: string, orgId: string | undefined, cursor?: SyncCursor): ChangeReadResult;
+    getDurableChangesSinceForUser(since: number, userEmail: string, orgId: string | undefined, cursor?: SyncCursor): Promise<ChangeReadResult>;
+    getCombinedChangesSinceForUser(since: number, userEmail: string, orgId: string | undefined, useDurableEvents: boolean, cursor?: SyncCursor): Promise<ChangeReadResult>;
     /**
      * Seed `version` from DB timestamps on the first call so serverless cold
      * starts don't return version 0 and confuse polling clients.
@@ -395,7 +405,7 @@ export declare function getChangesSinceForUser(since: number, userEmail: string,
 /**
  * Create an H3 handler for the poll endpoint.
  *
- * GET /_agent-native/poll?since=N → { version, events[] }
+ * GET /_agent-native/poll?since=N[&cursor=N.id] → { version, events[] }
  *
  * Requires an authenticated session. Events are filtered to the caller's
  * tenant — global events (owner-less, table-level pings) reach every
@@ -403,9 +413,7 @@ export declare function getChangesSinceForUser(since: number, userEmail: string,
  * Without auth + filtering, an anonymous attacker could poll the deployment
  * and infer cross-tenant activity from the global event stream.
  */
-export declare function createPollHandler(state?: AppSyncState): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    version: number;
-    events: ChangeEvent[];
-} | {
+export declare function createPollHandler(state?: AppSyncState): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<ChangeReadResult | {
     error: string;
 }>>;
+export {};

package/dist/server/poll.js

@@ -69,6 +69,7 @@ const ACCESS_CACHE_DENY_TTL_MS = 5_000;
 /** Max cache entries before FIFO eviction kicks in. */
 const ACCESS_CACHE_MAX = 500;
 const SCREEN_REFRESH_KEY = "__screen_refresh__";
+const SCREEN_REFRESH_QUERY_LIMIT = 256;
 /**
  * DB-assigned version allocation (see `AppSyncStateOptions.dbAssignedVersions`).
  * The allocator is a one-row table advanced with `GREATEST(v + 1, epoch_ms)` —
@@ -122,6 +123,32 @@ function sqlWatermarkValue(value) {
         return value;
     return undefined;
 }
+function compareSyncCursors(a, b) {
+    if (a.version !== b.version)
+        return a.version - b.version;
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+function cursorForEvent(event) {
+    return { version: event.version, id: event.cursorId ?? "" };
+}
+function encodeSyncCursor(cursor) {
+    return `${cursor.version}.${cursor.id}`;
+}
+function decodeSyncCursor(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const separator = value.indexOf(".");
+    if (separator < 1)
+        return undefined;
+    const version = Number(value.slice(0, separator));
+    const id = value.slice(separator + 1);
+    if (!Number.isSafeInteger(version) || version < 0)
+        return undefined;
+    return { version, id };
+}
+function isEventAfterCursor(event, cursor) {
+    return compareSyncCursors(cursorForEvent(event), cursor) > 0;
+}
 function syncEventsDisabled() {
     return (process.env.AGENT_NATIVE_SYNC_EVENTS_DISABLE === "1" ||
         (process.env.VITEST === "true" &&
@@ -260,11 +287,15 @@ export class AppSyncState {
     // the same range (seeded from DB, then incremented via Date.now). Plain
     // ++counter diverges across cold starts.
     version = 0;
+    latestCursor = { version: 0, id: "" };
     buffer = [];
     pollEmitter = new EventEmitter();
     syncEventsInitPromise;
-    lastDurablePrune = 0;
+    // Cold starts should not immediately run a potentially large anti-join. A
+    // long-lived process will still prune on its first scheduled interval.
+    lastDurablePrune = Date.now();
     durablePruneFailures = 0;
+    durableWriteFailures = 0;
     /**
      * Whether we've seeded `version` from the DB. In serverless (Netlify,
      * Vercel, etc.) each invocation starts fresh — without seeding, `version`
@@ -295,8 +326,9 @@ export class AppSyncState {
      * after a restart (where an existing row would look like a fresh bump).
      */
     lastScreenRefreshTs = 0;
+    lastScreenRefreshSessionId = "";
     screenRefreshInitialized = false;
-    lastScreenRefreshTsBySession = new Map();
+    screenRefreshHasMore = false;
     localEmittersWired = false;
     /**
      * TTL'd access cache for the access-aware branch of `canSeeChangeForUser`,
@@ -460,8 +492,9 @@ export class AppSyncState {
      *     `sync_events_created_at_id_idx` drives the batch and the delete is a
      *     bounded index range scan.
      *
-     * The `lastDurablePrune` throttle below is per-process, so every serverless
-     * worker prunes on its first poll. Postgres workers also take a
+     * The `lastDurablePrune` throttle below is per-process and starts at process
+     * initialization, so a cold serverless worker does not run a potentially
+     * large delete during its first request. Postgres workers also take a
      * transaction-scoped advisory lease for each batch. The lease and delete
      * are one bounded statement, so a serverless worker killed after the
      * statement starts cannot leave an open transaction.
@@ -521,18 +554,23 @@ export class AppSyncState {
             }
         }
     }
+    reportDurableWriteFailure(error, event) {
+        this.durableWriteFailures++;
+        if (this.durableWriteFailures === 1) {
+            console.warn(`[agent-native] sync_events write failed for ${event.source}/${event.type}${event.key ? `/${event.key}` : ""}; durable replay is unavailable until the database recovers:`, error instanceof Error ? error.message : String(error));
+        }
+    }
     async persistSyncEvent(event, dedupeKey, presetId) {
         if (!(await this.ensureSyncEventsTable()))
             return;
         const client = this.getDb();
-        await client
-            .execute({
+        await client.execute({
             sql: this.isPg()
                 ? `INSERT INTO sync_events (id, version, event_json, source, type, event_key, owner, org_id, resource_type, resource_id, created_at)
-           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-           ON CONFLICT (id) DO NOTHING`
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT (id) DO NOTHING`
                 : `INSERT OR IGNORE INTO sync_events (id, version, event_json, source, type, event_key, owner, org_id, resource_type, resource_id, created_at)
-           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
             args: [
                 // presetId lets a gated fallback reuse the allocating attempt's id,
                 // so a commit-then-timeout can't produce the same event twice.
@@ -548,8 +586,8 @@ export class AppSyncState {
                 event.resourceId ?? null,
                 Date.now(),
             ],
-        })
-            .catch(() => { });
+        });
+        this.durableWriteFailures = 0;
         await this.pruneDurableEvents(client);
     }
     /**
@@ -797,17 +835,27 @@ export class AppSyncState {
             // drop every later event.
             this.recordChain = this.recordChain
                 .then(() => this.recordWithDbVersion(event, opts?.dedupeKey))
-                .catch(() => { });
+                .catch((error) => {
+                this.reportDurableWriteFailure(error, event);
+            });
             return;
         }
         this.version = Math.max(this.version + 1, Date.now());
-        const entry = { ...event, version: this.version };
+        const provisional = { ...event, version: this.version };
+        const cursorId = this.durableEventId(provisional, opts?.dedupeKey);
+        const entry = { ...provisional, cursorId };
         this.commitEntry(entry);
-        void this.persistSyncEvent(entry, opts?.dedupeKey);
+        void this.persistSyncEvent(entry, opts?.dedupeKey, cursorId).catch((error) => {
+            this.reportDurableWriteFailure(error, entry);
+        });
     }
     /** Buffer + emit. Shared by both version-allocation modes. */
     commitEntry(entry) {
         this.buffer.push(entry);
+        const cursor = cursorForEvent(entry);
+        if (compareSyncCursors(cursor, this.latestCursor) > 0) {
+            this.latestCursor = cursor;
+        }
         if (this.buffer.length > MAX_BUFFER) {
             this.buffer.splice(0, this.buffer.length - MAX_BUFFER);
         }
@@ -826,7 +874,7 @@ export class AppSyncState {
             : `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
         let version = null;
         try {
-            version = await this.persistWithDbAssignedVersion(event, id);
+            version = await this.persistWithDbAssignedVersion({ ...event, cursorId: id }, id);
         }
         catch {
             version = null;
@@ -851,10 +899,16 @@ export class AppSyncState {
                 console.warn("[agent-native] sync version allocation failed; falling back to clock-assigned versions");
             }
             this.version = Math.max(this.version + 1, Date.now());
-            const entry = { ...event, version: this.version };
+            const entry = {
+                ...event,
+                version: this.version,
+                cursorId: id,
+            };
             await this.alignVersionAllocator(this.version);
             this.commitEntryForChain(entry);
-            void this.persistSyncEvent(entry, dedupeKey, id);
+            void this.persistSyncEvent(entry, dedupeKey, id).catch((error) => {
+                this.reportDurableWriteFailure(error, entry);
+            });
             return;
         }
         // A deterministic-id dedupe loser adopts the winner's (possibly older)
@@ -862,7 +916,7 @@ export class AppSyncState {
         // delivered correctly and the version-keyed combined-read dedupe collapses
         // it against the durable row.
         this.version = Math.max(this.version, version);
-        this.commitEntryForChain({ ...event, version });
+        this.commitEntryForChain({ ...event, version, cursorId: id });
     }
     /**
      * `commitEntry` for the deferred (chained) path: the buffer push must land
@@ -929,32 +983,61 @@ export class AppSyncState {
      * Get changes after a given version, filtered to events the caller is
      * allowed to see.
      */
-    getChangesSinceForUser(since, userEmail, orgId) {
-        if (since >= this.version) {
-            return { version: this.version, events: [] };
+    getChangesSinceForUser(since, userEmail, orgId, cursor) {
+        const readCursor = cursor ?? { version: since, id: "" };
+        if ((!cursor && since >= this.version) ||
+            (cursor && compareSyncCursors(this.latestCursor, readCursor) <= 0)) {
+            return {
+                version: this.version,
+                events: [],
+                ...(cursor ? { cursor: encodeSyncCursor(readCursor) } : {}),
+            };
         }
         const events = [];
         let version = this.version;
+        let lastCursor = readCursor;
         for (const event of this.buffer) {
-            if (event.version <= since)
+            if (cursor ? !isEventAfterCursor(event, readCursor) : event.version <= since) {
                 continue;
+            }
             const visibility = this.getChangeVisibilityForUser(event, userEmail, orgId);
             if (visibility === "visible") {
                 events.push(event);
+                lastCursor = cursorForEvent(event);
                 continue;
             }
             if (visibility === "pending") {
                 version = Math.max(since, event.version - 1);
-                return { version, events, cursorLimited: true };
+                return {
+                    version,
+                    events,
+                    cursorLimited: true,
+                    ...(cursor && lastCursor !== readCursor
+                        ? { cursor: encodeSyncCursor(lastCursor) }
+                        : {}),
+                };
             }
+            lastCursor = cursorForEvent(event);
         }
-        return { version, events };
+        return {
+            version,
+            events,
+            ...(cursor && compareSyncCursors(lastCursor, readCursor) > 0
+                ? { cursor: encodeSyncCursor(lastCursor) }
+                : {}),
+        };
     }
-    async getDurableChangesSinceForUser(since, userEmail, orgId) {
-        if (since <= 0 || !(await this.ensureSyncEventsTable())) {
+    async getDurableChangesSinceForUser(since, userEmail, orgId, cursor) {
+        if ((!cursor && since <= 0) ||
+            (cursor && cursor.version <= 0 && cursor.id === "") ||
+            !(await this.ensureSyncEventsTable())) {
             return { version: this.version, events: [] };
         }
         try {
+            const readCursor = cursor ?? { version: since, id: "" };
+            const compositeCursorSql = cursor
+                ? "(version > ? OR (version = ? AND id > ?))"
+                : "version > ?";
             // Scope the fetch to rows that could ever be visible to this caller
             // before paying to JSON.parse and visibility-check every deployment-wide
             // event: deployment-global rows (no owner, no org), the caller's own
@@ -965,19 +1048,29 @@ export class AppSyncState {
             // `orgId` bind param, which makes `org_id = ?` match no row in both
             // dialects — mirroring the `event.orgId && orgId` truthy check.
             const result = await this.getDb().execute({
-                sql: `SELECT version, event_json FROM sync_events WHERE version > ?
+                sql: `SELECT id, version, event_json FROM sync_events WHERE ${compositeCursorSql}
               AND (
                 (owner IS NULL AND org_id IS NULL)
                 OR owner = ?
                 OR org_id = ?
                 OR resource_type IS NOT NULL
               )
-            ORDER BY version ASC LIMIT ?`,
-                args: [since, userEmail, orgId ?? null, DURABLE_READ_LIMIT + 1],
+            ORDER BY version ASC, id ASC LIMIT ?`,
+                args: cursor
+                    ? [
+                        cursor.version,
+                        cursor.version,
+                        cursor.id,
+                        userEmail,
+                        orgId ?? null,
+                        DURABLE_READ_LIMIT + 1,
+                    ]
+                    : [since, userEmail, orgId ?? null, DURABLE_READ_LIMIT + 1],
             });
             const events = [];
             let version = Math.max(this.version, since);
             let lastDurableVersion = since;
+            let lastCursor = readCursor;
             const rows = result.rows.slice(0, DURABLE_READ_LIMIT);
             const overflowVersion = timestampValue(result.rows[DURABLE_READ_LIMIT]?.version);
             for (const row of rows) {
@@ -986,6 +1079,8 @@ export class AppSyncState {
                     lastDurableVersion = rawVersion;
                 if (rawVersion > version)
                     version = rawVersion;
+                const rowId = typeof row.id === "string" ? row.id : "";
+                let rowCursor = rowId ? { version: rawVersion, id: rowId } : undefined;
                 let event = null;
                 try {
                     const parsed = JSON.parse(String(row.event_json));
@@ -996,17 +1091,33 @@ export class AppSyncState {
                         event = {
                             ...parsed,
                             version: rawVersion || parsed.version,
+                            ...(rowId || typeof parsed.cursorId === "string"
+                                ? {
+                                    cursorId: rowId || parsed.cursorId,
+                                }
+                                : {}),
                         };
                     }
                 }
                 catch {
                     event = null;
                 }
-                if (!event)
+                if (!event) {
+                    // Malformed durable rows are skipped from delivery, but their
+                    // composite cursor still needs to advance. Otherwise every poll
+                    // rereads the same bad row forever and can never reach later rows.
+                    if (rowCursor)
+                        lastCursor = rowCursor;
                     continue;
+                }
+                if (!rowCursor && typeof event.cursorId === "string") {
+                    rowCursor = { version: event.version, id: event.cursorId };
+                }
                 const visibility = this.getChangeVisibilityForUser(event, userEmail, orgId);
                 if (visibility === "visible") {
                     events.push(event);
+                    if (rowCursor)
+                        lastCursor = rowCursor;
                     continue;
                 }
                 if (visibility === "pending") {
@@ -1014,10 +1125,23 @@ export class AppSyncState {
                         version: Math.max(since, event.version - 1),
                         events,
                         cursorLimited: true,
+                        ...(cursor && compareSyncCursors(lastCursor, readCursor) > 0
+                            ? { cursor: encodeSyncCursor(lastCursor) }
+                            : {}),
                     };
                 }
+                if (rowCursor)
+                    lastCursor = rowCursor;
             }
             if (rows.length >= DURABLE_READ_LIMIT) {
+                if (cursor) {
+                    return {
+                        version: Math.max(since, lastDurableVersion),
+                        events,
+                        cursor: encodeSyncCursor(lastCursor),
+                        cursorLimited: result.rows.length > DURABLE_READ_LIMIT,
+                    };
+                }
                 if (overflowVersion === lastDurableVersion) {
                     const boundaryVersion = lastDurableVersion;
                     return {
@@ -1032,20 +1156,31 @@ export class AppSyncState {
                     cursorLimited: true,
                 };
             }
-            return { version, events };
+            return {
+                version,
+                events,
+                ...(cursor && compareSyncCursors(lastCursor, readCursor) > 0
+                    ? { cursor: encodeSyncCursor(lastCursor) }
+                    : {}),
+            };
         }
         catch {
-            return { version: this.version, events: [] };
+            return {
+                version: this.version,
+                events: [],
+                ...(cursor ? { cursor: encodeSyncCursor(cursor) } : {}),
+            };
         }
     }
-    async getCombinedChangesSinceForUser(since, userEmail, orgId, useDurableEvents) {
-        const memory = this.getChangesSinceForUser(since, userEmail, orgId);
+    async getCombinedChangesSinceForUser(since, userEmail, orgId, useDurableEvents, cursor) {
+        const memory = this.getChangesSinceForUser(since, userEmail, orgId, cursor);
         if (!useDurableEvents)
             return memory;
-        const durable = await this.getDurableChangesSinceForUser(since, userEmail, orgId);
+        const durable = await this.getDurableChangesSinceForUser(since, userEmail, orgId, cursor);
         const byIdentity = new Map();
         for (const event of [...durable.events, ...memory.events]) {
             byIdentity.set(JSON.stringify([
+                event.cursorId,
                 event.version,
                 event.source,
                 event.type,
@@ -1056,7 +1191,37 @@ export class AppSyncState {
                 event.resourceId,
             ]), event);
         }
-        const events = Array.from(byIdentity.values()).sort((a, b) => a.version - b.version);
+        const events = Array.from(byIdentity.values()).sort((a, b) => compareSyncCursors(cursorForEvent(a), cursorForEvent(b)));
+        if (cursor) {
+            const limitedCursors = [memory, durable]
+                .filter((result) => result.cursorLimited)
+                .map((result) => decodeSyncCursor(result.cursor))
+                .filter((value) => !!value);
+            if (limitedCursors.length > 0) {
+                const boundary = limitedCursors.reduce((minimum, value) => compareSyncCursors(value, minimum) < 0 ? value : minimum);
+                return {
+                    version: boundary.version,
+                    cursor: encodeSyncCursor(boundary),
+                    cursorLimited: true,
+                    events: events.filter((event) => compareSyncCursors(cursorForEvent(event), boundary) <= 0),
+                };
+            }
+            const responseCursor = [
+                cursor,
+                decodeSyncCursor(memory.cursor),
+                decodeSyncCursor(durable.cursor),
+                ...events.map(cursorForEvent),
+            ]
+                .filter((value) => !!value)
+                .reduce((maximum, value) => compareSyncCursors(value, maximum) > 0 ? value : maximum, cursor);
+            return {
+                version: Math.max(memory.version, durable.version, since),
+                events,
+                ...(compareSyncCursors(responseCursor, cursor) > 0
+                    ? { cursor: encodeSyncCursor(responseCursor) }
+                    : {}),
+            };
+        }
         const limitedVersions = [memory, durable]
             .filter((result) => result.cursorLimited)
             .map((result) => result.version);
@@ -1088,7 +1253,7 @@ export class AppSyncState {
                 readActionMarkerMaxUpdatedAt(db),
                 db
                     .execute({
-                    sql: "SELECT session_id, updated_at FROM application_state WHERE key = ?",
+                    sql: "SELECT session_id, updated_at FROM application_state WHERE key = ? ORDER BY updated_at DESC, session_id DESC LIMIT 1",
                     args: [SCREEN_REFRESH_KEY],
                 })
                     .catch(() => ({ rows: [] })),
@@ -1130,12 +1295,11 @@ export class AppSyncState {
             this.lastActionMarkerTs = Math.max(0, actionMarkerTs - ACTION_MARKER_REPLAY_WINDOW_MS);
             this.replayActionMarkerOnce = actionMarkerTs > 0;
             this.lastScreenRefreshTs = refreshTs;
-            this.lastScreenRefreshTsBySession.clear();
-            for (const row of refreshResult.rows) {
-                if (typeof row.session_id === "string") {
-                    this.lastScreenRefreshTsBySession.set(row.session_id, timestampValue(row.updated_at));
-                }
-            }
+            this.lastScreenRefreshSessionId =
+                typeof refreshResult.rows[0]?.session_id === "string"
+                    ? refreshResult.rows[0].session_id
+                    : "";
+            this.screenRefreshHasMore = false;
             this.screenRefreshInitialized = true;
             // Skip the redundant cold-start recheck unless there is an existing durable
             // action marker that the first poll still needs to emit.
@@ -1207,15 +1371,28 @@ export class AppSyncState {
             const replayActionMarker = this.replayActionMarkerOnce;
             this.replayActionMarkerOnce = false;
             const appStateChanged = appStateMaxTs > this.lastAppStateTs || replayActionMarker;
-            const [appResult, refreshResult, extensionMarkerTs] = appStateChanged
+            const screenRefreshNeedsCheck = appStateChanged || this.screenRefreshHasMore;
+            const [appResult, refreshResult, extensionMarkerTs] = screenRefreshNeedsCheck
                 ? await Promise.all([
+                    appStateChanged
+                        ? db.execute({
+                            sql: "SELECT session_id, key, updated_at FROM application_state WHERE updated_at > ? ORDER BY updated_at ASC",
+                            args: [this.lastAppStateTs],
+                        })
+                        : Promise.resolve({ rows: [] }),
                     db.execute({
-                        sql: "SELECT session_id, key, updated_at FROM application_state WHERE updated_at > ? ORDER BY updated_at ASC",
-                        args: [this.lastAppStateTs],
-                    }),
-                    db.execute({
-                        sql: "SELECT session_id, updated_at, value FROM application_state WHERE key = ?",
-                        args: [SCREEN_REFRESH_KEY],
+                        sql: `SELECT session_id, updated_at, value FROM application_state
+                    WHERE key = ?
+                      AND (updated_at > ? OR (updated_at = ? AND session_id > ?))
+                    ORDER BY updated_at ASC, session_id ASC
+                    LIMIT ?`,
+                        args: [
+                            SCREEN_REFRESH_KEY,
+                            this.lastScreenRefreshTs,
+                            this.lastScreenRefreshTs,
+                            this.lastScreenRefreshSessionId,
+                            SCREEN_REFRESH_QUERY_LIMIT,
+                        ],
                     }),
                     readExtensionMarkerMaxUpdatedAt(db),
                 ])
@@ -1282,17 +1459,16 @@ export class AppSyncState {
             // application_state row moved, which is also exactly when this block
             // could not emit anything.
             if (refreshResult) {
-                const refreshTs = refreshResult.rows.reduce((max, row) => Math.max(max, timestampValue(row.updated_at)), 0);
                 if (!this.screenRefreshInitialized) {
-                    this.lastScreenRefreshTs = refreshTs;
-                    for (const row of refreshResult.rows) {
-                        if (typeof row.session_id === "string") {
-                            this.lastScreenRefreshTsBySession.set(row.session_id, timestampValue(row.updated_at));
-                        }
-                    }
+                    const lastRow = refreshResult.rows.at(-1);
+                    this.lastScreenRefreshTs = timestampValue(lastRow?.updated_at);
+                    this.lastScreenRefreshSessionId =
+                        typeof lastRow?.session_id === "string" ? lastRow.session_id : "";
+                    this.screenRefreshHasMore =
+                        refreshResult.rows.length >= SCREEN_REFRESH_QUERY_LIMIT;
                     this.screenRefreshInitialized = true;
                 }
-                else if (refreshTs > this.lastScreenRefreshTs) {
+                else {
                     // Emit a per-user event only for the session(s) whose row actually
                     // advanced, scoped with `owner` so canSeeChangeForUser delivers it only
                     // to that user — not every authenticated poller.
@@ -1301,9 +1477,6 @@ export class AppSyncState {
                         if (!owner)
                             continue;
                         const rowTs = timestampValue(row.updated_at);
-                        if (rowTs <= (this.lastScreenRefreshTsBySession.get(owner) ?? 0)) {
-                            continue;
-                        }
                         let scope;
                         try {
                             const raw = row.value;
@@ -1320,10 +1493,12 @@ export class AppSyncState {
                             key: SCREEN_REFRESH_KEY,
                             owner,
                             ...(scope ? { scope } : {}),
-                        }, { dedupeKey: `screen-refresh|${rowTs}` });
-                        this.lastScreenRefreshTsBySession.set(owner, rowTs);
+                        }, { dedupeKey: `screen-refresh|${rowTs}|${owner}` });
+                        this.lastScreenRefreshTs = rowTs;
+                        this.lastScreenRefreshSessionId = owner;
                     }
-                    this.lastScreenRefreshTs = refreshTs;
+                    this.screenRefreshHasMore =
+                        refreshResult.rows.length >= SCREEN_REFRESH_QUERY_LIMIT;
                 }
             }
             // Extension mutations write a durable marker row so delete and hide/unhide
@@ -1452,7 +1627,7 @@ export function getChangesSinceForUser(since, userEmail, orgId) {
 /**
  * Create an H3 handler for the poll endpoint.
  *
- * GET /_agent-native/poll?since=N → { version, events[] }
+ * GET /_agent-native/poll?since=N[&cursor=N.id] → { version, events[] }
  *
  * Requires an authenticated session. Events are filtered to the caller's
  * tenant — global events (owner-less, table-level pings) reach every
@@ -1479,7 +1654,8 @@ export function createPollHandler(state = getDefaultAppSyncState()) {
         // older processes that have not started writing durable events yet.
         await state.checkExternalDbChanges({ durableEvents });
         const query = getQuery(event);
-        const since = parseInt(String(query.since ?? "0"), 10) || 0;
-        return state.getCombinedChangesSinceForUser(since, session.email, session.orgId, durableEvents);
+        const cursor = decodeSyncCursor(query.cursor);
+        const since = cursor?.version ?? (parseInt(String(query.since ?? "0"), 10) || 0);
+        return state.getCombinedChangesSinceForUser(since, session.email, session.orgId, durableEvents, cursor);
     });
 }