@zaip-ai/cli 2.2.0 → 3.0.0

package/templates/.agents/dashboard/modules/cost-monitor/src/react/cost-monitor-page-selectors.ts

@@ -0,0 +1,49 @@
+import type { CostMonitorProjection } from "../contracts.js";
+import type { CostFilterState } from "./CostFilters.js";
+import type { CostView } from "./cost-monitor-views.js";
+
+/** The overview is a summary surface, not an exportable table view. */
+export function isCostViewExportEligible(view: CostView): boolean {
+  return view !== "overview";
+}
+
+/** Developers has no local provider/model filter contract. In the embedded
+ * all-time surface, do not let those residual UI filters narrow it to month. */
+export function resolveDeveloperAttributionRange({
+  embedded,
+  globalDateRange,
+  runPageRange,
+}: {
+  embedded: boolean;
+  globalDateRange?: { start: string; end: string };
+  runPageRange?: { from: string; to: string };
+}): { from: string; to: string } | undefined {
+  return embedded && globalDateRange === undefined ? undefined : runPageRange;
+}
+
+/**
+ * The Cost period request filters Runs, while Operations is the global snapshot
+ * used for shared entity detail. Keep the Executions tab on that same active
+ * Run population instead of accidentally showing an unfiltered empty/stale
+ * Operations table.
+ */
+export function visibleExecutionRows<T extends { id: string }>(
+  executions: readonly T[],
+  rows: readonly Pick<CostMonitorProjection["runs"][number], "execution_id">[],
+): T[] {
+  const visibleIds = new Set(
+    rows.flatMap((row) => (row.execution_id === null ? [] : [row.execution_id])),
+  );
+  return executions.filter((execution) => visibleIds.has(execution.id));
+}
+
+/** Only filters represented by the partial Runs endpoint may use page-only data. */
+export function isServerCostRunPagingEligible(filters: CostFilterState, globalQuery = ""): boolean {
+  return (
+    (globalQuery === "" || filters.query === "") &&
+    filters.priority === "" &&
+    filters.risk === "" &&
+    filters.origin === "" &&
+    filters.workType === ""
+  );
+}

package/templates/.agents/dashboard/modules/cost-monitor/src/react/cost-monitor-summary.ts

