[AAASM-5159] ♻️ (costs): Restore Avg / agent today KPI and surface cost date

[Chisanan232]

Description

Restores the fourth spec KPI on the Cost & Budget page — "Avg / agent today" (daily_spend / agentsTracked, captioned with costs.date) — from design/v1/hi-fi/costs.jsx:299-305. The shipped strip had Utilisation and Blocked-by-budget but was missing this card, and never surfaced CostSummary.date at all.

The computation lives in deriveCostKpis as a pure function with a divide-by-zero guard: a genuine zero-agent roster folds to not-evaluated (rendered as the canonical em-dash), never NaN or a fabricated $0.00 — the same false-negative the rest of the module exists to prevent. Any other absence in agentsTracked (outage, in-flight, no breakdown configured) propagates unchanged. The date sub-caption resolves independently, so it still renders even when the ratio is undefined.

ADR basis: ADR-0017 item 14 ratifies Utilisation and Blocked-by-budget as additive to the four spec KPIs — not replacements for one of them. The missing avg-per-agent card was therefore a genuine parity regression, and restoring it is purely additive, consistent with that recorded decision.

Type of Change

• ♻️ Refactoring

Breaking Changes

• No

Related Issues

• Related Jira ticket: AAASM-5159

Testing

• Unit tests added / updated — costKpis.test.ts (divide, zero-guard, absence propagation) and CostsPage.test.tsx (render, em-dash, failure states)
• Manual testing performed — Playwright review spec dashboard/tests/e2e/review-aaasm-5159.spec.ts drives both themes for the known-roster and zero-agent cases

Design verification: screenshots in dashboard/verify/5159/ (known + zero-agent, both themes) confirm all four spec KPI cards render, the avg-per-agent card shows $105.00 with 2026-05-13 as its sub-caption, and the zero-agent case renders an em-dash (not NaN / $0.00) while the date sub-caption still resolves.

Local checks (Node v22, pnpm): tsc --noEmit clean, eslint . clean, vitest run — 3066 passed.

Security: pure client-side arithmetic on already-fetched /costs data — no new network surface, no new inputs, no new trust boundary.

Checklist

• Self-review of the diff completed
• All CI checks passing (pending CI run)
• Commits are small and follow the Gitmoji convention

Closes AAASM-5159

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 87.50000% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
dashboard/src/features/costs/costKpis.ts	85.71%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
92.9% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Chisanan232]

✅ LGTM — reviewed and approved by Claude Code

(COMMENT review because GitHub blocks self-approval; this is the sign-off of record.)

Requirement correctness — AAASM-5159

Restores the "Avg / agent today" KPI per design/v1/hi-fi/costs.jsx:299-305, cites ADR-0017 item 14 (Utilisation/Blocked are additive, not a replacement — so the missing 4th card was a real regression). avgPerAgent = daily.spend / agentsTracked folds a genuine measured zero to not-evaluated (not NaN/$0.00), and propagates every other absence state (unconfigured/unavailable/in-flight) through the Certain<> boundary — matching the module's truthfulness discipline exactly. The card renders usd(avgPerAgent) with costs.date as the sub-caption via mapCertain, so the date propagates its own absence. Tests cover the divide, the zero-agent not-evaluated case, the unconfigured/unavailable propagation, plus a page-level render assertion.

CI — all checks green (CI Success pass).

Security — pure client-side arithmetic on already-fetched cost data; no new backend surface.

Merging as org admin with a merge commit.

🤖 Reviewed with Claude Code