@zaip-ai/cli 3.3.0 → 3.5.0

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

@@ -1,10 +1,12 @@
-import { type FormEvent, type ReactNode, useCallback, useEffect, useState } from "react";
+import { type FormEvent, useCallback, useEffect, useState } from "react";
 import type {
   DashboardApiClient,
   ProjectConfigSettings,
   ProjectOverview,
 } from "./dashboard-api.js";
 import { StackComponentEditor, StackVersions } from "./ProjectStackEditor.js";
+import { ProjectSettingsCard as SettingsCard } from "./ProjectSettingsCard.js";
+import { ProjectSettingsField as Field } from "./ProjectSettingsField.js";
 import {
   type InstallationDimensionStatus,
   projectInstallationStatus,
@@ -25,7 +27,9 @@ import {
 } from "./project-settings-model.js";
 import "./project-settings-page.css";
 import "./project-stack-versions.css";
+import "./project-settings-workspace.css";
 import { AutonomySettings } from "./AutonomySettings.js";
+import { useRuntimeStatus } from "./use-runtime-status.js";
 
 export function ProjectSettingsPage({
   api,
@@ -46,6 +50,7 @@ export function ProjectSettingsPage({
   const [error, setError] = useState<string | null>(null);
   const [notice, setNotice] = useState<string | null>(null);
   const [installationToastVisible, setInstallationToastVisible] = useState(false);
+  const runtime = useRuntimeStatus();
   const installation = overview === null ? null : projectInstallationStatus(overview);
 
   const loadProjectSettings = useCallback(async () => {
@@ -219,6 +224,16 @@ export function ProjectSettingsPage({
 
         <div className="project-settings-grid">
           <SettingsCard className="is-wide project-identity-card" title={text.identity}>
+            <Field
+              className="project-settings-workspace-field"
+              hint={text.workspacePathHint}
+              label={text.workspacePath}
+            >
+              <code className="project-settings-workspace-path">
+                {runtime.status?.workspace ??
+                  (runtime.unavailable ? text.workspacePathUnavailable : text.workspacePathLoading)}
+              </code>
+            </Field>
             <Field label="Schema">
               <input readOnly value={config.schema_version} />
             </Field>
@@ -599,33 +614,6 @@ function installationStateLabel(state: InstallationDimensionStatus["state"], loc
   return text.unknown;
 }
 
-function SettingsCard({
-  children,
-  className = "",
-  title,
-}: {
-  children: ReactNode;
-  className?: string;
-  title: string;
-}) {
-  return (
-    <section className={`project-settings-card ${className}`}>
-      <h2>{title}</h2>
-      <div className="project-settings-fields">{children}</div>
-    </section>
-  );
-}
-
-function Field({ children, hint, label }: { children: ReactNode; hint?: string; label: string }) {
-  return (
-    <div className="project-settings-field">
-      <span>{label}</span>
-      {children}
-      {hint ? <small>{hint}</small> : null}
-    </div>
-  );
-}
-
 function Toggle({
   checked,
   hint,

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

@@ -1,5 +1,6 @@
 import type { ProjectOverview } from "./dashboard-api.js";
 import {
+  acceptsDescriptiveVersion,
   type StackComponentId,
   type StackComponentsDraft,
   stackComponentDefinitions,
@@ -74,7 +75,9 @@ export function StackComponentEditor({
             <div className="project-stack-table-head" aria-hidden="true">
               <span>Item</span>
               <span>{locale === "pt-BR" ? "Tecnologia" : "Technology"}</span>
-              <span>{locale === "pt-BR" ? "Versão exata" : "Exact version"}</span>
+              <span>
+                {locale === "pt-BR" ? "Versão atual / referência" : "Current version / reference"}
+              </span>
               <span>
                 {locale === "pt-BR" ? "Pacote / imagem / serviço" : "Package / image / service"}
               </span>
@@ -92,9 +95,27 @@ export function StackComponentEditor({
                     onChange={(event) => update(definition.id, "name", event.target.value)}
                   />
                   <input
-                    aria-label={`${componentLabels[definition.id].pt}: versão exata`}
-                    inputMode="decimal"
-                    placeholder="x.y.z"
+                    aria-label={`${componentLabels[definition.id].pt}: ${
+                      acceptsDescriptiveVersion(definition.id)
+                        ? "versão atual ou referência"
+                        : "versão exata"
+                    }`}
+                    className={
+                      acceptsDescriptiveVersion(definition.id) ? "is-reference-value" : undefined
+                    }
+                    inputMode={acceptsDescriptiveVersion(definition.id) ? "text" : "decimal"}
+                    placeholder={
+                      acceptsDescriptiveVersion(definition.id)
+                        ? locale === "pt-BR"
+                          ? "Serviço em nuvem"
+                          : "Cloud service"
+                        : "x.y.z"
+                    }
+                    title={
+                      acceptsDescriptiveVersion(definition.id)
+                        ? components[definition.id].version
+                        : undefined
+                    }
                     value={components[definition.id].version}
                     onChange={(event) => update(definition.id, "version", event.target.value)}
                   />

package/templates/.agents/dashboard/apps/frontend/src/WorkspaceStatus.test.tsx

@@ -0,0 +1,51 @@
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { WorkspaceStatus } from "./WorkspaceStatus.js";
+
+describe("workspace diagnostics", () => {
+  it("does not render a global workspace banner when the runtime is healthy", () => {
+    const html = renderToStaticMarkup(
+      createElement(WorkspaceStatus, {
+        status: {
+          workspace: "C:/projects/zaip-growth",
+          workspace_name: "zaip-growth",
+          workspaceKey: "growth",
+          status: "ok",
+          lifecycle_manifest_state: "initialized",
+        },
+      }),
+    );
+    expect(html).toBe("");
+  });
+
+  it.each([
+    "missing",
+    "invalid",
+  ] as const)("keeps the %s lifecycle warning without exposing the served path", (state) => {
+    const html = renderToStaticMarkup(
+      createElement(WorkspaceStatus, {
+        status: {
+          workspace: "C:/projects/zaip-growth",
+          workspace_name: "zaip-growth",
+          workspaceKey: "growth",
+          status: "degraded",
+          lifecycle_manifest_state: state,
+        },
+      }),
+    );
+    expect(html).not.toContain("C:/projects/zaip-growth");
+    expect(html).not.toContain("zaip-growth");
+    if (state === "missing") expect(html).toContain("Lifecycle não inicializado");
+    if (state === "invalid") expect(html).toContain("Manifesto do lifecycle inválido");
+    expect(html).toContain("manifest rebuild --confirm-full-scan");
+  });
+
+  it("keeps unknown health explicit", () => {
+    const html = renderToStaticMarkup(
+      createElement(WorkspaceStatus, { status: null, unavailable: true }),
+    );
+    expect(html).toContain("Não foi possível consultar a saúde do Dashboard");
+    expect(html).not.toContain("Workspace indisponível");
+  });
+});

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

@@ -0,0 +1,39 @@
+import type { DashboardRuntimeStatus } from "./dashboard-runtime-status.js";
+import "./workspace-status.css";
+
+export function WorkspaceStatus({
+  status,
+  unavailable = false,
+}: {
+  status: DashboardRuntimeStatus | null;
+  unavailable?: boolean;
+}) {
+  const manifest = status?.lifecycle_manifest_state;
+  if (manifest === "initialized" && status?.status === "ok" && !unavailable) return null;
+
+  return (
+    <aside className="workspace-status" aria-label="Saúde do Dashboard">
+      {manifest === "missing" || manifest === "invalid" ? (
+        <div className="workspace-status__warning" role="alert">
+          <strong>
+            {manifest === "missing"
+              ? "Lifecycle não inicializado"
+              : "Manifesto do lifecycle inválido"}
+          </strong>
+          <p>Os dados deste workspace estão indisponíveis. Na pasta do projeto, execute:</p>
+          <code>node .agents/runtime/bin/zaip.mjs manifest rebuild --confirm-full-scan</code>
+        </div>
+      ) : status?.status === "degraded" || unavailable ? (
+        <p className="workspace-status__warning" role="status">
+          {unavailable
+            ? "Não foi possível consultar a saúde do Dashboard. Tentando novamente…"
+            : "Dashboard degradado: a atualização dos dados ou da telemetria requer atenção."}
+        </p>
+      ) : (
+        <p className="workspace-status__warning" role="status">
+          Identificando a saúde do Dashboard…
+        </p>
+      )}
+    </aside>
+  );
+}

package/templates/.agents/dashboard/apps/frontend/src/app-work-board-options.ts

@@ -0,0 +1,41 @@
+import type { OperationsProjection } from "@zaip-ai/dashboard-operations/contracts";
+import type { Dispatch, RefObject, SetStateAction } from "react";
+import type {
+  BoardStageState,
+  OverviewClassificationPages,
+  OverviewStatusPages,
+} from "./AppWorkBoard.js";
+import type {
+  DashboardApiClient,
+  OperationsBoardPage,
+  OperationsPageFilters,
+  WorkBoardStage,
+} from "./dashboard-api.js";
+import type { OperationsPeriodState } from "./operations-period.js";
+
+type StateSetter<T> = Dispatch<SetStateAction<T>>;
+
+export interface AppWorkBoardOptions {
+  api: DashboardApiClient;
+  boardAbortControllersRef: RefObject<Map<WorkBoardStage, AbortController>>;
+  boardFilterKeyRef: RefObject<string>;
+  boardFiltersRef: RefObject<OperationsPageFilters>;
+  boardInFlightRef: RefObject<Set<WorkBoardStage>>;
+  boardInitialPageRef: RefObject<Set<WorkBoardStage>>;
+  boardLoadedRef: RefObject<Partial<Record<WorkBoardStage, number>>>;
+  boardRequestVersionRef: RefObject<number>;
+  dashboardView: "operations" | "cost-monitor" | "traceability" | null;
+  operations: OperationsProjection | null;
+  operationsPeriod: OperationsPeriodState;
+  operationsPeriodRef: RefObject<OperationsPeriodState>;
+  overviewStatusInFlightRef: RefObject<Set<string>>;
+  quickOverviewMetricsRef: RefObject<OperationsProjection["summary"]["overview_metrics"]>;
+  setBoardKindTotals: StateSetter<
+    Partial<Record<WorkBoardStage, OperationsBoardPage["totals_by_kind"]>>
+  >;
+  setBoardStates: StateSetter<Partial<Record<WorkBoardStage, BoardStageState>>>;
+  setBoardTotals: StateSetter<Partial<Record<WorkBoardStage, number>>>;
+  setOperations: StateSetter<OperationsProjection | null>;
+  setOverviewClassificationPages: StateSetter<OverviewClassificationPages>;
+  setOverviewStatusPages: StateSetter<OverviewStatusPages>;
+}

package/templates/.agents/dashboard/apps/frontend/src/dashboard-runtime-status.ts

@@ -0,0 +1,25 @@
+export interface DashboardRuntimeStatus {
+  workspace: string;
+  workspace_name: string;
+  workspaceKey: string;
+  status: "ok" | "degraded";
+  lifecycle_manifest_state: "initialized" | "missing" | "invalid";
+  active_capture_failure?: { code: string } | null;
+}
+
+export async function readDashboardRuntimeStatus(
+  signal: AbortSignal,
+): Promise<DashboardRuntimeStatus> {
+  const response = await fetch("/api/v2/health", { cache: "no-store", signal });
+  const value = await response.json();
+  // A degraded response is useful diagnostic data, including HTTP 503.
+  if (
+    value?.kind !== "zaip-dashboard-sqlite-runtime" ||
+    typeof value.workspace !== "string" ||
+    typeof value.workspace_name !== "string" ||
+    !["initialized", "missing", "invalid"].includes(value.lifecycle_manifest_state)
+  ) {
+    throw new Error("Identidade do Dashboard indisponível");
+  }
+  return value;
+}

package/templates/.agents/dashboard/apps/frontend/src/project-settings-copy.ts

@@ -15,6 +15,10 @@ export const projectSettingsCopy = {
     framework: "Framework ZAIP-AIOS",
     frameworkHint: "Ativa ou desativa o framework para este projeto.",
     identity: "Identidade do projeto",
+    workspacePath: "Caminho do projeto",
+    workspacePathHint: "Pasta local usada por esta instância do Dashboard.",
+    workspacePathLoading: "Identificando caminho…",
+    workspacePathUnavailable: "Caminho indisponível",
     stack: "Stack e linguagens",
     execution: "Execução",
     assurance: "Assurance",
@@ -57,8 +61,9 @@ export const projectSettingsCopy = {
     available: "Criado",
     artifactUnavailable: "Ainda não criado",
     componentGuide:
-      "Preencha cada responsabilidade separadamente. A versão fica sem prefixos (^, ~, >=) e a referência identifica o pacote, imagem ou serviço.",
-    versionHint: "Versão exata: 22.16.0 ou 17.6. Deixe vazio para serviços sem versão fixada.",
+      "Preencha cada responsabilidade separadamente. Use a versão exata do software e, para serviços em nuvem ou hospedagem, informe Serviço em nuvem.",
+    versionHint:
+      "Software: 22.16.0 ou 17.6, sem prefixos (^, ~, >=). Serviço gerenciado: Serviço em nuvem. Hospedagem: Serviço em nuvem.",
     referenceHint:
       "Ex.: npm:hono, docker:node:22.16.0-bookworm-slim, service:supabase ou provider:cloudflare-pages.",
     overrides: "Opções avançadas (JSON)",
@@ -103,6 +108,10 @@ export const projectSettingsCopy = {
     framework: "ZAIP-AIOS framework",
     frameworkHint: "Enable or disable the framework for this project.",
     identity: "Project identity",
+    workspacePath: "Project path",
+    workspacePathHint: "Local folder used by this Dashboard instance.",
+    workspacePathLoading: "Identifying path…",
+    workspacePathUnavailable: "Path unavailable",
     stack: "Stack and languages",
     execution: "Execution",
     assurance: "Assurance",
@@ -145,9 +154,9 @@ export const projectSettingsCopy = {
     available: "Created",
     artifactUnavailable: "Not created yet",
     componentGuide:
-      "Fill each responsibility separately. Versions have no prefixes (^, ~, >=), and the reference identifies the package, image, or service.",
+      "Fill each responsibility separately. Use an exact software version and, for cloud services or hosting, enter Cloud service.",
     versionHint:
-      "Exact version: 22.16.0 or 17.6. Leave blank for services without a pinned version.",
+      "Software: 22.16.0 or 17.6, without prefixes (^, ~, >=). Managed service: Cloud service. Hosting: Cloud service.",
     referenceHint:
       "E.g. npm:hono, docker:node:22.16.0-bookworm-slim, service:supabase, or provider:cloudflare-pages.",
     overrides: "Advanced options (JSON)",

package/templates/.agents/dashboard/apps/frontend/src/project-settings-model.ts

@@ -34,6 +34,18 @@ export type StackComponentId = (typeof stackComponentDefinitions)[number]["id"];
 export type StackComponentDraft = { name: string; version: string; reference: string };
 export type StackComponentsDraft = Record<StackComponentId, StackComponentDraft>;
 
+const descriptiveVersionComponentIds = new Set<StackComponentId>([
+  "database",
+  "auth_storage",
+  "backend_hosting",
+  "frontend_hosting",
+  "site_hosting",
+]);
+
+export function acceptsDescriptiveVersion(id: StackComponentId): boolean {
+  return descriptiveVersionComponentIds.has(id);
+}
+
 export function projectSettingsDraft(config: ProjectConfigSettings): {
   components: StackComponentsDraft;
   otherOverrides: string;
@@ -110,11 +122,23 @@ export function buildProjectSettingsPayload(
   } = parsed;
   for (const definition of stackComponentDefinitions) {
     const version = components[definition.id].version.trim();
-    if (version !== "" && !/^\d+\.\d+(?:\.\d+)?(?:[-+][0-9A-Za-z.-]+)?$/.test(version)) {
+    if (
+      version !== "" &&
+      !acceptsDescriptiveVersion(definition.id) &&
+      !/^\d+\.\d+(?:\.\d+)?(?:[-+][0-9A-Za-z.-]+)?$/.test(version)
+    ) {
       throw new Error(
         `A versão de ${components[definition.id].name || definition.defaultName} deve ser exata, como 22.16.0 ou 17.6, sem ^, ~, >= ou latest.`,
       );
     }
+    if (
+      acceptsDescriptiveVersion(definition.id) &&
+      (version.length > 120 || /[\r\n]/.test(version))
+    ) {
+      throw new Error(
+        `A referência de ${components[definition.id].name || definition.defaultName} deve ter uma única linha com até 120 caracteres.`,
+      );
+    }
   }
   const normalized = Object.fromEntries(
     stackComponentDefinitions.map((definition) => [

package/templates/.agents/dashboard/apps/frontend/src/project-settings-workspace.css

@@ -0,0 +1,28 @@
+.project-settings-workspace-path {
+  display: block;
+  min-width: 0;
+  padding: 10px 12px;
+  border: 1px solid #cbd7e5;
+  border-radius: 12px;
+  background: #f8fafc;
+  overflow-wrap: anywhere;
+  color: #0f172a;
+}
+
+.project-settings-workspace-field {
+  grid-column: 1 / -1;
+}
+
+.project-stack-row input.is-reference-value {
+  border-color: #9edcf2;
+  background-color: #effaff;
+  color: #075985;
+  font-weight: 650;
+  -webkit-text-fill-color: #075985;
+}
+
+.project-stack-row input.is-reference-value:hover,
+.project-stack-row input.is-reference-value:focus-visible {
+  border-color: #00b0f0;
+  background-color: #f5fcff;
+}

package/templates/.agents/dashboard/apps/frontend/src/project-settings.test.ts

@@ -111,6 +111,45 @@ describe("project settings form mapping", () => {
     ).toThrow("deve ser exata");
   });
 
+  it("accepts descriptive references only for managed services and hosting", () => {
+    const components = projectSettingsDraft(config).components;
+    const payload = buildProjectSettingsPayload(
+      config,
+      {
+        ...components,
+        database: { ...components.database, version: "Serviço em nuvem" },
+        auth_storage: { ...components.auth_storage, version: "Serviço em nuvem" },
+        backend_hosting: {
+          ...components.backend_hosting,
+          version: "Serviço em nuvem",
+        },
+        frontend_hosting: { ...components.frontend_hosting, version: "Serviço em nuvem" },
+        site_hosting: { ...components.site_hosting, version: "Serviço em nuvem" },
+      },
+      "{}",
+    );
+
+    expect(payload.stack.overrides.components).toMatchObject({
+      database: { version: "Serviço em nuvem" },
+      auth_storage: { version: "Serviço em nuvem" },
+      backend_hosting: {
+        version: "Serviço em nuvem",
+      },
+      frontend_hosting: { version: "Serviço em nuvem" },
+      site_hosting: { version: "Serviço em nuvem" },
+    });
+    expect(() =>
+      buildProjectSettingsPayload(
+        config,
+        {
+          ...components,
+          backend_api: { ...components.backend_api, version: "Serviço em nuvem" },
+        },
+        "{}",
+      ),
+    ).toThrow("deve ser exata");
+  });
+
   it("keeps observability and on-demand testing tools editable with pinned-or-empty versions", () => {
     const configured = {
       ...config,

package/templates/.agents/dashboard/apps/frontend/src/snapshot-coherence.test.ts

@@ -334,8 +334,8 @@ describe("atomic Cost snapshot loading", () => {
     expect(boardHydration).toContain(
       "await Promise.all(batch.map((stage) => loadMoreBoard(stage)))",
     );
-    expect(boardHydration).toContain("window.requestIdleCallback(() => void hydrateBoard())");
     expect(boardHydration).toContain("window.setTimeout(() => void hydrateBoard(), 0)");
+    expect(boardHydration).not.toContain("window.requestIdleCallback");
     expect(boardHydration).toContain("!boardInitialPageRef.current.has(stage)");
     expect(boardHydration).toContain("boardInitialPageRef.current.add(stage)");
     expect(boardHydration).toContain("!boardInFlightRef.current.has(stage)");

package/templates/.agents/dashboard/apps/frontend/src/use-app-cost-loaders.ts

@@ -134,6 +134,10 @@ export async function loadSqliteCostRunPage(api: DashboardApiClient, request: Co
       ...(filters?.agent ? { agent: filters.agent } : {}),
       ...(filters?.phase ? { phase: filters.phase } : {}),
       ...(filters?.status ? { status: filters.status } : {}),
+      ...(filters?.priority ? { priority: filters.priority } : {}),
+      ...(filters?.risk ? { risk: filters.risk } : {}),
+      ...(filters?.origin ? { origin: filters.origin } : {}),
+      ...(filters?.workType ? { workType: filters.workType } : {}),
     },
     signal,
   );
@@ -360,7 +364,7 @@ export function useAppCostLoaders(api: DashboardApiClient) {
         {
           offset,
           limit,
-          ...(query === undefined || query === "" ? {} : { query }),
+          ...(filters.query || query ? { query: filters.query || query } : {}),
           ...(filters.provider ? { provider: filters.provider } : {}),
           ...(filters.model ? { model: filters.model } : {}),
           ...(filters.agent ? { agent: filters.agent } : {}),

package/templates/.agents/dashboard/apps/frontend/src/use-app-work-board.test.ts

@@ -0,0 +1,140 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { OperationsProjection } from "@zaip-ai/dashboard-operations/contracts";
+import type { DashboardApiClient, OperationsPageFilters, WorkBoardStage } from "./dashboard-api.js";
+import type { OperationsPeriodState } from "./operations-period.js";
+import { useAppWorkBoard } from "./use-app-work-board.js";
+
+const effects = vi.hoisted(() => [] as Array<() => void | (() => void)>);
+
+// Exercise the hook's actual request and reset logic while retaining direct
+// control of the deferred effect callback that races with a filter reset.
+vi.mock("react", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("react")>()),
+  useCallback: <T>(callback: T) => callback,
+  useEffect: (effect: () => void | (() => void)) => effects.push(effect),
+}));
+
+const filters: OperationsPageFilters = {
+  query: "",
+  status: "",
+  risk: "",
+  origin: "",
+  kind: "",
+};
+const operationsPeriod: OperationsPeriodState = {
+  preset: "all",
+  range: { start: "2026-08-01", end: "2026-08-31" },
+};
+
+function boardPage(stage: WorkBoardStage) {
+  return {
+    stage,
+    offset: 0,
+    total: 0,
+    totals_by_kind: { all: 0, task: 0, "standalone-task": 0, prd: 0, spec: 0 },
+    prds: [],
+    specs: [],
+    tasks: [],
+    changes: [],
+  };
+}
+
+function setup() {
+  const operationsBoard = vi.fn<DashboardApiClient["operationsBoard"]>(async (_period, stage) =>
+    boardPage(stage),
+  );
+  const api = { operationsBoard } as unknown as DashboardApiClient;
+  let operations = {
+    prds: [],
+    specs: [],
+    tasks: [],
+    changes: [],
+    summary: {},
+  } as unknown as OperationsProjection;
+  const boardInitialPageRef = { current: new Set<WorkBoardStage>() };
+  const boardRequestVersionRef = { current: 0 };
+  const setOperations = (
+    update:
+      | OperationsProjection
+      | null
+      | ((current: OperationsProjection | null) => OperationsProjection | null),
+  ) => {
+    operations = (
+      typeof update === "function" ? update(operations) : update
+    ) as OperationsProjection;
+  };
+  const render = () =>
+    useAppWorkBoard({
+      api,
+      boardAbortControllersRef: { current: new Map() },
+      boardFilterKeyRef: { current: "||||" },
+      boardFiltersRef: { current: filters },
+      boardInFlightRef: { current: new Set() },
+      boardInitialPageRef,
+      boardLoadedRef: { current: {} },
+      boardRequestVersionRef,
+      dashboardView: "operations",
+      operations,
+      operationsPeriod,
+      operationsPeriodRef: { current: operationsPeriod },
+      overviewStatusInFlightRef: { current: new Set() },
+      quickOverviewMetricsRef: { current: undefined },
+      setBoardKindTotals: vi.fn() as never,
+      setBoardStates: vi.fn() as never,
+      setBoardTotals: vi.fn() as never,
+      setOperations,
+      setOverviewClassificationPages: vi.fn() as never,
+      setOverviewStatusPages: vi.fn() as never,
+    });
+  return { boardInitialPageRef, operationsBoard, render };
+}
+
+beforeEach(() => {
+  effects.length = 0;
+  vi.useFakeTimers();
+  vi.stubGlobal("window", { setTimeout, clearTimeout, requestIdleCallback: undefined });
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.useRealTimers();
+});
+
+describe("work board hydration generation", () => {
+  it("hydrates the visible board when requestIdleCallback never runs", async () => {
+    const requestIdleCallback = vi.fn(() => 1);
+    vi.stubGlobal("window", {
+      setTimeout,
+      clearTimeout,
+      requestIdleCallback,
+      cancelIdleCallback: vi.fn(),
+    });
+    const { boardInitialPageRef, operationsBoard, render } = setup();
+    render();
+    const effect = effects[0];
+    if (effect === undefined) throw new Error("expected visible board hydration effect");
+    const cleanup = effect();
+
+    await vi.runAllTimersAsync();
+
+    expect(requestIdleCallback).not.toHaveBeenCalled();
+    expect(operationsBoard).toHaveBeenCalledTimes(9);
+    expect(boardInitialPageRef.current.size).toBe(9);
+    cleanup?.();
+  });
+
+  it("does not let an older scheduled callback consume the reset board generation", async () => {
+    const { boardInitialPageRef, operationsBoard, render } = setup();
+    const board = render();
+    const staleEffect = effects[0];
+    if (staleEffect === undefined) throw new Error("expected initial board hydration effect");
+    const cleanup = staleEffect();
+
+    board.loadFilteredBoard({ ...filters, kind: "task" });
+    await vi.advanceTimersByTimeAsync(0);
+
+    expect(operationsBoard).not.toHaveBeenCalled();
+    expect(boardInitialPageRef.current).toEqual(new Set());
+    cleanup?.();
+  });
+});