@agent-native/core 0.144.2 → 0.145.0

package/dist/client/browser-session-bridge.js

@@ -1,11 +1,27 @@
+import { createPollEngine } from "../shared/poll-engine.js";
 import { agentNativePath } from "./api-path.js";
 import { announceAgentNativeFrameReady, defaultAgentNativeHostCommands, requestAgentNativeHostActions, requestAgentNativeHostContext, runAgentNativeHostAction, sendAgentNativeHostCommand, } from "./host-bridge.js";
 const DEFAULT_ENDPOINT = "/_agent-native/browser-sessions";
 const DEFAULT_HEARTBEAT_MS = 5_000;
 const DEFAULT_POLL_MS = 500;
+const REQUEST_ABORT_MIN_MS = 10_000;
+// Relaxed cadence floor applied while the tab is hidden — mirrors
+// use-poll-loop.ts's `pauseWhenHidden: false` default so a backgrounded tab
+// keeps heartbeating (the server-side session TTL still needs refreshing)
+// instead of going fully silent.
+const HIDDEN_INTERVAL_FLOOR_MS = 10_000;
+function isDocumentHidden() {
+    return (typeof document !== "undefined" && document.visibilityState === "hidden");
+}
 function browserSessionId() {
     return `browser-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
 }
+// Bounds a single request so a hung fetch can't leave the caller waiting
+// forever on a wedged connection.
+function requestAbortMs(options) {
+    const cadence = Math.min(options.pollMs ?? DEFAULT_POLL_MS, options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS);
+    return Math.max(REQUEST_ABORT_MIN_MS, cadence * 4);
+}
 function messageError(error) {
     return error instanceof Error ? error : new Error(String(error));
 }
@@ -35,26 +51,48 @@ async function readJsonResponse(response) {
     return body;
 }
 async function postJson(options, path, body) {
-    const response = await fetchImpl(options)(endpointPath(options, path), {
-        method: "POST",
-        credentials: "include",
-        headers: {
-            "Content-Type": "application/json",
-            "X-Agent-Native-CSRF": "1",
-        },
-        body: JSON.stringify(body ?? {}),
-    });
-    return readJsonResponse(response);
+    const controller = typeof AbortController === "undefined" ? null : new AbortController();
+    const timeoutId = controller
+        ? setTimeout(() => controller.abort(), requestAbortMs(options))
+        : null;
+    try {
+        const response = await fetchImpl(options)(endpointPath(options, path), {
+            method: "POST",
+            credentials: "include",
+            headers: {
+                "Content-Type": "application/json",
+                "X-Agent-Native-CSRF": "1",
+            },
+            body: JSON.stringify(body ?? {}),
+            ...(controller ? { signal: controller.signal } : {}),
+        });
+        return readJsonResponse(response);
+    }
+    finally {
+        if (timeoutId)
+            clearTimeout(timeoutId);
+    }
 }
 async function deleteJson(options, path) {
-    const response = await fetchImpl(options)(endpointPath(options, path), {
-        method: "DELETE",
-        credentials: "include",
-        headers: {
-            "X-Agent-Native-CSRF": "1",
-        },
-    });
-    await readJsonResponse(response);
+    const controller = typeof AbortController === "undefined" ? null : new AbortController();
+    const timeoutId = controller
+        ? setTimeout(() => controller.abort(), requestAbortMs(options))
+        : null;
+    try {
+        const response = await fetchImpl(options)(endpointPath(options, path), {
+            method: "DELETE",
+            credentials: "include",
+            headers: {
+                "X-Agent-Native-CSRF": "1",
+            },
+            ...(controller ? { signal: controller.signal } : {}),
+        });
+        await readJsonResponse(response);
+    }
+    finally {
+        if (timeoutId)
+            clearTimeout(timeoutId);
+    }
 }
 function hostRequestOptions(options) {
     const { endpoint: _endpoint, sessionId: _sessionId, session: _session, getContext: _getContext, actions: _actions, commands: _commands, origin: _origin, label: _label, heartbeatMs: _heartbeatMs, pollMs: _pollMs, ttlMs: _ttlMs, fetch: _fetch, ...hostOptions } = options;
@@ -224,10 +262,7 @@ export function createAgentNativeBrowserSessionBridge(options = {}) {
     let currentSessionId = options.sessionId ?? null;
     let fallbackSessionId = null;
     let started = false;
-    let heartbeatTimer;
-    let pollTimer;
-    let refreshing = false;
-    let polling = false;
+    let onVisibility;
     async function refreshRegistration() {
         const direct = hasDirectHost(options);
         const hostOptions = hostRequestOptions(options);
@@ -256,17 +291,6 @@ export function createAgentNativeBrowserSessionBridge(options = {}) {
         });
         return body.session;
     }
-    async function heartbeat() {
-        if (refreshing)
-            return;
-        refreshing = true;
-        try {
-            await refreshRegistration();
-        }
-        finally {
-            refreshing = false;
-        }
-    }
     async function claimOnce() {
         if (!currentSessionId) {
             await refreshRegistration();
@@ -286,17 +310,27 @@ export function createAgentNativeBrowserSessionBridge(options = {}) {
         }
         return request;
     }
-    async function poll() {
-        if (polling)
-            return;
-        polling = true;
-        try {
-            await claimOnce();
-        }
-        finally {
-            polling = false;
-        }
-    }
+    // This is a plain factory function, not a React component, so it can't use
+    // the usePollLoop hook — createPollEngine gives each loop the same
+    // never-overlaps/never-stalls guarantees imperatively. The relaxed hidden
+    // cadence + visibilitychange wiring below mirrors what use-poll-loop.ts
+    // does internally for `pauseWhenHidden: false`.
+    const heartbeatEngine = createPollEngine(() => refreshRegistration().then(() => { }), {
+        intervalMs: () => {
+            const base = options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
+            return isDocumentHidden()
+                ? Math.max(base, HIDDEN_INTERVAL_FLOOR_MS)
+                : base;
+        },
+    });
+    const pollEngine = createPollEngine(() => claimOnce().then(() => { }), {
+        intervalMs: () => {
+            const base = options.pollMs ?? DEFAULT_POLL_MS;
+            return isDocumentHidden()
+                ? Math.max(base, HIDDEN_INTERVAL_FLOOR_MS)
+                : base;
+        },
+    });
     const bridge = {
         get sessionId() {
             return currentSessionId;
@@ -308,22 +342,31 @@ export function createAgentNativeBrowserSessionBridge(options = {}) {
             if (!hasDirectHost(options)) {
                 announceAgentNativeFrameReady(hostRequestOptions(options));
             }
-            void heartbeat();
-            void poll();
-            heartbeatTimer = setInterval(() => void heartbeat(), options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS);
-            pollTimer = setInterval(() => void poll(), options.pollMs ?? DEFAULT_POLL_MS);
+            heartbeatEngine.start();
+            pollEngine.start();
+            onVisibility = () => {
+                if (isDocumentHidden()) {
+                    heartbeatEngine.reschedule();
+                    pollEngine.reschedule();
+                }
+                else {
+                    heartbeatEngine.pollNow();
+                    pollEngine.pollNow();
+                }
+            };
+            document.addEventListener("visibilitychange", onVisibility);
             return bridge;
         },
         stop() {
             if (!started)
                 return;
             started = false;
-            if (heartbeatTimer)
-                clearInterval(heartbeatTimer);
-            if (pollTimer)
-                clearInterval(pollTimer);
-            heartbeatTimer = undefined;
-            pollTimer = undefined;
+            heartbeatEngine.stop();
+            pollEngine.stop();
+            if (onVisibility) {
+                document.removeEventListener("visibilitychange", onVisibility);
+                onVisibility = undefined;
+            }
             if (currentSessionId) {
                 void deleteJson(options, `/${encodePathSegment(currentSessionId)}`).catch(() => { });
             }

package/dist/client/db-admin/useAgentSync.js

@@ -16,6 +16,7 @@ import { useEffect, useRef } from "react";
 import { removeAgentChatContextItem, setAgentChatContextItem, } from "../agent-chat.js";
 import { agentNativePath } from "../api-path.js";
 import { deleteClientAppState, readClientAppState, setClientAppState, } from "../application-state.js";
+import { usePollLoop } from "../use-poll-loop.js";
 const NAVIGATION_PATH = agentNativePath("/_agent-native/application-state/navigation");
 const NAVIGATE_PATH = agentNativePath("/_agent-native/application-state/navigate");
 const POLL_INTERVAL_MS = 1500;
@@ -137,50 +138,40 @@ export function useDbAdminAgentSync({ table, mode, enabled = true, }) {
 export function useNavigateConsumer(onNavigate, enabled = true) {
     const handlerRef = useRef(onNavigate);
     handlerRef.current = onNavigate;
+    const mountedRef = useRef(true);
     useEffect(() => {
-        if (!enabled)
-            return;
-        let active = true;
-        let timer;
-        const tick = async () => {
-            if (!active)
-                return;
-            try {
-                const res = await fetch(NAVIGATE_PATH, {
-                    method: "GET",
-                    credentials: "include",
-                    headers: headers(),
-                });
-                if (active && res.ok) {
-                    const data = (await res.json());
-                    if (data &&
-                        data.view === "database" &&
-                        typeof data.table === "string" &&
-                        data.table) {
-                        const target = data.table;
-                        // Clear the one-shot command before acting so it fires once.
-                        fetch(NAVIGATE_PATH, {
-                            method: "DELETE",
-                            credentials: "include",
-                            headers: headers({ "X-Agent-Native-CSRF": "1" }),
-                        }).catch(() => { });
-                        handlerRef.current(target);
-                    }
-                }
-            }
-            catch {
-                // Ignore transient errors; the next tick retries.
-            }
-            finally {
-                if (active)
-                    timer = setTimeout(tick, POLL_INTERVAL_MS);
-            }
-        };
-        timer = setTimeout(tick, POLL_INTERVAL_MS);
+        mountedRef.current = true;
         return () => {
-            active = false;
-            if (timer)
-                clearTimeout(timer);
+            mountedRef.current = false;
         };
-    }, [enabled]);
+    }, []);
+    usePollLoop(async (signal) => {
+        const res = await fetch(NAVIGATE_PATH, {
+            method: "GET",
+            credentials: "include",
+            headers: headers(),
+            signal,
+        });
+        if (!mountedRef.current || !res.ok)
+            return;
+        const data = (await res.json());
+        if (data &&
+            data.view === "database" &&
+            typeof data.table === "string" &&
+            data.table) {
+            const target = data.table;
+            // Clear the one-shot command before acting so it fires once.
+            fetch(NAVIGATE_PATH, {
+                method: "DELETE",
+                credentials: "include",
+                headers: headers({ "X-Agent-Native-CSRF": "1" }),
+            }).catch(() => { });
+            handlerRef.current(target);
+        }
+    }, {
+        intervalMs: POLL_INTERVAL_MS,
+        leading: false,
+        pauseWhenHidden: true,
+        enabled,
+    });
 }

package/dist/client/dynamic-suggestions.d.ts

@@ -15,6 +15,8 @@ export interface AgentDynamicSuggestionsConfig {
     includeStatic?: boolean;
     /** Optional app-specific deterministic suggestion builder. */
     getSuggestions?: (context: AgentDynamicSuggestionContext) => string[];
+    /** Safety-net refresh cadence in ms, for updates that don't bump app-state version. Default 30_000. */
+    pollMs?: number;
 }
 export type AgentDynamicSuggestionsOption = boolean | AgentDynamicSuggestionsConfig;
 export interface AgentDynamicSuggestionsResult {
@@ -33,6 +35,7 @@ interface NormalizedAgentDynamicSuggestionsConfig {
     max: number;
     includeStatic: boolean;
     getSuggestions?: (context: AgentDynamicSuggestionContext) => string[];
+    pollMs: number;
 }
 export declare function normalizeAgentDynamicSuggestionsConfig(option?: AgentDynamicSuggestionsOption): NormalizedAgentDynamicSuggestionsConfig;
 export declare function buildDynamicAgentSuggestions(context: AgentDynamicSuggestionContext): string[];

package/dist/client/dynamic-suggestions.js

@@ -1,14 +1,17 @@
-import { useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { readClientAppState } from "./application-state.js";
 import { useChangeVersions } from "./use-change-version.js";
+import { usePollLoop } from "./use-poll-loop.js";
 const SAFE_BROWSER_TAB_ID_RE = /^[A-Za-z0-9_-]{1,96}$/;
 const DEFAULT_MAX_SUGGESTIONS = 3;
+const DEFAULT_POLL_MS = 30_000;
 export function normalizeAgentDynamicSuggestionsConfig(option) {
     if (option === false) {
         return {
             enabled: false,
             max: DEFAULT_MAX_SUGGESTIONS,
             includeStatic: true,
+            pollMs: DEFAULT_POLL_MS,
         };
     }
     if (option === true || option === undefined) {
@@ -16,6 +19,7 @@ export function normalizeAgentDynamicSuggestionsConfig(option) {
             enabled: true,
             max: DEFAULT_MAX_SUGGESTIONS,
             includeStatic: true,
+            pollMs: DEFAULT_POLL_MS,
         };
     }
     return {
@@ -25,6 +29,9 @@ export function normalizeAgentDynamicSuggestionsConfig(option) {
             : DEFAULT_MAX_SUGGESTIONS,
         includeStatic: option.includeStatic !== false,
         ...(option.getSuggestions ? { getSuggestions: option.getSuggestions } : {}),
+        pollMs: typeof option.pollMs === "number" && Number.isFinite(option.pollMs)
+            ? Math.max(0, Math.floor(option.pollMs))
+            : DEFAULT_POLL_MS,
     };
 }
 function normalizeBrowserTabId(browserTabId) {
@@ -263,64 +270,59 @@ export function useAgentDynamicSuggestionsResult(options) {
     const enabled = options.enabled !== false && config.enabled;
     const [context, setContext] = useState(null);
     const [isLoading, setIsLoading] = useState(false);
+    // Invalidates in-flight loads from a stale scope/browserTabId/enabled
+    // generation — shared between the leading load below and the safety-net
+    // poll so a slow response from an old generation can't clobber a newer one.
+    const loadGenerationRef = useRef(0);
+    const load = useCallback(async (showLoading) => {
+        const generation = loadGenerationRef.current;
+        if (showLoading)
+            setIsLoading(true);
+        try {
+            const [navigation, selection, pendingSelection, url] = await Promise.all([
+                readScopedAppState("navigation", browserTabId),
+                readScopedAppState("selection", browserTabId),
+                readScopedAppState("pending-selection-context", browserTabId),
+                readScopedAppState("__url__", browserTabId),
+            ]);
+            if (generation !== loadGenerationRef.current)
+                return;
+            setContext({ navigation, selection, pendingSelection, url, scope });
+        }
+        catch {
+            if (generation !== loadGenerationRef.current)
+                return;
+            setContext({
+                navigation: null,
+                selection: null,
+                pendingSelection: null,
+                url: null,
+                scope,
+            });
+        }
+        finally {
+            if (generation === loadGenerationRef.current && showLoading) {
+                setIsLoading(false);
+            }
+        }
+    }, [browserTabId, scope]);
     useEffect(() => {
+        loadGenerationRef.current += 1;
         if (!enabled) {
             setContext(null);
             setIsLoading(false);
             return;
         }
-        let cancelled = false;
-        const load = async (showLoading) => {
-            if (showLoading)
-                setIsLoading(true);
-            try {
-                const [navigation, selection, pendingSelection, url] = await Promise.all([
-                    readScopedAppState("navigation", browserTabId),
-                    readScopedAppState("selection", browserTabId),
-                    readScopedAppState("pending-selection-context", browserTabId),
-                    readScopedAppState("__url__", browserTabId),
-                ]);
-                if (cancelled)
-                    return;
-                setContext({
-                    navigation,
-                    selection,
-                    pendingSelection,
-                    url,
-                    scope,
-                });
-            }
-            catch {
-                if (cancelled)
-                    return;
-                setContext({
-                    navigation: null,
-                    selection: null,
-                    pendingSelection: null,
-                    url: null,
-                    scope,
-                });
-            }
-            finally {
-                if (!cancelled && showLoading)
-                    setIsLoading(false);
-            }
-        };
         void load(true);
-        const interval = setInterval(() => {
-            // The useEffect deps already include appStateVersion, so app-state
-            // changes trigger an immediate event-driven refresh above. This
-            // interval is only a slow safety net for updates that don't bump
-            // that version — skip ticks while the tab isn't visible.
-            if (document.hidden)
-                return;
-            void load(false);
-        }, 30_000);
-        return () => {
-            cancelled = true;
-            clearInterval(interval);
-        };
-    }, [appStateVersion, browserTabId, enabled, scope, scopeKey]);
+    }, [appStateVersion, enabled, load, scopeKey, config]);
+    // Slow safety net for app-state updates that don't bump `appStateVersion`
+    // (the effect above already handles the event-driven case). `pollMs <= 0`
+    // disables it.
+    usePollLoop(() => load(false), {
+        intervalMs: config.pollMs,
+        leading: false,
+        enabled: enabled && config.pollMs > 0,
+    });
     const suggestions = useMemo(() => {
         if (!enabled) {
             return options.staticSuggestions

package/dist/client/hooks/index.d.ts

@@ -10,3 +10,4 @@ export { createAgentNativeQueryClient } from "../create-query-client.js";
 export { AppProviders, type AppProvidersProps } from "../app-providers.js";
 export { usePinchZoom, type UsePinchZoomOptions } from "../use-pinch-zoom.js";
 export { useAvatarUrl, uploadAvatar, invalidateAvatarCache, } from "../use-avatar.js";
+export { usePollLoop, type UsePollLoopOptions, type UsePollLoopHandle, } from "../use-poll-loop.js";

package/dist/client/hooks/index.js

@@ -10,3 +10,4 @@ export { createAgentNativeQueryClient } from "../create-query-client.js";
 export { AppProviders } from "../app-providers.js";
 export { usePinchZoom } from "../use-pinch-zoom.js";
 export { useAvatarUrl, uploadAvatar, invalidateAvatarCache, } from "../use-avatar.js";
+export { usePollLoop, } from "../use-poll-loop.js";

package/dist/client/i18n.d.ts

@@ -14,6 +14,12 @@ export interface AgentNativeI18nCatalog {
     sourceLocale?: LocaleCode;
     messages?: LocaleMessages;
     loadMessages?: (locale: LocaleCode) => Promise<LocaleMessages | null>;
+    /**
+     * Locales this app actually ships translations for. Defaults to every
+     * framework-supported locale when omitted, which only matches apps whose
+     * `loadMessages` covers all of them.
+     */
+    supportedLocales?: readonly LocaleCode[];
 }
 export interface AgentNativeI18nProviderProps {
     children: React.ReactNode;
@@ -31,6 +37,7 @@ interface LocaleContextValue {
     metadata: LocaleMetadata;
     setPreference: (preference: LocalePreference) => Promise<void>;
     loading: boolean;
+    supportedLocales: readonly LocaleCode[];
 }
 declare global {
     var __AGENT_NATIVE_LOCALE_CONTEXT__: React.Context<LocaleContextValue | null> | undefined;

package/dist/client/i18n.js

@@ -155,6 +155,7 @@ export function AgentNativeI18nProvider({ children, catalog, initialLocale, init
     const sourceLocale = catalog?.sourceLocale ?? DEFAULT_LOCALE;
     const sourceMessages = catalog?.messages ?? {};
     const loadMessages = catalog?.loadMessages;
+    const supportedLocales = catalog?.supportedLocales ?? SUPPORTED_LOCALES;
     const hydration = readHydrationPayload();
     const initialState = useMemo(() => resolveInitialState({ initialLocale, initialPreference }), [initialLocale, initialPreference]);
     const [preference, setPreferenceState] = useState(initialState.preference);
@@ -305,7 +306,15 @@ export function AgentNativeI18nProvider({ children, catalog, initialLocale, init
         metadata: LOCALE_METADATA[locale],
         setPreference,
         loading,
-    }), [loading, locale, preference, setPreference, sourceLocale]);
+        supportedLocales,
+    }), [
+        loading,
+        locale,
+        preference,
+        setPreference,
+        sourceLocale,
+        supportedLocales,
+    ]);
     return (_jsx(LocaleContext.Provider, { value: context, children: _jsx(I18nextProvider, { i18n: i18n, children: children }) }));
 }
 export function useLocale() {
@@ -472,7 +481,7 @@ export function useFormatters() {
     }), [locale]);
 }
 export function LanguagePicker({ className, includeSystem = true, label, variant = "select", }) {
-    const { locale, preference, setPreference } = useLocale();
+    const { locale, preference, setPreference, supportedLocales } = useLocale();
     const [open, setOpen] = useState(false);
     const copy = LANGUAGE_PICKER_COPY[locale] ?? LANGUAGE_PICKER_COPY[DEFAULT_LOCALE];
     const resolvedLabel = label ?? copy.label;
@@ -486,7 +495,7 @@ export function LanguagePicker({ className, includeSystem = true, label, variant
                 },
             ]
             : []),
-        ...SUPPORTED_LOCALES.map((code) => ({
+        ...supportedLocales.map((code) => ({
             value: code,
             label: `${LOCALE_METADATA[code].nativeName} (${code})`,
             description: code,

package/dist/client/integrations/useIntegrationStatus.d.ts

@@ -10,5 +10,5 @@ export interface IntegrationStatus {
 export declare function useIntegrationStatus(): {
     statuses: IntegrationStatus[];
     loading: boolean;
-    refetch: () => Promise<void>;
+    refetch: (signal?: AbortSignal) => Promise<void>;
 };

package/dist/client/integrations/useIntegrationStatus.js

@@ -1,37 +1,24 @@
-import { useState, useEffect, useCallback, useRef } from "react";
+import { useState, useCallback } from "react";
 import { agentNativePath } from "../api-path.js";
+import { usePollLoop } from "../use-poll-loop.js";
 export function useIntegrationStatus() {
     const [statuses, setStatuses] = useState([]);
     const [loading, setLoading] = useState(true);
-    const mountedRef = useRef(true);
-    const fetchStatuses = useCallback(async () => {
+    const fetchStatuses = useCallback(async (signal) => {
         try {
-            const res = await fetch(agentNativePath("/_agent-native/integrations/status"));
+            const res = await fetch(agentNativePath("/_agent-native/integrations/status"), { signal });
             if (!res.ok) {
-                if (mountedRef.current)
-                    setLoading(false);
+                setLoading(false);
                 return;
             }
             const data = await res.json();
-            if (mountedRef.current) {
-                setStatuses(Array.isArray(data) ? data : []);
-                setLoading(false);
-            }
+            setStatuses(Array.isArray(data) ? data : []);
+            setLoading(false);
         }
         catch {
-            if (mountedRef.current) {
-                setLoading(false);
-            }
+            setLoading(false);
         }
     }, []);
-    useEffect(() => {
-        mountedRef.current = true;
-        fetchStatuses();
-        const interval = setInterval(fetchStatuses, 30000);
-        return () => {
-            mountedRef.current = false;
-            clearInterval(interval);
-        };
-    }, [fetchStatuses]);
+    usePollLoop(fetchStatuses, { intervalMs: 30_000 });
     return { statuses, loading, refetch: fetchStatuses };
 }

package/dist/client/notifications/NotificationsBell.js

@@ -3,7 +3,7 @@ import { IconBell, IconBellRinging, IconLoader2, IconX, } from "@tabler/icons-re
 import { useCallback, useEffect, useRef, useState } from "react";
 import { agentNativePath, appPath } from "../api-path.js";
 import { Popover, PopoverContent, PopoverTrigger, } from "../components/ui/popover.js";
-import { usePausingInterval } from "../use-pausing-interval.js";
+import { usePollLoop } from "../use-poll-loop.js";
 const POLL_MS_DEFAULT = 10_000;
 const SUPPORTS_NOTIFICATION = typeof window !== "undefined" && "Notification" in window;
 /**
@@ -47,10 +47,10 @@ export function NotificationsBell({ pollMs = POLL_MS_DEFAULT, className, browser
     // the popup loop — no second /count request), and pop Notification() for
     // any new ids. When off, we fetch just /count. The unread-list branch also
     // opts out of visibility pause so popups still fire for backgrounded tabs.
-    const refresh = useCallback(async () => {
+    const refresh = useCallback(async (signal) => {
         if (browserNotifications) {
             try {
-                const res = await fetch(agentNativePath("/_agent-native/notifications?unread=true&limit=20"));
+                const res = await fetch(agentNativePath("/_agent-native/notifications?unread=true&limit=20"), { signal });
                 if (!res.ok)
                     return;
                 const rows = (await res.json());
@@ -74,19 +74,21 @@ export function NotificationsBell({ pollMs = POLL_MS_DEFAULT, className, browser
                         new Notification(n.title, { body: n.body, tag: n.id });
                     }
                     catch {
-                        // Safari / restricted contexts may throw even when permission
-                        // claims to be granted — silent no-op.
+                        // coercion-ok: Safari / restricted contexts may throw even when
+                        // permission claims to be granted; one failed OS notification
+                        // must not abort the unread sweep around it.
                     }
                 }
                 seenIdsRef.current = seen;
             }
             catch {
-                // best-effort
+                // coercion-ok: the bell renders from the rows it already has; a
+                // failed sweep is retried by the next poll tick.
             }
             return;
         }
         try {
-            const res = await fetch(agentNativePath("/_agent-native/notifications/count"));
+            const res = await fetch(agentNativePath("/_agent-native/notifications/count"), { signal });
             if (!res.ok)
                 return;
             const data = (await res.json());
@@ -96,8 +98,11 @@ export function NotificationsBell({ pollMs = POLL_MS_DEFAULT, className, browser
             // best-effort
         }
     }, [browserNotifications]);
-    usePausingInterval(refresh, pollMs, 
-    /* pauseWhenHidden */ !browserNotifications);
+    usePollLoop(refresh, {
+        intervalMs: pollMs,
+        enabled: pollMs > 0,
+        pauseWhenHidden: !browserNotifications,
+    });
     useEffect(() => {
         if (!open)
             return;