@agent-native/core 0.98.0 → 0.98.1

package/corpus/templates/clips/app/hooks/use-auto-title.ts

@@ -16,6 +16,7 @@ import {
   callAction,
   sendToAgentChat,
   type AgentChatMessage,
+  useChangeVersions,
 } from "@agent-native/core/client";
 import { fullVideoAiModelSelection } from "@shared/clips-ai-prefs";
 import { useEffect, useRef } from "react";
@@ -23,7 +24,6 @@ import { useEffect, useRef } from "react";
 import { useRecordings, type RecordingSummary } from "./use-library";
 
 const DEFAULT_TITLE = "Untitled recording";
-const POLL_INTERVAL_MS = 3000;
 const TWO_MINUTES_MS = 2 * 60 * 1000;
 
 /** True when `title` is blank or equal to the server-seeded default. */
@@ -99,8 +99,9 @@ async function clearRequest(recordingId: string): Promise<void> {
 }
 
 /**
- * Mount this once in the app shell. It polls the recording list and fires
- * `sendToAgentChat` for every pending request queued by a clips action.
+ * Mount this once in the app shell. It watches the exact application-state
+ * keys used for queued Clips AI work and fires `sendToAgentChat` for every
+ * pending request queued by a clips action.
  * Idempotent — a given (recordingId, kind, requestedAt) is only dispatched
  * once per tab session.
  */
@@ -119,13 +120,26 @@ export function useAutoTitleBridge(): void {
         `${r.id}:${r.titleSource ?? ""}:${r.title}:${r.updatedAt}:${r.transcriptStatus ?? ""}:${r.transcriptHasText ? "1" : "0"}`,
     )
     .join("|");
