Make hydrated thread bootstraps usable and harden the persisted query cache

Review fixes for the persistedQueryCache experiment:

- A hydrated threadDetailBootstrap did nothing for first paint: the thread
  route reads the thread from the `thread`/`environment`/`host` caches, which
  only the live queryFn seeded, so the page still sat on "Loading…" until
  useThread round-tripped. Re-run ingestThreadDetailBootstrap for every
  bootstrap the hydrate call landed, stamped with the bootstrap's own fetch
  time so staleTime and the reconnect invalidation see the derived entries
  as exactly that old.
- The persister re-read and re-parsed the whole IndexedDB blob on every
  debounce tick (every 1.5 s during a streaming turn). Read the store once
  and carry the merged snapshot forward in memory; also stop a write whose
  initial read was overtaken by stop(), so turning the experiment off cannot
  repopulate the store it just cleared.
- The IndexedDB write only watched the transaction, whose abort error can be
  null while the put request carries the real QuotaExceededError; await the
  request so the quota path actually clears the store.
- A blob from an older app version that crashes the tree would crash every
  reload for 24 h. AppErrorBoundary gains an onError hook and main.tsx clears
  the store on a crash that follows a hydration.
- Put the experiments literals back on one key per line.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: SawyerHood

apps/app/src/components/AppErrorBoundary.test.tsx

@@ -53,6 +53,27 @@ describe("AppErrorBoundary", () => {
     dispose();
   });
 
