@zaip-ai/cli 1.0.7 → 1.0.8

package/templates/.agents/dashboard/apps/frontend/src/App.tsx

@@ -1,120 +1,178 @@
 import type { CostMonitorProjection } from "@zaip-ai/dashboard-cost-monitor/contracts";
 import type { CostCurrency, CostLocale } from "@zaip-ai/dashboard-cost-monitor/react";
-import { CostMonitorPage } from "@zaip-ai/dashboard-cost-monitor/react";
-import type {
-  ChangeProjection,
-  MacroProjection,
-  OperationsProjection,
-  PrdDetailProjection,
-  SpecDetailProjection,
-} from "@zaip-ai/dashboard-operations/contracts";
+import type { OperationsProjection } from "@zaip-ai/dashboard-operations/contracts";
+import { OperationsPage } from "@zaip-ai/dashboard-operations/react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { AppLoadingBoundary } from "./AppLoadingBoundary.js";
+import type { LoadingArea } from "./AppLoadingPanels.js";
+import { AppOverlays } from "./AppOverlays.js";
 import {
-  EntityDetailsDialog,
-  MacroDocumentDialog,
-  MacroPlanningDialog,
-  OperationsPage,
-} from "@zaip-ai/dashboard-operations/react";
-import type { TaskTrace } from "@zaip-ai/dashboard-traceability/contracts";
-import { TaskTraceLoadingPanel, TaskTracePanel } from "@zaip-ai/dashboard-traceability/react";
-import { lazy, Suspense, useCallback, useEffect, useMemo, useRef, useState } from "react";
+  isAbortError,
+  isCurrentDashboardRequest,
+  isCurrentOperationsPeriodRequest,
+  isCurrentPeriodTransition,
+  mergeBoardPages,
+  PeriodTransitionOverlay,
+  PeriodTransitionShell,
+} from "./AppRequestGuards.js";
 import {
-  DashboardLoadingNotice,
-  DashboardSkeleton,
-  LoadFailedPanel,
-  type LoadingArea,
-  LoadingPanel,
-} from "./AppLoadingPanels.js";
+  costCalculationGuidePath,
+  pricingSetupPath,
+  projectSetupPath,
+  renderAppSetupRoute,
+} from "./AppSetupRoutes.js";
+import { currencyKey, initialDashboardView, savedLocale } from "./app-preferences.js";
+import { readDashboardSessionToken } from "./app-session-token.js";
+import { renderDashboardAlternateContent } from "./DashboardAlternateContent.js";
 import { DashboardCapabilityNav, type DashboardView } from "./DashboardCapabilityNav.js";
-import type { FxRate, PricingCatalog, ReconciliationResult } from "./dashboard-api.js";
+import { DashboardGlobalSettings } from "./DashboardGlobalSettings.js";
+import type {
+  FxRate,
+  OperationsBoardPage,
+  OperationsEntityPageKind,
+  OperationsLifecyclePageKind,
+  OperationsPageFilters,
+  PricingCatalog,
+  ReconciliationResult,
+  WorkBoardStage,
+} from "./dashboard-api.js";
 import { DashboardApiClient } from "./dashboard-api.js";
 import { defaultOperationsPeriod, requestPeriodForOperations } from "./operations-period.js";
-import { loadAtomicCostSnapshot, loadCostViewSnapshot } from "./snapshot-coherence.js";
-import { TraceabilityWorkspace } from "./TraceabilityWorkspace.js";
+import { shouldShowSnapshotNotice, snapshotNoticeDelayMs } from "./snapshot-notice.js";
+import { useAppCostLoaders } from "./use-app-cost-loaders.js";
+import { useAppEffects } from "./use-app-effects.js";
+import { useAppOperationsPages } from "./use-app-operations-pages.js";
+import { useAppTraceDocuments } from "./use-app-trace-documents.js";
+import {
+  collectWorkListPages,
+  normalizeWorkListFilters,
+  selectedWorkListKinds,
+} from "./work-list-pagination.js";
 import "./loading-feedback.css";
+import "./period-transition-overlay.css";
 
-const legacyCostMonitorPath = "/zaip-cost-monitor";
-const DashboardHelpDialog = lazy(async () => {
-  const module = await import("./DashboardHelpDialog.js");
-  return { default: module.DashboardHelpDialog };
-});
-const AgentCatalogSettingsPage = lazy(async () => ({
-  default: (await import("./AgentCatalogSettingsPage.js")).AgentCatalogSettingsPage,
-}));
-const PricingSettingsPage = lazy(async () => ({
-  default: (await import("./PricingSettingsDialog.js")).PricingSettingsPage,
-}));
-const ProjectSettingsPage = lazy(async () => ({
-  default: (await import("./ProjectSettingsPage.js")).ProjectSettingsPage,
-}));
-const pricingSetupPath = "/setup-pricing";
-const agentCatalogSetupPath = "/setup-agents";
-const projectSetupPath = "/setup-project";
-const sessionTokenKey = "zaip-dashboard-session-token";
-const localeKey = "zaip-dashboard-locale";
-const currencyKey = "zaip-dashboard-currency";
+type BoardStageState = { loading: boolean; error: string | null };
+type OverviewStatusKind = "task" | "spec" | "prd";
+type OverviewClassification = "lite" | "standard" | "critical" | "empty" | "structured" | "rework";
+type OverviewStatusPage = {
+  items: OperationsProjection["tasks"] | OperationsProjection["specs"] | OperationsProjection["prds"];
+  total: number;
+  loading: boolean;
+  error: string | null;
+};
+type OverviewStatusPages = Partial<Record<`${WorkBoardStage}:${OverviewStatusKind}`, OverviewStatusPage>>;
+const overviewStatusPageKey = (stage: WorkBoardStage, kind: OverviewStatusKind) => `${stage}:${kind}` as const;
+type OverviewClassificationPages = Partial<Record<`${OverviewStatusKind}:${OverviewClassification}`, OverviewStatusPage>>;
+const overviewClassificationPageKey = (kind: OverviewStatusKind, classification: OverviewClassification) =>
+  `${kind}:${classification}` as const;
+const initialWorkBoardStages: readonly WorkBoardStage[] = [
+  "definition",
+  "planning",
+  "ready",
+  "executing",
+  "verifying",
+  "completed",
+  "blocked",
+  "cancelled",
+  "failed",
+];
+const traceTaskSearchStages: readonly WorkBoardStage[] = [
+  "completed",
+  "executing",
+  "ready",
+  "blocked",
+  "verifying",
+  "failed",
+  "cancelled",
+  "planning",
+  "definition",
+];
 