+  const aiRequestVersion = useChangeVersions(
+    readyRecordings.map(
+      (recording) => `app-state:clips-ai-request-${recording.id}`,
+    ),
+  );
 
   useEffect(() => {
     if (readyRecordings.length === 0) return;
     let cancelled = false;
+    let fallbackTimer: ReturnType<typeof setTimeout> | null = null;
 
     async function tick() {
-      if (cancelled || inflight.current) return;
+      if (cancelled) return;
+      if (inflight.current) {
+        // A new request-state version can arrive while the previous list read
+        // is in flight. Recheck after it settles so that event is not the last
+        // chance to dispatch the queued work.
+        fallbackTimer = setTimeout(() => void tick(), 50);
+        return;
+      }
       inflight.current = true;
       try {
         const requestsById = await listRequests();
@@ -192,14 +206,66 @@ export function useAutoTitleBridge(): void {
       }
     }
 
-    tick();
-    const handle = setInterval(tick, POLL_INTERVAL_MS);
+    function scheduleNextFallback() {
+      if (cancelled) return;
+      const delay = nextAutoTitleFallbackDelay(
+        readyRecordings,
+        dispatched.current,
+      );
+      if (delay === null) return;
+      // Keep the timeout non-zero so a failed request cannot spin a tight loop.
+      fallbackTimer = setTimeout(
+        () => {
+          fallbackTimer = null;
+          void tick().finally(scheduleNextFallback);
+        },
+        Math.max(delay, 50),
+      );
+    }
+
+    // One initial read catches requests queued before this component mounted.
+    // Later reads are driven by the exact clips-ai-request application-state
+    // counters above. The only timer left is a one-shot wake-up when an old
+    // transcript-backed recording becomes eligible for the legacy fallback.
+    void tick().finally(scheduleNextFallback);
     return () => {
       cancelled = true;
-      clearInterval(handle);
+      if (fallbackTimer) clearTimeout(fallbackTimer);
     };
+    // readyRecordingsKey is the stable snapshot consumed by tick; depending on
+    // the array itself would restart the effect on every query result object.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [readyRecordingsKey]);
+  }, [aiRequestVersion, readyRecordingsKey]);
+}
+
+export function nextAutoTitleFallbackDelay(
+  recordings: readonly RecordingSummary[],
+  dispatched: ReadonlySet<string>,
+  now = Date.now(),
+): number | null {
+  let nextDelay: number | null = null;
+
+  for (const recording of recordings) {
+    if (recording.status !== "ready") continue;
+    if (!isAutoTitleReplaceable(recording.title, recording.titleSource)) {
+      continue;
+    }
+    if (
+      recording.transcriptStatus !== "ready" ||
+      recording.transcriptHasText !== true ||
+      dispatched.has(`${recording.id}:fallback`)
+    ) {
+      continue;
+    }
+
+    const createdAt = new Date(recording.createdAt).getTime();
+    const delay = Number.isFinite(createdAt)
+      ? Math.max(0, TWO_MINUTES_MS - (now - createdAt))
+      : 0;
+    nextDelay = nextDelay === null ? delay : Math.min(nextDelay, delay);
+  }
+
+  return nextDelay;
 }
 
 function buildRequestContext(rec: RecordingSummary, request: AiRequest) {

package/corpus/templates/clips/app/hooks/use-library.ts

@@ -44,24 +44,13 @@ export interface ListRecordingsArgs {
   offset?: number;
 }
 
-function isAwaitingAutoTitle(recording: RecordingSummary): boolean {
-  const title = (recording.title ?? "").trim();
-  const titleIsReplaceable =
-    title === "" ||
-    title === "Untitled recording" ||
-    recording.titleSource === "default" ||
-    recording.titleSource === "context";
-  if (!titleIsReplaceable) return false;
-
-  if (recording.transcriptStatus === "failed") return false;
-  if (recording.transcriptStatus === "ready") {
-    return recording.transcriptHasText === true;
-  }
-
-  return (
-    recording.transcriptStatus === "pending" ||
-    recording.transcriptStatus === "streaming"
-  );
+export function recordingsRefetchInterval(
+  recordings: readonly RecordingSummary[] | undefined,
+): number | false {
+  if (!recordings || recordings.length === 0) return false;
+  return recordings.some((recording) => isLiveRecordingUpload(recording))
+    ? 3000
+    : false;
 }
 
 export function useRecordings(args: ListRecordingsArgs = {}) {
@@ -74,17 +63,15 @@ export function useRecordings(args: ListRecordingsArgs = {}) {
           recordings: Array.isArray(data?.recordings) ? data.recordings : [],
         };
       },
-      // Keep a short poll while uploads/processors are active so the library
-      // card does not get stuck if the global refresh signal is missed.
-      // Also poll for replaceable seed titles so the card upgrades promptly.
+      // Keep a short poll only while uploads/processors are active so the
+      // library card does not get stuck if the global refresh signal is
+      // missed. Generated titles arrive through the shared DB sync transport;
+      // polling completed recordings forever is both redundant and expensive.
       refetchInterval: (q) => {
         const recs = (q.state.data as any)?.recordings as
           | RecordingSummary[]
           | undefined;
-        if (!recs || recs.length === 0) return false;
-        const pendingUpload = recs.some((rec) => isLiveRecordingUpload(rec));
-        const pendingTitle = recs.some(isAwaitingAutoTitle);
-        return pendingUpload || pendingTitle ? 3000 : false;
+        return recordingsRefetchInterval(recs);
       },
     },
   );

package/corpus/templates/clips/app/routes/_app.settings._index.tsx