+  it("reports the caught error to onError so boot can drop a bad persisted cache", () => {
+    vi.spyOn(console, "error").mockImplementation(() => undefined);
+    const { container, render, dispose } = mountRoot();
+    const onError = vi.fn();
+
+    function Boom(): never {
+      throw new Error("hydrated shape mismatch");
+    }
+    render(
+      <AppErrorBoundary onError={onError}>
+        <Boom />
+      </AppErrorBoundary>,
+    );
+
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onError.mock.calls[0]?.[0]).toBeInstanceOf(Error);
+    expect(onError.mock.calls[0]?.[0].message).toBe("hydrated shape mismatch");
+    expect(container.textContent).toContain("bb hit an error and stopped");
+    dispose();
+  });
+
   it("catches the commit-phase removeChild failure instead of blanking the root", () => {
     vi.spyOn(console, "error").mockImplementation(() => undefined);
     const { container, render, dispose } = mountRoot();

apps/app/src/components/AppErrorBoundary.tsx

@@ -17,6 +17,13 @@ import { Component, type ErrorInfo, type ReactNode } from "react";
 
 interface AppErrorBoundaryProps {
   children: ReactNode;
+  /**
+   * Runs once per caught error, after the console report. Must not throw and
+   * must not depend on anything the crashed tree owned; main.tsx uses it to
+   * drop the persisted query cache so a bad hydration cannot crash every
+   * reload in a row.
+   */
+  onError?: (error: Error) => void;
 }
 
 interface AppErrorBoundaryState {
@@ -37,6 +44,7 @@ export class AppErrorBoundary extends Component<
     // The component stack is the part a screenshot of the console never has,
     // and the part that names the subtree at fault.
     console.error("[bb] the app crashed", error, info.componentStack);
+    this.props.onError?.(error);
   }
 
   override render(): ReactNode {

apps/app/src/components/layout/AppLayout.plugin-panel-header.test.tsx

@@ -30,7 +30,8 @@ vi.mock("@/hooks/queries/system-queries", () => ({
         claudeCodeMockCliTraffic: false,
         editMessages: false,
         newOnboarding: false,
-        persistedQueryCache: false,        providerSessionReaping: false,
+        persistedQueryCache: false,
+        providerSessionReaping: false,
       },
     },
   }),

apps/app/src/components/layout/AppLayout.root-compose-project.test.tsx

@@ -26,7 +26,8 @@ vi.mock("@/hooks/queries/system-queries", () => ({
         claudeCodeMockCliTraffic: false,
         editMessages: false,
         newOnboarding: false,
-        persistedQueryCache: false,        providerSessionReaping: false,
+        persistedQueryCache: false,
+        providerSessionReaping: false,
       },
     },
   }),

apps/app/src/hooks/cache-owners/thread-detail-cache-owner.ts

@@ -27,6 +27,13 @@ interface UpsertHostListArgs {
 export interface ThreadDetailBootstrapIngestionArgs {
   queryClient: QueryClient;
   thread: ThreadWithIncludesResponse;
+  /**
+   * When the bootstrap did not just arrive from the network (a slice hydrated
+   * from the persisted query cache), stamp the derived entries with the
+   * bootstrap's own fetch time so their staleTime and the reconnect
+   * invalidation treat them as exactly that old. Omit for a live response.
+   */
+  updatedAt?: number;
 }
 
 function stripThreadIncludes(
@@ -65,24 +72,30 @@ function upsertHostList({ host, hosts }: UpsertHostListArgs): HostList {
 export function ingestThreadDetailBootstrap({
   queryClient,
   thread,
+  updatedAt,
 }: ThreadDetailBootstrapIngestionArgs): void {
+  const setOptions = updatedAt === undefined ? undefined : { updatedAt };
   queryClient.setQueryData(
     threadQueryKey(thread.id),
     stripThreadIncludes(thread),
+    setOptions,
   );
 
   if (thread.environment) {
     queryClient.setQueryData(
       environmentQueryKey(thread.environment.id),
       thread.environment,
+      setOptions,
     );
   }
 
   if (thread.host) {
     const host = thread.host;
-    queryClient.setQueryData(hostQueryKey(host.id), host);
-    queryClient.setQueryData<HostList>(hostsQueryKey(), (hosts) =>
-      upsertHostList({ host, hosts }),
+    queryClient.setQueryData(hostQueryKey(host.id), host, setOptions);
+    queryClient.setQueryData<HostList>(
+      hostsQueryKey(),
+      (hosts) => upsertHostList({ host, hosts }),
+      setOptions,
     );
   }
 

apps/app/src/lib/persisted-query-cache/persisted-query-cache-store.ts

@@ -94,7 +94,11 @@ export function createIndexedDbPersistedQueryCacheStore(): PersistedQueryCacheSt
     },
     async write(value) {
       await withDatabase("readwrite", async (store, transaction) => {
-        store.put(value, IDB_SNAPSHOT_KEY);
+        // Await the request itself, not just the transaction: a failed put
+        // aborts the transaction, but the abort event's `error` can still be
+        // null while the request's is the real `QuotaExceededError`, which the
+        // persister needs to see to clear the store.
+        await requestToPromise(store.put(value, IDB_SNAPSHOT_KEY));
         await transactionDone(transaction);
       });
     },

apps/app/src/lib/persisted-query-cache/persisted-query-cache.test.ts

@@ -1,10 +1,14 @@
 import { QueryClient } from "@tanstack/react-query";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
+  environmentQueryKey,
+  hostQueryKey,
+  hostsQueryKey,
   sidebarNavigationQueryKey,
   systemConfigQueryKey,
   threadDetailBootstrapQueryKey,
   threadHostFilePreviewQueryKey,
+  threadQueryKey,
   threadsQueryKey,
   threadTimelineQueryKey,
 } from "@/hooks/queries/query-keys";
@@ -213,6 +217,78 @@ describe("restorePersistedQueryCache", () => {
     expect(state?.dataUpdatedAt).toBe(NOW - 60_000);
   });
 
+  it("seeds the thread, environment and host caches from a hydrated bootstrap with its fetch time", async () => {
+    const queryClient = new QueryClient();
+    const fetchedAt = NOW - 90_000;
+    const bootstrap = entry(threadDetailBootstrapQueryKey("thr_1"), fetchedAt, {
+      id: "thr_1",
+      title: "Cached",
+      environment: { id: "env_1" },
+      host: { id: "host_1" },
+    });
+    const store = createMemoryPersistedQueryCacheStore(
+      serializePersistedQueryCache([bootstrap], fetchedAt),
+    );
+
+    await restorePersistedQueryCache({ queryClient, store, now: NOW });
+
+    // The route reads the thread from `thread`, not from the bootstrap query;
+    // without this seed a hydrated bootstrap still paints "Loading…".
+    expect(queryClient.getQueryData(threadQueryKey("thr_1"))).toEqual({
+      id: "thr_1",
+      title: "Cached",
+    });
+    expect(queryClient.getQueryData(environmentQueryKey("env_1"))).toEqual({
+      id: "env_1",
+    });
+    expect(queryClient.getQueryData(hostQueryKey("host_1"))).toEqual({
+      id: "host_1",
+    });
+    expect(queryClient.getQueryData(hostsQueryKey())).toEqual([
+      { id: "host_1" },
+    ]);
+    // Same age as the bootstrap, so staleTime and reconnect invalidation
+    // treat the derived entries as stale too.
+    for (const key of [
+      threadQueryKey("thr_1"),
+      environmentQueryKey("env_1"),
+      hostQueryKey("host_1"),
+      hostsQueryKey(),
+    ]) {
+      expect(queryClient.getQueryState(key)?.dataUpdatedAt).toBe(fetchedAt);
+    }
+  });
+
+  it("leaves the derived caches alone when the live bootstrap is fresher", async () => {
+    const queryClient = new QueryClient();
+    seedQuery(
+      queryClient,
+      threadDetailBootstrapQueryKey("thr_1"),
+      { id: "thr_1", title: "Live", environment: null, host: null },
+      NOW,
+    );
+    const store = createMemoryPersistedQueryCacheStore(
+      serializePersistedQueryCache(
+        [
+          entry(threadDetailBootstrapQueryKey("thr_1"), NOW - 1, {
+            id: "thr_1",
+            title: "Stale",
+            environment: { id: "env_stale" },
+            host: null,
+          }),
+        ],
+        NOW - 1,
+      ),
+    );
+
+    await restorePersistedQueryCache({ queryClient, store, now: NOW });
+
+    expect(queryClient.getQueryData(threadQueryKey("thr_1"))).toBeUndefined();
+    expect(
+      queryClient.getQueryData(environmentQueryKey("env_stale")),
+    ).toBeUndefined();
+  });
+
   it("does not overwrite fresher data already in the client", async () => {
     const queryClient = new QueryClient();
     seedQuery(queryClient, systemConfigQueryKey(), { v: "live" }, NOW);
@@ -345,9 +421,13 @@ describe("startPersistedQueryCachePersister", () => {
       collectLivePersistedQueryCacheEntries(queryClient).map((e) => e.queryKey),
     ).toEqual([sidebarNavigationQueryKey()]);
 
-    // A later successful update is picked up on the next flush.
+    // A later successful update is picked up on the next flush, the previous
+    // snapshot still survives, and the store is not re-read for it: a
+    // streaming turn must not parse the whole blob on every debounce tick.
+    const read = vi.spyOn(store, "read");
     seedQuery(queryClient, threadTimelineQueryKey("gcd"), { rows: [] }, NOW);
     await persister.flush();
+    expect(read).not.toHaveBeenCalled();
     expect(
       parsePersistedQueryCache(store.value, NOW)?.map((e) => e.queryKey),
     ).toEqual([
@@ -358,6 +438,32 @@ describe("startPersistedQueryCachePersister", () => {
     persister.stop();
   });
 
+  it("does not write after stop() lands during the initial store read", async () => {
+    const queryClient = new QueryClient();
+    seedQuery(queryClient, sidebarNavigationQueryKey(), { s: 1 }, NOW);
+    let resolveRead: (value: string | null) => void = () => {};
+    const store = createMemoryPersistedQueryCacheStore();
+    vi.spyOn(store, "read").mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          resolveRead = resolve;
+        }),
+    );
+    const write = vi.spyOn(store, "write");
+    const persister = startPersistedQueryCachePersister({
+      queryClient,
+      store,
+      now: () => NOW,
+    });
+    const flushed = persister.flush();
+    // The experiment turned off (or the app tore down) mid-read; the store
+    // is about to be cleared and must not be repopulated by this write.
+    persister.stop();
+    resolveRead(null);
+    await flushed;
+    expect(write).not.toHaveBeenCalled();
+  });
+
   it("debounces cache updates into one write and stops after stop()", async () => {
     vi.useFakeTimers();
     const queryClient = new QueryClient();

apps/app/src/lib/persisted-query-cache/persisted-query-cache.ts

@@ -26,6 +26,8 @@ import {
   type QueryState,
 } from "@tanstack/react-query";
 import { z } from "zod";
+import type { ThreadWithIncludesResponse } from "@bb/server-contract";
+import { ingestThreadDetailBootstrap } from "@/hooks/cache-owners/thread-detail-cache-owner";
 import {
   SIDEBAR_NAVIGATION_QUERY_KEY,
   SYSTEM_CONFIG_QUERY_KEY,
@@ -342,9 +344,47 @@ export async function restorePersistedQueryCache({
       state: hydratedQueryState(entry),
     })),
   });
+  ingestHydratedThreadDetailBootstraps(queryClient, entries);
   return { status: "hydrated", entryCount: entries.length };
 }
 
+/**
+ * The live bootstrap query seeds the `thread`, `environment` and `host` caches
+ * from inside its queryFn, and the thread route reads the thread from those —
+ * a hydrated bootstrap alone would still leave the page on "Loading…" until
+ * `useThread` round-trips. Re-run that ingestion for every bootstrap the
+ * hydrate call actually landed (fresher live data is left alone), stamped with
+ * the bootstrap's own fetch time so the derived entries stay exactly as stale.
+ */
+function ingestHydratedThreadDetailBootstraps(
+  queryClient: QueryClient,
+  entries: ReadonlyArray<PersistedQueryCacheEntry>,
+): void {
+  for (const entry of entries) {
+    if (
+      classifyPersistedQueryKey(entry.queryKey)?.kind !==
+      "threadDetailBootstrap"
+    ) {
+      continue;
+    }
+    const state = queryClient.getQueryState<ThreadWithIncludesResponse>(
+      entry.queryKey,
+    );
+    if (
+      state === undefined ||
+      state.data === undefined ||
+      state.dataUpdatedAt !== entry.dataUpdatedAt
+    ) {
+      continue;
+    }
+    ingestThreadDetailBootstrap({
+      queryClient,
+      thread: state.data,
+      updatedAt: state.dataUpdatedAt,
+    });
+  }
+}
+
 export interface RestorePersistedQueryCacheIfEnabledArgs {
   queryClient: QueryClient;
   /** The local mirror of the experiment; false skips storage entirely. */
@@ -431,6 +471,12 @@ export function startPersistedQueryCachePersister({
   let dirty = false;
   let timer: ReturnType<typeof setTimeout> | null = null;
   let writeChain: Promise<void> = Promise.resolve();
+  // What the store held the last time we looked. Read from IndexedDB once
+  // (entries hydrated on a previous launch may since have been garbage-
+  // collected from memory and must survive), then carried forward from our
+  // own writes so a streaming turn does not re-read and re-parse the whole
+  // blob on every debounce tick.
+  let previousEntries: PersistedQueryCacheEntry[] | null = null;
 
   const cancelTimer = () => {
     if (timer !== null) {
@@ -451,14 +497,23 @@ export function startPersistedQueryCachePersister({
     dirty = false;
     const timestamp = now();
     try {
-      const previous =
-        parsePersistedQueryCache(await store.read(), timestamp) ?? [];
+      if (previousEntries === null) {
+        previousEntries =
+          parsePersistedQueryCache(await store.read(), timestamp) ?? [];
+        // stop() may have landed during the read; the caller is gone.
+        if (disabled || stopped) return;
+      }
       const selected = selectPersistedQueryCacheEntries(
-        [...collectLivePersistedQueryCacheEntries(queryClient), ...previous],
+        [
+          ...collectLivePersistedQueryCacheEntries(queryClient),
+          ...previousEntries,
+        ],
         { now: timestamp },
       );
       await store.write(serializePersistedQueryCache(selected, timestamp));
+      previousEntries = selected;
     } catch (error) {
+      previousEntries = null;
       if (isQuotaExceededError(error)) {
         await store.clear();
       }

apps/app/src/lib/system-config-atoms.ts

@@ -24,7 +24,8 @@ const unavailableSystemConfig: SystemConfigResponse = {
     claudeCodeMockCliTraffic: false,
     editMessages: false,
     newOnboarding: false,
-    persistedQueryCache: false,    providerSessionReaping: false,
+    persistedQueryCache: false,
+    providerSessionReaping: false,
   },
   appearance: defaultAppTheme,
   customThemes: [],