@zaip-ai/cli 2.2.0 → 3.0.0

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

@@ -0,0 +1,55 @@
+.project-settings-page,
+.project-settings-state {
+  color-scheme: light;
+  min-height: 100vh;
+  padding: clamp(20px, 4vw, 48px);
+  background: #f5f7fb;
+  color: #0f172a;
+}
+
+.project-settings-page form,
+.project-settings-state-card {
+  width: min(1440px, 100%);
+  margin-inline: auto;
+}
+
+.project-settings-state {
+  display: grid;
+  place-items: center;
+}
+
+.project-settings-state-card {
+  display: grid;
+  gap: 12px;
+  justify-items: center;
+  max-width: 420px;
+  border: 1px solid #dbe4ef;
+  border-radius: 24px;
+  padding: clamp(32px, 6vw, 48px);
+  background: #fff;
+  box-shadow: 0 18px 48px rgba(15, 23, 42, 0.08);
+  text-align: center;
+}
+
+.project-settings-loader {
+  width: 32px;
+  height: 32px;
+  border: 3px solid rgba(0, 176, 240, 0.18);
+  border-top-color: #00b0f0;
+  border-radius: 50%;
+  animation: project-settings-spin 0.8s linear infinite;
+}
+
+.project-settings-state-card h1 {
+  max-width: 18ch;
+  font-size: clamp(1.75rem, 5vw, 2.25rem);
+}
+
+.project-settings-state-error {
+  color: #b91c1c;
+}
+
+.project-settings-state-card button {
+  width: auto;
+  margin-top: 12px;
+}

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

