@zaip-ai/cli 4.9.0 → 5.1.0

package/templates/.agents/dashboard/modules/operations/src/react/OperationsOverviewTopPanel.navigation.test.tsx

@@ -0,0 +1,150 @@
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import type { Browser } from "@playwright/test";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+declare global {
+  interface Window {
+    __topFiveNavigationProbe: {
+      tasks: string[];
+      documents: { kind: "prd" | "spec"; id: string }[];
+    };
+  }
+}
+
+const browserRequire = createRequire(
+  fileURLToPath(new URL("../../../../tests/e2e/package.json", import.meta.url)),
+);
+const { chromium, expect: expectPlaywright } = browserRequire("@playwright/test");
+
+describe("Operations Top 5 navigation", () => {
+  let browser: Browser;
+  let bundle: string;
+
+  beforeAll(async () => {
+    const esbuild = browserRequire("esbuild");
+    const harness = await esbuild.build({
+      bundle: true,
+      define: { "import.meta.url": '"http://localhost/"' },
+      format: "iife",
+      loader: { ".css": "text" },
+      logLevel: "silent",
+      platform: "browser",
+      alias: {
+        "@zaip-ai/dashboard-ui": fileURLToPath(
+          new URL("../../../../packages/ui/src/index.ts", import.meta.url),
+        ),
+        react: fileURLToPath(
+          new URL(
+            "../../../../../../node_modules/.pnpm/react@19.2.7/node_modules/react",
+            import.meta.url,
+          ),
+        ),
+        "react-dom": fileURLToPath(
+          new URL(
+            "../../../../../../node_modules/.pnpm/react-dom@19.2.7_react@19.2.7/node_modules/react-dom",
+            import.meta.url,
+          ),
+        ),
+      },
+      stdin: {
+        contents: `
+          import React, { useState } from "react";
+          import { createRoot } from "react-dom/client";
+          import { OperationsOverviewTopPanel } from "./OperationsOverviewTopPanel.js";
+
+          const entities = {
+            tasks: [
+              { id: "TASK-TRACE-FIRST", title: "First task", durationMs: 120000, tokens: 1, costBrl: 1, runCount: 1 },
+              { id: "TASK-TRACE-SECOND", title: "Second task", durationMs: 60000, tokens: 1, costBrl: 1, runCount: 1 },
+            ],
+            specs: [
+              { id: "SPEC-TRACE-FIRST", title: "First spec", durationMs: 120000, tokens: 1, costBrl: 1, runCount: 1 },
+              { id: "SPEC-TRACE-SECOND", title: "Second spec", durationMs: 60000, tokens: 1, costBrl: 1, runCount: 1 },
+            ],
+            prds: [
+              { id: "PRD-TRACE-FIRST", title: "First prd", durationMs: 120000, tokens: 1, costBrl: 1, runCount: 1 },
+              { id: "PRD-TRACE-SECOND", title: "Second prd", durationMs: 60000, tokens: 1, costBrl: 1, runCount: 1 },
+            ],
+          };
+          const probe = { tasks: [], documents: [] };
+          window.__topFiveNavigationProbe = probe;
+
+          function Harness() {
+            const [view, setView] = useState("tasks");
+            return <>
+              <nav aria-label="Overview mode">
+                {Object.keys(entities).map((mode) => <button key={mode} type="button" onClick={() => setView(mode)}>{mode}</button>)}
+              </nav>
+              <OperationsOverviewTopPanel
+                copy={{ empty: "Empty", hint: "Duration", title: "Top 5" }}
+                currency="BRL" locale="en-US" maxDuration={120000}
+                onOpenTask={async (id) => { probe.tasks.push(id); return true; }}
+                onOpenMacro={(kind, id) => probe.documents.push({ kind, id })}
+                summary={{ durationMs: 180000, durationShare: 1, runCount: 2, tokens: 2 }}
+                text={{ accumulatedTime: "Time", associatedRuns: "runs", concentration: "Concentration", totalMeasuredTime: "Total", topFiveCost: "Cost", tokensUnavailable: "Unavailable" }}
+                topCost={2} topEntities={entities[view]} view={view}
+              />
+            </>;
+          }
+          createRoot(document.getElementById("root")).render(<Harness />);
+        `,
+        loader: "tsx",
+        resolveDir: fileURLToPath(new URL(".", import.meta.url)),
+        sourcefile: "OperationsOverviewTopPanel.navigation-harness.tsx",
+      },
+      write: false,
+    });
+    bundle = harness.outputFiles[0].text;
+    browser = await chromium.launch({ headless: true });
+  }, 60_000);
+
+  afterAll(async () => {
+    await browser?.close();
+  }, 60_000);
+
+  it("opens the selected Task, SPEC, and PRD after switching modes by mouse and keyboard", async () => {
+    const page = await browser.newPage();
+    const pageErrors: string[] = [];
+    page.on("pageerror", (error) => pageErrors.push(error.message));
+    try {
+      await page.setContent('<div id="root"></div>');
+      await page.addScriptTag({ content: bundle });
+      await expectPlaywright(page.locator(".operations-run-bar")).toHaveCount(2);
+
+      await page.getByRole("button", { name: /Open task details for Second task/ }).click();
+      await page
+        .getByRole("navigation", { name: "Overview mode" })
+        .getByRole("button", { name: "specs" })
+        .click();
+      const spec = page.getByRole("button", { name: /Open details for SPEC First spec/ });
+      await expectPlaywright(spec).toBeEnabled();
+      await spec.focus();
+      await page.keyboard.press("Enter");
+      await page
+        .getByRole("navigation", { name: "Overview mode" })
+        .getByRole("button", { name: "prds" })
+        .click();
+      const prd = page.getByRole("button", { name: /Open details for PRD Second prd/ });
+      await expectPlaywright(prd).toBeEnabled();
+      await prd.focus();
+      await page.keyboard.press("Space");
+      await page
+        .getByRole("navigation", { name: "Overview mode" })
+        .getByRole("button", { name: "tasks" })
+        .click();
+      await page.getByRole("button", { name: /Open task details for First task/ }).click();
+
+      expect(await page.evaluate(() => window.__topFiveNavigationProbe)).toEqual({
+        tasks: ["TASK-TRACE-SECOND", "TASK-TRACE-FIRST"],
+        documents: [
+          { kind: "spec", id: "SPEC-TRACE-FIRST" },
+          { kind: "prd", id: "PRD-TRACE-SECOND" },
+        ],
+      });
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await page.close();
+    }
+  }, 60_000);
+});