@@ -5,6 +5,7 @@ import {
 } from "@zaip-ai/dashboard-operations/contracts";
 import {
   aggregateDurationCoverage,
+  averageCompleteCost,
   type CostGroupRow,
   type CostMonitorProjection,
   type CostRunRow,
@@ -120,8 +121,8 @@ export function summarizeCostRows(
     estimated_brl: sumKnown(rows.map((row) => row.estimated_brl)),
     recorded_usd: sumKnown(rows.map((row) => row.recorded_usd)),
     recorded_brl: sumKnown(rows.map((row) => row.recorded_brl)),
-    average_run_cost_usd: average(rows.map((row) => row.estimated_usd)),
-    average_run_cost_brl: average(rows.map((row) => row.estimated_brl)),
+    average_run_cost_usd: averageCompleteCost(rows.map((row) => row.estimated_usd)),
+    average_run_cost_brl: averageCompleteCost(rows.map((row) => row.estimated_brl)),
     average_run_duration_ms: average(durationContributors(rows).map((row) => row.duration_ms)),
     known_tokens_per_cycle: knownCycles === 0 ? null : knownTokens / knownCycles,
     top_10_token_share: knownTokens === 0 ? null : top10Tokens / knownTokens,

package/templates/.agents/dashboard/modules/cost-monitor/src/react/cost-table-formatters.ts

@@ -0,0 +1,115 @@
+import { formatCompactNumber, formatCurrency, formatDurationMs } from "@zaip-ai/dashboard-ui";
+import type { CostRunRow, DurationCoverage } from "../contracts.js";
+import type { CostCurrency, CostLocale } from "./cost-monitor-copy.js";
+import {
+  formatBrlRate,
+  formatMultiplierPair,
+  formatRate,
+  formatUsd,
+} from "./cost-table-presentation.js";
+
+export function displayCostGroupLabel(label: string, locale: CostLocale): string {
+  const normalized = label.trim().toLowerCase();
+  return normalized.length === 0 || normalized === "unknown"
+    ? locale === "pt-BR"
+      ? "Sem modelo/provedor atribuído"
+      : "No model/provider assigned"
+    : label;
+}
+
+export function formatAuditableNumber(value: number | null, locale: CostLocale): string {
+  return new Intl.NumberFormat(locale, { maximumFractionDigits: 0 }).format(value ?? 0);
+}
+
+export function formatFactualCount(value: number | null, locale: CostLocale): string {
+  return value === null
+    ? locale === "pt-BR"
+      ? "Indisponível"
+      : "Unavailable"
+    : formatAuditableNumber(value, locale);
+}
+
+export function formatAuditableCompactNumber(value: number | null, locale: CostLocale): string {
+  return formatCompactNumber(value ?? 0, locale);
+}
+
+export function formatAuditableCurrency(
+  value: number | null,
+  currency: CostCurrency,
+  locale: CostLocale,
+): string {
+  if (value === null) return locale === "pt-BR" ? "Indispon\u00edvel" : "Unavailable";
+  return formatCurrency(value, currency, locale);
+}
+
+export function formatAuditableDuration(value: number | null, locale: CostLocale): string {
+  if (value === null) return locale === "pt-BR" ? "Indisponível" : "Unavailable";
+  return value === 0 ? "0" : formatDurationMs(value, locale);
+}
+
+export const formatInvocationNumber = (value: number | null, locale: CostLocale) =>
+  formatAuditableNumber(value, locale);
+export const formatInvocationCurrency = (
+  value: number | null,
+  currency: CostCurrency,
+  locale: CostLocale,
+) => formatAuditableCurrency(value, currency, locale);
+export const formatInvocationDuration = (value: number | null, locale: CostLocale) =>
+  formatAuditableDuration(value, locale);
+export const formatInvocationRate = (value: number | null, locale: CostLocale) =>
+  formatRate(value, locale);
+export const formatInvocationUsd = (value: number | null, locale: CostLocale) =>
+  formatUsd(value, locale);
+export const formatInvocationBrlRate = (value: number | null, locale: CostLocale) =>
+  formatBrlRate(value, locale);
+export const formatInvocationMultiplierPair = (
+  input: number | null,
+  output: number | null,
+  locale: CostLocale,
+) => formatMultiplierPair(input, output, locale);
+
+export function formatDurationCoverage(value: DurationCoverage, locale: CostLocale): string {
+  // `known_sum` is a factual elapsed-time observation even when another
+  // activity in the population is unavailable.  Keep completeness and the
+  // unknown count as coverage metadata; hiding the known portion would turn a
+  // true observation into an indistinguishable absence.
+  if (value.known_sum <= 0 && !value.complete)
+    return locale === "pt-BR" ? "Indisponível" : "Unavailable";
+  return value.known_sum <= 0 ? "0" : formatDurationMs(value.known_sum, locale);
+}
+
+export function hasKnownDuration(value: DurationCoverage): boolean {
+  return value.known_sum > 0 || value.coverage_ratio > 0;
+}
+
+export function formatTokenBackedDuration(
+  value: DurationCoverage,
+  _totalTokens: number | null,
+  locale: CostLocale,
+): string {
+  // Token presence is a financial observation, not evidence of elapsed time.
+  return formatDurationCoverage(value, locale);
+}
+
+export function costRunsFooterLabel(locale: CostLocale, pageOnly: boolean): string {
+  if (!pageOnly) return locale === "pt-BR" ? "Total" : "Total";
+  return locale === "pt-BR" ? "Subtotal da página" : "Page subtotal";
+}
+
+/** Keeps table ordering tied to the raw monetary value, not its localized label. */
+export function sortCostValue(
+  currency: CostCurrency,
+  brl: number | null,
+  usd: number | null,
+): number | null {
+  return currency === "BRL" ? brl : usd;
+}
+
+export function runOriginBadge(row: Pick<CostRunRow, "prd_id" | "spec_id" | "task_id">): {
+  label: "PRD" | "SPEC" | "Tarefa avulsa";
+  tone: "prd" | "spec" | "task";
+} {
+  if (row.prd_id !== null) return { label: "PRD", tone: "prd" };
+  if (row.spec_id !== null) return { label: "SPEC", tone: "spec" };
+  return { label: "Tarefa avulsa", tone: "task" };
+}

package/templates/.agents/dashboard/modules/cost-monitor/src/react/period-cost-groups.ts

@@ -3,14 +3,7 @@ import type { CostGroupRow } from "../contracts.js";
 
 export type CostPeriodGranularity = "daily" | "monthly" | "annual";
 
-export interface CostPeriodAverages {
-  tasks: number | null;
-  specs: number | null;
-  prds: number | null;
-  durationMs: number | null;
-  tokens: number | null;
-  cost: number | null;
-}
+export { type CostPeriodAverages, summarizeCostPeriodAverages } from "../period-averages.js";
 
 interface PeriodEntities {
   prds: readonly { created_at: string | null }[];
@@ -122,40 +115,6 @@ export function enrichPeriodCostGroups(
   return [...rows.values()].sort((left, right) => right.key.localeCompare(left.key));
 }
 
-export function summarizeCostPeriodAverages(
-  rows: readonly CostGroupRow[],
-  currency: "BRL" | "USD",
-): CostPeriodAverages {
-  const divisor = rows.length;
-  return {
-    tasks:
-      divisor === 0 ? null : rows.reduce((sum, row) => sum + (row.task_count ?? 0), 0) / divisor,
-    specs:
-      divisor === 0 ? null : rows.reduce((sum, row) => sum + (row.spec_count ?? 0), 0) / divisor,
-    prds: divisor === 0 ? null : rows.reduce((sum, row) => sum + (row.prd_count ?? 0), 0) / divisor,
-    durationMs: averagePerPeriod(
-      rows.map((row) => row.duration_ms),
-      divisor,
-    ),
-    tokens: averageObserved(rows.map((row) => row.total_tokens)),
-    cost: averageObserved(
-      rows.map((row) => (currency === "BRL" ? row.estimated_brl : row.estimated_usd)),
-    ),
-  };
-}
-
-function averageObserved(values: readonly (number | null)[]): number | null {
-  const present = values.filter((value): value is number => value !== null);
-  return present.length === 0
-    ? null
-    : present.reduce((sum, value) => sum + value, 0) / present.length;
-}
-
-function averagePerPeriod(values: readonly (number | null)[], periodCount: number): number | null {
-  if (periodCount === 0) return null;
-  return values.reduce<number>((sum, value) => sum + (value ?? 0), 0) / periodCount;
-}
-
 function periodKey(value: string | null, granularity: CostPeriodGranularity): string | null {
   return saoPauloPeriodKey(
     value,

package/templates/.agents/dashboard/modules/cost-monitor/src/react/use-cost-group-page.ts

@@ -1,5 +1,5 @@
 import { useEffect, useRef, useState } from "react";
-import type { CostGroupRow } from "../contracts.js";
+import type { CostGroupRow, CostPeriodAverages } from "../contracts.js";
 import type { CostFilterState } from "./CostFilters.js";
 import type { CostLocale } from "./cost-monitor-copy.js";
 
@@ -26,6 +26,7 @@ export type CostGroupPage = {
   has_more: boolean;
   rows: readonly CostGroupRow[];
   totals?: CostGroupTotals;
+  period_averages?: Record<"BRL" | "USD", CostPeriodAverages>;
 };
 export type CostGroupFilters = CostFilterState;
 export type LoadCostGroupPage = (request: {

package/templates/.agents/dashboard/modules/cost-monitor/src/server/build-cost-monitor-projection.test-fixtures.ts

@@ -71,6 +71,7 @@ export function catalogWithInputRate(rate: number): PricingCatalog {
         output_per_million_usd: 0,
         reasoning_per_million_usd: 0,
         reasoning_billed_separately: false,
+        priority_long_context_supported: false,
         long_context_threshold_tokens: null,
         long_context_input_multiplier: 1,
         long_context_output_multiplier: 1,
@@ -102,6 +103,7 @@ export function gpt54Catalog(): PricingCatalog {
         priority_output_per_million_usd: 30,
         priority_reasoning_per_million_usd: 30,
         reasoning_billed_separately: false,
+        priority_long_context_supported: false,
         long_context_threshold_tokens: 272_000,
         long_context_input_multiplier: 2,
         long_context_output_multiplier: 1.5,

package/templates/.agents/dashboard/modules/cost-monitor/src/server/build-cost-monitor-projection.ts

@@ -15,6 +15,7 @@ import type {
 import { LEGACY_EFFORT_SNAPSHOT, saoPauloPeriodKey } from "@zaip-ai/dashboard-operations/contracts";
 import { includeConfiguredAgentGroups } from "../agent-groups.js";
 import {
+  averageCompleteCost,
   type CostMonitorProjection,
   type CostRunRow,
   durationAggregationRows,
@@ -215,8 +216,8 @@ export function buildCostMonitorProjection(
       recorded_brl: availableCurrencySum(
         tableRuns.map((run) => recordedRunsById.get(run.id)?.usage.total.cost.brl ?? null),
       ),
-      average_run_cost_usd: averageAvailable(rows.map((row) => row.estimated_usd)),
-      average_run_cost_brl: averageAvailable(rows.map((row) => row.estimated_brl)),
+      average_run_cost_usd: averageCompleteCost(rows.map((row) => row.estimated_usd)),
+      average_run_cost_brl: averageCompleteCost(rows.map((row) => row.estimated_brl)),
       average_run_duration_ms: averageAvailable(
         durationAggregationRows(rows).map((row) => row.duration_ms),
       ),

package/templates/.agents/dashboard/modules/cost-monitor/src/server/build-cost-summary-projection.ts

@@ -183,8 +183,14 @@ export function buildCostSummaryProjection(
       estimated_brl: brlTotal,
       recorded_usd: null,
       recorded_brl: null,
-      average_run_cost_usd: runCount === 0 || usdTotal === null ? null : usdTotal / runCount,
-      average_run_cost_brl: runCount === 0 || brlTotal === null ? null : brlTotal / runCount,
+      average_run_cost_usd:
+        runCount === 0 || usdTotal === null || coverage.usd !== runCount
+          ? null
+          : usdTotal / runCount,
+      average_run_cost_brl:
+        runCount === 0 || brlTotal === null || coverage.brl !== runCount
+          ? null
+          : brlTotal / runCount,
       // Legacy effort has no individual Run cardinality, so it is not a
       // legitimate contributor to an average per Run.
       average_run_duration_ms: observedDurationAverage,

package/templates/.agents/dashboard/modules/cost-monitor/src/server/index.ts

@@ -1,3 +1,4 @@
+export { summarizeCostPeriodAverages } from "../period-averages.js";
 export * from "./build-cost-monitor-projection.js";
 export * from "./build-cost-summary-projection.js";
 export * from "./run-telemetry.js";

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

@@ -1,6 +1,6 @@
 {
   "name": "@zaip-ai/dashboard-operations",
-  "version": "2.2.0",
+  "version": "3.0.0",
   "private": true,
   "type": "module",
   "exports": {

package/templates/.agents/dashboard/modules/operations/src/contracts.ts

@@ -544,6 +544,10 @@ export interface OperationsProjection extends ReadonlyV2Projection {
       partial?: boolean;
     };
     decisions: { human: number; agent: number };
+    /** Timestamp of the immutable projection currently displayed. */
+    projection_updated_at?: string | null;
+    /** Latest positive-token usage record in the materialized SQLite snapshot. */
+    latest_token_collected_at?: string | null;
     source_latest_at: string | null;
     quality: QualityProjection;
     reconciliation: {

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

@@ -0,0 +1,34 @@
+import type { DecisionProjection, RunProjection } from "../contracts.js";
+
+export function StatusBadge({ status }: { status: string }) {
+  return <span className={`operations-table-status is-${status}`}>{status}</span>;
+}
+
+export function RiskBadge({ risk }: { risk: string }) {
+  return <span className={`operations-table-risk is-${risk}`}>{risk}</span>;
+}
+
+export function EntryBadge({ entrypoint }: { entrypoint: RunProjection["entrypoint"] }) {
+  const label =
+    entrypoint === "prd"
+      ? "PRD"
+      : entrypoint === "spec"
+        ? "SPEC"
+        : entrypoint === "task"
+          ? "Tarefa"
+          : "Conversa";
+  return <span className={`operations-table-entry is-${entrypoint}`}>{label}</span>;
+}
+
+export function DecisionOriginBadge({ origin }: { origin: DecisionProjection["origin"] }) {
+  return <span className={`operations-table-decision-origin is-${origin}`}>{origin}</span>;
+}
+
+export function DecisionStageBadge({ scopeType }: { scopeType: DecisionProjection["scope_type"] }) {
+  const stage = scopeType === "change" ? "planning" : "execution";
+  return (
+    <span className={`operations-table-stage is-${stage}`}>
+      {stage === "planning" ? "Planejamento" : "Execução"}
+    </span>
+  );
+}

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

@@ -13,12 +13,7 @@ import type {
 } from "../contracts.js";
 import { buildConversationRows } from "./conversation-rows.js";
 import { EntityDetailsDialog } from "./EntityDetailsDialog.js";
-import {
-  displayedDuration,
-  formatDisplayedDuration,
-  formatOperationDuration,
-  operationalDurationMs,
-} from "./operation-duration.js";
+import { displayedDuration, formatDisplayedDuration } from "./operation-duration.js";
 import type { OperationsLocale } from "./status-labels.js";
 import { sortByDateDesc } from "./table-order.js";
 
@@ -784,35 +779,10 @@ export function DecisionTable({
   );
 }
 
-function StatusBadge({ status }: { status: string }) {
-  return <span className={`operations-table-status is-${status}`}>{status}</span>;
-}
-
-function RiskBadge({ risk }: { risk: string }) {
-  return <span className={`operations-table-risk is-${risk}`}>{risk}</span>;
-}
-
-function EntryBadge({ entrypoint }: { entrypoint: RunProjection["entrypoint"] }) {
-  const label =
-    entrypoint === "prd"
-      ? "PRD"
-      : entrypoint === "spec"
-        ? "SPEC"
-        : entrypoint === "task"
-          ? "Tarefa"
-          : "Conversa";
-  return <span className={`operations-table-entry is-${entrypoint}`}>{label}</span>;
-}
-
-function DecisionOriginBadge({ origin }: { origin: DecisionProjection["origin"] }) {
-  return <span className={`operations-table-decision-origin is-${origin}`}>{origin}</span>;
-}
-
-function DecisionStageBadge({ scopeType }: { scopeType: DecisionProjection["scope_type"] }) {
-  const stage = scopeType === "change" ? "planning" : "execution";
-  return (
-    <span className={`operations-table-stage is-${stage}`}>
-      {stage === "planning" ? "Planejamento" : "Execução"}
-    </span>
-  );
-}
+import {
+  DecisionOriginBadge,
+  DecisionStageBadge,
+  EntryBadge,
+  RiskBadge,
+  StatusBadge,
+} from "./EntityTableBadges.js";

package/templates/.agents/dashboard/modules/operations/src/react/OperationsOverview-keeps-structure-classes-mutually-exclusive.test.ts

@@ -0,0 +1,244 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import {
+  findLatestCreatedAt,
+  findLatestTaskCreatedAt,
+  macroClassificationStats,
+  macroStatusDistribution,
+  summarizeTopEntityMetrics,
+  summarizeTopTaskMetrics,
+  taskStatusDistribution,
+} from "./OperationsOverview.js";
+
+const _readOverviewSource = (file = "OperationsOverview.tsx") =>
+  readFileSync(new URL(file, import.meta.url), "utf8");
+function run(
+  taskId: string | null,
+  durationMs: number,
+  tokens: number,
+  costBrl: number,
+  links: { id?: string; specId?: string | null; prdId?: string | null } = {},
+) {
+  return {
+    id: links.id ?? `RUN-${taskId ?? "NONE"}-${durationMs}`,
+    phase: "execution",
+    task_id: taskId,
+    parent_run_id: null,
+    spec_id: links.specId ?? null,
+    prd_id: links.prdId ?? null,
+    duration_ms: durationMs,
+    usage: { total: { tokens: { total: tokens }, cost: { brl: costBrl } } },
+  };
+}
+function entityMetric(
+  id: string,
+  durationMs: number | null,
+  tokens: number | null,
+  costBrl: number | null,
+  runCount: number,
+) {
+  return { id, title: id, durationMs, tokens, costBrl, runCount };
+}
+describe("macroClassificationStats", () => {
+  it("keeps structure classes mutually exclusive", () => {
+    const stats = macroClassificationStats(
+      [
+        { task_count: 0, rework_run_count: 0 },
+        { task_count: 0, rework_run_count: 2 },
+        { task_count: 2, rework_run_count: 0 },
+        { task_count: 3, rework_run_count: 1 },
+      ],
+      "pt-BR",
+    );
+
+    expect(stats.map(({ key, label, count }) => ({ key, label, count }))).toEqual([
+      { key: "empty", label: "Sem tarefas", count: 1 },
+      { key: "structured", label: "Com tarefas", count: 1 },
+      { key: "rework", label: "Com retrabalho", count: 2 },
+    ]);
+    expect(stats.reduce((total, row) => total + row.count, 0)).toBe(4);
+  });
+});
+describe("taskStatusDistribution", () => {
+  it("includes cancelled and failed statuses with the other task states", () => {
+    const distribution = taskStatusDistribution(
+      [
+        { status: "draft", spec_id: "SPEC-1" },
+        { status: "planned", spec_id: "SPEC-1" },
+        { status: "draft", spec_id: null },
+        {
+          status: "planned",
+          spec_id: null,
+          attempt_count: 0,
+          started_at: null,
+          execution_started: false,
+        },
+        { status: "executing", spec_id: null },
+        { status: "verifying", spec_id: null },
+        { status: "completed", spec_id: null },
+        { status: "blocked", spec_id: null },
+        { status: "cancelled", spec_id: null },
+        { status: "failed", spec_id: null },
+      ],
+      "pt-BR",
+    );
+
+    expect(distribution.map(({ key, label, count }) => ({ key, label, count }))).toEqual([
+      { key: "definition", label: "Definição (PRD + Requisitos)", count: 0 },
+      { key: "planning", label: "Planejamento (SPEC + Change)", count: 0 },
+      { key: "ready", label: "Pronto para Executar", count: 2 },
+      { key: "executing", label: "Execução", count: 1 },
+      { key: "verifying", label: "Verificação", count: 1 },
+      { key: "completed", label: "Concluído", count: 1 },
+      { key: "blocked", label: "Bloqueado", count: 1 },
+      { key: "cancelled", label: "Cancelado", count: 1 },
+      { key: "failed", label: "Falhado", count: 1 },
+    ]);
+  });
+  it("includes cancelled and failed statuses in the visible total", () => {
+    const visible = taskStatusDistribution(
+      [
+        { status: "draft", spec_id: "SPEC-1" },
+        { status: "planned", spec_id: "SPEC-1" },
+        {
+          status: "planned",
+          spec_id: null,
+          attempt_count: 0,
+          started_at: null,
+          execution_started: false,
+        },
+        { status: "completed", spec_id: null },
+        { status: "executing", spec_id: null },
+        { status: "blocked", spec_id: null },
+        { status: "failed", spec_id: null },
+        { status: "cancelled", spec_id: null },
+      ],
+      "pt-BR",
+    );
+
+    expect(visible.map(({ key, count }) => ({ key, count }))).toEqual([
+      { key: "definition", count: 0 },
+      { key: "planning", count: 0 },
+      { key: "ready", count: 2 },
+      { key: "executing", count: 1 },
+      { key: "verifying", count: 0 },
+      { key: "completed", count: 1 },
+      { key: "blocked", count: 1 },
+      { key: "cancelled", count: 1 },
+      { key: "failed", count: 1 },
+    ]);
+    // Draft Tasks stay in the list, outside the PRD/SPEC pipeline stages.
+    expect(visible.reduce((total, item) => total + item.count, 0)).toBe(7);
+  });
+});
+describe("macroStatusDistribution", () => {
+  it("includes every macro status so the distribution totals match the macro card", () => {
+    const macros = [
+      { kind: "spec", lifecycle_status: "draft", work_status: "planning" },
+      { kind: "prd", lifecycle_status: "completed", work_status: "completed" },
+      { kind: "spec", lifecycle_status: "failed", work_status: "failed" },
+      { kind: "prd", lifecycle_status: "blocked", work_status: "blocked" },
+      { kind: "spec", lifecycle_status: "cancelled", work_status: "cancelled" },
+    ];
+    const macroCount = macros.length;
+
+    const visible = macroStatusDistribution(macros as never, [], "pt-BR");
+
+    expect(visible.map(({ key, count }) => ({ key, count }))).toEqual([
+      { key: "definition", count: 0 },
+      { key: "planning", count: 1 },
+      { key: "ready", count: 0 },
+      { key: "executing", count: 0 },
+      { key: "verifying", count: 0 },
+      { key: "completed", count: 1 },
+      { key: "blocked", count: 1 },
+      { key: "cancelled", count: 1 },
+      { key: "failed", count: 1 },
+    ]);
+    expect(visible.reduce((total, item) => total + item.count, 0)).toBe(macroCount);
+  });
+});
+describe("findLatestTaskCreatedAt", () => {
+  it("selects the newest task regardless of lifecycle status", () => {
+    expect(
+      findLatestTaskCreatedAt([
+        { created_at: "2026-07-16T10:00:00.000Z" },
+        { created_at: "2026-07-16T12:30:00.000Z" },
+        { created_at: "2026-07-16T11:00:00.000Z" },
+      ]),
+    ).toBe("2026-07-16T12:30:00.000Z");
+  });
+  it("returns null when no valid task date exists", () => {
+    expect(findLatestTaskCreatedAt([])).toBeNull();
+    expect(findLatestTaskCreatedAt([{ created_at: "invalid" }])).toBeNull();
+  });
+});
+describe("findLatestCreatedAt", () => {
+  it("supports nullable macro dates", () => {
+    expect(
+      findLatestCreatedAt([{ created_at: null }, { created_at: "2026-07-16T10:00:00.000Z" }]),
+    ).toBe("2026-07-16T10:00:00.000Z");
+  });
+});
+describe("summarizeTopEntityMetrics", () => {
+  it("summarizes the top entities against the selected entity total", () => {
+    const first = entityMetric("ONE", 100, 10, 1, 1);
+    const second = entityMetric("TWO", 300, 30, 3, 2);
+    expect(summarizeTopEntityMetrics([second], [first, second])).toEqual({
+      durationMs: 300,
+      durationShare: 0.75,
+      runCount: 2,
+      tokens: 30,
+      costBrl: 3,
+    });
+  });
+});
+describe("summarizeTopTaskMetrics", () => {
+  it("summarizes the selected tasks against all measured run duration", () => {
+    const runs = [run("TASK-1", 100, 10, 1), run("TASK-2", 200, 20, 2), run("TASK-3", 300, 30, 3)];
+
+    expect(
+      summarizeTopTaskMetrics(
+        [
+          { id: "TASK-1", durationMs: 100 },
+          { id: "TASK-2", durationMs: 200 },
+        ],
+        runs,
+      ),
+    ).toEqual({ durationMs: 300, durationShare: 0.5, runCount: 2, tokens: 30, costBrl: 3 });
+  });
+  it("keeps tokens and cost unavailable when no related run has coverage", () => {
+    expect(
+      summarizeTopTaskMetrics(
+        [{ id: "TASK-1", durationMs: 100 }],
+        [
+          {
+            ...run("TASK-1", 100, 0, 0),
+            usage: { total: { tokens: { total: null }, cost: { brl: null } } },
+          },
+        ],
+      ),
+    ).toMatchObject({ tokens: null, costBrl: null });
+  });
+  it("uses root execution duration but all related phases for top-task usage", () => {
+    const root = run("TASK-1", 2_000, 10, 1, { id: "RUN-ROOT" });
+    const child = {
+      ...run("TASK-1", 1_000, 20, 2, { id: "RUN-CHILD" }),
+      parent_run_id: "RUN-ROOT",
+    };
+    const conversation = {
+      ...run("TASK-1", 9_000, 30, 3, { id: "RUN-CONVERSATION" }),
+      phase: "conversation",
+    };
+
+    expect(
+      summarizeTopTaskMetrics([{ id: "TASK-1", durationMs: 2_000 }], [root, child, conversation]),
+    ).toEqual({
+      durationMs: 2_000,
+      durationShare: 1,
+      runCount: 3,
+      tokens: 60,
+      costBrl: 6,
+    });
+  });
+});