Add header throughput telemetry API (codex)

[numnx]

🧩 Task: Add header throughput telemetry API

Automated task PR opened by Code UX for T01.

📋 Summary

Sprint: Sprint 159 · Header Menu bar - Token throughput + Runtime warning · Task: T01

Add a polished header-bar token throughput signal for app-wide and selected-project usage, and make the runtime-not-ready warning a critical red animated warning that is hard to miss while preserving accessibility and existing header behavior.

📝 Full Task Prompt

## Objective
Add a typed backend telemetry contract and HTTP endpoint that returns token throughput for the whole Code UX app and, when provided, the selected project, so the header can render the values without issuing per-project fan-out requests.

## Scope
- src/contracts/app-types.ts
- src/repositories/execution/header-token-throughput-query.ts
- src/repositories/execution-repository.ts
- src/app/lifecycle/dashboard-snapshot-cache.ts
- src/app/lifecycle/dashboard-snapshot-cache-policy.ts
- src/app/lifecycle/dashboard-lifecycle-service.ts
- src/server/dashboard-server.ts
- src/server/runtime-routes.ts
- tests/backend/repositories/execution/header-token-throughput-query.test.ts
- tests/backend/server/dashboard-server.test.ts or a focused runtime route test under tests/backend/server/
- docs/architecture/usage-telemetry-and-stats.md

## Implementation Requirements
1. Add a typed `HeaderTokenThroughputSnapshot` contract with `generatedAt`, `window`, `range`, `app`, and nullable `project` sections; each throughput section must include total tokens, input tokens, cached input tokens, output tokens, reasoning tokens, invocation count, active time, and tokens per minute.
2. Implement a repository query that aggregates `provider_invocations` across all projects for the requested window and separately aggregates the selected `projectId` when present; support at least `1h`, `24h`, `7d`, `30d`, and `all`, and treat missing or unknown project IDs as validation errors rather than silently returning misleading project values.
3. Wire `ExecutionRepository.getHeaderTokenThroughputSnapshot`, cache it briefly in `DashboardSnapshotCache`, expose it through `DashboardServerOptions`, and register `GET /api/stats/header-throughput?projectId=<id>&window=1h` in `runtime-routes.ts`.
4. Add backend tests covering app totals, project totals, empty-data zero throughput, invalid project handling, and route query parsing.
5. Update the telemetry architecture docs to describe the header throughput read model and its relationship to the existing project stats snapshot.

## Constraints
- Do not change the existing `GET /api/projects/:projectId/stats` response shape or stats page behavior.
- Do not add a database migration; compute the header values from existing `provider_invocations` usage columns.
- Keep cache invalidation compatible with existing project execution and stats invalidation paths.
- Use numeric zeroes for empty aggregates so the dashboard can render stable placeholders.

## Verification
- Run `pnpm exec vitest run tests/backend/repositories/execution/header-token-throughput-query.test.ts`.
- Run the focused server route test that covers `/api/stats/header-throughput`.
- Run `pnpm run lint`.
- Success means the new endpoint returns deterministic app and project throughput values and existing project stats tests still compile.

✅ QA Review

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

🤖 Model & Provider

Provider	Codex CLI
Model	gpt-5.5

⏱️ Timing

Started	2026-07-07 04:32:35 UTC
Finished	2026-07-07 04:41:07 UTC
Duration	8m 33s

📊 Token Usage

Metric	Value
Input tokens	172,563
Cached input tokens	3,882,240
Output tokens	20,304
Total tokens	4,075,107
Invocations	1
Tool calls	83
Active time	7m 56s

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

🌿 Branch Info

Base: feature/CODUX-159-header-menu-bar-token-throughput-runtime-warning
Head: task/feature-codux-159-header-menu-bar-token-throughp-t01-codex-mra5konc

---

🤖 Generated by Code UX