@@ -34,9 +34,21 @@ const config: ProjectConfigSettings = {
 };
 
 describe("project settings form mapping", () => {
+  it.each([
+    "essential",
+    "balanced",
+    "persistent",
+  ] as const)("preserves autonomy %s without rewriting execution or assurance", (preset) => {
+    const source = { ...config, autonomy: { version: 1 as const, preset } };
+    const draft = projectSettingsDraft(source);
+    const payload = buildProjectSettingsPayload(source, draft.components, draft.otherOverrides);
+    expect(payload.autonomy).toEqual(source.autonomy);
+    expect(payload.execution).toEqual(source.execution);
+    expect(payload.assurance).toEqual(source.assurance);
+  });
   it("renders a canonical framework SemVer as a short major.minor label", () => {
-    expect(shortFrameworkVersion("2.2.0")).toBe("v2.0");
-    expect(shortFrameworkVersion("v2.2.0")).toBe("v2.0");
+    expect(shortFrameworkVersion("2.5.0")).toBe("v2.5");
+    expect(shortFrameworkVersion("v2.5.0")).toBe("v2.5");
     expect(shortFrameworkVersion("1.0")).toBeNull();
   });
 

package/templates/.agents/dashboard/apps/frontend/src/sao-paulo-day-rollover.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import {
+  millisecondsUntilNextSaoPauloDay,
+  rolloverOperationsPeriod,
+} from "./sao-paulo-day-rollover.js";
+
+describe("Sao Paulo day rollover", () => {
+  it("moves Today and Yesterday at the America/Sao_Paulo midnight boundary", () => {
+    const beforeMidnight = new Date("2026-09-08T02:59:59.000Z");
+    const afterMidnight = new Date("2026-09-08T03:00:01.000Z");
+    expect(
+      rolloverOperationsPeriod(
+        { preset: "today", range: { start: "x", end: "x" } },
+        beforeMidnight,
+      ),
+    ).toEqual({ preset: "today", range: { start: "2026-09-07", end: "2026-09-07" } });
+    expect(
+      rolloverOperationsPeriod(
+        { preset: "yesterday", range: { start: "x", end: "x" } },
+        afterMidnight,
+      ),
+    ).toEqual({ preset: "yesterday", range: { start: "2026-09-07", end: "2026-09-07" } });
+    expect(millisecondsUntilNextSaoPauloDay(beforeMidnight)).toBeGreaterThanOrEqual(1_000);
+    expect(millisecondsUntilNextSaoPauloDay(beforeMidnight)).toBeLessThan(1_100);
+  });
+
+  it("keeps custom bounds and renews the All Time display range", () => {
+    const now = new Date("2026-09-08T03:00:01.000Z");
+    const custom = { preset: "custom" as const, range: { start: "2026-08-01", end: "2026-08-02" } };
+    expect(rolloverOperationsPeriod(custom, now)).toBe(custom);
+    expect(rolloverOperationsPeriod({ preset: "all", range: custom.range }, now)).toEqual({
+      preset: "all",
+      range: { start: "2026-09-01", end: "2026-09-08" },
+    });
+  });
+});

package/templates/.agents/dashboard/apps/frontend/src/sao-paulo-day-rollover.ts

@@ -0,0 +1,30 @@
+import { saoPauloPeriodKey } from "@zaip-ai/dashboard-operations/contracts";
+import { dateRangeForPreset } from "@zaip-ai/dashboard-operations/react";
+import type { OperationsPeriodState } from "./operations-period.js";
+
+export function rolloverOperationsPeriod(
+  period: OperationsPeriodState,
+  now = new Date(),
+): OperationsPeriodState {
+  if (period.preset === "custom") return period;
+  if (period.preset === "all") {
+    return { ...period, range: dateRangeForPreset("this-month", now) };
+  }
+  return { ...period, range: dateRangeForPreset(period.preset, now) };
+}
+
+/** Schedule against the project calendar rather than the browser's local zone. */
+export function millisecondsUntilNextSaoPauloDay(now = new Date()): number {
+  const day = saoPauloPeriodKey(now.toISOString(), "day");
+  if (day === null) throw new RangeError("Invalid Sao Paulo day anchor");
+  let low = now.getTime();
+  let high = low + 30 * 60 * 60 * 1_000;
+  while (saoPauloPeriodKey(new Date(high).toISOString(), "day") === day)
+    high += 6 * 60 * 60 * 1_000;
+  while (high - low > 1) {
+    const middle = Math.floor((low + high) / 2);
+    if (saoPauloPeriodKey(new Date(middle).toISOString(), "day") === day) low = middle;
+    else high = middle;
+  }
+  return Math.max(1, high - now.getTime() + 25);
+}

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

@@ -42,14 +42,11 @@ describe("snapshot update banner semantics", () => {
   });
 
   it("presents a stale local snapshot as neutral status and reserves alert red for errors", () => {
-    const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
+    const app = readFileSync(new URL("./AppDashboardContent.tsx", import.meta.url), "utf8");
     const boundary = readFileSync(new URL("./AppLoadingBoundary.tsx", import.meta.url), "utf8");
     const overlays = readFileSync(new URL("./AppOverlays.tsx", import.meta.url), "utf8");
     const styles = readFileSync(new URL("./styles.css", import.meta.url), "utf8");
-    const snapshot = app.slice(
-      app.indexOf("const initialDataPending"),
-      app.indexOf("const renderedOperations"),
-    );
+    const snapshot = readFileSync(new URL("./use-snapshot-notice.tsx", import.meta.url), "utf8");
     const compactSnapshot = snapshot.replace(/\s+/g, " ");
     const error = app.slice(app.indexOf("{error ?"), app.indexOf("{/* Cost Monitor boundary"));
 

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

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { describe, expect, it } from "vitest";
+import { readAppCompositionSource } from "./__tests__/app-composition-support.js";
 import { isCurrentDashboardRequest, mergeBoardPages, needsAtomicCostSnapshot } from "./App.js";
 import { loadAtomicCostSnapshot } from "./snapshot-coherence.js";
 import {
@@ -35,7 +36,7 @@ describe("atomic Cost snapshot loading", () => {
   });
 
   it("keeps Cost out of quick Operations and fetches its narrow summary on entry", () => {
-    const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
+    const app = readAppCompositionSource();
     expect(app).not.toContain("api.snapshot(currency, period)");
     expect(app).toContain('api.costMonitor(currency, period, "summary", controller.signal)');
     expect(app).not.toContain("dailyCostSeed(currency, period)");
@@ -51,10 +52,9 @@ describe("atomic Cost snapshot loading", () => {
   });
 
   it("mounts Cost immediately and lets its Daily page own the only initial request", () => {
-    const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
-    const costSelection = app.slice(
-      app.indexOf('if (nextView === "cost-monitor")'),
-      app.indexOf('if (nextView === "traceability")'),
+    const costSelection = readFileSync(
+      new URL("./dashboard-view-actions.ts", import.meta.url),
+      "utf8",
     );
     expect(costSelection).toContain("loadCostSummary()");
     expect(costSelection).not.toContain("loadCostDetails");
@@ -62,10 +62,10 @@ describe("atomic Cost snapshot loading", () => {
   });
 
   it("never blocks the dashboard or starts a full snapshot for a paged Cost request", () => {
-    const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
+    const app = readAppCompositionSource();
     const globalGate = app.slice(
-      app.indexOf("const globalLoadingPending"),
-      app.indexOf("const renderedOperations"),
+      app.indexOf("globalLoadingPending:"),
+      app.indexOf("snapshotNotice:"),
     );
     expect(app).toContain("const [, setCostSurfaceLoading] = useState(false);");
     expect(globalGate).not.toContain("costSurfaceLoading");
@@ -76,7 +76,7 @@ describe("atomic Cost snapshot loading", () => {
   });
 
   it("does not request Cost Monitor while the initial route is Operations", () => {
-    const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
+    const app = readAppCompositionSource();
     const initialLoad = app.slice(
       app.indexOf("const refresh = useCallback"),
       app.indexOf("const loadOperationsDetails"),
@@ -88,15 +88,15 @@ describe("atomic Cost snapshot loading", () => {
   });
 
   it("retries a failed Cost snapshot through its summary request", () => {
-    const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
-    const retry = app.slice(app.indexOf("const retryLastLoad"), app.indexOf("const setupRoute"));
+    const app = readAppCompositionSource();
+    const retry = readFileSync(new URL("./dashboard-retry.ts", import.meta.url), "utf8");
 
     expect(retry).toContain('if (failedArea === "costs") void loadCostSummary();');
     expect(retry).not.toContain("loadCosts");
   });
 
   it("does not prefetch a newer Operations snapshot in the background", () => {
-    const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
+    const app = readAppCompositionSource();
     const effects = readFileSync(new URL("./use-app-effects.ts", import.meta.url), "utf8");
     const costLoaders = readFileSync(new URL("./use-app-cost-loaders.ts", import.meta.url), "utf8");
     expect(app).not.toContain("const costPrefetch = useRef");
@@ -204,6 +204,7 @@ describe("atomic Cost snapshot loading", () => {
       "isCommittedSnapshotRevision(ready.snapshot_state, ready.snapshot_revision)",
     );
     expect(effects).toContain("settleSnapshotRevisionRefresh({");
+    expect(effects).toContain("if (succeeded) setSnapshotUpdating(false);");
     expect(effects).toContain(
       "snapshotRevisionPollDelay(document.visibilityState, consecutiveFailures)",
     );
@@ -212,13 +213,23 @@ describe("atomic Cost snapshot loading", () => {
   });
 
   it("does not reconcile open work automatically", () => {
-    const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
+    const app = readAppCompositionSource();
     expect(app).not.toContain("startupReconciliation");
     expect(app).toContain("await refresh(false, reconcileOpenWork, !reconcileOpenWork)");
   });
 
+  it("uses only materialized positive-token telemetry for the Atualizado header", () => {
+    const app = readAppCompositionSource();
+    // A file rebuild or task lifecycle event is not token collection. The
+    // header remains absent until the committed snapshot carries positive-token
+    // effective usage, whether it arrives through a regular, reconciliation,
+    // or explicit projection refresh.
+    expect(app).toContain("projection.summary.latest_token_collected_at ?? null");
+    expect(app).toContain("snapshot.projection.latest_token_collected_at ?? null");
+  });
+
   it("removes the global Cost detail request and keeps stale request guards", () => {
-    const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
+    const app = readAppCompositionSource();
     const costPage = readFileSync(
       new URL("../../../modules/cost-monitor/src/react/CostMonitorPage.tsx", import.meta.url),
       "utf8",
@@ -252,7 +263,7 @@ describe("atomic Cost snapshot loading", () => {
     });
     expect(afterPeriodChange).toEqual({ costs: null, activeExport: null });
 
-    const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
+    const app = readAppCompositionSource();
     const periodChange = app.slice(
       app.indexOf("onDateChange={(preset, range) => {"),
       app.indexOf("settings={"),
@@ -266,7 +277,7 @@ describe("atomic Cost snapshot loading", () => {
       periodChange.lastIndexOf("setOperationsPeriod(nextPeriod);"),
     );
     expect(periodChange).toContain(
-      "isAllTimeDisplayRangeChange(operationsPeriodRef.current, nextPeriod)",
+      "isSameOperationsRequestPeriod(operationsPeriodRef.current, nextPeriod)",
     );
     expect(periodChange).toContain("setOperationsLoading(true);");
     expect(periodChange).toContain('setLoadingArea("operations");');
@@ -274,7 +285,7 @@ describe("atomic Cost snapshot loading", () => {
   });
 
   it("owns the rendered Operations period in App and routes date changes back to its request state", () => {
-    const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
+    const app = readAppCompositionSource();
     const operationsPage = app.slice(app.indexOf("<OperationsPage"), app.indexOf("<AppOverlays"));
 
     expect(operationsPage).toContain("datePreset={operationsPeriod.preset}");
@@ -284,7 +295,7 @@ describe("atomic Cost snapshot loading", () => {
   });
 
   it("keeps detail hydration stable when the quick Operations projection updates", () => {
-    const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
+    const app = readAppCompositionSource();
     const detailsLoader = app.slice(
       app.indexOf("const loadOperationsDetails"),
       app.indexOf("const loadMoreBoard"),
@@ -296,7 +307,7 @@ describe("atomic Cost snapshot loading", () => {
   });
 
   it("loads the compact Operations projection before detail data", () => {
-    const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
+    const app = readAppCompositionSource();
     const initialLoad = app.slice(
       app.indexOf("const refresh = useCallback"),
       app.indexOf("const loadOperationsDetails"),
@@ -313,7 +324,7 @@ describe("atomic Cost snapshot loading", () => {
   });
 
   it("defers bounded work-board hydration until after the quick first paint", () => {
-    const app = readFileSync(new URL("./App.tsx", import.meta.url), "utf8");
+    const app = readAppCompositionSource();
     const boardHydration = app.slice(
       app.indexOf('if (dashboardView !== "operations" || operations === null) return;'),
       app.indexOf("const loadCostDetails"),

package/templates/.agents/dashboard/apps/frontend/src/traceability-task-pagination.ts

@@ -1,5 +1,4 @@
 import type { OperationsProjection } from "@zaip-ai/dashboard-operations/contracts";
-import type { OperationsBoardPage } from "./dashboard-api.js";
 
 /** The selector is a navigation aid, not a full task export. */
 export const traceabilityTaskPageSize = 10;
@@ -12,7 +11,7 @@ export function appendTraceabilityTaskPage({
   tasks,
 }: {
   cursor: TraceabilityTaskCursor;
-  page: OperationsBoardPage;
+  page: { tasks: OperationsProjection["tasks"]; total: number };
   tasks: OperationsProjection["tasks"];
 }): { cursor: TraceabilityTaskCursor; tasks: OperationsProjection["tasks"] } {
   const tasksById = new Map(tasks.map((task) => [task.id, task]));

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

@@ -10,12 +10,15 @@ import {
 describe("daily Cost Monitor continuous pagination", () => {
   it("uses cost_monitor_daily as a 30-day direct pager across months and keeps full-filter totals", async () => {
     const calls: Array<{ view: string; range: unknown; page: Record<string, unknown> }> = [];
+    const average = { tasks: 5, specs: 2, prds: 1, durationMs: 1000, tokens: 50, cost: 10 };
+    const periodAverages = { BRL: average, USD: { ...average, cost: 2 } };
     const api = {
       sqliteViewPage: async (view: string, range: unknown, page: Record<string, unknown>) => {
         calls.push({ view, range, page });
         if (page.offset === 0) {
           return {
             offset: 0,
+            period_averages: periodAverages,
             limit: 30,
             total_count: 35,
             has_more: true,
@@ -34,6 +37,7 @@ describe("daily Cost Monitor continuous pagination", () => {
         }
         return {
           offset: 30,
+          period_averages: periodAverages,
           limit: 30,
           total_count: 35,
           has_more: false,
@@ -83,6 +87,8 @@ describe("daily Cost Monitor continuous pagination", () => {
       filters,
     });
 
+    expect(firstPage.period_averages).toEqual(periodAverages);
+    expect(secondPage.period_averages).toEqual(periodAverages);
     expect(calls).toEqual([
       {
         view: "cost_monitor_daily",

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

@@ -90,6 +90,7 @@ export async function loadSqliteCostGroupPage(
       total_count: page.total_count,
       has_more: page.has_more,
       rows: page.rows.map(adaptSqliteCostGroup),
+      ...(page.period_averages === undefined ? {} : { period_averages: page.period_averages }),
       ...(page.totals === undefined ? {} : { totals: adaptSqliteCostGroup(page.totals) }),
     };
   }
@@ -114,6 +115,7 @@ export async function loadSqliteCostGroupPage(
     total_count: page.total_count,
     has_more: page.has_more,
     rows: page.rows.map(adaptSqliteCostGroup),
+    ...(page.period_averages === undefined ? {} : { period_averages: page.period_averages }),
     ...(page.totals === undefined ? {} : { totals: adaptSqliteCostGroup(page.totals) }),
   };
 }

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

@@ -62,6 +62,7 @@ export function isCommittedSnapshotRevision(
   );
 }
 
+/** A changed immutable revision is usable even while its successor is building. */
 export function settleSnapshotRevisionRefresh({
   observedRevision,
   pendingRevision,
@@ -248,6 +249,10 @@ export function useAppEffects({
       // lifecycle reconciliation from a tab that happened to stay open.
       void refresh(false, false, false, true)
         .then((succeeded) => {
+          // Do not settle an updating banner merely because `/ready` observed
+          // a new hash. Settle it only after the tab has loaded that committed
+          // immutable generation successfully.
+          if (succeeded) setSnapshotUpdating(false);
           const settled = settleSnapshotRevisionRefresh({
             observedRevision: observedSnapshotRevision.current,
             pendingRevision: pendingSnapshotRevisionRefresh.current,
@@ -281,6 +286,9 @@ export function useAppEffects({
             observedSnapshotRevision.current = ready.snapshot_revision;
           }
           if (shouldRefreshForSnapshotRevision(previousRevision, ready.snapshot_revision)) {
+            // `updating` can describe a later rebuild. The revision in this
+            // response is already immutable; `refreshChangedRevision` settles
+            // the banner after its GET has loaded that generation.
             pendingSnapshotRevisionRefresh.current = ready.snapshot_revision;
             refreshChangedRevision();
           }
@@ -301,7 +309,7 @@ export function useAppEffects({
       cancelled = true;
       if (timeout !== null) window.clearTimeout(timeout);
     };
-  }, [api, refresh]);
+  }, [api, refresh, setSnapshotUpdating]);
 
   useEffect(() => {
     if (

package/templates/.agents/dashboard/apps/frontend/src/use-app-trace-documents.ts

@@ -65,7 +65,9 @@ export function useAppTraceDocuments({
         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,
+        // The detail response is authoritative; an earlier quick card may still
+        // carry a partial/default progress value during hydration.
+        task_progress: loadedTrace.task_progress ?? cardTask?.progress ?? 0,
       });
       return true;
     } catch (cause) {

package/templates/.agents/dashboard/apps/frontend/src/use-app-trace-task-pagination.ts

@@ -0,0 +1,66 @@
+import type { OperationsProjection } from "@zaip-ai/dashboard-operations/contracts";
+import {
+  type Dispatch,
+  type SetStateAction,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+import type { DashboardApiClient } from "./dashboard-api.js";
+import {
+  appendTraceabilityTaskPage,
+  traceabilityTaskPageSize,
+} from "./traceability-task-pagination.js";
+export function useAppTraceTaskPagination(
+  api: DashboardApiClient,
+  traceTasks: OperationsProjection["tasks"],
+  setTraceTasks: Dispatch<SetStateAction<OperationsProjection["tasks"]>>,
+) {
+  const traceTasksRef = useRef(traceTasks);
+  const traceTaskCursorRef = useRef({ offset: 0, stageIndex: 0 });
+  const traceTasksLoadingRef = useRef(false);
+  const [traceTasksHasMore, setTraceTasksHasMore] = useState(false);
+  const [traceTasksLoading, setTraceTasksLoading] = useState(false);
+  useEffect(() => {
+    traceTasksRef.current = traceTasks;
+  }, [traceTasks]);
+  const loadMoreTraceTasks = useCallback(
+    async (loadAll = false, reset = false): Promise<OperationsProjection["tasks"]> => {
+      if (traceTasksLoadingRef.current) return traceTasksRef.current;
+      if (reset) {
+        traceTaskCursorRef.current = { offset: 0, stageIndex: 0 };
+        traceTasksRef.current = [];
+        setTraceTasks([]);
+        setTraceTasksHasMore(true);
+      }
+      if (traceTaskCursorRef.current.stageIndex >= 1) return traceTasksRef.current;
+
+      traceTasksLoadingRef.current = true;
+      setTraceTasksLoading(true);
+      try {
+        do {
+          const cursor = traceTaskCursorRef.current;
+          const page = await api.traceabilityTasks(cursor.offset, traceabilityTaskPageSize);
+          const updated = appendTraceabilityTaskPage({
+            cursor,
+            page,
+            tasks: traceTasksRef.current,
+          });
+          traceTasksRef.current = updated.tasks;
+          setTraceTasks(traceTasksRef.current);
+          traceTaskCursorRef.current = updated.cursor;
+          if (page.tasks.length > 0 && !loadAll) break;
+        } while (traceTaskCursorRef.current.stageIndex < 1);
+        setTraceTasksHasMore(traceTaskCursorRef.current.stageIndex < 1);
+        return traceTasksRef.current;
+      } finally {
+        traceTasksLoadingRef.current = false;
+        setTraceTasksLoading(false);
+      }
+    },
+    [api, setTraceTasks],
+  );
+
+  return { loadMoreTraceTasks, traceTasksHasMore, traceTasksLoading };
+}