@@ -734,7 +734,7 @@ export default function SettingsIndexRoute() {
     builderStatus.loading ||
     !builderConnect.hasFetchedStatus;
   const s3Configured = activeProviderId === "s3";
-  const s3Collapsed = builderConnected && !s3Expanded;
+  const s3Collapsed = !s3Expanded;
   const configuredApiKeyCount = AI_PROVIDER_FIELDS.filter(
     (field) => apiKeyStatus[field.key],
   ).length;
@@ -908,7 +908,7 @@ export default function SettingsIndexRoute() {
                   </div>
 
                   <Collapsible
-                    open={builderConnected ? !s3Collapsed : true}
+                    open={!s3Collapsed}
                     onOpenChange={(open) => setS3Expanded(open)}
                   >
                     <div className="rounded-md border border-border">
@@ -939,26 +939,24 @@ export default function SettingsIndexRoute() {
                                 : t("settings.s3OwnBucketDescription")}
                           </p>
                         </div>
-                        {builderConnected ? (
-                          <CollapsibleTrigger asChild>
-                            <Button
-                              type="button"
-                              variant="ghost"
-                              size="sm"
-                              className="shrink-0"
-                            >
-                              {s3Collapsed
-                                ? t("settings.configureS3")
-                                : t("settings.hideS3")}
-                              <IconChevronDown
-                                className={cn(
-                                  "h-4 w-4 transition-transform",
-                                  !s3Collapsed && "rotate-180",
-                                )}
-                              />
-                            </Button>
-                          </CollapsibleTrigger>
-                        ) : null}
+                        <CollapsibleTrigger asChild>
+                          <Button
+                            type="button"
+                            variant="ghost"
+                            size="sm"
+                            className="shrink-0"
+                          >
+                            {s3Collapsed
+                              ? t("settings.configureS3")
+                              : t("settings.hideS3")}
+                            <IconChevronDown
+                              className={cn(
+                                "h-4 w-4 transition-transform",
+                                !s3Collapsed && "rotate-180",
+                              )}
+                            />
+                          </Button>
+                        </CollapsibleTrigger>
                       </div>
 
                       <CollapsibleContent>

package/corpus/templates/clips/changelog/2026-07-11-generated-titles-no-longer-cause-continuous-background-refreshes.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-11
+---
+
+Generated titles no longer cause continuous background refreshes after a recording is ready.

package/corpus/templates/clips/changelog/2026-07-11-s3-storage-setup-stays-collapsed-until-you-choose-it-as-the-.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-11
+---
+
+S3 storage setup stays collapsed until you choose it as the secondary storage option.

package/corpus/templates/content/.agents/skills/real-time-sync/SKILL.md

@@ -30,7 +30,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
    useDbSync({ queryClient });
    ```
 
-   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries for ordinary domain events — that caused a request storm in production. The exception is `source: "action"`: a successful mutating action is the framework-wide "agent changed app data" signal, so `useDbSync` also refreshes active React Query observers as a compatibility safety net for custom apps that have not yet moved every read to `useActionQuery` or source-versioned query keys.
+   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries — that caused request storms in production. A successful mutating action refreshes active `useActionQuery` observers under the `["action"]` prefix. Browser actions carry a tab id so their originating tab ignores the sync echo while other tabs refresh. Legacy apps can opt into broader compatibility with `actionInvalidatePredicate`, but first-party apps should use action-backed or source-versioned query keys. Idle fallback polling runs once per minute; active agent work temporarily uses the faster cadence.
 
 3. **Templates fold per-source counters into their query keys.** This is the pattern that makes "agent writes show up without a manual refresh" reliable:
 
@@ -117,7 +117,7 @@ useQuery({
 | UI not updating after agent writes | Is `useDbSync` called with the correct `queryClient`? Does the affected query have an active observer?         |
 | Poll endpoint not responding       | Is `/_agent-native/poll` accessible? Is the server running?                                                    |
 | SSE not connecting                 | Is `/_agent-native/events` accessible and authenticated? Polling should still keep the UI fresh as fallback.   |
-| High CPU / event storms            | The agent is writing rapidly. Add `staleTime` to queries to debounce refetches.                                |
+| High CPU / event storms            | Use targeted source keys, settle bursty list counters, and avoid broad action invalidation.                   |
 
 ## Jitter Prevention
 

package/corpus/templates/content/app/hooks/use-comments.ts

@@ -65,7 +65,6 @@ export function useComments(documentId: string | null) {
         }
         return Array.from(threadMap.values());
       },
-      refetchInterval: 5000,
     },
   );
 }

package/corpus/templates/content/changelog/2026-07-11-comments-now-update-from-live-collaboration-events-without-c.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-11
+---
+
+Comments now update from live collaboration events without continuous background requests

package/corpus/templates/design/app/components/layout/Header.tsx

@@ -88,7 +88,7 @@ export function Header() {
       </div>
       <div className="flex items-center gap-2 shrink-0">
         {actions}
-        <RunsTray onOpenThread={openRunThread} />
+        <RunsTray pollMs={0} onOpenThread={openRunThread} />
         <AgentToggleButton />
       </div>
     </header>

package/corpus/templates/forms/.agents/skills/real-time-sync/SKILL.md

@@ -30,7 +30,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
    useDbSync({ queryClient });
    ```
 
-   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries for ordinary domain events — that caused a request storm in production. The exception is `source: "action"`: a successful mutating action is the framework-wide "agent changed app data" signal, so `useDbSync` also refreshes active React Query observers as a compatibility safety net for custom apps that have not yet moved every read to `useActionQuery` or source-versioned query keys.
+   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries — that caused request storms in production. A successful mutating action refreshes active `useActionQuery` observers under the `["action"]` prefix. Browser actions carry a tab id so their originating tab ignores the sync echo while other tabs refresh. Legacy apps can opt into broader compatibility with `actionInvalidatePredicate`, but first-party apps should use action-backed or source-versioned query keys. Idle fallback polling runs once per minute; active agent work temporarily uses the faster cadence.
 
 3. **Templates fold per-source counters into their query keys.** This is the pattern that makes "agent writes show up without a manual refresh" reliable:
 
@@ -117,7 +117,7 @@ useQuery({
 | UI not updating after agent writes | Is `useDbSync` called with the correct `queryClient`? Does the affected query have an active observer?         |
 | Poll endpoint not responding       | Is `/_agent-native/poll` accessible? Is the server running?                                                    |
 | SSE not connecting                 | Is `/_agent-native/events` accessible and authenticated? Polling should still keep the UI fresh as fallback.   |
-| High CPU / event storms            | The agent is writing rapidly. Add `staleTime` to queries to debounce refetches.                                |
+| High CPU / event storms            | Use targeted source keys, settle bursty list counters, and avoid broad action invalidation.                   |
 
 ## Jitter Prevention
 

package/corpus/templates/macros/app/components/layout/AppLayout.tsx

@@ -80,7 +80,7 @@ export function AppLayout({ children }: { children: React.ReactNode }) {
     }).catch(() => {});
   }, [location.pathname, isAnalytics, isSettings]);
 
-  // Poll for navigate commands from the agent
+  // useDbSync invalidates this key when the agent writes a navigate command.
   const { data: navCommand } = useQuery({
     queryKey: ["navigate-command"],
     queryFn: async () => {
@@ -94,7 +94,6 @@ export function AppLayout({ children }: { children: React.ReactNode }) {
         return null;
       }
     },
-    refetchInterval: 2000,
   });
 
   useEffect(() => {

package/corpus/templates/macros/app/root.tsx

@@ -169,9 +169,6 @@ export default function Root() {
     createAgentNativeQueryClient({
       defaultOptions: {
         queries: {
-          // Macros UI refetches on focus to pick up meals logged in other
-          // browser tabs or mobile, which don't always arrive via DB sync.
-          refetchOnWindowFocus: true,
           // Flat retry: macros data errors are usually transient network
           // issues, not auth failures, so a flat count is sufficient.
           retry: 1,

package/corpus/templates/mail/.agents/skills/real-time-sync/SKILL.md

@@ -30,7 +30,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
    useDbSync({ queryClient });
    ```
 
-   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries for ordinary domain events — that caused a request storm in production. The exception is `source: "action"`: a successful mutating action is the framework-wide "agent changed app data" signal, so `useDbSync` also refreshes active React Query observers as a compatibility safety net for custom apps that have not yet moved every read to `useActionQuery` or source-versioned query keys.
+   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries — that caused request storms in production. A successful mutating action refreshes active `useActionQuery` observers under the `["action"]` prefix. Browser actions carry a tab id so their originating tab ignores the sync echo while other tabs refresh. Legacy apps can opt into broader compatibility with `actionInvalidatePredicate`, but first-party apps should use action-backed or source-versioned query keys. Idle fallback polling runs once per minute; active agent work temporarily uses the faster cadence.
 
 3. **Templates fold per-source counters into their query keys.** This is the pattern that makes "agent writes show up without a manual refresh" reliable:
 
@@ -117,7 +117,7 @@ useQuery({
 | UI not updating after agent writes | Is `useDbSync` called with the correct `queryClient`? Does the affected query have an active observer?         |
 | Poll endpoint not responding       | Is `/_agent-native/poll` accessible? Is the server running?                                                    |
 | SSE not connecting                 | Is `/_agent-native/events` accessible and authenticated? Polling should still keep the UI fresh as fallback.   |
-| High CPU / event storms            | The agent is writing rapidly. Add `staleTime` to queries to debounce refetches.                                |
+| High CPU / event storms            | Use targeted source keys, settle bursty list counters, and avoid broad action invalidation.                   |
 
 ## Jitter Prevention
 

package/corpus/templates/mail/app/hooks/use-compose-state.ts

@@ -139,6 +139,7 @@ export function useComposeState() {
       return merged;
     },
     staleTime: 1_000,
+    // request-storm-allow: one focus refresh reconciles bounded compose drafts across tabs.
     refetchOnWindowFocus: true,
   });
 

package/corpus/templates/mail/app/root.tsx

@@ -419,18 +419,7 @@ function DbSyncSetup() {
 const MAIL_TOASTER = <Toaster richColors position="bottom-left" />;
 
 export default function Root() {
-  const [queryClient] = useState(() =>
-    createAgentNativeQueryClient({
-      defaultOptions: {
-        queries: {
-          // Mail's VisibilityRefresh handles the focus-based refresh with a
-          // 60 s throttle, so we also want React Query's focus refetch to
-          // fire for other query keys (labels, settings, etc.).
-          refetchOnWindowFocus: true,
-        },
-      },
-    }),
-  );
+  const [queryClient] = useState(() => createAgentNativeQueryClient());
   return (
     <AppToolkitProvider>
       <AppProviders

package/corpus/templates/plan/.agents/skills/real-time-sync/SKILL.md

@@ -30,7 +30,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
    useDbSync({ queryClient });
    ```
 
-   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries for ordinary domain events — that caused a request storm in production. The exception is `source: "action"`: a successful mutating action is the framework-wide "agent changed app data" signal, so `useDbSync` also refreshes active React Query observers as a compatibility safety net for custom apps that have not yet moved every read to `useActionQuery` or source-versioned query keys.
+   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries — that caused request storms in production. A successful mutating action refreshes active `useActionQuery` observers under the `["action"]` prefix. Browser actions carry a tab id so their originating tab ignores the sync echo while other tabs refresh. Legacy apps can opt into broader compatibility with `actionInvalidatePredicate`, but first-party apps should use action-backed or source-versioned query keys. Idle fallback polling runs once per minute; active agent work temporarily uses the faster cadence.
 
 3. **Templates fold per-source counters into their query keys.** This is the pattern that makes "agent writes show up without a manual refresh" reliable:
 
@@ -117,7 +117,7 @@ useQuery({
 | UI not updating after agent writes | Is `useDbSync` called with the correct `queryClient`? Does the affected query have an active observer?         |
 | Poll endpoint not responding       | Is `/_agent-native/poll` accessible? Is the server running?                                                    |
 | SSE not connecting                 | Is `/_agent-native/events` accessible and authenticated? Polling should still keep the UI fresh as fallback.   |
-| High CPU / event storms            | The agent is writing rapidly. Add `staleTime` to queries to debounce refetches.                                |
+| High CPU / event storms            | Use targeted source keys, settle bursty list counters, and avoid broad action invalidation.                   |
 
 ## Jitter Prevention
 

package/corpus/templates/plan/app/hooks/use-navigation-state.ts

@@ -55,7 +55,10 @@ export function useNavigationState() {
     }).catch(() => {});
   }, [location.pathname, location.search]);
 
-  // Listen for navigate commands from agent
+  // Listen for one-shot navigate commands from the agent. useDbSync
+  // invalidates this exact key when the shared SSE/poll transport receives an
+  // app-state:navigate event, so this stays idle between real commands instead
+  // of charging the host for a request every two seconds.
   const { data: navCommand } = useQuery({
     queryKey: ["navigate-command"],
     queryFn: async () => {
@@ -70,7 +73,7 @@ export function useNavigationState() {
       }
       return null;
     },
-    refetchInterval: 2_000,
+    retry: false,
     structuralSharing: false,
   });
 

package/corpus/templates/plan/app/hooks/use-plans.ts

@@ -17,7 +17,6 @@ import type {
   PlanVersionListResponse,
 } from "@shared/types";
 import { useQueryClient, type UseQueryOptions } from "@tanstack/react-query";
-import type { RefObject } from "react";
 import { toast } from "sonner";
 
 import type { PlanMdxFolder } from "@/lib/desktop-plan-files";
@@ -337,23 +336,17 @@ export function localPlanBundleQueryKey(slug: string, path?: string | null) {
   ] as const;
 }
 
-export function usePlan(
-  id?: string,
-  pausePollRef?: RefObject<boolean> | { current: boolean },
-) {
+export function usePlan(id?: string) {
   return useActionQuery<PlanBundle & { html?: string }>(
     "get-visual-plan",
     planBundleQueryParams(id ?? ""),
     {
       enabled: !!id,
-      // Pause the 3-second poll while a comment mutation is in-flight so
-      // an optimistic comment inserted into the cache isn't evicted before
-      // the server write commits (Issue 4a).
-      refetchInterval: (query: { state: { status: string } }) => {
-        if (query.state.status === "error") return false;
-        if (pausePollRef?.current) return false;
-        return 3_000;
-      },
+      // Mutating actions and collaboration writes already arrive through the
+      // shared useDbSync SSE/poll transport, which invalidates active action
+      // reads. Keep the last bundle visible during that targeted refresh and
+      // avoid repeatedly downloading the full plan while nothing changed.
+      placeholderData: (previous) => previous,
     },
   );
 }

package/corpus/templates/plan/app/pages/PlansPage.tsx

@@ -2018,7 +2018,6 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
   // Ref that signals the 3-second poll to pause while a comment mutation is
   // in-flight. Prevents poll-driven cache replacement from evicting optimistic
   // comments before the server write commits (Issue 4a).
-  const commentMutationPendingRef = useRef(false);
   const { session, isLoading: sessionLoading } = useSession();
   const localPlanMode = Boolean(localPlanSlug);
   const routeSearchParams = useMemo(
@@ -2217,10 +2216,7 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
   const immersiveReader = Boolean(
     selectedId && (planFullscreen || prototypeOnly),
   );
-  const planQuery = usePlan(
-    localPlanMode ? undefined : selectedId,
-    commentMutationPendingRef,
-  );
+  const planQuery = usePlan(localPlanMode ? undefined : selectedId);
   const bundle = localPlanMode ? localPlanData : planQuery.data;
   const localPlanBundle =
     localPlanMode && bundle && "localOnly" in bundle
@@ -4550,8 +4546,7 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
     };
     clearPendingDocumentRestore();
     pendingDocumentRestoreRef.current = documentStateRef.current;
-    commentMutationPendingRef.current = true;
-    // Await the cancel so an in-flight 3s poll can't resolve *after* our
+    // Await the cancel so an in-flight sync refresh can't resolve *after* our
     // optimistic write and revert it (the "comment lagged / didn't stick"
     // symptom). cancelQueries reverts outstanding fetches before we patch.
     await queryClient.cancelQueries({ queryKey: selectedPlanQueryKey });
@@ -4588,9 +4583,6 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
         setInlineCommentPosition(
           getPositionFromAnchor(anchor) ?? capturedPosition,
         );
-      })
-      .finally(() => {
-        commentMutationPendingRef.current = false;
       });
   };
 
@@ -4606,7 +4598,6 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
         annotation.anchor.resolutionTarget,
       ),
     };
-    commentMutationPendingRef.current = true;
     void writeComments(
       [
         {
@@ -4629,9 +4620,6 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
       })
       .catch(() => {
         // The mutation hook surfaces the failure toast; just clear pending.
-      })
-      .finally(() => {
-        commentMutationPendingRef.current = false;
       });
   };
 
@@ -4669,8 +4657,7 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
       createdAt: now,
       updatedAt: now,
     };
-    commentMutationPendingRef.current = true;
-    // Await the cancel so an in-flight 3s poll can't resolve *after* our
+    // Await the cancel so an in-flight sync refresh can't resolve *after* our
     // optimistic write and revert it (the "comment lagged / didn't stick"
     // symptom). cancelQueries reverts outstanding fetches before we patch.
     await queryClient.cancelQueries({ queryKey: selectedPlanQueryKey });
@@ -4709,8 +4696,6 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
           current ? removePlanCommentFromBundle(current, replyId) : current,
       );
       throw new Error("Could not send reply. Try again.");