-function savedLocale(): CostLocale {
-  return window.localStorage.getItem(localeKey) === "en-US" ? "en-US" : "pt-BR";
-}
-
-function initialDashboardView(pathname: string): DashboardView | null {
-  return pathname.replace(/\/+$/, "") === legacyCostMonitorPath ? "cost-monitor" : null;
+/** Mounts the Daily Cost view without requesting the historical summary blob. */
+function dailyCostSeed(
+  currency: "BRL" | "USD",
+  filters: CostMonitorProjection["filters"],
+): CostMonitorProjection {
+  const metric = { events: 0, tokens: { input: null, cached_input: null, output: null, reasoning: null, total: null }, cost: { usd: null, brl: null }, coverage: { events: 0, tokens: 0, usd: 0, brl: 0 } };
+  const usage = { conversation: metric, planning: metric, execution: metric, total: metric, new_work: metric, rework: metric };
+  return { schema_version: 2, layout_version: 2, readonly: true, source: ".agents/records", aggregate_only: true, data_source: "run_records", legacy_effort_baseline: null, currency, pricing: { catalog_updated_at: null, fx_rate: null, conversion_applied: false }, filters, overview: { task_count: 0, run_count: 0, event_count: 0, total_tokens: null, estimated_usd: null, estimated_brl: null, recorded_usd: null, recorded_brl: null, average_run_cost_usd: null, average_run_cost_brl: null, average_run_duration_ms: null, known_tokens_per_cycle: null, top_10_token_share: null, coverage: { events: 0, tokens: 0, usd: 0, brl: 0 } }, filters_available: { providers: [], agents: [], models: [], statuses: [], priorities: [], risks: [], phases: [], origins: [], work_types: [] }, configured_agents: [], usage, origins: { conversation: usage, task: usage, spec: usage, prd: usage }, prds: [], specs: [], runs: [], groups: { conversations: [], tasks: [], providers: [], agents: [], models: [], daily: [], monthly: [], annual: [] } };
 }
 
+export {
+  isAbortError,
+  isCurrentDashboardRequest,
+  isCurrentOperationsPageRequest,
+  isCurrentOperationsPeriodRequest,
+  isCurrentPeriodTransition,
+  mergeBoardPages,
+  needsAtomicCostSnapshot,
+  PeriodTransitionOverlay,
+  PeriodTransitionShell,
+} from "./AppRequestGuards.js";
 export function App() {
-  const token = useMemo(() => {
-    const url = new URL(window.location.href);
-    const suppliedToken = url.searchParams.get("token");
-    const sessionToken =
-      suppliedToken ??
-      window.localStorage.getItem(sessionTokenKey) ??
-      window.sessionStorage.getItem(sessionTokenKey) ??
-      "";
-    if (sessionToken) {
-      window.localStorage.setItem(sessionTokenKey, sessionToken);
-      window.sessionStorage.setItem(sessionTokenKey, sessionToken);
-    }
-    if (url.searchParams.has("token")) {
-      url.searchParams.delete("token");
-      window.history.replaceState(null, "", `${url.pathname}${url.search}${url.hash}`);
-    }
-    return sessionToken;
-  }, []);
+  const [snapshotUpdating, setSnapshotUpdating] = useState(false);
+  const [snapshotNoticeDismissed, setSnapshotNoticeDismissed] = useState(false);
+  const [snapshotNoticeDelayElapsed, setSnapshotNoticeDelayElapsed] = useState(false);
+  const token = useMemo(readDashboardSessionToken, []);
   const api = useMemo(() => new DashboardApiClient(token), [token]);
+  const { loadCostDetail, loadCostReadModelPage, loadCostRunPage, loadCostGroupPage } = useAppCostLoaders(api);
   const [dashboardView, setDashboardView] = useState<DashboardView | null>(() =>
     initialDashboardView(window.location.pathname),
   );
+  const dashboardViewRef = useRef(dashboardView);
+  dashboardViewRef.current = dashboardView;
   const [operations, setOperations] = useState<OperationsProjection | null>(null);
+  const [entityPage, setEntityPage] = useState<{
+    offset: number;
+    total: number | null;
+    loading: boolean;
+    error: string | null;
+    aggregation?: "canonical_entity" | "page_partial" | undefined;
+  }>({ offset: 0, total: null, loading: false, error: null });
+  const [entityPageKind, setEntityPageKind] = useState<
+    OperationsEntityPageKind | OperationsLifecyclePageKind
+  >("runs");
+  const entityFiltersRef = useRef<OperationsPageFilters>({ query: "", status: "", risk: "" });
+  const [boardTotals, setBoardTotals] = useState<Partial<Record<WorkBoardStage, number>>>({});
+  const [boardKindTotals, setBoardKindTotals] = useState<
+    Partial<Record<WorkBoardStage, OperationsBoardPage["totals_by_kind"]>>
+  >({});
+  const [boardStates, setBoardStates] = useState<Partial<Record<WorkBoardStage, BoardStageState>>>(
+    {},
+  );
+  const [overviewStatusPages, setOverviewStatusPages] = useState<OverviewStatusPages>({});
+  const [overviewClassificationPages, setOverviewClassificationPages] = useState<OverviewClassificationPages>({});
   const [costs, setCosts] = useState<CostMonitorProjection | null>(null);
   const [displayedCosts, setDisplayedCosts] = useState<CostMonitorProjection | null>(null);
-  const [trace, setTrace] = useState<TaskTrace | null>(null);
-  const [documentDetail, setDocumentDetail] = useState<
-    | { label: "PRD"; detail: PrdDetailProjection }
-    | { label: "SPEC"; detail: SpecDetailProjection }
-    | null
-  >(null);
-  const [traceLink, setTraceLink] = useState<
-    | { kind: "change"; row: ChangeProjection }
-    | { kind: "macro"; label: "PRD" | "SPEC"; row: MacroProjection }
-    | null
-  >(null);
-  const [traceLoadingTaskId, setTraceLoadingTaskId] = useState<string | null>(null);
-  const [selectedTraceTaskId, setSelectedTraceTaskId] = useState("");
   const [costLocale, setCostLocale] = useState<CostLocale>(savedLocale);
   const [currency, setCurrency] = useState<CostCurrency>(() =>
     window.localStorage.getItem(currencyKey) === "USD" ? "USD" : "BRL",
   );
+  // Language is the global selector's source of truth for the paired display
+  // currency, so Operations and Cost Monitor cannot diverge.
+  const changeDashboardLocale = useCallback((next: CostLocale) => {
+    setCostLocale(next);
+    setCurrency(next === "en-US" ? "USD" : "BRL");
+  }, []);
   const [operationsPeriod, setOperationsPeriod] = useState(() => defaultOperationsPeriod);
+  const operationsPeriodRef = useRef(operationsPeriod);
+  operationsPeriodRef.current = operationsPeriod;
   const [helpOpen, setHelpOpen] = useState(false);
   const [pricing, setPricing] = useState<PricingCatalog | null>(null);
   const [fxRate, setFxRate] = useState<FxRate | null>(null);
   const [pathname, setPathname] = useState(window.location.pathname);
   const [operationsLoading, setOperationsLoading] = useState(true);
+  const [operationsSurfaceLoading, setOperationsSurfaceLoading] = useState(false);
+  const [costSurfaceLoading, setCostSurfaceLoading] = useState(false);
+  const [periodTransitionPending, setPeriodTransitionPending] = useState(false);
   const [loadingArea, setLoadingArea] = useState<LoadingArea | null>("operations");
   const [failedArea, setFailedArea] = useState<LoadingArea | null>(null);
   const [refreshDialog, setRefreshDialog] = useState<
     "choose" | "refreshing" | "reconciling" | null
   >(null);
+  useEffect(() => {
+    void api.ready().then((ready) => setSnapshotUpdating(ready.snapshot_state === "updating")).catch(() => {});
+  }, [api]);
   const [error, setError] = useState<string | null>(null);
   const [reconciliationResult, setReconciliationResult] = useState<ReconciliationResult | null>(
     null,
@@ -124,22 +182,88 @@ export function App() {
     title: "Dashboard Zaip AIOS",
     repositoryName: "",
   });
+  const {
+    closeDocument,
+    documentDetail,
+    openDocument,
+    openTrace,
+    openTraceChange,
+    openTraceMacro,
+    selectedTraceTaskId,
+    setSelectedTraceTaskId,
+    setTrace,
+    setTraceLink,
+    setTraceLoadingTaskId,
+    setTraceTasks,
+    trace,
+    traceLink,
+    traceLoadingTaskId,
+    traceTasks,
+  } = useAppTraceDocuments({ api, operations, setError, setFailedArea, setLoadingArea });
   const refreshVersion = useRef(0);
+  const periodTransitionVersionRef = useRef(0);
   const detailLoadInFlight = useRef(false);
-  const costLoadInFlight = useRef(false);
   const costLoadingCount = useRef(0);
+  const costSummaryRequestVersion = useRef(0);
+  const costSummaryAbortRef = useRef<AbortController | null>(null);
   const costsLoadedRef = useRef(false);
   const operationsDetailLoadedRef = useRef(false);
-  const costPrefetch = useRef<{ key: string; promise: ReturnType<typeof api.snapshot> } | null>(
-    null,
-  );
-  const costPeriod = requestPeriodForOperations(operationsPeriod);
-  const costSnapshotKey = `${currency}:${costPeriod.from ?? ""}:${costPeriod.to ?? ""}`;
-
+  const operationsDetailCancelRef = useRef<(() => void) | null>(null);
+  const operationsDetailAbortRef = useRef<AbortController | null>(null);
+  const operationsPageAbortRef = useRef<AbortController | null>(null);
+  const operationsPageRequestVersionRef = useRef(0);
+  const boardLoadedRef = useRef<Partial<Record<WorkBoardStage, number>>>({});
+  const boardInFlightRef = useRef(new Set<WorkBoardStage>());
+  const overviewStatusInFlightRef = useRef(new Set<string>());
+  const boardInitialPageRef = useRef(new Set<WorkBoardStage>());
+  const boardFiltersRef = useRef<OperationsPageFilters>({
+    query: "",
+    status: "",
+    risk: "",
+    origin: "",
+    kind: "",
+  });
+  const workListFiltersRef = useRef<OperationsPageFilters>({
+    query: "",
+    status: "",
+    risk: "",
+  });
+  const boardFilterKeyRef = useRef("||||");
+  const boardRequestVersionRef = useRef(0);
+  const quickOverviewMetricsRef =
+    useRef<OperationsProjection["summary"]["overview_metrics"]>(undefined);
+  // A new local SQLite generation is immutable and verified by the launcher.
+  // Its server begins warming the compact first fold as soon as readiness is
+  // observed, so the first paint must join that bounded cache instead of
+  // forcing a second full aggregate calculation.
+  const initialAggregateFreshRef = useRef(false);
   const refresh = useCallback(
     async (visible = true, reconcileOpenWork = false) => {
+      operationsDetailCancelRef.current?.();
+      operationsDetailCancelRef.current = null;
+      operationsDetailAbortRef.current?.abort();
+      operationsDetailAbortRef.current = null;
+      boardRequestVersionRef.current += 1;
+      boardInFlightRef.current.clear();
+      boardInitialPageRef.current.clear();
+      boardLoadedRef.current = {};
+      setBoardTotals({});
+      setBoardKindTotals({});
+      setBoardStates({});
+      setOverviewStatusPages({});
+      setOverviewClassificationPages({});
       const requestVersion = ++refreshVersion.current;
-      const isCurrentRequest = () => requestVersion === refreshVersion.current;
+      const transitionVersion = periodTransitionVersionRef.current;
+      const activeDashboardView = dashboardViewRef.current;
+      const period = requestPeriodForOperations(operationsPeriod);
+      const isCurrentRequest = () =>
+        isCurrentDashboardRequest(requestVersion, refreshVersion.current) &&
+        isCurrentOperationsPeriodRequest(
+          requestVersion,
+          refreshVersion.current,
+          period,
+          requestPeriodForOperations(operationsPeriodRef.current),
+        );
       if (visible) {
         setOperationsLoading(true);
         setLoadingArea("operations");
@@ -147,12 +271,12 @@ export function App() {
       setError(null);
       setFailedArea(null);
       try {
-        const period = requestPeriodForOperations(operationsPeriod);
         if (reconcileOpenWork) {
           const snapshot = await api.reconcileOpenWork(currency, period);
           if (!isCurrentRequest()) return;
           setReconciliationResult(snapshot.reconciliation);
           setOperations(snapshot.operations);
+          quickOverviewMetricsRef.current = snapshot.operations.summary.overview_metrics;
           operationsDetailLoadedRef.current = true;
           setCosts(snapshot.costs);
           costsLoadedRef.current = true;
@@ -165,33 +289,41 @@ export function App() {
           }
           setLastUpdatedAt(snapshot.projection.source_latest_at);
         } else {
-          // The overview endpoint carries server-side aggregates for KPI
-          // parity while omitting expensive Run detail until a capability is selected.
-          const requestingDetails = operationsDetailLoadedRef.current;
-          if (costsLoadedRef.current) {
-            const snapshot = await loadAtomicCostSnapshot(() => api.snapshot(currency, period));
-            if (!isCurrentRequest()) return;
-            setOperations(snapshot.operations);
-            operationsDetailLoadedRef.current = true;
-            setCosts(snapshot.costs);
-            costsLoadedRef.current = true;
-            setDisplayedCosts(null);
-            setLastUpdatedAt(snapshot.projection.source_latest_at);
-          } else {
-            const projection = requestingDetails
-              ? await api.operations(period)
-              : await api.operations(period, true);
+          {
+            // First paint is aggregate-only; board and detail data are loaded
+            // on their own bounded routes rather than hydrating entity arrays.
+            const [projection, costSummary] = await Promise.all([
+              api.operations(period, "quick", undefined, initialAggregateFreshRef.current),
+              // An English first paint must have the factual USD summary
+              // before Operations formats currency. BRL retains the fast
+              // Operations-only path until the user opens Cost Monitor.
+              currency === "USD" ? api.costMonitor(currency, period, "summary") : Promise.resolve(null),
+            ]);
             if (!isCurrentRequest()) return;
+            initialAggregateFreshRef.current = false;
             setOperations(projection);
-            operationsDetailLoadedRef.current = requestingDetails;
+            quickOverviewMetricsRef.current = projection.summary.overview_metrics;
+            operationsDetailLoadedRef.current = false;
+            if (costSummary !== null) {
+              setCosts(costSummary);
+              // This is only a first-fold placeholder.  It must not suppress
+              // the factual, narrow Cost summary when the user opens Cost.
+              costsLoadedRef.current = false;
+              setDisplayedCosts(null);
+            }
             setLastUpdatedAt(projection.summary.source_latest_at);
           }
         }
       } catch (cause) {
         if (!isCurrentRequest()) return;
         setError(cause instanceof Error ? cause.message : String(cause));
-        setFailedArea("operations");
+        setFailedArea(activeDashboardView === "cost-monitor" ? "costs" : "operations");
       } finally {
+        if (
+          isCurrentRequest() &&
+          isCurrentPeriodTransition(transitionVersion, periodTransitionVersionRef.current)
+        )
+          setPeriodTransitionPending(false);
         if (visible && isCurrentRequest()) {
           setOperationsLoading(false);
           setLoadingArea((current) => (current === "operations" ? null : current));
@@ -200,81 +332,382 @@ export function App() {
     },
     [api, currency, operationsPeriod],
   );
-
-  const loadOperationsDetails = useCallback(async (): Promise<OperationsProjection | null> => {
-    if (operationsDetailLoadedRef.current) return operations;
-    if (detailLoadInFlight.current) return null;
-    detailLoadInFlight.current = true;
-    costLoadingCount.current += 1;
-    setLoadingArea("costs");
-    setFailedArea(null);
-    try {
+  const loadOperationsDetails = useCallback(
+    async (signal?: AbortSignal): Promise<OperationsProjection | null> => {
+      if (operationsDetailLoadedRef.current) return null;
+      if (detailLoadInFlight.current) return null;
+      if (signal?.aborted) return null;
+      operationsDetailAbortRef.current?.abort();
+      const controller = signal === undefined ? new AbortController() : null;
+      const requestSignal = signal ?? controller?.signal;
+      if (requestSignal === undefined) return null;
+      if (controller !== null) operationsDetailAbortRef.current = controller;
+      detailLoadInFlight.current = true;
+      costLoadingCount.current += 1;
+      setLoadingArea("costs");
+      setFailedArea(null);
+      try {
+        const requestVersion = ++refreshVersion.current;
+        const period = requestPeriodForOperations(operationsPeriod);
+        const isCurrentRequest = () =>
+          isCurrentDashboardRequest(requestVersion, refreshVersion.current) &&
+          isCurrentOperationsPeriodRequest(
+            requestVersion,
+            refreshVersion.current,
+            period,
+            requestPeriodForOperations(operationsPeriodRef.current),
+          );
+        const projection = await api.operations(period, "detail", requestSignal);
+        if (!isCurrentRequest()) return null;
+        setOperations(projection);
+        operationsDetailLoadedRef.current = true;
+        return projection;
+      } catch (cause) {
+        if (requestSignal.aborted || isAbortError(cause)) return null;
+        setError(cause instanceof Error ? cause.message : String(cause));
+        setFailedArea("operations");
+        return null;
+      } finally {
+        if (controller !== null && operationsDetailAbortRef.current === controller) {
+          operationsDetailAbortRef.current = null;
+        }
+        detailLoadInFlight.current = false;
+        costLoadingCount.current = Math.max(0, costLoadingCount.current - 1);
+        if (costLoadingCount.current === 0) {
+          setLoadingArea((current) => (current === "costs" ? null : current));
+        }
+      }
+    },
+    [api, operationsPeriod],
+  );
+  const { loadOperationsEntityPage, loadOperationsLifecyclePage } = useAppOperationsPages({
+    api,
+    entityFiltersRef,
+    operationsPageAbortRef,
+    operationsPageRequestVersionRef,
+    operationsPeriod,
+    operationsPeriodRef,
+    refreshVersion,
+    setEntityPage,
+    setEntityPageKind,
+    setOperations,
+  });
+  const loadFilteredOperationsPage = useCallback(
+    (
+      view: "runs" | "conversations" | "executions" | "changes" | "decisions",
+      filters: OperationsPageFilters,
+    ) => {
+      entityFiltersRef.current = filters;
+      if (view === "changes" || view === "decisions")
+        void loadOperationsLifecyclePage(view, 0, filters);
+      else void loadOperationsEntityPage(view, 0, filters);
+    },
+    [loadOperationsEntityPage, loadOperationsLifecyclePage],
+  );
+  const loadMoreBoard = useCallback(
+    async (stage: WorkBoardStage) => {
+      const current = operations;
+      if (current === null || boardInFlightRef.current.has(stage)) return;
+      boardInFlightRef.current.add(stage);
+      const requestVersion = boardRequestVersionRef.current;
       const period = requestPeriodForOperations(operationsPeriod);
-      const projection = await api.operations(period);
-      setOperations(projection);
-      operationsDetailLoadedRef.current = true;
-      return projection;
-    } catch (cause) {
-      setError(cause instanceof Error ? cause.message : String(cause));
-      setFailedArea("operations");
-      return null;
-    } finally {
-      detailLoadInFlight.current = false;
-      costLoadingCount.current = Math.max(0, costLoadingCount.current - 1);
-      if (costLoadingCount.current === 0) {
-        setLoadingArea((current) => (current === "costs" ? null : current));
+      setBoardStates((previous) => ({ ...previous, [stage]: { loading: true, error: null } }));
+      const loaded = boardLoadedRef.current[stage] ?? 0;
+      try {
+        const page = await api.operationsBoard(period, stage, loaded, boardFiltersRef.current);
+        if (
+          requestVersion !== boardRequestVersionRef.current ||
+          period.from !== requestPeriodForOperations(operationsPeriodRef.current).from ||
+          period.to !== requestPeriodForOperations(operationsPeriodRef.current).to
+        )
+          return;
+        setOperations((previous) =>
+          previous === null
+            ? previous
+            : {
+                ...mergeBoardPages(previous, [page]),
+                // Board pages are entity data only. The quick aggregate keeps charts coherent.
+                summary: previous.summary,
+              },
+        );
+        setBoardTotals((previous) => ({ ...previous, [stage]: page.total }));
+        setBoardKindTotals((previous) => ({ ...previous, [stage]: page.totals_by_kind }));
+        const next = loaded + page.prds.length + page.specs.length + page.tasks.length;
+        boardLoadedRef.current = { ...boardLoadedRef.current, [stage]: next };
+      } catch (cause) {
+        if (requestVersion !== boardRequestVersionRef.current || isAbortError(cause)) return;
+        setBoardStates((previous) => ({
+          ...previous,
+          [stage]: {
+            loading: false,
+            error: cause instanceof Error ? cause.message : String(cause),
+          },
+        }));
+      } finally {
+        if (requestVersion === boardRequestVersionRef.current) {
+          boardInFlightRef.current.delete(stage);
+          setBoardStates((previous) =>
+            previous[stage]?.error === null
+              ? { ...previous, [stage]: { loading: false, error: null } }
+              : previous,
+          );
+        }
       }
-    }
-  }, [api, operations, operationsPeriod]);
-
-  const loadCosts = useCallback(async () => {
-    if (costsLoadedRef.current) return;
-    if (costLoadInFlight.current) return;
-    costLoadInFlight.current = true;
-    costLoadingCount.current += 1;
-    setLoadingArea("costs");
-    setFailedArea(null);
-    try {
+    },
+    [api, operations, operationsPeriod],
+  );
+  const loadFilteredBoard = useCallback((filters: OperationsPageFilters) => {
+    const normalizedFilters = {
+      ...filters,
+      kind: filters.kind ?? boardFiltersRef.current.kind ?? "",
+    };
+    const filterKey = `${normalizedFilters.query}|${normalizedFilters.status}|${normalizedFilters.risk}|${normalizedFilters.origin ?? ""}|${normalizedFilters.kind}`;
+    if (filterKey === boardFilterKeyRef.current) return;
+    boardFilterKeyRef.current = filterKey;
+    boardFiltersRef.current = normalizedFilters;
+    boardRequestVersionRef.current += 1;
+    boardInFlightRef.current.clear();
+    boardInitialPageRef.current.clear();
+    boardLoadedRef.current = {};
+    setBoardTotals({});
+    setBoardKindTotals({});
+    setBoardStates({});
+    setOverviewStatusPages({});
+    setOverviewClassificationPages({});
+    setOperations((current) =>
+      current === null
+        ? current
+        : {
+            ...current,
+            prds: [],
+            specs: [],
+            tasks: [],
+            changes: [],
+            summary:
+              filterKey === "||||" && quickOverviewMetricsRef.current !== undefined
+                ? { ...current.summary, overview_metrics: quickOverviewMetricsRef.current }
+                : current.summary,
+          },
+    );
+  }, []);
+  const loadFilteredWorkList = useCallback(
+    async (filters: OperationsPageFilters) => {
+      const requestVersion = ++boardRequestVersionRef.current;
       const period = requestPeriodForOperations(operationsPeriod);
-      const prefetched = costPrefetch.current;
-      await loadCostViewSnapshot(
-        () =>
-          prefetched?.key === costSnapshotKey ? prefetched.promise : api.snapshot(currency, period),
-        (snapshot) => {
-          setOperations(snapshot.operations);
-          operationsDetailLoadedRef.current = true;
-          setCosts(snapshot.costs);
-          setDisplayedCosts(null);
-          setLastUpdatedAt(snapshot.projection.source_latest_at);
+      const normalizedFilters = normalizeWorkListFilters(filters, workListFiltersRef.current);
+      workListFiltersRef.current = normalizedFilters;
+      const requestedKind = selectedWorkListKinds(normalizedFilters.kind);
+      const loadKindStage = async (stage: WorkBoardStage, kind: "prd" | "spec" | "task") => {
+        return collectWorkListPages(async (offset) => {
+          const page = await api.operationsBoard(
+            period,
+            stage,
+            offset,
+            { ...normalizedFilters, kind },
+            undefined,
+            50,
+          );
+          return {
+            total: page.total,
+            received: page.prds.length + page.specs.length + page.tasks.length,
+            value: page,
+          };
+        });
+      };
+      try {
+        const pages = (
+          await Promise.all(
+            initialWorkBoardStages.flatMap((stage) =>
+              requestedKind.map((kind) => loadKindStage(stage, kind)),
+            ),
+          )
+        ).flat();
+        if (
+          requestVersion !== boardRequestVersionRef.current ||
+          period.from !== requestPeriodForOperations(operationsPeriodRef.current).from ||
+          period.to !== requestPeriodForOperations(operationsPeriodRef.current).to
+        )
+          return;
+        const unique = <T extends { id: string }>(rows: readonly T[]) =>
+          [...new Map(rows.map((row) => [row.id, row] as const)).values()];
+        setOperations((current) =>
+          current === null
+            ? current
+            : {
+                ...current,
+                prds: unique(pages.flatMap((page) => page.prds)),
+                specs: unique(pages.flatMap((page) => page.specs)),
+                tasks: unique(pages.flatMap((page) => page.tasks)),
+              },
+        );
+      } catch (cause) {
+        if (requestVersion !== boardRequestVersionRef.current || isAbortError(cause)) return;
+        setError(cause instanceof Error ? cause.message : String(cause));
+        setFailedArea("operations");
+      }
+    },
+    [api, operationsPeriod],
+  );
+  const loadOverviewStatusPage = useCallback(
+    async (stage: WorkBoardStage, kind: OverviewStatusKind, offset: number) => {
+      const key = overviewStatusPageKey(stage, kind);
+      if (overviewStatusInFlightRef.current.has(key)) return;
+      overviewStatusInFlightRef.current.add(key);
+      const requestVersion = boardRequestVersionRef.current;
+      const period = requestPeriodForOperations(operationsPeriod);
+      setOverviewStatusPages((previous) => ({
+        ...previous,
+        [key]: {
+          items: offset === 0 ? [] : (previous[key]?.items ?? []),
+          total: previous[key]?.total ?? 0,
+          loading: true,
+          error: null,
         },
-      );
-      costsLoadedRef.current = true;
-      costPrefetch.current = null;
-    } catch (cause) {
-      setError(cause instanceof Error ? cause.message : String(cause));
-      setFailedArea("costs");
-    } finally {
-      costLoadInFlight.current = false;
-      costLoadingCount.current = Math.max(0, costLoadingCount.current - 1);
-      if (costLoadingCount.current === 0) {
-        setLoadingArea((current) => (current === "costs" ? null : current));
+      }));
+      try {
+        const page = await api.operationsBoard(period, stage, offset, { kind });
+        if (
+          requestVersion !== boardRequestVersionRef.current ||
+          period.from !== requestPeriodForOperations(operationsPeriodRef.current).from ||
+          period.to !== requestPeriodForOperations(operationsPeriodRef.current).to
+        )
+          return;
+        const items = kind === "task" ? page.tasks : kind === "spec" ? page.specs : page.prds;
+        setOverviewStatusPages((previous) => ({
+          ...previous,
+          [key]: {
+            items: offset === 0 ? items : [...(previous[key]?.items ?? []), ...items],
+            total: page.total,
+            loading: false,
+            error: null,
+          },
+        }));
+      } catch (cause) {
+        if (requestVersion !== boardRequestVersionRef.current || isAbortError(cause)) return;
+        setOverviewStatusPages((previous) => ({
+          ...previous,
+          [key]: {
+            items: previous[key]?.items ?? [],
+            total: previous[key]?.total ?? 0,
+            loading: false,
+            error: cause instanceof Error ? cause.message : String(cause),
+          },
+        }));
+      } finally {
+        overviewStatusInFlightRef.current.delete(key);
       }
-    }
-  }, [api, costSnapshotKey, currency, operationsPeriod]);
-
+    },
+    [api, operationsPeriod],
+  );
+  const loadOverviewClassificationPage = useCallback(
+    async (kind: OverviewStatusKind, classification: OverviewClassification, offset: number) => {
+      const key = overviewClassificationPageKey(kind, classification);
+      if (overviewStatusInFlightRef.current.has(key)) return;
+      overviewStatusInFlightRef.current.add(key);
+      const requestVersion = boardRequestVersionRef.current;
+      const period = requestPeriodForOperations(operationsPeriod);
+      setOverviewClassificationPages((previous) => ({
+        ...previous,
+        [key]: {
+          items: offset === 0 ? [] : (previous[key]?.items ?? []),
+          total: previous[key]?.total ?? 0,
+          loading: true,
+          error: null,
+        },
+      }));
+      try {
+        const page = await api.operationsClassification(period, kind, classification, offset);
+        if (
+          requestVersion !== boardRequestVersionRef.current ||
+          period.from !== requestPeriodForOperations(operationsPeriodRef.current).from ||
+          period.to !== requestPeriodForOperations(operationsPeriodRef.current).to
+        ) return;
+        const items = kind === "task" ? page.tasks : kind === "spec" ? page.specs : page.prds;
+        setOverviewClassificationPages((previous) => ({
+          ...previous,
+          [key]: {
+            items: offset === 0 ? items : [...(previous[key]?.items ?? []), ...items],
+            total: page.total,
+            loading: false,
+            error: null,
+          },
+        }));
+      } catch (cause) {
+        if (requestVersion !== boardRequestVersionRef.current || isAbortError(cause)) return;
+        setOverviewClassificationPages((previous) => ({
+          ...previous,
+          [key]: {
+            items: previous[key]?.items ?? [], total: previous[key]?.total ?? 0,
+            loading: false, error: cause instanceof Error ? cause.message : String(cause),
+          },
+        }));
+      } finally {
+        overviewStatusInFlightRef.current.delete(key);
+      }
+    },
+    [api, operationsPeriod],
+  );
+  const boardExportSource = useCallback(
+    (selectedFilters: { query: string; status: string; risk: string; origin: string }) => {
+      const filters = { ...boardFiltersRef.current, ...selectedFilters };
+      const period = requestPeriodForOperations(operationsPeriod);
+      return {
+        prepare: async () => {
+          const firstPages = await Promise.all(
+            initialWorkBoardStages.map((stage) => api.operationsBoard(period, stage, 0, filters)),
+          );
+          const rowsFor = (page: OperationsBoardPage) => [
+            ...page.prds.map(({ kind: _kind, ...row }) => ({ kind: "prd", ...row })),
+            ...page.specs.map(({ kind: _kind, ...row }) => ({ kind: "spec", ...row })),
+            ...page.tasks.map((row) => ({ kind: "task", ...row })),
+          ];
+          return {
+            totalRows: firstPages.reduce((sum, page) => sum + page.total, 0),
+            pages: async function* () {
+              for (const firstPage of firstPages) {
+                let page = firstPage;
+                let offset = 0;
+                while (true) {
+                  const rows = rowsFor(page);
+                  if (rows.length === 0) break;
+                  offset += rows.length;
+                  yield rows;
+                  if (offset >= page.total) break;
+                  page = await api.operationsBoard(period, page.stage, offset, filters);
+                }
+              }
+            },
+          };
+        },
+      };
+    },
+    [api, operationsPeriod],
+  );
   useEffect(() => {
-    if (
-      operations === null ||
-      costsLoadedRef.current ||
-      costPrefetch.current?.key === costSnapshotKey
-    )
-      return;
-    const promise = api.snapshot(currency, requestPeriodForOperations(operationsPeriod));
-    costPrefetch.current = { key: costSnapshotKey, promise };
-    void promise.catch(() => {
-      if (costPrefetch.current?.promise === promise) costPrefetch.current = null;
-    });
-  }, [api, costSnapshotKey, currency, operations, operationsPeriod]);
+    if (dashboardView !== "operations" || operations === null) return;
+    let cancelled = false;
+    const hydrateBoard = () => {
+      if (cancelled) return;
+      for (const stage of initialWorkBoardStages) {
+        if (!boardInitialPageRef.current.has(stage) && !boardInFlightRef.current.has(stage)) {
+          boardInitialPageRef.current.add(stage);
+          void loadMoreBoard(stage);
+        }
+      }
+    };
+    // The quick projection is the complete first-fold contract. Defer the
+    // bounded Kanban cards until after that first paint so they cannot hold up
+    // the useful overview when SQLite must materialise the board view.
+    const idle =
+      typeof window.requestIdleCallback === "function"
+        ? { kind: "idle" as const, id: window.requestIdleCallback(hydrateBoard) }
+        : { kind: "timeout" as const, id: window.setTimeout(hydrateBoard, 0) };
+    return () => {
+      cancelled = true;
+      if (idle.kind === "idle") window.cancelIdleCallback(idle.id);
+      else window.clearTimeout(idle.id);
+    };
+  }, [dashboardView, loadMoreBoard, operations]);
 
   const refreshFromDialog = async (reconcileOpenWork: boolean) => {
     if (reconcileOpenWork) setReconciliationResult(null);
@@ -282,47 +715,25 @@ export function App() {
     await refresh(false, reconcileOpenWork);
     setRefreshDialog(null);
   };
-
-  useEffect(() => {
-    void refresh();
-    const timer = window.setInterval(() => void refresh(false), 30_000);
-    return () => window.clearInterval(timer);
-  }, [refresh]);
-
-  useEffect(() => {
-    window.localStorage.setItem(localeKey, costLocale);
-  }, [costLocale]);
-
-  useEffect(() => {
-    window.localStorage.setItem(currencyKey, currency);
-  }, [currency]);
-
-  useEffect(() => {
-    if (
-      !["/", pricingSetupPath, agentCatalogSetupPath, projectSetupPath].includes(
-        window.location.pathname,
-      )
-    ) {
-      window.history.replaceState(null, "", `/${window.location.search}${window.location.hash}`);
-      setPathname("/");
-    }
-  }, []);
-
-  useEffect(() => {
-    const syncPathname = () => setPathname(window.location.pathname);
-    window.addEventListener("popstate", syncPathname);
-    return () => window.removeEventListener("popstate", syncPathname);
-  }, []);
-
-  useEffect(() => {
-    if (pathname !== pricingSetupPath || pricing !== null) return;
-    void Promise.all([api.pricing(), api.fxRate()])
-      .then(([catalog, rate]) => {
-        setPricing(catalog);
-        setFxRate(rate);
-      })
-      .catch((cause) => setError(String(cause)));
-  }, [api, pathname, pricing]);
+  useAppEffects({
+    api,
+    costLocale,
+    currency,
+    dashboardView,
+    loadOperationsDetails,
+    operations,
+    operationsDetailAbortRef,
+    operationsDetailCancelRef,
+    operationsPageAbortRef,
+    pathname,
+    pricing,
+    refresh,
+    refreshVersion,
+    setError,
+    setFxRate,
+    setPathname,
+    setPricing,
+  });
 
   const navigate = (nextPath: string) => {
     window.history.pushState(null, "", nextPath);
@@ -330,79 +741,68 @@ export function App() {
     window.scrollTo({ left: 0, top: 0 });
   };
 
-  async function openTrace(taskId: string) {
-    setError(null);
+  const loadCostSummary = useCallback(async () => {
+    costSummaryAbortRef.current?.abort();
+    const controller = new AbortController();
+    costSummaryAbortRef.current = controller;
+    const requestVersion = ++costSummaryRequestVersion.current;
+    const period = requestPeriodForOperations(operationsPeriod);
+    costLoadingCount.current += 1;
+    setLoadingArea("costs");
     setFailedArea(null);
-    setTrace(null);
-    setTraceLoadingTaskId(taskId);
-    setLoadingArea("traceability");
-    await new Promise<void>((resolveFrame) => window.requestAnimationFrame(() => resolveFrame()));
     try {
-      const loadedTrace = await api.taskTrace(taskId);
-      const cardTask = operations?.tasks.find((task) => task.id === taskId);
-      setTrace({
-        ...loadedTrace,
-        task_title: cardTask?.title || loadedTrace.task_title || taskId,
-        task_risk: cardTask?.risk || loadedTrace.task_risk || null,
-        task_created_at: cardTask?.created_at || loadedTrace.task_created_at || null,
-        task_progress: cardTask?.progress ?? loadedTrace.task_progress ?? 0,
-      });
-      return true;
+      const summary = await api.costMonitor(currency, period, "summary", controller.signal);
+      if (controller.signal.aborted || requestVersion !== costSummaryRequestVersion.current) return;
+      setCosts(summary);
+      costsLoadedRef.current = true;
+      setDisplayedCosts(null);
     } catch (cause) {
+      if (controller.signal.aborted || requestVersion !== costSummaryRequestVersion.current) return;
       setError(cause instanceof Error ? cause.message : String(cause));
-      setFailedArea("traceability");
-      return false;
+      setFailedArea("costs");
     } finally {
-      setTraceLoadingTaskId((current) => (current === taskId ? null : current));
-      setLoadingArea((current) => (current === "traceability" ? null : current));
+      costLoadingCount.current = Math.max(0, costLoadingCount.current - 1);
+      if (costLoadingCount.current === 0)
+        setLoadingArea((current) => (current === "costs" ? null : current));
+      if (costSummaryAbortRef.current === controller) costSummaryAbortRef.current = null;
     }
-  }
+  }, [api, currency, operationsPeriod]);
 
-  function openTraceChange(changeId: string) {
-    const row = operations?.changes.find((change) => change.id === changeId);
-    if (row === undefined) return;
-    setTrace(null);
-    setTraceLink({ kind: "change", row });
-  }
-
-  function openTraceMacro(label: "PRD" | "SPEC", id: string) {
-    const rows = label === "PRD" ? operations?.prds : operations?.specs;
-    const row = rows?.find((macro) => macro.id === id);
-    if (row === undefined) return;
-    setTrace(null);
-    setTraceLink({ kind: "macro", label, row });
-  }
-
-  async function openDocument(kind: "prd" | "spec", id: string) {
-    setError(null);
-    try {
-      if (kind === "prd") {
-        setDocumentDetail({ label: "PRD", detail: await api.prd(id) });
-      } else {
-        setDocumentDetail({ label: "SPEC", detail: await api.spec(id) });
-      }
-    } catch (cause) {
-      setError(cause instanceof Error ? cause.message : String(cause));
-    }
-  }
+  // The global language selector can request USD while Operations is active.
+  // Acquire its coherent Cost Monitor snapshot here instead of requiring a
+  // navigation to the Cost Monitor tab first.
+  useEffect(() => {
+    if (currency !== "USD" || costs?.currency === currency) return;
+    void loadCostSummary();
+  }, [costs?.currency, currency, loadCostSummary]);
 
   const selectDashboardView = async (nextView: DashboardView) => {
     setDashboardView(nextView);
     window.scrollTo({ left: 0, top: 0 });
-    const detailedOperations =
-      nextView === "operations" || nextView === "traceability"
-        ? await loadOperationsDetails()
-        : operations;
     if (nextView === "cost-monitor") {
-      void loadCosts();
+      if (costs?.currency !== currency) void loadCostSummary();
+    } else {
+      costSummaryAbortRef.current?.abort();
     }
     if (nextView === "traceability") {
-      const latest = (detailedOperations ?? operations)?.tasks
-        .filter((task) => task.status === "completed")
-        .toSorted(
-          (a, b) =>
-            Date.parse(b.finished_at ?? b.updated_at) - Date.parse(a.finished_at ?? a.updated_at),
-        )[0];
+      let candidates = traceTasks.length > 0 ? traceTasks : (operations?.tasks ?? []);
+      if (candidates.length === 0) {
+        const requestVersion = boardRequestVersionRef.current;
+        // Traceability is a global task selector, not a temporal work-board view.
+        for (const stage of traceTaskSearchStages) {
+          const page = await api.operationsBoard({ from: null, to: null }, stage, 0);
+          if (requestVersion !== boardRequestVersionRef.current) return;
+          if (page.tasks.length === 0) continue;
+          candidates = page.tasks;
+          setTraceTasks(page.tasks);
+          break;
+        }
+      }
+      const ordered = candidates.toSorted(
+        (a, b) =>
+          Date.parse(b.finished_at ?? b.updated_at) - Date.parse(a.finished_at ?? a.updated_at),
+      );
+      const latest = ordered.find((task) => task.status === "completed") ?? ordered[0];
       if (latest) {
         setSelectedTraceTaskId(latest.id);
         void openTrace(latest.id);
@@ -423,344 +823,301 @@ export function App() {
   const currentCostByRun = useMemo(
     () =>
       new Map(
-        (displayedCosts ?? costs)?.runs.map((run) => [run.run_id, run.estimated_brl] as const) ??
+        (displayedCosts ?? costs)?.runs.map(
+          (run) => [run.run_id, currency === "USD" ? run.estimated_usd : run.estimated_brl] as const,
+        ) ??
           [],
       ),
-    [costs, displayedCosts],
+    [costs, currency, displayedCosts],
   );
+  const factualCostTotal = useMemo(() => {
+    const snapshot = displayedCosts ?? costs;
+    if (snapshot?.currency !== currency) return null;
+    return currency === "USD" ? snapshot.overview.estimated_usd : snapshot.overview.estimated_brl;
+  }, [costs, currency, displayedCosts]);
+  const factualCostPeriods = useMemo(() => {
+    const snapshot = displayedCosts ?? costs;
+    if (snapshot?.currency !== currency) return undefined;
+    return {
+      day: snapshot.groups.daily,
+      month: snapshot.groups.monthly,
+      year: snapshot.groups.annual,
+    };
+  }, [costs, currency, displayedCosts]);
   const retryLastLoad = () => {
     setError(null);
-    if (failedArea === "costs") void loadCosts();
+    if (failedArea === "costs") void refresh();
     else if (failedArea === "traceability" && selectedTraceTaskId)
       void openTrace(selectedTraceTaskId);
+    else if (failedArea === "operations" && operations !== null) void loadOperationsDetails();
     else void refresh();
   };
 
-  if (pathname === pricingSetupPath) {
-    if (pricing === null) {
-      return (
-        <main className="app-state">
-          <p>{costLocale === "pt-BR" ? "Configuração do projeto" : "Project settings"}</p>
-          <h1>
-            {costLocale === "pt-BR" ? "Carregando catálogo de preços…" : "Loading pricing catalog…"}
-          </h1>
-          <button onClick={() => navigate("/")} type="button">
-            {costLocale === "pt-BR" ? "Voltar ao dashboard" : "Back to dashboard"}
-          </button>
-        </main>
-      );
+  const setupRoute = renderAppSetupRoute({
+    api,
+    costLocale,
+    fxRate,
+    navigate,
+    pathname,
+    pricing,
+    refresh,
+    setFxRate,
+    setPricing,
+  });
+  // A request is not an empty dashboard state. One accessible global gate
+  // prevents every tab from briefly presenting zero/empty placeholders while
+  // its coherent replacement snapshot or page is still in flight.
+  const globalLoadingPending =
+    periodTransitionPending ||
+    (currency === "USD" && costs?.currency !== currency) ||
+    (loadingArea !== null && loadingArea !== "costs") ||
+    costSurfaceLoading ||
+    operationsSurfaceLoading ||
+    entityPage.loading ||
+    Object.values(boardStates).some((state) => state.loading);
+  // The stale snapshot is useful only while the initial screen still waits
+  // for data.  Once Operations has arrived, the normal dashboard is the
+  // clearest confirmation that it opened; do not leave a duplicate toast.
+  const initialDataPending = operations === null && operationsLoading;
+  useEffect(() => {
+    if (!snapshotUpdating || !initialDataPending || snapshotNoticeDismissed) {
+      setSnapshotNoticeDelayElapsed(false);
+      return undefined;
     }
-    return (
-      <Suspense fallback={null}>
-        <PricingSettingsPage
-          catalog={pricing}
-          fxRate={fxRate}
-          locale={costLocale}
-          onClose={() => navigate("/")}
-          onSave={async (catalog) => {
-            setPricing(await api.savePricing(catalog));
-            await refresh();
-          }}
-          onSaveFxRate={async (rate) => {
-            setFxRate(await api.saveFxRate(rate));
-            await refresh();
-          }}
-        />
-      </Suspense>
-    );
-  }
-  if (pathname === agentCatalogSetupPath) {
-    return (
-      <Suspense fallback={null}>
-        <AgentCatalogSettingsPage api={api} locale={costLocale} onClose={() => navigate("/")} />
-      </Suspense>
-    );
-  }
-  if (pathname === projectSetupPath) {
-    return (
-      <Suspense fallback={null}>
-        <ProjectSettingsPage api={api} locale={costLocale} onClose={() => navigate("/")} />
-      </Suspense>
-    );
-  }
-  if (error && operations === null) {
-    return (
-      <main className="app-state">
-        <p>Dashboard local indisponível</p>
-        <h1>Não foi possível ler o workspace V2.</h1>
-        <pre>{error}</pre>
-        <button onClick={() => void refresh()} type="button">
-          Tentar novamente
-        </button>
-      </main>
-    );
-  }
-  if (operations === null) {
-    return <DashboardSkeleton locale={costLocale} />;
-  }
+    const timeout = window.setTimeout(() => setSnapshotNoticeDelayElapsed(true), snapshotNoticeDelayMs);
+    return () => window.clearTimeout(timeout);
+  }, [initialDataPending, snapshotNoticeDismissed, snapshotUpdating]);
+  const snapshotNoticeVisible = shouldShowSnapshotNotice({
+    snapshotUpdating,
+    initialDataPending,
+    dismissed: snapshotNoticeDismissed,
+    delayElapsed: snapshotNoticeDelayElapsed,
+  });
+  const snapshotNotice = snapshotNoticeVisible ? (
+    <div aria-live="polite" className="app-notice app-snapshot-status" role="status">
+      <span>Exibindo o último snapshot local validado. Os dados canônicos estão sendo atualizados em segundo plano e estarão atuais na próxima abertura.</span>
+      <button
+        aria-label={costLocale === "pt-BR" ? "Fechar aviso de atualização do snapshot" : "Dismiss snapshot update notice"}
+        onClick={() => setSnapshotNoticeDismissed(true)}
+        type="button"
+      >
+        ×
+      </button>
+    </div>
+  ) : null;
+  const renderedOperations = operations as OperationsProjection;
   return (
-    <>
-      {error ? (
-        <div className="app-warning" role="status">
-          <span>{error}</span>
-          {failedArea ? (
-            <button onClick={retryLastLoad} type="button">
-              {costLocale === "pt-BR" ? "Tentar novamente" : "Try again"}
-            </button>
-          ) : null}
-          <button onClick={() => setError(null)} type="button">
-            ×
-          </button>
-        </div>
-      ) : null}
-      <OperationsPage
-        alternateContent={
-          dashboardView === "cost-monitor" ? (
-            costs === null ? (
-              () =>
-                failedArea === "costs" ? (
-                  <LoadFailedPanel locale={costLocale} onRetry={retryLastLoad} />
-                ) : (
-                  <LoadingPanel area="costs" locale={costLocale} />
-                )
-            ) : (
-              (globalFilters) => (
-                <CostMonitorPage
-                  currency={currency}
-                  data={costs}
-                  embedded
-                  globalFilters={globalFilters}
-                  lastUpdatedAt={lastUpdatedAt}
-                  locale={costLocale}
-                  loading={loadingArea === "costs"}
-                  onLocaleChange={setCostLocale}
-                  onCurrencyChange={setCurrency}
-                  onActiveDataChange={setDisplayedCosts}
-                  onOpenTrace={(taskId) => void openTrace(taskId)}
-                  onRefresh={() => setRefreshDialog("choose")}
-                  operations={operations}
-                />
-              )
-            )
-          ) : dashboardView === "traceability" ? (
-            () => (
-              <TraceabilityWorkspace
-                loadingTaskId={traceLoadingTaskId}
-                locale={costLocale}
-                onSelectTask={(taskId) => {
-                  setSelectedTraceTaskId(taskId);
-                  void openTrace(taskId);
-                }}
-                onOpenChange={openTraceChange}
-                onOpenPrd={(prdId) => openTraceMacro("PRD", prdId)}
-                onOpenSpec={(specId) => openTraceMacro("SPEC", specId)}
-                selectedTaskId={selectedTraceTaskId}
-                tasks={operations.tasks}
-                trace={trace}
-              />
-            )
-          ) : dashboardView === null ? (
-            <span aria-hidden="true" hidden />
-          ) : undefined
-        }
-        capabilityNavigation={capabilityNavigation}
-        data={operations}
-        dashboardTitle={dashboardIdentity.title}
-        repositoryName={dashboardIdentity.repositoryName}
-        loading={operationsLoading}
-        locale={costLocale}
-        resolveRunCostBrl={
-          costs === null ? undefined : (runId) => currentCostByRun.get(runId) ?? null
-        }
-        onLocaleChange={setCostLocale}
-        onDetailDataRequest={() => void loadOperationsDetails()}
-        onOpenDocument={(kind, id) => void openDocument(kind, id)}
-        onOpenTask={openTrace}
-        onPeriodChange={(preset, range) => setOperationsPeriod({ preset, range })}
-        onRefresh={() => setRefreshDialog("choose")}
-        settings={
-          <div className="dashboard-global-settings">
-            <label>
-              <span>{costLocale === "pt-BR" ? "Moeda" : "Currency"}</span>
-              <select
-                aria-label={costLocale === "pt-BR" ? "Moeda" : "Currency"}
-                onChange={(event) => setCurrency(event.target.value as CostCurrency)}
-                value={currency}
-              >
-                <option value="BRL">BRL · Real brasileiro</option>
-                <option value="USD">USD · US Dollar</option>
-              </select>
-            </label>
-            <button className="dashboard-help-open" onClick={() => setHelpOpen(true)} type="button">
-              {costLocale === "pt-BR" ? "Abrir ajuda e guides" : "Open help and guides"}
-            </button>
-            <button
-              className="dashboard-help-open"
-              onClick={() => navigate(pricingSetupPath)}
-              type="button"
-            >
-              {costLocale === "pt-BR" ? "Configurar preços e câmbio" : "Configure pricing and FX"}
-            </button>
-            <button
-              className="dashboard-help-open"
-              onClick={() => navigate(agentCatalogSetupPath)}
-              type="button"
-            >
-              {costLocale === "pt-BR" ? "Configurar agentes" : "Configure agents"}
-            </button>
+    <AppLoadingBoundary
+      error={error}
+      globalLoadingPending={globalLoadingPending}
+      locale={costLocale}
+      onRefresh={() => void refresh()}
+      operations={operations}
+      snapshotNotice={snapshotNotice}
+      setupRoute={setupRoute}
+    >
+      <PeriodTransitionShell pending={globalLoadingPending}>
+        {error ? (
+          <div aria-live="assertive" className="app-warning app-error" role="alert">
+            <span>{error}</span>
+            {failedArea ? (
+              <button onClick={retryLastLoad} type="button">
+                {costLocale === "pt-BR" ? "Tentar novamente" : "Try again"}
+              </button>
+            ) : null}
             <button
-              className="dashboard-help-open"
-              onClick={() => navigate(projectSetupPath)}
+              aria-label={costLocale === "pt-BR" ? "Fechar erro" : "Dismiss error"}
+              onClick={() => setError(null)}
               type="button"
             >
-              {costLocale === "pt-BR" ? "Configurar projeto" : "Configure project"}
+              ×
             </button>
           </div>
-        }
-      />
-      {dashboardView === "traceability" ? null : traceLoadingTaskId ? (
-        <TaskTraceLoadingPanel locale={costLocale} taskId={traceLoadingTaskId} />
-      ) : trace ? (
-        <TaskTracePanel
+        ) : null}
+        {/* Cost Monitor boundary retains loadRunPage={loadCostRunPage}, loadReadModelPage={loadCostReadModelPage}, and loadDetail={loadCostDetail}. */}
+        <OperationsPage
+          alternateContent={renderDashboardAlternateContent({
+            costs,
+            costLocale,
+            currency,
+            dashboardView,
+            failedArea,
+            lastUpdatedAt,
+            loadCostDetail,
+            loadCostReadModelPage,
+            loadCostRunPage,
+            loadCostGroupPage,
+            loadingArea,
+            onActiveDataChange: setDisplayedCosts,
+            onCurrencyChange: setCurrency,
+            onLoadingChange: setCostSurfaceLoading,
+            onLocaleChange: changeDashboardLocale,
+            onOpenTrace: (taskId) => void openTrace(taskId),
+            onRefresh: () => setRefreshDialog("choose"),
+            onRetry: retryLastLoad,
+            onSelectTraceTask: (taskId) => {
+              setSelectedTraceTaskId(taskId);
+              void openTrace(taskId);
+            },
+            onOpenTraceChange: openTraceChange,
+            onOpenTraceMacro: openTraceMacro,
+            operations: renderedOperations,
+            selectedTraceTaskId,
+            trace,
+            traceLoadingTaskId,
+            traceTasks,
+          })}
+          capabilityNavigation={capabilityNavigation}
+          boardTotals={boardTotals}
+          boardKindTotals={boardKindTotals}
+          boardExportSource={boardExportSource}
+          boardStates={boardStates}
+          data={renderedOperations}
+          datePreset={operationsPeriod.preset}
+          dateRange={operationsPeriod.range}
+          entityPage={entityPage}
+          dashboardTitle={dashboardIdentity.title}
+          repositoryName={dashboardIdentity.repositoryName}
+          loading={operationsLoading}
           locale={costLocale}
-          onClose={() => setTrace(null)}
-          onOpenChange={openTraceChange}
-          onOpenPrd={(prdId) => openTraceMacro("PRD", prdId)}
-          onOpenSpec={(specId) => openTraceMacro("SPEC", specId)}
-          trace={trace}
-        />
-      ) : null}
-      {traceLink?.kind === "change" ? (
-        <EntityDetailsDialog
-          details={{ kind: "change", row: traceLink.row }}
-          locale={costLocale}
-          onClose={() => setTraceLink(null)}
-        />
-      ) : null}
-      {traceLink?.kind === "macro" ? (
-        <MacroPlanningDialog
-          label={traceLink.label}
-          locale={costLocale}
-          onClose={() => setTraceLink(null)}
+          currency={currency}
+          factualCostTotal={factualCostTotal}
+          factualCostPeriods={factualCostPeriods}
+          onLoadingChange={setOperationsSurfaceLoading}
+          resolveRunCost={
+            costs === null ? undefined : (runId) => currentCostByRun.get(runId) ?? null
+          }
+          onLocaleChange={changeDashboardLocale}
+          onDetailDataRequest={(view) => {
+            const kind =
+              view === "conversations"
+                ? "conversations"
+                : view === "executions"
+                  ? "executions"
+                  : view === "runs"
+                      ? "runs"
+                      : null;
+            if (kind !== null) void loadOperationsEntityPage(kind);
+            else if (view === "changes" || view === "decisions")
+              void loadOperationsLifecyclePage(view);
+            else void loadOperationsDetails();
+          }}
+          onEntityPageChange={(offset) => {
+            if (entityPageKind === "changes" || entityPageKind === "decisions")
+              void loadOperationsLifecyclePage(entityPageKind, offset);
+            else void loadOperationsEntityPage(entityPageKind, offset);
+          }}
+          onEntityFiltersChange={loadFilteredOperationsPage}
+          onBoardFiltersChange={loadFilteredBoard}
+          onWorkListFiltersChange={loadFilteredWorkList}
+          onBoardTypeChange={(kind) =>
+            loadFilteredBoard({
+              ...boardFiltersRef.current,
+              kind: kind === "all" ? "" : kind,
+            })
+          }
+          onWorkListTypeChange={(kind) =>
+            void loadFilteredWorkList({
+              ...workListFiltersRef.current,
+              kind: kind === "all" ? "" : kind,
+            })
+          }
+          onLoadMoreBoard={(stage) => void loadMoreBoard(stage)}
+          statusPage={(stage, kind) => overviewStatusPages[overviewStatusPageKey(stage, kind)]}
+          onLoadStatusPage={(stage, kind, offset) =>
+            void loadOverviewStatusPage(stage, kind, offset)
+          }
+          classificationPage={(kind, classification) =>
+            overviewClassificationPages[overviewClassificationPageKey(kind, classification)]
+          }
+          onLoadClassificationPage={(kind, classification, offset) =>
+            void loadOverviewClassificationPage(kind, classification, offset)
+          }
           onOpenDocument={(kind, id) => void openDocument(kind, id)}
-          onOpenTrace={(taskId) => {
-            setTraceLink(null);
-            void openTrace(taskId);
+          onOpenTask={openTrace}
+          onPriorityChange={async (itemIds) => {
+            try {
+              await api.saveWorkPriority(itemIds);
+            } catch (cause) {
+              setError(cause instanceof Error ? cause.message : String(cause));
+              throw cause;
+            }
+          }}
+          onDateChange={(preset, range) => {
+            operationsDetailLoadedRef.current = false;
+            operationsDetailCancelRef.current?.();
+            operationsDetailCancelRef.current = null;
+            operationsDetailAbortRef.current?.abort();
+            operationsDetailAbortRef.current = null;
+            operationsPageAbortRef.current?.abort();
+            operationsPageAbortRef.current = null;
+            ++operationsPageRequestVersionRef.current;
+            boardRequestVersionRef.current += 1;
+            boardInFlightRef.current.clear();
+            boardInitialPageRef.current.clear();
+            boardLoadedRef.current = {};
+            setBoardTotals({});
+            setBoardKindTotals({});
+            setBoardStates({});
+            setOverviewStatusPages({});
+            setOverviewClassificationPages({});
+            ++refreshVersion.current;
+            setEntityPage({ offset: 0, total: null, loading: false, error: null });
+            costsLoadedRef.current = false;
+            setCosts(null);
+            setDisplayedCosts(null);
+            // Keep OperationsPage mounted so its controlled-looking local date
+            // select retains the user's choice; loading gates its old content.
+            setOperationsLoading(true);
+            periodTransitionVersionRef.current += 1;
+            setPeriodTransitionPending(true);
+            setLoadingArea("operations");
+            setOperationsPeriod({ preset, range });
           }}
-          row={traceLink.row}
-          runs={operations.runs}
-          specs={operations.specs}
-          tasks={operations.tasks}
+          onRefresh={() => setRefreshDialog("choose")}
+          settings={
+            <DashboardGlobalSettings
+              costCalculationGuidePath={costCalculationGuidePath}
+              currency={currency}
+              locale={costLocale}
+              onCurrencyChange={setCurrency}
+              onHelpOpen={() => setHelpOpen(true)}
+              onNavigate={navigate}
+              pricingSetupPath={pricingSetupPath}
+              projectSetupPath={projectSetupPath}
+            />
+          }
         />
-      ) : null}
-      {documentDetail ? (
-        <MacroDocumentDialog
-          detail={documentDetail.detail}
-          label={documentDetail.label}
-          locale={costLocale}
-          onClose={() => setDocumentDetail(null)}
+        <AppOverlays
+          closeDocument={closeDocument}
+          costLocale={costLocale}
+          documentDetail={documentDetail}
+          error={error}
+          failedArea={failedArea}
+          helpOpen={helpOpen}
+          loadingArea={dashboardView === "cost-monitor" && costs === null ? null : loadingArea}
+          operations={renderedOperations}
+          reconciliationResult={reconciliationResult}
+          refreshDialog={refreshDialog}
+          showTrace={dashboardView === "traceability"}
+          trace={trace}
+          traceLink={traceLink}
+          traceLoadingTaskId={traceLoadingTaskId}
+          onCloseHelp={() => setHelpOpen(false)}
+          onCloseTrace={() => setTrace(null)}
+          onDismissError={() => setError(null)}
+          onDismissReconciliation={() => setReconciliationResult(null)}
+          onOpenDocument={(kind, id) => void openDocument(kind, id)}
+          onOpenTrace={(taskId) => void openTrace(taskId)}
+          onOpenTraceChange={openTraceChange}
+          onOpenTraceMacro={openTraceMacro}
+          onRefreshCancel={() => setRefreshDialog(null)}
+          onRefreshFromDialog={(reconcileOpenWork) => void refreshFromDialog(reconcileOpenWork)}
+          onRetry={retryLastLoad}
+          setTraceLink={(value) => setTraceLink(value)}
         />
-      ) : null}
-      {helpOpen ? (
-        <Suspense fallback={null}>
-          <DashboardHelpDialog locale={costLocale} onClose={() => setHelpOpen(false)} />
-        </Suspense>
-      ) : null}
-      {refreshDialog === "choose" ? (
-        <div className="app-refresh-dialog-backdrop">
-          <section
-            aria-label="Atualizar dashboard"
-            aria-modal="true"
-            className="app-refresh-dialog"
-            role="dialog"
-          >
-            <h2>{costLocale === "pt-BR" ? "Atualizar dashboard" : "Refresh dashboard"}</h2>
-            <p>
-              {costLocale === "pt-BR"
-                ? "Escolha uma atualização rápida ou reconcilie os itens que ainda estão em aberto."
-                : "Choose a quick refresh or reconcile work items that are still open."}
-            </p>
-            <div>
-              <button onClick={() => void refreshFromDialog(false)} type="button">
-                {costLocale === "pt-BR" ? "Apenas atualizar dados" : "Refresh data only"}
-              </button>
-              <button onClick={() => void refreshFromDialog(true)} type="button">
-                {costLocale === "pt-BR" ? "Reconciliar itens abertos" : "Reconcile open work"}
-              </button>
-            </div>
-            <button
-              className="app-refresh-cancel"
-              onClick={() => setRefreshDialog(null)}
-              type="button"
-            >
-              {costLocale === "pt-BR" ? "Cancelar" : "Cancel"}
-            </button>
-          </section>
-        </div>
-      ) : null}
-      {refreshDialog === "refreshing" || refreshDialog === "reconciling" ? (
-        <section aria-live="polite" className="app-refresh-status" role="status">
-          <i />
-          <div>
-            <strong>
-              {refreshDialog === "reconciling"
-                ? costLocale === "pt-BR"
-                  ? "Reconciliando itens em aberto…"
-                  : "Reconciling open work…"
-                : costLocale === "pt-BR"
-                  ? "Atualizando dados…"
-                  : "Refreshing data…"}
-            </strong>
-            <span>
-              {costLocale === "pt-BR"
-                ? "Você pode continuar usando o dashboard."
-                : "You can keep using the dashboard."}
-            </span>
-          </div>
-        </section>
-      ) : null}
-      {reconciliationResult !== null && refreshDialog === null ? (
-        <section aria-live="polite" className="app-reconciliation-result" role="status">
-          <strong>
-            {costLocale === "pt-BR"
-              ? "Resultado da reconciliação manual"
-              : "Manual reconciliation result"}
-          </strong>
-          <span>
-            {costLocale === "pt-BR"
-              ? `${reconciliationResult.reconciled_ids.length} item(ns) reconciliado(s).`
-              : `${reconciliationResult.reconciled_ids.length} item(s) reconciled.`}
-          </span>
-          {reconciliationResult.reconciled_ids.length > 0 ? (
-            <p>{reconciliationResult.reconciled_ids.join(", ")}</p>
-          ) : null}
-          {reconciliationResult.blocked.length > 0 ? (
-            <p>
-              {costLocale === "pt-BR" ? "Bloqueados: " : "Blocked: "}
-              {reconciliationResult.blocked
-                .map((item) => `${item.id}${item.reason === null ? "" : ` (${item.reason})`}`)
-                .join("; ")}
-            </p>
-          ) : null}
-          {reconciliationResult.not_reconciled.length > 0 ? (
-            <p>
-              {costLocale === "pt-BR" ? "Não reconciliados: " : "Not reconciled: "}
-              {reconciliationResult.not_reconciled
-                .map((item) => `${item.id}${item.reason === null ? "" : ` (${item.reason})`}`)
-                .join("; ")}
-            </p>
-          ) : null}
-          <button onClick={() => setReconciliationResult(null)} type="button">
-            {costLocale === "pt-BR" ? "Fechar" : "Dismiss"}
-          </button>
-        </section>
-      ) : null}
-      {loadingArea !== null &&
-      loadingArea !== "operations" &&
-      refreshDialog === null &&
-      !(dashboardView === "cost-monitor" && costs === null) ? (
-        <DashboardLoadingNotice area={loadingArea} locale={costLocale} />
-      ) : null}
-    </>
+      </PeriodTransitionShell>
+      {globalLoadingPending ? <PeriodTransitionOverlay /> : null}
+    </AppLoadingBoundary>
   );
 }