package/templates/.agents/dashboard/modules/operations/src/react/OperationsOverviewTopPanel.tsx

@@ -18,6 +18,7 @@ export function OperationsOverviewTopPanel({
   currency,
   locale,
   maxDuration,
+  onOpenMacro,
   onOpenTask,
   summary,
   text,
@@ -30,6 +31,7 @@ export function OperationsOverviewTopPanel({
   currency: "BRL" | "USD";
   locale: OperationsLocale;
   maxDuration: number;
+  onOpenMacro: (kind: "prd" | "spec", id: string) => void;
   onOpenTask: (taskId: string) => Promise<boolean>;
   summary: {
     durationMs: number | null;
@@ -68,14 +70,16 @@ export function OperationsOverviewTopPanel({
               const label =
                 view === "tasks"
                   ? `${locale === "pt-BR" ? "Abrir detalhes da tarefa" : "Open task details for"} ${entity.title}: ${measuredDuration}`
-                  : `${entityKind} ${entity.title}: ${measuredDuration}`;
+                  : `${locale === "pt-BR" ? "Abrir detalhes da" : "Open details for"} ${entityKind} ${entity.title}: ${measuredDuration}`;
               return (
                 <button
                   aria-label={label}
                   className={`operations-run-bar${entity.durationMs === null ? " is-duration-unavailable" : ""}`}
-                  disabled={view !== "tasks"}
                   key={entity.id}
-                  onClick={() => void onOpenTask(entity.id)}
+                  onClick={() => {
+                    if (view === "tasks") void onOpenTask(entity.id);
+                    else onOpenMacro(view === "specs" ? "spec" : "prd", entity.id);
+                  }}
                   title={`${entity.title}: ${measuredDuration}`}
                   type="button"
                 >

package/templates/.agents/dashboard/modules/operations/src/react/OperationsPage.tsx

@@ -20,6 +20,8 @@ import {
   workListTypeOnViewChange,
 } from "./operations-page-contract.js";
 import { useOperationFilterFeedback } from "./use-operation-filter-feedback.js";
+import { useOperationsDefaultRange } from "./use-operations-default-range.js";
+import { useOperationsFilterSync } from "./use-operations-filter-sync.js";
 
 export {
   type DashboardGlobalFilters,
@@ -85,6 +87,7 @@ export function OperationsPage({
   locale,
   onLocaleChange,
   onOpenDocument,
+  onOpenMacro,
   onOpenTask,
   onPriorityChange,
   onLoadMacroMetrics,
@@ -124,13 +127,7 @@ export function OperationsPage({
   const [originFilter, setOriginFilter] = useState<TaskOrigin | "">("");
   const { filterLoading, showFilterLoading } = useOperationFilterFeedback();
   const searchInputRef = useRef<HTMLInputElement>(null);
-  const defaultDateRange = useMemo(() => {
-    const operationsRange = initialOperationsDateRange(
-      data.tasks,
-      Object.keys(data.summary.periods?.daily ?? {}),
-    );
-    return factualCostDateRange(factualCostPeriods?.day, operationsRange);
-  }, [data.summary.periods, data.tasks, factualCostPeriods?.day]);
+  const defaultDateRange = useOperationsDefaultRange(data, factualCostPeriods);
   const initialDateRange = useMemo(() => dateRangeForPreset("this-month"), []);
   const [localDateRange, setLocalDateRange] = useState(() => initialDateRange);
   const [localDatePreset, setLocalDatePreset] = useState<OperationDatePreset>("all");
@@ -179,43 +176,17 @@ export function OperationsPage({
     setRiskFilter("");
     setOriginFilter("");
   };
-  useEffect(() => {
-    // The parent replaces the aggregate snapshot while a period transition is
-    // loading. Defer paged entity hydration until that replacement is stable,
-    // otherwise the aggregate response can overwrite a newer entity page.
-    if (loading) return;
-    if (view === "work-kanban" || view === "work-list") {
-      const timeout = window.setTimeout(() => {
-        const filters = {
-          query,
-          status: statusFilter,
-          risk: riskFilter,
-          origin: originFilter,
-        };
-        if (view === "work-kanban") onBoardFiltersChange?.(filters);
-        else onWorkListFiltersChange?.(filters);
-      }, 180);
-      return () => window.clearTimeout(timeout);
-    }
-    if (!["runs", "conversations", "executions", "changes", "decisions"].includes(view)) return;
-    const timeout = window.setTimeout(() => {
-      onEntityFiltersChange?.(
-        view as "runs" | "conversations" | "executions" | "changes" | "decisions",
-        { query, status: statusFilter, risk: riskFilter },
-      );
-    }, 180);
-    return () => window.clearTimeout(timeout);
-  }, [
-    onBoardFiltersChange,
-    onWorkListFiltersChange,
-    onEntityFiltersChange,
+  useOperationsFilterSync({
     loading,
-    originFilter,
+    view,
     query,
-    riskFilter,
     statusFilter,
-    view,
-  ]);
+    riskFilter,
+    originFilter,
+    onBoardFiltersChange,
+    onWorkListFiltersChange,
+    onEntityFiltersChange,
+  });
   // Only work views interpret a status option as a canonical work stage.
   // Runs, Changes and Executions use their respective persisted statuses.
   const hasEntityStageStatus =
@@ -329,6 +300,7 @@ export function OperationsPage({
     (row) =>
       row.entrypoint === "conversation" &&
       row.task_id === null &&
+      row.conversation_id !== null &&
       conversationIds.has(row.conversation_id),
   );
   const decisions = data.decisions.filter(
@@ -657,6 +629,7 @@ export function OperationsPage({
               locale={locale}
               onOpenTask={onOpenTask}
               onOpenDocument={onOpenDocument}
+              onOpenMacro={onOpenMacro}
               onLoadStatus={onLoadStatusPage}
               prds={prds}
               query={query}
@@ -756,5 +729,3 @@ export function OperationsPage({
     </main>
   );
 }
-
-/** Loading is never a valid zero-valued Operations projection. */

package/templates/.agents/dashboard/modules/operations/src/react/OperationsPageOverview.tsx

@@ -25,6 +25,7 @@ export function OperationsPageOverview({
   locale,
   onOpenTask,
   onOpenDocument,
+  onOpenMacro,
   onLoadStatus,
   statusPage,
   onLoadStatusPage,
@@ -55,6 +56,7 @@ export function OperationsPageOverview({
   locale: OperationsLocale;
   onOpenTask: OverviewProps["onOpenTask"];
   onOpenDocument: OverviewProps["onOpenDocument"];
+  onOpenMacro: OverviewProps["onOpenMacro"];
   onLoadStatus: OverviewProps["onLoadStatus"];
   statusPage: OverviewProps["statusPage"];
   onLoadStatusPage: OverviewProps["onLoadStatusPage"];
@@ -96,6 +98,7 @@ export function OperationsPageOverview({
         }}
         onOpenTask={onOpenTask}
         onOpenDocument={onOpenDocument}
+        onOpenMacro={onOpenMacro}
         onLoadStatus={onLoadStatus}
         statusPage={statusPage}
         onLoadStatusPage={onLoadStatusPage}

package/templates/.agents/dashboard/modules/operations/src/react/operations-overview-contract.ts

@@ -0,0 +1,51 @@
+import type { OperationsProjection } from "../contracts.js";
+import type { OperationDatePreset, OperationDateRange } from "./operation-date-range.js";
+import type {
+  FactualCostFact,
+  OverviewClassification,
+  OverviewClassificationPage,
+  OverviewStatusKind,
+  OverviewStatusPage,
+} from "./operations-page-contract.js";
+import type { OperationsLocale } from "./status-labels.js";
+import type { WorkStage } from "./work-board-model.js";
+export interface OperationsOverviewProps {
+  currency: "BRL" | "USD";
+  data: OperationsProjection;
+  /** App-controlled range paired with datePreset; retained by Page while loading. */
+  dateRange?: OperationDateRange;
+  datePreset: OperationDatePreset;
+  locale: OperationsLocale;
+  onDatePresetChange: (preset: OperationDatePreset) => void;
+  onOpenTask: (taskId: string) => Promise<boolean>;
+  onOpenDocument: (kind: "prd" | "spec", id: string) => void;
+  onOpenMacro: (kind: "prd" | "spec", id: string) => void;
+  onLoadStatus?: ((stage: WorkStage, kind: OverviewStatusKind, offset: number) => void) | undefined;
+  statusPage?:
+    | ((stage: WorkStage, kind: OverviewStatusKind) => OverviewStatusPage | undefined)
+    | undefined;
+  onLoadStatusPage?:
+    | ((stage: WorkStage, kind: OverviewStatusKind, offset: number) => void)
+    | undefined;
+  classificationPage?:
+    | ((
+        kind: OverviewStatusKind,
+        classification: OverviewClassification,
+      ) => OverviewClassificationPage | undefined)
+    | undefined;
+  onLoadClassificationPage?:
+    | ((kind: OverviewStatusKind, classification: OverviewClassification, offset: number) => void)
+    | undefined;
+  onLoadMacroMetrics?: (() => void) | undefined;
+  prds?: OperationsProjection["prds"];
+  runs?: OperationsProjection["runs"];
+  specs?: OperationsProjection["specs"];
+  tasks?: OperationsProjection["tasks"];
+  /** Factual Cost Monitor snapshot total for the selected locale/currency. */
+  factualCostTotal?: number | null | undefined;
+  /** Measurement completeness for the matching Cost Monitor snapshot. */
+  factualCostFact?: FactualCostFact | undefined;
+  costLoading?: boolean | undefined;
+  resolveRunCost?: ((runId: string) => number | null) | undefined;
+  includeLegacyEffort?: boolean;
+}

package/templates/.agents/dashboard/modules/operations/src/react/operations-overview-period-filter.test.ts

@@ -118,7 +118,11 @@ describe("overview period filter", () => {
     const periods = readFileSync(new URL("PeriodSummaryTable.tsx", import.meta.url), "utf8");
     const costCard = readFileSync(new URL("OverviewCostKpi.tsx", import.meta.url), "utf8");
 
-    expect(source).toContain('currency: "BRL" | "USD"');
+    const contract = readFileSync(
+      new URL("operations-overview-contract.ts", import.meta.url),
+      "utf8",
+    );
+    expect(contract).toContain('currency: "BRL" | "USD"');
     expect(source).toContain("const selectedCurrencyCost =");
     expect(source).toContain("formatCurrency(value, currency, locale)");
     expect(source).toContain("<OverviewCostKpi");
@@ -188,13 +192,18 @@ describe("overview period filter", () => {
 
   it("resets the real List navigation callback on re-entry without changing Kanban routing", () => {
     const source = readFileSync(new URL("OperationsPage.tsx", import.meta.url), "utf8");
+    const filterSync = readFileSync(
+      new URL("use-operations-filter-sync.ts", import.meta.url),
+      "utf8",
+    );
 
     expect(workListTypeOnViewChange("work-list")).toBe("all");
     expect(workListTypeOnViewChange("work-kanban")).toBeNull();
     expect(source).toContain("const nextWorkListType = workListTypeOnViewChange(nextView)");
     expect(source).toContain("onWorkListTypeChange?.(nextWorkListType)");
-    expect(source).toContain('if (view === "work-kanban") onBoardFiltersChange?.(filters)');
-    expect(source).toContain("else onWorkListFiltersChange?.(filters)");
+    expect(source).toContain("useOperationsFilterSync({");
+    expect(filterSync).toContain('if (view === "work-kanban") onBoardFiltersChange?.(filters)');
+    expect(filterSync).toContain("else onWorkListFiltersChange?.(filters)");
   });
 
   it("scopes task and macro metrics to the active overview entity kind", () => {

package/templates/.agents/dashboard/modules/operations/src/react/operations-page-contract.ts

@@ -103,6 +103,7 @@ export interface OperationsPageProps {
   locale: OperationsLocale;
   onLocaleChange: (locale: OperationsLocale) => void;
   onOpenDocument: (kind: "prd" | "spec", id: string) => void;
+  onOpenMacro: (kind: "prd" | "spec", id: string) => void;
   onOpenTask: (taskId: string) => Promise<boolean>;
   onPriorityChange: (itemIds: readonly string[]) => Promise<void>;
   onDetailDataRequest?: (view: OperationsView) => void;

package/templates/.agents/dashboard/modules/operations/src/react/use-operations-default-range.ts

@@ -0,0 +1,16 @@
+import { useMemo } from "react";
+import { factualCostDateRange, initialOperationsDateRange } from "./operation-date-range.js";
+import type { OperationsPageProps } from "./operations-page-contract.js";
+export function useOperationsDefaultRange(
+  data: OperationsPageProps["data"],
+  factualCostPeriods: OperationsPageProps["factualCostPeriods"],
+) {
+  const defaultDateRange = useMemo(() => {
+    const operationsRange = initialOperationsDateRange(
+      data.tasks,
+      Object.keys(data.summary.periods?.daily ?? {}),
+    );
+    return factualCostDateRange(factualCostPeriods?.day, operationsRange);
+  }, [data.summary.periods, data.tasks, factualCostPeriods?.day]);
+  return defaultDateRange;
+}

package/templates/.agents/dashboard/modules/operations/src/react/use-operations-filter-sync.ts

@@ -0,0 +1,66 @@
+import { useEffect } from "react";
+import type { OperationsPageProps } from "./operations-page-contract.js";
+import type { OperationsView } from "./operations-page-filters.js";
+import type { TaskOrigin } from "./task-origin.js";
+
+interface OperationsFilterSyncInput {
+  loading: boolean;
+  view: OperationsView;
+  query: string;
+  statusFilter: string;
+  riskFilter: string;
+  originFilter: TaskOrigin | "";
+  onBoardFiltersChange: OperationsPageProps["onBoardFiltersChange"];
+  onWorkListFiltersChange: OperationsPageProps["onWorkListFiltersChange"];
+  onEntityFiltersChange: OperationsPageProps["onEntityFiltersChange"];
+}
+
+export function useOperationsFilterSync({
+  loading,
+  view,
+  query,
+  statusFilter,
+  riskFilter,
+  originFilter,
+  onBoardFiltersChange,
+  onWorkListFiltersChange,
+  onEntityFiltersChange,
+}: OperationsFilterSyncInput): void {
+  useEffect(() => {
+    // The parent replaces the aggregate snapshot while a period transition is
+    // loading. Defer paged entity hydration until that replacement is stable,
+    // otherwise the aggregate response can overwrite a newer entity page.
+    if (loading) return;
+    if (view === "work-kanban" || view === "work-list") {
+      const timeout = window.setTimeout(() => {
+        const filters = {
+          query,
+          status: statusFilter,
+          risk: riskFilter,
+          origin: originFilter,
+        };
+        if (view === "work-kanban") onBoardFiltersChange?.(filters);
+        else onWorkListFiltersChange?.(filters);
+      }, 180);
+      return () => window.clearTimeout(timeout);
+    }
+    if (!["runs", "conversations", "executions", "changes", "decisions"].includes(view)) return;
+    const timeout = window.setTimeout(() => {
+      onEntityFiltersChange?.(
+        view as "runs" | "conversations" | "executions" | "changes" | "decisions",
+        { query, status: statusFilter, risk: riskFilter },
+      );
+    }, 180);
+    return () => window.clearTimeout(timeout);
+  }, [
+    onBoardFiltersChange,
+    onWorkListFiltersChange,
+    onEntityFiltersChange,
+    loading,
+    originFilter,
+    query,
+    riskFilter,
+    statusFilter,
+    view,
+  ]);
+}

package/templates/.agents/dashboard/modules/traceability/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaip-ai/dashboard-traceability",
-  "version": "4.9.0",
+  "version": "5.1.0",
   "private": true,
   "type": "module",
   "exports": {

package/templates/.agents/dashboard/packages/branding/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaip-ai/dashboard-branding",
-  "version": "4.9.0",
+  "version": "5.1.0",
   "private": true,
   "type": "module",
   "exports": {

package/templates/.agents/dashboard/packages/contracts/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaip-ai/dashboard-contracts",
-  "version": "4.9.0",
+  "version": "5.1.0",
   "private": true,
   "type": "module",
   "exports": {

package/templates/.agents/dashboard/packages/data-export/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaip-ai/dashboard-data-export",
-  "version": "4.9.0",
+  "version": "5.1.0",
   "private": true,
   "type": "module",
   "exports": {

package/templates/.agents/dashboard/packages/local-runtime/dashboard-build-fingerprint.mjs

@@ -0,0 +1,87 @@
+import { createHash } from "node:crypto";
+import { mkdir, readdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { dashboardBuildTargets, workspaceRoot } from "./start-dashboard-paths.mjs";
+
+export async function contentFingerprint(paths, excluded = [], root = workspaceRoot) {
+  const entries = new Map();
+  async function visit(path) {
+    const key = relative(root, path).replaceAll("\\", "/");
+    const name = path.replaceAll("\\", "/").split("/").at(-1);
+    if (
+      ["node_modules", ".turbo"].includes(name) ||
+      /\.(test|spec)\./.test(name) ||
+      excluded.some((part) => `/${key}/`.includes(part))
+    )
+      return;
+    const details = await stat(path).catch((error) => {
+      if (error.code === "ENOENT") return null;
+      throw error;
+    });
+    if (!details) {
+      entries.set(key, "missing");
+      return;
+    }
+    if (details.isDirectory()) {
+      entries.set(`${key}/`, "directory");
+      for (const entry of await readdir(path)) await visit(join(path, entry));
+    } else
+      entries.set(
+        key,
+        createHash("sha256")
+          .update(await readFile(path))
+          .digest("hex"),
+      );
+  }
+  for (const path of paths) await visit(path);
+  return createHash("sha256")
+    .update(JSON.stringify([...entries].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))))
+    .digest("hex");
+}
+
+const receiptPath = (name, root) => resolve(root, ".local/dashboard-build", `${name}.json`);
+export const sourceFingerprint = (target, root = workspaceRoot) =>
+  contentFingerprint(target.sourceRoots, ["/dist/", ...target.excludedSourcePaths], root);
+const outputFingerprint = (target, root) =>
+  contentFingerprint(target.outputRoots ?? target.artifacts, [], root);
+
+export async function inspectBuildFingerprint(name, target, root = workspaceRoot) {
+  const receipt = await readFile(receiptPath(name, root), "utf8")
+    .then(JSON.parse)
+    .catch(() => null);
+  if (receipt?.version !== 1) return false;
+  return (
+    receipt.source === (await sourceFingerprint(target, root)) &&
+    receipt.output === (await outputFingerprint(target, root))
+  );
+}
+
+export async function recordDashboardBuild(
+  name,
+  before,
+  target = dashboardBuildTargets[name],
+  root = workspaceRoot,
+) {
+  const source = await sourceFingerprint(target, root);
+  if (source !== before)
+    throw new Error(
+      `Dashboard ${name} inputs changed during build; no reusable receipt was recorded`,
+    );
+  for (const path of target.artifacts) await stat(path);
+  const receipt = { version: 1, source, output: await outputFingerprint(target, root) };
+  const path = receiptPath(name, root);
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(receipt)}\n`);
+  await rename(temporary, path);
+}
+
+export async function dashboardReleaseFrozen(root = workspaceRoot) {
+  const text = await readFile(resolve(root, ".agents/config/release-cycle.json"), "utf8").catch(
+    (error) => {
+      if (error.code === "ENOENT") return null;
+      throw error;
+    },
+  );
+  return text !== null && JSON.parse(text).state === "frozen";
+}

package/templates/.agents/dashboard/packages/local-runtime/dashboard-build-fingerprint.test.mjs

@@ -0,0 +1,48 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, utimes, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "vitest";
+import {
+  inspectBuildFingerprint,
+  recordDashboardBuild,
+  sourceFingerprint,
+} from "./dashboard-build-fingerprint.mjs";
+import { refreshDashboardBuildTargets } from "./start-dashboard-build.mjs";
+
+test("build reuse follows bytes, includes missing/deleted inputs, and freezes without mutation", async (context) => {
+  const root = await mkdtemp(join(tmpdir(), "zaip-build-fingerprint-"));
+  context.onTestFinished(() => rm(root, { recursive: true, force: true }));
+  await mkdir(join(root, "src"));
+  const source = join(root, "src/readme.md"),
+    output = join(root, "bundle.js");
+  await writeFile(source, "help");
+  await writeFile(output, "bundle");
+  const target = { sourceRoots: [join(root, "src")], excludedSourcePaths: [], artifacts: [output] };
+  await recordDashboardBuild("fixture", await sourceFingerprint(target, root), target, root);
+  await utimes(source, new Date(), new Date(Date.now() + 60_000));
+  assert.equal(await inspectBuildFingerprint("fixture", target, root), true);
+  await writeFile(source, "new help");
+  assert.equal(await inspectBuildFingerprint("fixture", target, root), false);
+  const before = await sourceFingerprint(target, root);
+  await rm(source);
+  await assert.rejects(
+    recordDashboardBuild("fixture", before, target, root),
+    /changed during build/,
+  );
+  let builds = 0;
+  await assert.rejects(
+    refreshDashboardBuildTargets({
+      targets: { fixture: target },
+      frozen: true,
+      inspectTarget: async () => ({
+        missingArtifacts: [],
+        artifactsModifiedAt: 1,
+        sourcesModifiedAt: 2,
+      }),
+      runBuild: async () => builds++,
+    }),
+    /release is frozen/,
+  );
+  assert.equal(builds, 0);
+});