-    } finally {
-      commentMutationPendingRef.current = false;
     }
   };
 
@@ -4729,8 +4714,7 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
     // popover update without waiting for the server round-trip (Issue 3).
     const prevBundle =
       queryClient.getQueryData<PlanBundleWithHtml>(selectedPlanQueryKey);
-    commentMutationPendingRef.current = true;
-    // Await the cancel so an in-flight 3s poll can't resolve *after* our
+    // Await the cancel so an in-flight sync refresh can't resolve *after* our
     // optimistic write and revert it (the "comment lagged / didn't stick"
     // symptom). cancelQueries reverts outstanding fetches before we patch.
     await queryClient.cancelQueries({ queryKey: selectedPlanQueryKey });
@@ -4777,9 +4761,6 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
         if (prevBundle !== undefined) {
           queryClient.setQueryData(selectedPlanQueryKey, prevBundle);
         }
-      })
-      .finally(() => {
-        commentMutationPendingRef.current = false;
       });
   };
 
@@ -4802,8 +4783,7 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
     const prevBundle =
       queryClient.getQueryData<PlanBundleWithHtml>(selectedPlanQueryKey);
     const commentId = request.commentId;
-    commentMutationPendingRef.current = true;
-    // Await the cancel so an in-flight 3s poll can't resolve *after* our
+    // Await the cancel so an in-flight sync refresh can't resolve *after* our
     // optimistic write and revert it (the "comment lagged / didn't stick"
     // symptom). cancelQueries reverts outstanding fetches before we patch.
     await queryClient.cancelQueries({ queryKey: selectedPlanQueryKey });
@@ -4826,8 +4806,6 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
         queryClient.setQueryData(selectedPlanQueryKey, prevBundle);
       }
       setDeleteCommentRequest(request);
-    } finally {
-      commentMutationPendingRef.current = false;
     }
   };
 

package/corpus/templates/plan/changelog/2026-07-11-plan-refreshes-only-when-content-changes.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-11
+---
+
+Plan pages stay current while making far fewer background requests when nothing has changed.

package/corpus/templates/slides/app/components/comments/SlideCommentsPanel.tsx

@@ -336,7 +336,10 @@ function ThreadCard({
                     <TooltipTrigger asChild>
                       <button
                         onClick={() =>
-                          resolveComment.mutate({ id: rootComment.id })
+                          resolveComment.mutate({
+                            id: rootComment.id,
+                            resolved: true,
+                          })
                         }
                         className="p-0.5 rounded text-muted-foreground hover:text-green-400"
                       >

package/corpus/templates/slides/app/components/editor/EditorToolbar.tsx

@@ -1023,7 +1023,7 @@ graph TD
         </DropdownMenuContent>
       </DropdownMenu>
 
-      <RunsTray />
+      <RunsTray pollMs={0} />
       <AgentToggleButton />
     </div>
   );