feat(webapp): keep the run inspector and queued time fresh on live runs

With progressive trace loading, the span inspector now stays up to date
while a run is live, and the timeline's queued time corrects itself as
soon as a queued run starts.

Mono-RevId: 8e43c0dc3369b6bca9731cca71cc306eeb0216c4

Author: Mariefay

apps/webapp/app/hooks/useRunStatusBackstop.ts

@@ -4,28 +4,28 @@ import type { RunStatusData } from "~/routes/resources.orgs.$organizationSlug.pr
 
 const DEFAULT_POLL_MS = 15_000;
 
-// Polls the run status and calls `onFinished` on each poll that sees the run finished,
-// until the caller disables it. The reload `onFinished` triggers can read a lagging
-// replica or be interrupted, so polling continues until the page data shows the run
-// finished. Failed polls are ignored and retried on the next interval.
+// Polls the run status and passes each result to `onStatus` until the caller disables
+// it. Reloads the caller triggers can read a lagging replica or be interrupted, so the
+// caller keeps polling until the page data agrees. Failed polls are ignored and retried
+// on the next interval.
 export function useRunStatusBackstop({
   enabled,
   statusPath,
   shouldSkip,
-  onFinished,
+  onStatus,
   pollMs = DEFAULT_POLL_MS,
 }: {
   enabled: boolean;
   statusPath: string;
   shouldSkip: () => boolean;
-  onFinished: () => void;
+  onStatus: (data: RunStatusData) => void;
   pollMs?: number;
 }) {
   const shouldSkipRef = useRef(shouldSkip);
-  const onFinishedRef = useRef(onFinished);
+  const onStatusRef = useRef(onStatus);
   useEffect(() => {
     shouldSkipRef.current = shouldSkip;
-    onFinishedRef.current = onFinished;
+    onStatusRef.current = onStatus;
   });
 
   useEffect(() => {
@@ -38,8 +38,8 @@ export function useRunStatusBackstop({
       );
       if (stopped || fetchError || !response.ok) return;
       const [parseError, data] = await tryCatch(response.json() as Promise<RunStatusData>);
-      if (stopped || parseError || (!data.isFinished && data.completedAt === null)) return;
-      onFinishedRef.current();
+      if (stopped || parseError) return;
+      onStatusRef.current(data);
     };
     const id = window.setInterval(() => void poll(), pollMs);
     return () => {

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.runs.$runParam/route.tsx

@@ -131,6 +131,7 @@ import { useCurrentPlan } from "../_app.orgs.$organizationSlug/route";
 import { shouldRevalidateRunPage } from "./shouldRevalidateRunPage";
 import { settleUnloadedRoot } from "./settleUnloadedRoot";
 import { getTraceStatus, type TraceStatus } from "./traceStatus";
+import { useThrottledRefresh } from "./useThrottledRefresh";
 import { SpanView } from "../resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.runs.$runParam.spans.$spanParam/route";
 import { pageMeta } from "~/utils/pageTitle";
 
@@ -679,6 +680,7 @@ function TraceFilters({
 
 // Coarse on purpose: the tail normally flips the root to terminal itself.
 const RUN_STATUS_BACKSTOP_POLL_MS = 15_000;
+const INSPECTOR_REFRESH_MS = 5_000;
 
 // Tail path: no size cap. Keeps tailing while the root still looks unfinished, so
 // final rows that become visible late still land, but not long after completion.
@@ -837,17 +839,24 @@ function TraceView({
     }
   }, [run.friendlyId, rootSpanStatus, liveTailEnabled, runDataUnfinished]);
 
-  // Tail path backstop: reload once the run finishes, even if the tail missed the
-  // root's final row. Polls whatever the stream is doing, and keeps reloading until the
-  // page data shows the run finished (a reload can read a lagging replica).
+  // Tail path backstop: reload when the run starts and when it finishes, even if the
+  // tail missed the root's final row. Polls whatever the stream is doing, and keeps
+  // reloading until the page data agrees (a reload can read a lagging replica).
   useRunStatusBackstop({
     enabled: liveTailEnabled && runDataUnfinished,
     statusPath,
     shouldSkip: () => document.visibilityState === "hidden",
-    onFinished: () => {
-      // The revalidate alone won't refresh the tree if the span count didn't change.
-      tailLive();
-      revalidatorRef.current.revalidate();
+    onStatus: (data) => {
+      if (data.isFinished || data.completedAt !== null) {
+        // The revalidate alone won't refresh the tree if the span count didn't change.
+        tailLive();
+        revalidatorRef.current.revalidate();
+        return;
+      }
+      // Run started: reload once for the queued offset, retried until the page data has it.
+      if (data.startedAt !== null && run.startedAt === null) {
+        revalidatorRef.current.revalidate();
+      }
     },
     pollMs: RUN_STATUS_BACKSTOP_POLL_MS,
   });
@@ -866,6 +875,15 @@ function TraceView({
     }
   }, [isComplete, recentlyActive, traceIsTruncated, loadFailed, liveTailEnabled, tailLive]);
 
+  // Tail path: the inspector loads separately, so reload it when the tree changes. After
+  // the background load, rebuilds come from the tail or a revalidate merge.
+  const inspectorRefreshKey = useThrottledRefresh(events, {
+    enabled: liveTailEnabled && isLiveReloading && isComplete,
+    intervalMs: INSPECTOR_REFRESH_MS,
+  });
+  // Frozen while the panel is closed, so closing doesn't reload it and reopening catches up.
+  const displayRefreshKey = useFrozenValue(selectedSpanId ? inspectorRefreshKey : undefined);
+
   const spanOverrides = selectedSpanId ? overridesBySpanId?.[selectedSpanId] : undefined;
   const frozenSpanOverrides = useFrozenValue(spanOverrides);
   const displaySpanOverrides = selectedSpanId ? spanOverrides : frozenSpanOverrides;
@@ -961,6 +979,7 @@ function TraceView({
                 spanOverrides={displaySpanOverrides as SpanOverride | undefined}
                 closePanel={() => replaceSearchParam("span")}
                 linkedRunId={displayLinkedRunId}
+                refreshKey={displayRefreshKey ?? undefined}
               />
             )}
           </div>

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.runs.$runParam/useThrottledRefresh.ts

@@ -0,0 +1,66 @@
+import { useEffect, useRef, useState } from "react";
+
+type ThrottleState = {
+  lastBumpAt: number;
+  trailing: ReturnType<typeof setTimeout> | null;
+  hiddenChange: boolean;
+};
+
+const isHidden = () => document.visibilityState === "hidden";
+
+function requestBump(state: ThrottleState, intervalMs: number, bump: () => void) {
+  if (isHidden()) {
+    state.hiddenChange = true;
+    return;
+  }
+  const wait = state.lastBumpAt + intervalMs - Date.now();
+  if (wait <= 0) {
+    state.lastBumpAt = Date.now();
+    bump();
+    return;
+  }
+  if (state.trailing !== null) return;
+  state.trailing = setTimeout(() => {
+    state.trailing = null;
+    requestBump(state, intervalMs, bump);
+  }, wait);
+}
+
+/**
+ * Returns a key that bumps when `signal` changes, at most once per `intervalMs` with one
+ * trailing bump. Changes while the tab is hidden bump once when it's visible again.
+ */
+export function useThrottledRefresh(
+  signal: unknown,
+  { enabled, intervalMs }: { enabled: boolean; intervalMs: number }
+): number {
+  const [refreshKey, setRefreshKey] = useState(0);
+  const stateRef = useRef<ThrottleState>({ lastBumpAt: 0, trailing: null, hiddenChange: false });
+  const prevSignalRef = useRef(signal);
+
+  useEffect(() => {
+    const changed = prevSignalRef.current !== signal;
+    prevSignalRef.current = signal;
+    if (!enabled || !changed) return;
+    requestBump(stateRef.current, intervalMs, () => setRefreshKey((key) => key + 1));
+  }, [signal, enabled, intervalMs]);
+
+  useEffect(() => {
+    if (!enabled) return;
+    const state = stateRef.current;
+    const onVisibilityChange = () => {
+      if (isHidden() || !state.hiddenChange) return;
+      state.hiddenChange = false;
+      requestBump(state, intervalMs, () => setRefreshKey((key) => key + 1));
+    };
+    document.addEventListener("visibilitychange", onVisibilityChange);
+    return () => {
+      document.removeEventListener("visibilitychange", onVisibilityChange);
+      if (state.trailing !== null) clearTimeout(state.trailing);
+      state.trailing = null;
+      state.hiddenChange = false;
+    };
+  }, [enabled, intervalMs]);
+
+  return refreshKey;
+}

apps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.runs.$runParam.spans.$spanParam/route.tsx

@@ -237,12 +237,15 @@ export function SpanView({
   spanOverrides,
   closePanel,
   linkedRunId,
+  refreshKey,
 }: {
   runParam: string;
   spanId: string | undefined;
   spanOverrides?: SpanOverride;
   closePanel?: () => void;
   linkedRunId?: string;
+  /** Changing it reloads the span. */
+  refreshKey?: number;
 }) {
   const organization = useOrganization();
   const project = useProject();
@@ -256,7 +259,16 @@ export function SpanView({
       environment.slug
     }/runs/${runParam}/spans/${spanId}${linkedRunId ? `?linkedRunId=${linkedRunId}` : ""}`;
     load(url);
-  }, [organization.slug, project.slug, environment.slug, runParam, spanId, linkedRunId, load]);
+  }, [
+    organization.slug,
+    project.slug,
+    environment.slug,
+    runParam,
+    spanId,
+    linkedRunId,
+    load,
+    refreshKey,
+  ]);
 
   if (spanId === undefined) {
     return null;

apps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.runs.$runParam.status.ts

@@ -7,8 +7,12 @@ import { controlPlaneResolver } from "~/v3/runOpsMigration/controlPlaneResolver.
 import { runStore } from "~/v3/runStore.server";
 import { isFinalRunStatus } from "~/v3/taskStatus";
 
-// Run terminal-state probe polled by the trace viewer's live tail backstop.
-export type RunStatusData = { isFinished: boolean; completedAt: string | null };
+// Run start/finish probe polled by the trace viewer's live tail backstop.
+export type RunStatusData = {
+  isFinished: boolean;
+  startedAt: string | null;
+  completedAt: string | null;
+};
 
 export async function loader({ request, params }: LoaderFunctionArgs) {
   const userId = await requireUserId(request);
@@ -17,7 +21,13 @@ export async function loader({ request, params }: LoaderFunctionArgs) {
   const run = await runStore.findRun(
     { friendlyId: runParam },
     {
-      select: { status: true, completedAt: true, projectId: true, runtimeEnvironmentId: true },
+      select: {
+        status: true,
+        startedAt: true,
+        completedAt: true,
+        projectId: true,
+        runtimeEnvironmentId: true,
+      },
     }
   );
 
@@ -47,6 +57,7 @@ export async function loader({ request, params }: LoaderFunctionArgs) {
 
   return json<RunStatusData>({
     isFinished: isFinalRunStatus(run.status),
+    startedAt: run.startedAt ? run.startedAt.toISOString() : null,
     completedAt: run.completedAt ? run.completedAt.toISOString() : null,
   });
 }

apps/webapp/test/useRunStatusBackstop.dom.test.ts

@@ -6,6 +6,7 @@ import { createRoot, type Root } from "react-dom/client";
 import { act } from "react-dom/test-utils";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { useRunStatusBackstop } from "~/hooks/useRunStatusBackstop";
+import type { RunStatusData } from "~/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.runs.$runParam.status";
 
 type Reply = { status: number; body?: unknown };
 
@@ -49,13 +50,13 @@ function poll() {
 }
 
 function render(props: { enabled?: boolean; skip?: () => boolean }) {
-  let finished = 0;
+  const seen: RunStatusData[] = [];
   function Harness({ enabled }: { enabled: boolean }) {
     useRunStatusBackstop({
       enabled,
       statusPath: `${baseUrl}/status`,
       shouldSkip: props.skip ?? (() => false),
-      onFinished: () => finished++,
+      onStatus: (data) => seen.push(data),
       pollMs: POLL_MS,
     });
     return null;
@@ -65,56 +66,60 @@ function render(props: { enabled?: boolean; skip?: () => boolean }) {
   root = createRoot(container);
   act(() => root!.render(createElement(Harness, { enabled: props.enabled ?? true })));
   return {
-    finished: () => finished,
+    seen: () => seen,
+    count: () => seen.length,
     disable: () => act(() => root!.render(createElement(Harness, { enabled: false }))),
   };
 }
 
 describe("useRunStatusBackstop", () => {
-  it("calls onFinished on each poll that sees the run finished until disabled", async () => {
+  it("passes each poll's data to onStatus until disabled", async () => {
     vi.useFakeTimers({ toFake: ["setInterval", "clearInterval"] });
+    const queued = { isFinished: false, startedAt: null, completedAt: null };
+    const started = { isFinished: false, startedAt: "2026-10-06T10:00:00.000Z", completedAt: null };
     replies = [
-      { status: 200, body: { isFinished: false, completedAt: null } },
-      { status: 200, body: { isFinished: true, completedAt: null } },
+      { status: 200, body: queued },
+      { status: 200, body: started },
     ];
     const harness = render({});
     poll();
-    await expect.poll(() => requests, ASSERTION_POLL_OPTIONS).toBe(1);
-    expect(harness.finished()).toBe(0);
+    await expect.poll(harness.count, ASSERTION_POLL_OPTIONS).toBe(1);
+    expect(harness.seen()[0]).toEqual(queued);
     poll();
-    await expect.poll(harness.finished, ASSERTION_POLL_OPTIONS).toBe(1);
-    poll();
-    await expect.poll(harness.finished, ASSERTION_POLL_OPTIONS).toBe(2);
+    await expect.poll(harness.count, ASSERTION_POLL_OPTIONS).toBe(2);
+    expect(harness.seen()[1]).toEqual(started);
 
     harness.disable();
-    const finishedAtDisable = harness.finished();
+    const seenAtDisable = harness.count();
     const requestsAtDisable = requests;
     act(() => vi.advanceTimersByTime(POLL_MS * 5));
     await act(() => sleep(100));
-    expect(harness.finished()).toBe(finishedAtDisable);
+    expect(harness.count()).toBe(seenAtDisable);
     expect(requests).toBe(requestsAtDisable);
   });
 
-  it("ignores failed polls and keeps polling", async () => {
-    replies = [
-      { status: 404 },
-      { status: 500 },
-      { status: 200, body: { isFinished: false, completedAt: "2026-10-06T10:00:00.000Z" } },
-    ];
+  it("ignores failed and unparseable polls and keeps polling", async () => {
+    const finished = {
+      isFinished: true,
+      startedAt: "2026-10-06T10:00:00.000Z",
+      completedAt: "2026-10-06T10:01:00.000Z",
+    };
+    replies = [{ status: 404 }, { status: 500 }, { status: 200 }, { status: 200, body: finished }];
     const harness = render({});
-    await expect.poll(harness.finished).toBeGreaterThanOrEqual(1);
+    await expect.poll(harness.count).toBeGreaterThanOrEqual(1);
+    expect(harness.seen().every((data) => data.isFinished)).toBe(true);
   });
 
   it("does not poll while shouldSkip is true", async () => {
-    replies = [{ status: 200, body: { isFinished: true, completedAt: null } }];
+    replies = [{ status: 200, body: { isFinished: true, startedAt: null, completedAt: null } }];
     const harness = render({ skip: () => true });
     await act(() => sleep(150));
     expect(requests).toBe(0);
-    expect(harness.finished()).toBe(0);
+    expect(harness.count()).toBe(0);
   });
 
   it("does not poll when disabled", async () => {
-    replies = [{ status: 200, body: { isFinished: true, completedAt: null } }];
+    replies = [{ status: 200, body: { isFinished: true, startedAt: null, completedAt: null } }];
     render({ enabled: false });
     await act(() => sleep(100));
     expect(requests).toBe(0);