@open-mercato/ui 0.10.1-develop.7618.1.ba9531c18e → 0.10.1-develop.7622.1.0584ba2a04

package/dist/ai/parts/useAiPendingActionPolling.js

@@ -1,7 +1,7 @@
 "use client";
 import * as React from "react";
 import { createLogger } from "@open-mercato/shared/lib/logger";
-import { apiCallOrThrow } from "../../backend/utils/apiCall.js";
+import { apiCall } from "../../backend/utils/apiCall.js";
 const logger = createLogger("ui").child({ component: "useAiPendingActionPolling" });
 const TERMINAL_STATUSES = [
   "confirmed",
@@ -9,29 +9,47 @@ const TERMINAL_STATUSES = [
   "failed",
   "expired"
 ];
+const TERMINAL_HTTP_ERROR_CODES = ["not_found", "unauthorized", "forbidden"];
+const MAX_BACKOFF_MS = 6e4;
+const MAX_CONSECUTIVE_FAILURES = 5;
 function isTerminal(status) {
   if (!status) return false;
   return TERMINAL_STATUSES.includes(status);
 }
+function httpStatusToErrorCode(status) {
+  if (status === 404) return "not_found";
+  if (status === 401) return "unauthorized";
+  if (status === 403) return "forbidden";
+  return null;
+}
+function isHiddenDocument() {
+  return typeof document !== "undefined" && document.visibilityState === "hidden";
+}
 async function fetchPendingAction(pendingActionId, endpoint) {
   const url = `${endpoint}/${encodeURIComponent(pendingActionId)}`;
-  const call = await apiCallOrThrow(url, { method: "GET" });
+  const call = await apiCall(url, { method: "GET" });
   const body = call.result;
+  if (!call.ok) {
+    const code = httpStatusToErrorCode(call.status) ?? body?.code ?? "request_failed";
+    const message = body?.error ?? `Request failed with status ${call.status}.`;
+    return { ok: false, pendingAction: null, error: { code, message } };
+  }
   if (body && typeof body === "object") {
     if (body.pendingAction) {
-      return { pendingAction: body.pendingAction, error: null };
+      return { ok: true, pendingAction: body.pendingAction, error: null };
     }
     if (typeof body.id === "string" && typeof body.status === "string") {
-      return { pendingAction: body, error: null };
+      return { ok: true, pendingAction: body, error: null };
     }
     if (body.error) {
       return {
+        ok: true,
         pendingAction: null,
         error: { message: body.error, code: body.code }
       };
     }
   }
-  return { pendingAction: null, error: null };
+  return { ok: true, pendingAction: null, error: null };
 }
 function useAiPendingActionPolling(options) {
   const {
@@ -46,6 +64,12 @@ function useAiPendingActionPolling(options) {
   const mountedRef = React.useRef(true);
   const timerRef = React.useRef(null);
   const statusRef = React.useRef(null);
+  const terminalErrorCodeRef = React.useRef(null);
+  const consecutiveFailuresRef = React.useRef(0);
+  const stoppedRef = React.useRef(false);
+  const hiddenRef = React.useRef(isHiddenDocument());
+  const scheduleNextRef = React.useRef(() => {
+  });
   const clearTimer = React.useCallback(() => {
     if (timerRef.current) {
       clearTimeout(timerRef.current);
@@ -54,26 +78,46 @@ function useAiPendingActionPolling(options) {
   }, []);
   const refresh = React.useCallback(async () => {
     if (!pendingActionId) return null;
+    let pendingAction = null;
     try {
       const result = await fetchPendingAction(pendingActionId, endpoint);
       if (!mountedRef.current) return result.pendingAction ?? null;
-      if (result.error) {
-        setError(result.error);
+      pendingAction = result.pendingAction ?? null;
+      if (result.ok) {
+        consecutiveFailuresRef.current = 0;
+        stoppedRef.current = false;
+        terminalErrorCodeRef.current = null;
+        setError(result.error ?? null);
+        if (result.pendingAction) {
+          setAction(result.pendingAction);
+          statusRef.current = result.pendingAction.status;
+        }
       } else {
-        setError(null);
+        setError(result.error ?? null);
+        const code = result.error?.code;
+        if (code && TERMINAL_HTTP_ERROR_CODES.includes(code)) {
+          terminalErrorCodeRef.current = code;
+        } else {
+          consecutiveFailuresRef.current += 1;
+          if (consecutiveFailuresRef.current >= MAX_CONSECUTIVE_FAILURES) {
+            stoppedRef.current = true;
+          }
+        }
       }
-      if (result.pendingAction) {
-        setAction(result.pendingAction);
-        statusRef.current = result.pendingAction.status;
-      }
-      return result.pendingAction;
     } catch (err) {
       logger.error("Failed to load the pending AI action", { err, pendingActionId });
       if (!mountedRef.current) return null;
       const message = err instanceof Error ? err.message : "Failed to load pending action.";
       setError({ message });
-      return null;
+      consecutiveFailuresRef.current += 1;
+      if (consecutiveFailuresRef.current >= MAX_CONSECUTIVE_FAILURES) {
+        stoppedRef.current = true;
+      }
+    }
+    if (mountedRef.current) {
+      scheduleNextRef.current();
     }
+    return pendingAction;
   }, [endpoint, pendingActionId]);
   const scheduleNext = React.useCallback(() => {
     clearTimer();
@@ -86,19 +130,50 @@ function useAiPendingActionPolling(options) {
       setIsPolling(false);
       return;
     }
+    if (terminalErrorCodeRef.current) {
+      setIsPolling(false);
+      return;
+    }
+    if (stoppedRef.current) {
+      setIsPolling(false);
+      return;
+    }
+    if (hiddenRef.current) {
+      return;
+    }
     setIsPolling(true);
-    timerRef.current = setTimeout(async () => {
-      try {
-        await refresh();
-      } catch (err) {
-        logger.error("Polling the pending AI action failed unexpectedly", { err });
-      }
-      scheduleNext();
-    }, intervalMs);
+    const delay = consecutiveFailuresRef.current > 0 ? Math.min(intervalMs * 2 ** consecutiveFailuresRef.current, MAX_BACKOFF_MS) : intervalMs;
+    timerRef.current = setTimeout(() => {
+      void refresh();
+    }, delay);
   }, [clearTimer, disabled, intervalMs, refresh]);
+  React.useEffect(() => {
+    scheduleNextRef.current = scheduleNext;
+  }, [scheduleNext]);
+  React.useEffect(() => {
+    if (disabled) return;
+    const handleVisibilityChange = () => {
+      const wasHidden = hiddenRef.current;
+      hiddenRef.current = isHiddenDocument();
+      if (!wasHidden && hiddenRef.current) {
+        clearTimer();
+        return;
+      }
+      if (wasHidden && !hiddenRef.current && mountedRef.current) {
+        void refresh();
+      }
+    };
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+    return () => {
+      document.removeEventListener("visibilitychange", handleVisibilityChange);
+    };
+  }, [clearTimer, disabled, refresh]);
   React.useEffect(() => {
     mountedRef.current = true;
     statusRef.current = null;
+    terminalErrorCodeRef.current = null;
+    consecutiveFailuresRef.current = 0;
+    stoppedRef.current = false;
     if (disabled) {
       setIsPolling(false);
       return () => {
@@ -107,13 +182,7 @@ function useAiPendingActionPolling(options) {
       };
     }
     setIsPolling(true);
-    void refresh().catch((err) => {
-      logger.error("Loading the pending AI action failed unexpectedly", { err });
-      return null;
-    }).then(() => {
-      if (!mountedRef.current) return;
-      scheduleNext();
-    });
+    void refresh();
     return () => {
       mountedRef.current = false;
       clearTimer();

package/dist/ai/parts/useAiPendingActionPolling.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/ai/parts/useAiPendingActionPolling.ts"],
-  "sourcesContent": ["\"use client\"\n\nimport * as React from 'react'\nimport { createLogger } from '@open-mercato/shared/lib/logger'\nimport { apiCallOrThrow } from '../../backend/utils/apiCall'\nimport type { AiPendingActionCardAction, AiPendingActionCardStatus } from './types'\n\nconst logger = createLogger('ui').child({ component: 'useAiPendingActionPolling' })\n\n/**\n * Shared polling hook for the Phase 3 mutation-approval cards (Step 5.10).\n *\n * Responsibilities:\n * - Fetch `GET /api/ai_assistant/ai/actions/:id` on mount, even when the\n *   server previously streamed a preview card. This is the \"reconnect\" path:\n *   after a page reload or navigation away+back, the card recovers the\n *   current pending-action state instead of staying blank.\n * - Poll every 3 seconds while the status is non-terminal\n *   (`pending` / `executing`). Terminal states (`confirmed`, `cancelled`,\n *   `failed`, `expired`) stop polling.\n * - Expose a `refresh()` force-fetch helper the confirmation card uses after\n *   a confirm POST races with the polling loop.\n *\n * The hook owns a single `setInterval`/`setTimeout` \u2014 unmounting clears\n * every outstanding timer. This is required for the Jest fake-timers\n * \"mount, unmount mid-poll\" test contract.\n */\n\nconst TERMINAL_STATUSES: ReadonlyArray<AiPendingActionCardStatus> = [\n  'confirmed',\n  'cancelled',\n  'failed',\n  'expired',\n]\n\nfunction isTerminal(status: AiPendingActionCardStatus | null): boolean {\n  if (!status) return false\n  return TERMINAL_STATUSES.includes(status)\n}\n\nexport interface UseAiPendingActionPollingOptions {\n  pendingActionId: string\n  /**\n   * Poll interval in ms while the status is non-terminal. Defaults to 3000.\n   */\n  intervalMs?: number\n  /**\n   * Endpoint base. Override to point at a mock during tests.\n   */\n  endpoint?: string\n  /**\n   * When true, the hook does NOT schedule any network activity. Used by the\n   * result card which already holds a terminal state and only needs to read\n   * what the preview card fetched.\n   */\n  disabled?: boolean\n}\n\nexport interface AiPendingActionFetchResult {\n  pendingAction: AiPendingActionCardAction | null\n  error?: { code?: string; message: string } | null\n}\n\nexport interface UseAiPendingActionPollingResult {\n  action: AiPendingActionCardAction | null\n  status: AiPendingActionCardStatus | null\n  isPolling: boolean\n  error: { code?: string; message: string } | null\n  refresh: () => Promise<AiPendingActionCardAction | null>\n}\n\nasync function fetchPendingAction(\n  pendingActionId: string,\n  endpoint: string,\n): Promise<AiPendingActionFetchResult> {\n  const url = `${endpoint}/${encodeURIComponent(pendingActionId)}`\n  const call = await apiCallOrThrow<unknown>(url, { method: 'GET' })\n  const body = call.result as\n    | (Partial<AiPendingActionCardAction> & {\n        pendingAction?: AiPendingActionCardAction\n        error?: string\n        code?: string\n      })\n    | null\n    | undefined\n\n  // The GET route returns the bare action object (`serializePendingActionForClient(row)`),\n  // but earlier client code expected it under a `pendingAction` envelope.\n  // Accept BOTH shapes so the cards work whether the dispatcher wraps or\n  // not \u2014 bare-object payloads were the actual cause of empty\n  // `fieldDiff` and missing `executionResult.error` displays in\n  // MutationPreviewCard / ConfirmationCard / MutationResultCard.\n  if (body && typeof body === 'object') {\n    if (body.pendingAction) {\n      return { pendingAction: body.pendingAction, error: null }\n    }\n    if (\n      typeof (body as Partial<AiPendingActionCardAction>).id === 'string' &&\n      typeof (body as Partial<AiPendingActionCardAction>).status === 'string'\n    ) {\n      return { pendingAction: body as AiPendingActionCardAction, error: null }\n    }\n    if (body.error) {\n      return {\n        pendingAction: null,\n        error: { message: body.error, code: body.code },\n      }\n    }\n  }\n  return { pendingAction: null, error: null }\n}\n\nexport function useAiPendingActionPolling(\n  options: UseAiPendingActionPollingOptions,\n): UseAiPendingActionPollingResult {\n  const {\n    pendingActionId,\n    intervalMs = 3000,\n    endpoint = '/api/ai_assistant/ai/actions',\n    disabled = false,\n  } = options\n\n  const [action, setAction] = React.useState<AiPendingActionCardAction | null>(null)\n  const [error, setError] = React.useState<{ code?: string; message: string } | null>(null)\n  const [isPolling, setIsPolling] = React.useState<boolean>(!disabled)\n\n  const mountedRef = React.useRef(true)\n  const timerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null)\n  const statusRef = React.useRef<AiPendingActionCardStatus | null>(null)\n\n  const clearTimer = React.useCallback(() => {\n    if (timerRef.current) {\n      clearTimeout(timerRef.current)\n      timerRef.current = null\n    }\n  }, [])\n\n  const refresh = React.useCallback(async (): Promise<AiPendingActionCardAction | null> => {\n    if (!pendingActionId) return null\n    try {\n      const result = await fetchPendingAction(pendingActionId, endpoint)\n      if (!mountedRef.current) return result.pendingAction ?? null\n      if (result.error) {\n        setError(result.error)\n      } else {\n        setError(null)\n      }\n      if (result.pendingAction) {\n        setAction(result.pendingAction)\n        statusRef.current = result.pendingAction.status\n      }\n      return result.pendingAction\n    } catch (err) {\n      logger.error('Failed to load the pending AI action', { err, pendingActionId })\n      if (!mountedRef.current) return null\n      const message = err instanceof Error ? err.message : 'Failed to load pending action.'\n      setError({ message })\n      return null\n    }\n  }, [endpoint, pendingActionId])\n\n  const scheduleNext = React.useCallback(() => {\n    clearTimer()\n    if (!mountedRef.current) return\n    if (disabled) {\n      setIsPolling(false)\n      return\n    }\n    if (isTerminal(statusRef.current)) {\n      setIsPolling(false)\n      return\n    }\n    setIsPolling(true)\n    timerRef.current = setTimeout(async () => {\n      try {\n        await refresh()\n      } catch (err) {\n        logger.error('Polling the pending AI action failed unexpectedly', { err })\n      }\n      scheduleNext()\n    }, intervalMs)\n  }, [clearTimer, disabled, intervalMs, refresh])\n\n  React.useEffect(() => {\n    mountedRef.current = true\n    statusRef.current = null\n    if (disabled) {\n      setIsPolling(false)\n      return () => {\n        mountedRef.current = false\n        clearTimer()\n      }\n    }\n    setIsPolling(true)\n    // Always fetch on mount \u2014 the \"reconnect behavior\" guarantee. The catch\n    // runs before the scheduling step so a rejected first fetch degrades to a\n    // logged error instead of silently killing the polling loop.\n    void refresh()\n      .catch((err) => {\n        logger.error('Loading the pending AI action failed unexpectedly', { err })\n        return null\n      })\n      .then(() => {\n        if (!mountedRef.current) return\n        scheduleNext()\n      })\n    return () => {\n      mountedRef.current = false\n      clearTimer()\n    }\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [pendingActionId, endpoint, intervalMs, disabled])\n\n  const status = action?.status ?? null\n\n  return {\n    action,\n    status,\n    isPolling: isPolling && !isTerminal(status),\n    error,\n    refresh,\n  }\n}\n\nexport default useAiPendingActionPolling\n"],
-  "mappings": "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",
+  "sourcesContent": ["\"use client\"\n\nimport * as React from 'react'\nimport { createLogger } from '@open-mercato/shared/lib/logger'\nimport { apiCall } from '../../backend/utils/apiCall'\nimport type { AiPendingActionCardAction, AiPendingActionCardStatus } from './types'\n\nconst logger = createLogger('ui').child({ component: 'useAiPendingActionPolling' })\n\n/**\n * Shared polling hook for the Phase 3 mutation-approval cards (Step 5.10).\n *\n * Responsibilities:\n * - Fetch `GET /api/ai_assistant/ai/actions/:id` on mount, even when the\n *   server previously streamed a preview card. This is the \"reconnect\" path:\n *   after a page reload or navigation away+back, the card recovers the\n *   current pending-action state instead of staying blank.\n * - Poll every 3 seconds while the status is non-terminal\n *   (`pending` / `executing`). Terminal states (`confirmed`, `cancelled`,\n *   `failed`, `expired`) stop polling.\n * - A 404/401/403 from the endpoint is also terminal \u2014 the row is gone or\n *   unreachable and retrying cannot help (issue #7550: without this, every\n *   card whose row disappeared polled every 3s forever, in every tab).\n * - Any other failure (5xx, network error) backs off exponentially (capped\n *   at 60s) and gives up after 5 consecutive failures.\n * - Polling pauses while the tab is hidden (`document.visibilityState`) and\n *   resumes on `visibilitychange`.\n * - Expose a `refresh()` force-fetch helper the confirmation card uses after\n *   a confirm POST races with the polling loop. `refresh()` also restarts a\n *   stopped loop (backoff-exhausted or resumed-from-hidden) without\n *   creating a second timer chain.\n *\n * The hook owns a single `setInterval`/`setTimeout` \u2014 unmounting clears\n * every outstanding timer. This is required for the Jest fake-timers\n * \"mount, unmount mid-poll\" test contract.\n */\n\nconst TERMINAL_STATUSES: ReadonlyArray<AiPendingActionCardStatus> = [\n  'confirmed',\n  'cancelled',\n  'failed',\n  'expired',\n]\n\nconst TERMINAL_HTTP_ERROR_CODES: ReadonlyArray<string> = ['not_found', 'unauthorized', 'forbidden']\n\nconst MAX_BACKOFF_MS = 60_000\nconst MAX_CONSECUTIVE_FAILURES = 5\n\nfunction isTerminal(status: AiPendingActionCardStatus | null): boolean {\n  if (!status) return false\n  return TERMINAL_STATUSES.includes(status)\n}\n\nfunction httpStatusToErrorCode(status: number): string | null {\n  if (status === 404) return 'not_found'\n  if (status === 401) return 'unauthorized'\n  if (status === 403) return 'forbidden'\n  return null\n}\n\nfunction isHiddenDocument(): boolean {\n  return typeof document !== 'undefined' && document.visibilityState === 'hidden'\n}\n\nexport interface UseAiPendingActionPollingOptions {\n  pendingActionId: string\n  /**\n   * Poll interval in ms while the status is non-terminal. Defaults to 3000.\n   */\n  intervalMs?: number\n  /**\n   * Endpoint base. Override to point at a mock during tests.\n   */\n  endpoint?: string\n  /**\n   * When true, the hook does NOT schedule any network activity. Used by the\n   * result card which already holds a terminal state and only needs to read\n   * what the preview card fetched.\n   */\n  disabled?: boolean\n}\n\nexport interface AiPendingActionFetchResult {\n  ok: boolean\n  pendingAction: AiPendingActionCardAction | null\n  error?: { code?: string; message: string } | null\n}\n\nexport interface UseAiPendingActionPollingResult {\n  action: AiPendingActionCardAction | null\n  status: AiPendingActionCardStatus | null\n  isPolling: boolean\n  error: { code?: string; message: string } | null\n  refresh: () => Promise<AiPendingActionCardAction | null>\n}\n\nasync function fetchPendingAction(\n  pendingActionId: string,\n  endpoint: string,\n): Promise<AiPendingActionFetchResult> {\n  const url = `${endpoint}/${encodeURIComponent(pendingActionId)}`\n  const call = await apiCall<unknown>(url, { method: 'GET' })\n  const body = call.result as\n    | (Partial<AiPendingActionCardAction> & {\n        pendingAction?: AiPendingActionCardAction\n        error?: string\n        code?: string\n      })\n    | null\n    | undefined\n\n  if (!call.ok) {\n    const code = httpStatusToErrorCode(call.status) ?? body?.code ?? 'request_failed'\n    const message = body?.error ?? `Request failed with status ${call.status}.`\n    return { ok: false, pendingAction: null, error: { code, message } }\n  }\n\n  // The GET route returns the bare action object (`serializePendingActionForClient(row)`),\n  // but earlier client code expected it under a `pendingAction` envelope.\n  // Accept BOTH shapes so the cards work whether the dispatcher wraps or\n  // not \u2014 bare-object payloads were the actual cause of empty\n  // `fieldDiff` and missing `executionResult.error` displays in\n  // MutationPreviewCard / ConfirmationCard / MutationResultCard.\n  if (body && typeof body === 'object') {\n    if (body.pendingAction) {\n      return { ok: true, pendingAction: body.pendingAction, error: null }\n    }\n    if (\n      typeof (body as Partial<AiPendingActionCardAction>).id === 'string' &&\n      typeof (body as Partial<AiPendingActionCardAction>).status === 'string'\n    ) {\n      return { ok: true, pendingAction: body as AiPendingActionCardAction, error: null }\n    }\n    if (body.error) {\n      return {\n        ok: true,\n        pendingAction: null,\n        error: { message: body.error, code: body.code },\n      }\n    }\n  }\n  return { ok: true, pendingAction: null, error: null }\n}\n\nexport function useAiPendingActionPolling(\n  options: UseAiPendingActionPollingOptions,\n): UseAiPendingActionPollingResult {\n  const {\n    pendingActionId,\n    intervalMs = 3000,\n    endpoint = '/api/ai_assistant/ai/actions',\n    disabled = false,\n  } = options\n\n  const [action, setAction] = React.useState<AiPendingActionCardAction | null>(null)\n  const [error, setError] = React.useState<{ code?: string; message: string } | null>(null)\n  const [isPolling, setIsPolling] = React.useState<boolean>(!disabled)\n\n  const mountedRef = React.useRef(true)\n  const timerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null)\n  const statusRef = React.useRef<AiPendingActionCardStatus | null>(null)\n  const terminalErrorCodeRef = React.useRef<string | null>(null)\n  const consecutiveFailuresRef = React.useRef(0)\n  const stoppedRef = React.useRef(false)\n  const hiddenRef = React.useRef(isHiddenDocument())\n  const scheduleNextRef = React.useRef<() => void>(() => {})\n\n  const clearTimer = React.useCallback(() => {\n    if (timerRef.current) {\n      clearTimeout(timerRef.current)\n      timerRef.current = null\n    }\n  }, [])\n\n  const refresh = React.useCallback(async (): Promise<AiPendingActionCardAction | null> => {\n    if (!pendingActionId) return null\n    let pendingAction: AiPendingActionCardAction | null = null\n    try {\n      const result = await fetchPendingAction(pendingActionId, endpoint)\n      if (!mountedRef.current) return result.pendingAction ?? null\n      pendingAction = result.pendingAction ?? null\n      if (result.ok) {\n        consecutiveFailuresRef.current = 0\n        stoppedRef.current = false\n        terminalErrorCodeRef.current = null\n        setError(result.error ?? null)\n        if (result.pendingAction) {\n          setAction(result.pendingAction)\n          statusRef.current = result.pendingAction.status\n        }\n      } else {\n        setError(result.error ?? null)\n        const code = result.error?.code\n        if (code && TERMINAL_HTTP_ERROR_CODES.includes(code)) {\n          terminalErrorCodeRef.current = code\n        } else {\n          consecutiveFailuresRef.current += 1\n          if (consecutiveFailuresRef.current >= MAX_CONSECUTIVE_FAILURES) {\n            stoppedRef.current = true\n          }\n        }\n      }\n    } catch (err) {\n      logger.error('Failed to load the pending AI action', { err, pendingActionId })\n      if (!mountedRef.current) return null\n      const message = err instanceof Error ? err.message : 'Failed to load pending action.'\n      setError({ message })\n      consecutiveFailuresRef.current += 1\n      if (consecutiveFailuresRef.current >= MAX_CONSECUTIVE_FAILURES) {\n        stoppedRef.current = true\n      }\n    }\n    if (mountedRef.current) {\n      scheduleNextRef.current()\n    }\n    return pendingAction\n  }, [endpoint, pendingActionId])\n\n  const scheduleNext = React.useCallback(() => {\n    clearTimer()\n    if (!mountedRef.current) return\n    if (disabled) {\n      setIsPolling(false)\n      return\n    }\n    if (isTerminal(statusRef.current)) {\n      setIsPolling(false)\n      return\n    }\n    if (terminalErrorCodeRef.current) {\n      setIsPolling(false)\n      return\n    }\n    if (stoppedRef.current) {\n      setIsPolling(false)\n      return\n    }\n    if (hiddenRef.current) {\n      // Paused while the tab is hidden. `visibilitychange` resumes via refresh().\n      return\n    }\n    setIsPolling(true)\n    const delay =\n      consecutiveFailuresRef.current > 0\n        ? Math.min(intervalMs * 2 ** consecutiveFailuresRef.current, MAX_BACKOFF_MS)\n        : intervalMs\n    timerRef.current = setTimeout(() => {\n      void refresh()\n    }, delay)\n  }, [clearTimer, disabled, intervalMs, refresh])\n\n  React.useEffect(() => {\n    scheduleNextRef.current = scheduleNext\n  }, [scheduleNext])\n\n  React.useEffect(() => {\n    if (disabled) return\n    const handleVisibilityChange = () => {\n      const wasHidden = hiddenRef.current\n      hiddenRef.current = isHiddenDocument()\n      if (!wasHidden && hiddenRef.current) {\n        // Cancel any already-scheduled poll immediately \u2014 do not wait for\n        // it to fire before honoring the pause.\n        clearTimer()\n        return\n      }\n      if (wasHidden && !hiddenRef.current && mountedRef.current) {\n        // Resume immediately rather than waiting out a stale backoff delay.\n        void refresh()\n      }\n    }\n    document.addEventListener('visibilitychange', handleVisibilityChange)\n    return () => {\n      document.removeEventListener('visibilitychange', handleVisibilityChange)\n    }\n  }, [clearTimer, disabled, refresh])\n\n  React.useEffect(() => {\n    mountedRef.current = true\n    statusRef.current = null\n    terminalErrorCodeRef.current = null\n    consecutiveFailuresRef.current = 0\n    stoppedRef.current = false\n    if (disabled) {\n      setIsPolling(false)\n      return () => {\n        mountedRef.current = false\n        clearTimer()\n      }\n    }\n    setIsPolling(true)\n    // Always fetch on mount \u2014 the \"reconnect behavior\" guarantee. `refresh`\n    // schedules the next poll itself once it settles.\n    void refresh()\n    return () => {\n      mountedRef.current = false\n      clearTimer()\n    }\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [pendingActionId, endpoint, intervalMs, disabled])\n\n  const status = action?.status ?? null\n\n  return {\n    action,\n    status,\n    isPolling: isPolling && !isTerminal(status),\n    error,\n    refresh,\n  }\n}\n\nexport default useAiPendingActionPolling\n"],
+  "mappings": "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",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/ui",
-  "version": "0.10.1-develop.7618.1.ba9531c18e",
+  "version": "0.10.1-develop.7622.1.0584ba2a04",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -155,14 +155,14 @@
     "remark-gfm": "^4.0.1"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.10.1-develop.7618.1.ba9531c18e",
+    "@open-mercato/shared": "0.10.1-develop.7622.1.0584ba2a04",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0",
     "react-is": ">=18.0.0"
   },
   "devDependencies": {
     "@figma/code-connect": "^1.3.4",
-    "@open-mercato/shared": "0.10.1-develop.7618.1.ba9531c18e",
+    "@open-mercato/shared": "0.10.1-develop.7622.1.0584ba2a04",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^7.0.1",
     "@testing-library/react": "^16.3.3",

package/src/ai/parts/__tests__/useAiPendingActionPolling.test.tsx

@@ -6,7 +6,7 @@ import * as React from 'react'
 import { act, renderHook, waitFor } from '@testing-library/react'
 
 jest.mock('../../../backend/utils/apiCall', () => ({
-  apiCallOrThrow: jest.fn(),
+  apiCall: jest.fn(),
 }))
 
 jest.mock('@open-mercato/shared/lib/logger', () => {
@@ -22,7 +22,7 @@ jest.mock('@open-mercato/shared/lib/logger', () => {
 })
 
 import { createLogger } from '@open-mercato/shared/lib/logger'
-import { apiCallOrThrow } from '../../../backend/utils/apiCall'
+import { apiCall } from '../../../backend/utils/apiCall'
 import { useAiPendingActionPolling } from '../useAiPendingActionPolling'
 import type { AiPendingActionCardAction, AiPendingActionCardStatus } from '../types'
 
@@ -51,8 +51,8 @@ function makeAction(
   }
 }
 
-function mockResponse(action: AiPendingActionCardAction) {
-  ;(apiCallOrThrow as jest.Mock).mockImplementation(async () => ({
+function mockOkResponse(action: AiPendingActionCardAction) {
+  ;(apiCall as jest.Mock).mockImplementation(async () => ({
     ok: true,
     status: 200,
     result: { pendingAction: action },
@@ -61,17 +61,35 @@ function mockResponse(action: AiPendingActionCardAction) {
   }))
 }
 
+function mockStatusResponse(status: number) {
+  return {
+    ok: false,
+    status,
+    result: null,
+    response: {},
+    cacheStatus: null,
+  }
+}
+
+function setDocumentVisibility(state: 'visible' | 'hidden') {
+  Object.defineProperty(document, 'visibilityState', {
+    configurable: true,
+    get: () => state,
+  })
+}
+
 const loggerError = createLogger('ui').error as jest.Mock
 
 describe('useAiPendingActionPolling', () => {
   beforeEach(() => {
-    ;(apiCallOrThrow as jest.Mock).mockReset()
+    ;(apiCall as jest.Mock).mockReset()
     loggerError.mockClear()
+    setDocumentVisibility('visible')
   })
 
   it('fetches on mount and continues polling while status is pending', async () => {
     let status: AiPendingActionCardStatus = 'pending'
-    ;(apiCallOrThrow as jest.Mock).mockImplementation(async () => ({
+    ;(apiCall as jest.Mock).mockImplementation(async () => ({
       ok: true,
       status: 200,
       result: { pendingAction: makeAction({ status }) },
@@ -90,7 +108,7 @@ describe('useAiPendingActionPolling', () => {
         await Promise.resolve()
         await Promise.resolve()
       })
-      expect(apiCallOrThrow).toHaveBeenCalledTimes(1)
+      expect(apiCall).toHaveBeenCalledTimes(1)
       expect(result.current.status).toBe('pending')
 
       await act(async () => {
@@ -98,7 +116,7 @@ describe('useAiPendingActionPolling', () => {
         await Promise.resolve()
         await Promise.resolve()
       })
-      expect((apiCallOrThrow as jest.Mock).mock.calls.length).toBeGreaterThanOrEqual(2)
+      expect((apiCall as jest.Mock).mock.calls.length).toBeGreaterThanOrEqual(2)
 
       status = 'confirmed'
       await act(async () => {
@@ -107,13 +125,13 @@ describe('useAiPendingActionPolling', () => {
         await Promise.resolve()
       })
       expect(result.current.status).toBe('confirmed')
-      const callsAfterTerminal = (apiCallOrThrow as jest.Mock).mock.calls.length
+      const callsAfterTerminal = (apiCall as jest.Mock).mock.calls.length
 
       await act(async () => {
         jest.advanceTimersByTime(5000)
         await Promise.resolve()
       })
-      expect((apiCallOrThrow as jest.Mock).mock.calls.length).toBe(callsAfterTerminal)
+      expect((apiCall as jest.Mock).mock.calls.length).toBe(callsAfterTerminal)
       expect(result.current.isPolling).toBe(false)
 
       unmount()
@@ -123,14 +141,14 @@ describe('useAiPendingActionPolling', () => {
   })
 
   it('refresh() force-fetches and updates state', async () => {
-    mockResponse(makeAction({ status: 'pending' }))
+    mockOkResponse(makeAction({ status: 'pending' }))
     const { result } = renderHook(() =>
       useAiPendingActionPolling({ pendingActionId: 'pa-1', intervalMs: 99999 }),
     )
 
     await waitFor(() => expect(result.current.action?.status).toBe('pending'))
 
-    ;(apiCallOrThrow as jest.Mock).mockImplementationOnce(async () => ({
+    ;(apiCall as jest.Mock).mockImplementationOnce(async () => ({
       ok: true,
       status: 200,
       result: { pendingAction: makeAction({ status: 'confirmed' }) },
@@ -148,26 +166,26 @@ describe('useAiPendingActionPolling', () => {
   it('clears outstanding timers when unmounted mid-poll', async () => {
     jest.useFakeTimers()
     try {
-      mockResponse(makeAction({ status: 'pending' }))
+      mockOkResponse(makeAction({ status: 'pending' }))
       const { unmount } = renderHook(() =>
         useAiPendingActionPolling({ pendingActionId: 'pa-1', intervalMs: 1000 }),
       )
-      await waitFor(() => expect(apiCallOrThrow).toHaveBeenCalledTimes(1))
+      await waitFor(() => expect(apiCall).toHaveBeenCalledTimes(1))
       unmount()
-      const callsAtUnmount = (apiCallOrThrow as jest.Mock).mock.calls.length
+      const callsAtUnmount = (apiCall as jest.Mock).mock.calls.length
       // Advance well past several intervals — no more calls must be fired.
       await act(async () => {
         jest.advanceTimersByTime(10_000)
       })
-      expect((apiCallOrThrow as jest.Mock).mock.calls.length).toBe(callsAtUnmount)
+      expect((apiCall as jest.Mock).mock.calls.length).toBe(callsAtUnmount)
     } finally {
       jest.useRealTimers()
     }
   })
 
-  it('logs a failed fetch and keeps polling until it recovers', async () => {
+  it('logs a failed fetch and keeps polling (with backoff) until it recovers', async () => {
     const failure = new Error('[internal] pending action endpoint unreachable')
-    ;(apiCallOrThrow as jest.Mock)
+    ;(apiCall as jest.Mock)
       .mockImplementationOnce(async () => {
         throw failure
       })
@@ -196,8 +214,9 @@ describe('useAiPendingActionPolling', () => {
       expect(result.current.error?.message).toBe(failure.message)
       expect(result.current.action).toBeNull()
 
+      // First retry after a failure backs off to intervalMs * 2.
       await act(async () => {
-        jest.advanceTimersByTime(1000)
+        jest.advanceTimersByTime(2000)
         await Promise.resolve()
         await Promise.resolve()
       })
@@ -209,4 +228,152 @@ describe('useAiPendingActionPolling', () => {
       jest.useRealTimers()
     }
   })
+
+  it('stops polling on a 404 and reports error.code=not_found', async () => {
+    ;(apiCall as jest.Mock).mockImplementation(async () => mockStatusResponse(404))
+
+    jest.useFakeTimers()
+    try {
+      const { result, unmount } = renderHook(() =>
+        useAiPendingActionPolling({ pendingActionId: 'pa-1', intervalMs: 1000 }),
+      )
+
+      await act(async () => {
+        await Promise.resolve()
+        await Promise.resolve()
+      })
+      expect(result.current.error?.code).toBe('not_found')
+      expect(result.current.isPolling).toBe(false)
+      const callsAfterNotFound = (apiCall as jest.Mock).mock.calls.length
+
+      await act(async () => {
+        jest.advanceTimersByTime(60_000)
+        await Promise.resolve()
+      })
+      expect((apiCall as jest.Mock).mock.calls.length).toBe(callsAfterNotFound)
+
+      unmount()
+    } finally {
+      jest.useRealTimers()
+    }
+  })
+
+  it('backs off exponentially on repeated 500s and stops after 5 consecutive failures', async () => {
+    ;(apiCall as jest.Mock).mockImplementation(async () => mockStatusResponse(500))
+
+    jest.useFakeTimers()
+    try {
+      const { result, unmount } = renderHook(() =>
+        useAiPendingActionPolling({ pendingActionId: 'pa-1', intervalMs: 1000 }),
+      )
+
+      // Initial fetch (failure #1), then drive through failures #2-#5 by
+      // advancing past each capped backoff delay.
+      for (let i = 0; i < 5; i += 1) {
+        await act(async () => {
+          jest.advanceTimersByTime(60_000)
+          await Promise.resolve()
+          await Promise.resolve()
+        })
+      }
+
+      expect(result.current.isPolling).toBe(false)
+      const callsAfterStop = (apiCall as jest.Mock).mock.calls.length
+      expect(callsAfterStop).toBeGreaterThanOrEqual(5)
+
+      await act(async () => {
+        jest.advanceTimersByTime(60_000)
+        await Promise.resolve()
+      })
+      expect((apiCall as jest.Mock).mock.calls.length).toBe(callsAfterStop)
+
+      unmount()
+    } finally {
+      jest.useRealTimers()
+    }
+  })
+
+  it('refresh() restarts a stopped loop', async () => {
+    ;(apiCall as jest.Mock).mockImplementation(async () => mockStatusResponse(500))
+
+    jest.useFakeTimers()
+    try {
+      const { result, unmount } = renderHook(() =>
+        useAiPendingActionPolling({ pendingActionId: 'pa-1', intervalMs: 1000 }),
+      )
+
+      for (let i = 0; i < 5; i += 1) {
+        await act(async () => {
+          jest.advanceTimersByTime(60_000)
+          await Promise.resolve()
+          await Promise.resolve()
+        })
+      }
+      expect(result.current.isPolling).toBe(false)
+
+      ;(apiCall as jest.Mock).mockImplementation(async () => ({
+        ok: true,
+        status: 200,
+        result: { pendingAction: makeAction({ status: 'pending' }) },
+        response: {},
+        cacheStatus: null,
+      }))
+
+      await act(async () => {
+        await result.current.refresh()
+      })
+      expect(result.current.action?.status).toBe('pending')
+      expect(result.current.isPolling).toBe(true)
+
+      const callsAfterRestart = (apiCall as jest.Mock).mock.calls.length
+      await act(async () => {
+        jest.advanceTimersByTime(1000)
+        await Promise.resolve()
+        await Promise.resolve()
+      })
+      expect((apiCall as jest.Mock).mock.calls.length).toBeGreaterThan(callsAfterRestart)
+
+      unmount()
+    } finally {
+      jest.useRealTimers()
+    }
+  })
+
+  it('pauses polling while the tab is hidden and resumes on visibilitychange', async () => {
+    mockOkResponse(makeAction({ status: 'pending' }))
+
+    jest.useFakeTimers()
+    try {
+      const { unmount } = renderHook(() =>
+        useAiPendingActionPolling({ pendingActionId: 'pa-1', intervalMs: 1000 }),
+      )
+
+      await act(async () => {
+        await Promise.resolve()
+        await Promise.resolve()
+      })
+      const callsBeforeHidden = (apiCall as jest.Mock).mock.calls.length
+
+      setDocumentVisibility('hidden')
+      document.dispatchEvent(new Event('visibilitychange'))
+
+      await act(async () => {
+        jest.advanceTimersByTime(10_000)
+        await Promise.resolve()
+      })
+      expect((apiCall as jest.Mock).mock.calls.length).toBe(callsBeforeHidden)
+
+      setDocumentVisibility('visible')
+      await act(async () => {
+        document.dispatchEvent(new Event('visibilitychange'))
+        await Promise.resolve()
+        await Promise.resolve()
+      })
+      expect((apiCall as jest.Mock).mock.calls.length).toBeGreaterThan(callsBeforeHidden)
+
+      unmount()
+    } finally {
+      jest.useRealTimers()
+    }
+  })
 })

package/src/ai/parts/useAiPendingActionPolling.ts

@@ -2,7 +2,7 @@
 
 import * as React from 'react'
 import { createLogger } from '@open-mercato/shared/lib/logger'
-import { apiCallOrThrow } from '../../backend/utils/apiCall'
+import { apiCall } from '../../backend/utils/apiCall'
 import type { AiPendingActionCardAction, AiPendingActionCardStatus } from './types'
 
 const logger = createLogger('ui').child({ component: 'useAiPendingActionPolling' })
@@ -18,8 +18,17 @@ const logger = createLogger('ui').child({ component: 'useAiPendingActionPolling'
  * - Poll every 3 seconds while the status is non-terminal
  *   (`pending` / `executing`). Terminal states (`confirmed`, `cancelled`,
  *   `failed`, `expired`) stop polling.
+ * - A 404/401/403 from the endpoint is also terminal — the row is gone or
+ *   unreachable and retrying cannot help (issue #7550: without this, every
+ *   card whose row disappeared polled every 3s forever, in every tab).
+ * - Any other failure (5xx, network error) backs off exponentially (capped
+ *   at 60s) and gives up after 5 consecutive failures.
+ * - Polling pauses while the tab is hidden (`document.visibilityState`) and
+ *   resumes on `visibilitychange`.
  * - Expose a `refresh()` force-fetch helper the confirmation card uses after
- *   a confirm POST races with the polling loop.
+ *   a confirm POST races with the polling loop. `refresh()` also restarts a
+ *   stopped loop (backoff-exhausted or resumed-from-hidden) without
+ *   creating a second timer chain.
  *
  * The hook owns a single `setInterval`/`setTimeout` — unmounting clears
  * every outstanding timer. This is required for the Jest fake-timers
@@ -33,11 +42,27 @@ const TERMINAL_STATUSES: ReadonlyArray<AiPendingActionCardStatus> = [
   'expired',
 ]
 
+const TERMINAL_HTTP_ERROR_CODES: ReadonlyArray<string> = ['not_found', 'unauthorized', 'forbidden']
+
+const MAX_BACKOFF_MS = 60_000
+const MAX_CONSECUTIVE_FAILURES = 5
+
 function isTerminal(status: AiPendingActionCardStatus | null): boolean {
   if (!status) return false
   return TERMINAL_STATUSES.includes(status)
 }
 
+function httpStatusToErrorCode(status: number): string | null {
+  if (status === 404) return 'not_found'
+  if (status === 401) return 'unauthorized'
+  if (status === 403) return 'forbidden'
+  return null
+}
+
+function isHiddenDocument(): boolean {
+  return typeof document !== 'undefined' && document.visibilityState === 'hidden'
+}
+
 export interface UseAiPendingActionPollingOptions {
   pendingActionId: string
   /**
@@ -57,6 +82,7 @@ export interface UseAiPendingActionPollingOptions {
 }
 
 export interface AiPendingActionFetchResult {
+  ok: boolean
   pendingAction: AiPendingActionCardAction | null
   error?: { code?: string; message: string } | null
 }
@@ -74,7 +100,7 @@ async function fetchPendingAction(
   endpoint: string,
 ): Promise<AiPendingActionFetchResult> {
   const url = `${endpoint}/${encodeURIComponent(pendingActionId)}`
-  const call = await apiCallOrThrow<unknown>(url, { method: 'GET' })
+  const call = await apiCall<unknown>(url, { method: 'GET' })
   const body = call.result as
     | (Partial<AiPendingActionCardAction> & {
         pendingAction?: AiPendingActionCardAction
@@ -84,6 +110,12 @@ async function fetchPendingAction(
     | null
     | undefined
 
+  if (!call.ok) {
+    const code = httpStatusToErrorCode(call.status) ?? body?.code ?? 'request_failed'
+    const message = body?.error ?? `Request failed with status ${call.status}.`
+    return { ok: false, pendingAction: null, error: { code, message } }
+  }
+
   // The GET route returns the bare action object (`serializePendingActionForClient(row)`),
   // but earlier client code expected it under a `pendingAction` envelope.
   // Accept BOTH shapes so the cards work whether the dispatcher wraps or
@@ -92,22 +124,23 @@ async function fetchPendingAction(
   // MutationPreviewCard / ConfirmationCard / MutationResultCard.
   if (body && typeof body === 'object') {
     if (body.pendingAction) {
-      return { pendingAction: body.pendingAction, error: null }
+      return { ok: true, pendingAction: body.pendingAction, error: null }
     }
     if (
       typeof (body as Partial<AiPendingActionCardAction>).id === 'string' &&
       typeof (body as Partial<AiPendingActionCardAction>).status === 'string'
     ) {
-      return { pendingAction: body as AiPendingActionCardAction, error: null }
+      return { ok: true, pendingAction: body as AiPendingActionCardAction, error: null }
     }
     if (body.error) {
       return {
+        ok: true,
         pendingAction: null,
         error: { message: body.error, code: body.code },
       }
     }
   }
-  return { pendingAction: null, error: null }
+  return { ok: true, pendingAction: null, error: null }
 }
 
 export function useAiPendingActionPolling(
@@ -127,6 +160,11 @@ export function useAiPendingActionPolling(
   const mountedRef = React.useRef(true)
   const timerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null)
   const statusRef = React.useRef<AiPendingActionCardStatus | null>(null)
+  const terminalErrorCodeRef = React.useRef<string | null>(null)
+  const consecutiveFailuresRef = React.useRef(0)
+  const stoppedRef = React.useRef(false)
+  const hiddenRef = React.useRef(isHiddenDocument())
+  const scheduleNextRef = React.useRef<() => void>(() => {})
 
   const clearTimer = React.useCallback(() => {
     if (timerRef.current) {
@@ -137,26 +175,46 @@ export function useAiPendingActionPolling(
 
   const refresh = React.useCallback(async (): Promise<AiPendingActionCardAction | null> => {
     if (!pendingActionId) return null
+    let pendingAction: AiPendingActionCardAction | null = null
     try {
       const result = await fetchPendingAction(pendingActionId, endpoint)
       if (!mountedRef.current) return result.pendingAction ?? null
-      if (result.error) {
-        setError(result.error)
+      pendingAction = result.pendingAction ?? null
+      if (result.ok) {
+        consecutiveFailuresRef.current = 0
+        stoppedRef.current = false
+        terminalErrorCodeRef.current = null
+        setError(result.error ?? null)
+        if (result.pendingAction) {
+          setAction(result.pendingAction)
+          statusRef.current = result.pendingAction.status
+        }
       } else {
-        setError(null)
+        setError(result.error ?? null)
+        const code = result.error?.code
+        if (code && TERMINAL_HTTP_ERROR_CODES.includes(code)) {
+          terminalErrorCodeRef.current = code
+        } else {
+          consecutiveFailuresRef.current += 1
+          if (consecutiveFailuresRef.current >= MAX_CONSECUTIVE_FAILURES) {
+            stoppedRef.current = true
+          }
+        }
       }
-      if (result.pendingAction) {
-        setAction(result.pendingAction)
-        statusRef.current = result.pendingAction.status
-      }
-      return result.pendingAction
     } catch (err) {
       logger.error('Failed to load the pending AI action', { err, pendingActionId })
       if (!mountedRef.current) return null
       const message = err instanceof Error ? err.message : 'Failed to load pending action.'
       setError({ message })
-      return null
+      consecutiveFailuresRef.current += 1
+      if (consecutiveFailuresRef.current >= MAX_CONSECUTIVE_FAILURES) {
+        stoppedRef.current = true
+      }
     }
+    if (mountedRef.current) {
+      scheduleNextRef.current()
+    }
+    return pendingAction
   }, [endpoint, pendingActionId])
 
   const scheduleNext = React.useCallback(() => {
@@ -170,20 +228,60 @@ export function useAiPendingActionPolling(
       setIsPolling(false)
       return
     }
+    if (terminalErrorCodeRef.current) {
+      setIsPolling(false)
+      return
+    }
+    if (stoppedRef.current) {
+      setIsPolling(false)
+      return
+    }
+    if (hiddenRef.current) {
+      // Paused while the tab is hidden. `visibilitychange` resumes via refresh().
+      return
+    }
     setIsPolling(true)
-    timerRef.current = setTimeout(async () => {
-      try {
-        await refresh()
-      } catch (err) {
-        logger.error('Polling the pending AI action failed unexpectedly', { err })
-      }
-      scheduleNext()
-    }, intervalMs)
+    const delay =
+      consecutiveFailuresRef.current > 0
+        ? Math.min(intervalMs * 2 ** consecutiveFailuresRef.current, MAX_BACKOFF_MS)
+        : intervalMs
+    timerRef.current = setTimeout(() => {
+      void refresh()
+    }, delay)
   }, [clearTimer, disabled, intervalMs, refresh])
 
+  React.useEffect(() => {
+    scheduleNextRef.current = scheduleNext
+  }, [scheduleNext])
+
+  React.useEffect(() => {
+    if (disabled) return
+    const handleVisibilityChange = () => {
+      const wasHidden = hiddenRef.current
+      hiddenRef.current = isHiddenDocument()
+      if (!wasHidden && hiddenRef.current) {
+        // Cancel any already-scheduled poll immediately — do not wait for
+        // it to fire before honoring the pause.
+        clearTimer()
+        return
+      }
+      if (wasHidden && !hiddenRef.current && mountedRef.current) {
+        // Resume immediately rather than waiting out a stale backoff delay.
+        void refresh()
+      }
+    }
+    document.addEventListener('visibilitychange', handleVisibilityChange)
+    return () => {
+      document.removeEventListener('visibilitychange', handleVisibilityChange)
+    }
+  }, [clearTimer, disabled, refresh])
+
   React.useEffect(() => {
     mountedRef.current = true
     statusRef.current = null
+    terminalErrorCodeRef.current = null
+    consecutiveFailuresRef.current = 0
+    stoppedRef.current = false
     if (disabled) {
       setIsPolling(false)
       return () => {
@@ -192,18 +290,9 @@ export function useAiPendingActionPolling(
       }
     }
     setIsPolling(true)
-    // Always fetch on mount — the "reconnect behavior" guarantee. The catch
-    // runs before the scheduling step so a rejected first fetch degrades to a
-    // logged error instead of silently killing the polling loop.
+    // Always fetch on mount — the "reconnect behavior" guarantee. `refresh`
+    // schedules the next poll itself once it settles.
     void refresh()
-      .catch((err) => {
-        logger.error('Loading the pending AI action failed unexpectedly', { err })
-        return null
-      })
-      .then(() => {
-        if (!mountedRef.current) return
-        scheduleNext()
-      })
     return () => {
       mountedRef.current = false
       clearTimer()