(CODUX-228) Make Stats refreshes cost-aware

[numnx]

🧩 Task: Make Stats refreshes cost-aware

Automated task PR opened by Code UX for T02.

📋 Summary

Sprint: Sprint 228 · Stats Cost analytics · Task: T02

Add a trustworthy, accessible Cost analysis mode to Stats that exposes provenance-aware spend, averages, token and spend allocation, canonical per-sprint and per-task detail, model and execution-purpose breakdowns, and resilient navigation and refresh states across every existing Stats time range.

🤖 Model & Provider

Provider	Codex CLI
Model	gpt-5.6-sol

⏱️ Timing

Started	2026-07-14 00:51:02 UTC
Finished	2026-07-14 00:55:37 UTC
Duration	4m 35s

📊 Token Usage

Metric	Value
Input tokens	121,850
Cached input tokens	2,640,384
Output tokens	19,596
Total tokens	2,781,830
Invocations	2
Tool calls	37
Active time	19m 28s

Included usage estimate (subscription/local login): $2.52

✅ QA Review

⏳ QA review runs after this PR is opened. Check the task card in the dashboard for the outcome once it lands.

📝 Full Task Prompt

## Objective
Prevent the Stats resource cache from discarding refreshed Cost data when tokens or entity identities have not changed.

## Scope
- `dashboard/src/v2/lib/resource-equality.ts`: `isEqualUsageTotals`, `isEqualProjectStatsSnapshot`, and `stabilizeProjectStatsSnapshot`
- `tests/dashboard/v2/lib/resource-equality.test.ts`
- Verify `dashboard/src/v2/hooks/use-project-stats.ts` keeps its current cache, polling, abort, and stale-data behavior
- `docs/architecture/dashboard-resource-layer.md`

## Implementation Requirements
1. Extend usage equality to compare input, output, cached, total, provider-reported cost, and every cost-coverage counter, treating absent optional fields consistently without equating unknown coverage with proven full coverage.
2. Include `costAnalytics`, models, chart series, status counts, duration, and other Cost-consumed snapshot fields in top-level equality and stabilization so price-setting changes and new telemetry replace stale values even when token totals are unchanged.
3. Preserve previous object references for genuinely unchanged usage, buckets, entities, models, series, and cost analytics using linear-time keyed reconciliation rather than repeated nested scans.
4. Add regression tests for cost-only changes, canonical sprint-cost changes, model and purpose cost changes, chart-series changes, coverage-only changes, unchanged refreshes, and reordered entity arrays.
5. Document that project Stats stabilization ignores assembly-only timestamps but must propagate all analytical data and pricing-provenance changes.

## Constraints
- Consume the additive contracts from T01 and remain compatible with snapshots where optional Cost fields are absent.
- Do not change polling intervals, realtime event scopes, request keys, abort behavior, or the policy of keeping a previous snapshot visible during silent refresh.
- Do not fall back to whole-snapshot `JSON.stringify` comparisons or introduce superlinear reconciliation for large ledgers.

## Verification
- Run `pnpm exec vitest run tests/dashboard/v2/lib/resource-equality.test.ts`.
- Run `pnpm run typecheck:dashboard` and `pnpm run build`.
- Confirm a cost-only refreshed snapshot is returned as new data, while an analytically identical snapshot reuses stable references and ignores only `generatedAt` churn.

🌿 Branch Info

Base: feature/CODUX-228-stats-cost-analytics
Head: task/feature-codux-22-t02-codex-3cfbf972-mrjwruip

---

🤖 Generated by Code UX