fix(gui): revalidate seeded resources and clear React Doctor blockers

Pre-subscribe session seeds skipped the mount fetch, so cache-backed revisits never announced load failures. Move seeding into initialData, quiet-revalidate on first subscribe, and fix the related ApiKeys/Startup/Desktop review gaps.

Author: Wibias

gui/src/client-resource.ts

@@ -40,6 +40,12 @@ type Store<T> = {
   /** Store-level visibilitychange handler, installed only while this store polls. */
   visibilityListener: (() => void) | null;
   generation: number;
+  /**
+   * Set when `setClientResourceData` publishes while nobody is subscribed (session-cache
+   * seed). The first subscribe must quiet-revalidate; otherwise mount never fetches and
+   * seeded rows stay indefinitely stale with `lastAttemptOk: true`.
+   */
+  seedNeedsRevalidate: boolean;
 };
 
 /**
@@ -80,6 +86,7 @@ function getStore<T>(key: string): Store<T> {
       inflightOwner: null,
       visibilityListener: null,
       generation: 0,
+      seedNeedsRevalidate: false,
     };
     stores.set(key, store);
   }
@@ -298,9 +305,13 @@ function subscribeResource<T>(
   store.fetcherByListener.set(onStoreChange, fetcher);
   store.subscriberCount++;
 
-  // Cold start only — keep cached data across transient 0→1 resubscribe gaps.
-  if (store.subscriberCount === 1 && store.snapshot.data === undefined) {
-    void runFetch(store, fetcher, { replaceInflight: true, owner: onStoreChange });
+  // Cold start, or a pre-subscribe seed that still needs a network check. Keep
+  // cached data across transient 0→1 resubscribe gaps when neither applies.
+  if (store.subscriberCount === 1) {
+    if (store.snapshot.data === undefined || store.seedNeedsRevalidate) {
+      store.seedNeedsRevalidate = false;
+      void runFetch(store, fetcher, { replaceInflight: true, owner: onStoreChange });
+    }
   }
   recomputePoll(store);
 
@@ -328,7 +339,7 @@ function subscribeResource<T>(
 }
 
 /** Module-level fetch cache with useSyncExternalStore subscriptions (no fetch in useEffect). */
-export interface ClientResourceOptions {
+export interface ClientResourceOptions<T = unknown> {
   pollMs?: number;
   enabled?: boolean;
   /**
@@ -337,18 +348,34 @@ export interface ClientResourceOptions {
    * happening off-screen — a restarting server, for instance.
    */
   pauseWhenHidden?: boolean;
+  /**
+   * Optional seed applied once before the first subscribe (session-cache revisit).
+   * Lives in the store — not a render-time ref — so React Compiler / react-hooks/refs
+   * stay quiet while the mount fetch still quiet-revalidates via `seedNeedsRevalidate`.
+   */
+  initialData?: T;
+}
+
+/** Seed an empty, unsubscribed store. No-ops when data already exists or someone is listening. */
+function seedClientResourceIfEmpty<T>(key: string, data: T): void {
+  const store = getStore<T>(key);
+  if (store.subscriberCount !== 0 || store.snapshot.data !== undefined) return;
+  setClientResourceData(key, data);
 }
 
 export function useClientResource<T>(
   key: string,
   fetcher: (signal: AbortSignal) => Promise<T>,
-  options?: ClientResourceOptions,
+  options?: ClientResourceOptions<T>,
 ): ResourceSnapshot<T> & { refresh: (opts?: { forceLoading?: boolean }) => void } {
   const enabled = options?.enabled !== false;
   const pollMs = options?.pollMs;
   // Default true: a background tab has nobody reading the paint. Opt out for polls that
   // must keep running while hidden, such as waiting for a restarted server to answer.
   const pauseWhenHidden = options?.pauseWhenHidden !== false;
+  if (enabled && options?.initialData !== undefined) {
+    seedClientResourceIfEmpty(key, options.initialData);
+  }
   const fetcherRef = useRef(fetcher);
   // Sync latest fetcher every commit. No dep array on purpose: inline fetchers are
   // reallocated every render; listing them would re-subscribe forever.
@@ -411,7 +438,7 @@ export function useKeyedClientResource<T>(
   key: string,
   deps: readonly unknown[],
   load: (signal: AbortSignal) => Promise<T>,
-  options?: ClientResourceOptions,
+  options?: ClientResourceOptions<T>,
 ): ResourceSnapshot<T> & { refresh: (opts?: { forceLoading?: boolean }) => void } {
   const resource = useClientResource(key, load, options);
   const prevDepsRef = useRef<readonly unknown[] | null>(null);
@@ -447,6 +474,9 @@ export function setClientResourceData<T>(key: string, data: T) {
     hasSucceeded: true,
     lastAttemptOk: true,
   };
+  // Only pre-subscribe seeds need a follow-up fetch. Live publishers (mutation
+  // results) already hold the fresh value and must not schedule a redundant GET.
+  store.seedNeedsRevalidate = store.subscriberCount === 0;
   emit(store);
 }
 

gui/src/components/apikeys-workspace/ApiKeysWorkspace.tsx

@@ -38,6 +38,8 @@ export interface ApiKeysWorkspaceProps {
   copied: boolean;
   filteredModels: ExternalModelRow[];
   modelsLoading: boolean;
+  /** Quiet revalidation / retry over rows already on screen — not a skeleton. */
+  modelsRefreshing?: boolean;
   modelsLoadFailed: boolean;
   modelCount: number;
   hasModelData: boolean;
@@ -74,6 +76,7 @@ export default function ApiKeysWorkspace({
   copied,
   filteredModels,
   modelsLoading,
+  modelsRefreshing = false,
   modelsLoadFailed,
   modelCount,
   hasModelData,
@@ -418,6 +421,7 @@ export default function ApiKeysWorkspace({
                 <ApiKeysModelsPanel
                   filteredModels={filteredModels}
                   modelsLoading={modelsLoading}
+                  modelsRefreshing={modelsRefreshing}
                   modelsLoadFailed={modelsLoadFailed}
                   modelCount={modelCount}
                   hasModelData={hasModelData}

gui/src/components/section-tabs.tsx

@@ -41,6 +41,26 @@ export function SectionTabs({
     }
   }, []);
 
+  /** Timeout path: drop the click lock and re-read the visible section. */
+  const expireScrollLock = useCallback(() => {
+    clearScrollLock();
+    // If the user interrupted smooth scroll, the target may never intersect — without a
+    // resync `active` would stay on the clicked tab while another section is on screen.
+    let bestId: string | null = null;
+    let bestTop = Number.NEGATIVE_INFINITY;
+    for (const item of items) {
+      const node = document.getElementById(sectionAnchorId(scope, item.id));
+      if (!node) continue;
+      const top = node.getBoundingClientRect().top;
+      // Match the observer bias: prefer a heading near the top of the viewport.
+      if (top <= 120 && top > bestTop) {
+        bestTop = top;
+        bestId = item.id;
+      }
+    }
+    if (bestId) setActive(bestId);
+  }, [clearScrollLock, items, scope]);
+
   useEffect(() => () => clearScrollLock(), [clearScrollLock]);
 
   // Follow the scroll position. `rootMargin` biases the observer toward the top of the
@@ -82,7 +102,7 @@ export function SectionTabs({
     if (!target) return;
     scrollLockRef.current = id;
     if (scrollLockTimerRef.current !== null) clearTimeout(scrollLockTimerRef.current);
-    scrollLockTimerRef.current = setTimeout(clearScrollLock, SECTION_TAB_SCROLL_LOCK_MS);
+    scrollLockTimerRef.current = setTimeout(expireScrollLock, SECTION_TAB_SCROLL_LOCK_MS);
     setActive(id);
     // `scroll-margin-top` on the target keeps the heading clear of the pinned strip.
     target.scrollIntoView({ behavior: "smooth", block: "start" });

gui/src/data-surface.ts

@@ -43,6 +43,8 @@ export type DataSurfaceOptions<T> = {
   enabled?: boolean;
   /** Forwarded to the resource layer; see ClientResourceOptions.pauseWhenHidden. */
   pauseWhenHidden?: boolean;
+  /** Forwarded to the resource layer; see ClientResourceOptions.initialData. */
+  initialData?: T;
 };
 
 /**

gui/src/pages/ApiKeys.tsx

@@ -8,7 +8,6 @@ import {
   type ExternalModelRow,
   type GatewayInboundProtocol,
 } from "../api-access-models";
-import { setClientResourceData } from "../client-resource";
 import { readSessionListCache, writeSessionListCache } from "../session-list-cache";
 import { createBoundedFetch } from "../bounded-fetch";
 import { useDataSurface } from "../data-surface";
@@ -98,17 +97,6 @@ export default function ApiKeys({ apiBase }: { apiBase: string }) {
   // "no rules" table, or a row without `usage` throwing on first render.
   const cachedKeys = validCachedKeys(readSessionListCache<CachedKeysShape>(keysCacheKey));
   const cachedModels = readSessionListCache<ExternalModelRow[]>(modelsCacheKey);
-  // Seed before subscribe so a revisit does not flash loading status under the page title.
-  const seededKeysRef = useRef<string | null>(null);
-  if (seededKeysRef.current !== keysResourceKey) {
-    if (cachedKeys) setClientResourceData(keysResourceKey, cachedKeys);
-    seededKeysRef.current = keysResourceKey;
-  }
-  const seededModelsRef = useRef<string | null>(null);
-  if (seededModelsRef.current !== modelsResourceKey) {
-    if (cachedModels) setClientResourceData(modelsResourceKey, cachedModels);
-    seededModelsRef.current = modelsResourceKey;
-  }
   const [actionError, setActionError] = useState<string | null>(null);
   const [modelQuery, setModelQuery] = useState("");
   const [copiedModelId, setCopiedModelId] = useState<string | null>(null);
@@ -178,13 +166,13 @@ export default function ApiKeys({ apiBase }: { apiBase: string }) {
     keysResourceKey,
     [apiBase],
     fetchKeys,
-    { isEmpty: data => data.keys.length === 0 },
+    { isEmpty: data => data.keys.length === 0, initialData: cachedKeys ?? undefined },
   );
   const modelsResource = useDataSurface<ExternalModelRow[]>(
     modelsResourceKey,
     [apiBase],
     fetchModels,
-    { isEmpty: models => models.length === 0 },
+    { isEmpty: models => models.length === 0, initialData: cachedModels ?? undefined },
   );
   const keysState = keysResource.state;
   const modelsState = modelsResource.state;
@@ -427,6 +415,8 @@ export default function ApiKeys({ apiBase }: { apiBase: string }) {
         copied={copied}
         filteredModels={filteredModels}
         modelsLoading={modelsState.showSkeleton && !modelsState.data && !cachedModels}
+        // Only announce progress on a retry after failure — quiet warm revisits stay silent.
+        modelsRefreshing={modelsState.refreshing && modelsState.showError && (modelsState.data !== undefined || cachedModels !== null)}
         modelsLoadFailed={modelsState.showError}
         modelCount={models.length}
         // `readSessionListCache` answers `null`, not `undefined`, when it has

gui/src/pages/Claude.tsx

@@ -6,17 +6,23 @@ import { readSessionListCache } from "../session-list-cache";
 
 type ClaudeTab = "code" | "desktop";
 
+function readCachedDesktopPort(apiBase: string): number | null {
+  const cached = readSessionListCache<{ data?: { port?: number } }>(`ocx.claude-desktop.v1:${apiBase}`);
+  return typeof cached?.data?.port === "number" ? cached.data.port : null;
+}
+
 export default function Claude({ apiBase }: { apiBase: string }) {
   const [tab, setTab] = useState<ClaudeTab>("code");
   const t = useT();
   const codeTabRef = useRef<HTMLButtonElement>(null);
   const desktopTabRef = useRef<HTMLButtonElement>(null);
   // Seed Desktop's port subtitle from session cache so the intro above the Code/Desktop
-  // strip does not wait on the first status paint after a tab hop.
-  const [desktopPort, setDesktopPort] = useState<number | null>(() => {
-    const cached = readSessionListCache<{ data?: { port?: number } }>(`ocx.claude-desktop.v1:${apiBase}`);
-    return typeof cached?.data?.port === "number" ? cached.data.port : null;
-  });
+  // strip does not wait on the first status paint after a tab hop. Live updates from
+  // Desktop win while they match the current apiBase; a base change falls back to cache.
+  const seededDesktopPort = readCachedDesktopPort(apiBase);
+  const [liveDesktopPort, setLiveDesktopPort] = useState<{ base: string; port: number | null } | null>(null);
+  const desktopPort = liveDesktopPort?.base === apiBase ? liveDesktopPort.port : seededDesktopPort;
+  const setDesktopPort = (port: number | null) => setLiveDesktopPort({ base: apiBase, port });
 
   const selectTab = (next: ClaudeTab) => {
     setTab(next);

gui/src/pages/ClaudeCode.tsx

@@ -1,5 +1,4 @@
-import { useCallback, useMemo, useRef, useState, type ReactNode } from "react";
-import { setClientResourceData } from "../client-resource";
+import { useCallback, useMemo, useState, type ReactNode } from "react";
 import { Notice } from "../ui";
 import { useI18n, useT, LOCALES } from "../i18n/shared";
 import { readJsonOrThrow } from "../fetch-json";
@@ -34,12 +33,6 @@ export default function ClaudeCode({ apiBase, active = true }: { apiBase: string
   const cacheKey = `ocx.claude-code.v1:${apiBase}`;
   const resourceKey = `claude-code:${apiBase}`;
   const cached = useMemo(() => seedClaudeCode(cacheKey), [cacheKey]);
-  // Seed before subscribe so Code↔Desktop hops do not flash "Loading…" under the title.
-  const seededKeyRef = useRef<string | null>(null);
-  if (seededKeyRef.current !== resourceKey) {
-    if (cached) setClientResourceData(resourceKey, cached);
-    seededKeyRef.current = resourceKey;
-  }
   const [draftState, setState] = useState<ClaudeCodeState | null>(() => cached?.state ?? null);
   const [draftRows, setRows] = useState<MapRow[]>(() => cached?.rows ?? []);
   const [hasDraftRows, setHasDraftRows] = useState(Boolean(cached));
@@ -83,7 +76,7 @@ export default function ClaudeCode({ apiBase, active = true }: { apiBase: string
     resourceKey,
     [apiBase],
     fetchCode,
-    { isEmpty: () => false, enabled: active },
+    { isEmpty: () => false, enabled: active, initialData: cached ?? undefined },
   );
   const loadState = codeResource.state;
   const data = loadState.data ?? cached;