> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase19-session15-metrics-and-notifications/implementation_summary.md).

# Implementation Summary

**Session ID**: `phase19-session15-metrics-and-notifications` **Package**: cross-cutting **Completed**: 2026-06-28 **Duration**: 4 hours

***

## Overview

Session 15 turned command-center metrics and notification readiness into a product-facing operator surface. The work added protocol contracts, server aggregation and routing, web API/store handling, local notification routing, Web Push readiness guardrails, the Metrics and Notifications panel, and focused documentation and tests while preserving local-first and no-claim hosted-service boundaries.

***

## Deliverables

### Files Created

| File                                                                     | Purpose                                                                                                                | Lines |
| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | ----- |
| `apps/server/src/managers/usageMetricsManager.ts`                        | Aggregates bounded command-center usage, age, backlog, utilization, provider import, and rollup metrics.               | 705   |
| `apps/server/src/lib/notificationRouting.ts`                             | Validates notification preferences, readiness, consent, VAPID posture, subscription summaries, and payload categories. | 592   |
| `apps/server/src/routes/commandCenterNotifications.ts`                   | Adds notification preference, readiness, subscribe, and unsubscribe routes.                                            | 294   |
| `apps/server/tests/usageMetricsManager.test.ts`                          | Covers deterministic metric aggregation and redaction boundaries.                                                      | 285   |
| `apps/server/tests/notificationRouting.test.ts`                          | Covers routing validation, consent, VAPID, subscription, and malformed timestamp handling.                             | 156   |
| `apps/server/tests/commandCenterNotifications.test.ts`                   | Covers notification routes, readiness WebSocket frames, subscribe/unsubscribe gating, and no raw endpoint echo.        | 294   |
| `apps/web/src/lib/commandCenterMetrics.ts`                               | Builds metrics, attention, cost, and readiness view models for the web surface.                                        | 553   |
| `apps/web/src/lib/commandCenterNotifications.ts`                         | Routes command-center attention and review records into local notification candidates with duplicate suppression.      | 298   |
| `apps/web/src/components/orchestration/MetricsAndNotificationsPanel.tsx` | Provides the product-facing Metrics tab surface for rollups, attention, local notifications, and Web Push readiness.   | 513   |
| `apps/web/tests/commandCenterMetrics.test.ts`                            | Covers metric buckets, readiness cards, attention counts, safe labels, and cost projection labels.                     | 211   |
| `apps/web/tests/commandCenterNotifications.test.ts`                      | Covers local routing categories, muted states, permission fallbacks, and duplicate suppression.                        | 231   |
| `apps/web/tests/MetricsAndNotificationsPanel.test.tsx`                   | Covers panel filters, states, controls, readiness copy, and accessibility labels.                                      | 227   |

### Files Modified

| File                                                            | Changes                                                                                                            |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `packages/protocol/src/orchestrationCommandCenter.ts`           | Added metric, rollup, notification, readiness, subscription, and parser contracts with blocked raw-field handling. |
| `packages/protocol/tests/orchestrationCommandCenter.test.ts`    | Added parser coverage for enriched metrics, readiness, subscriptions, and blocked fields.                          |
| `packages/protocol/tests/events.test.ts`                        | Added compact usage and notification update event coverage.                                                        |
| `apps/server/src/lib/commandCenterValidation.ts`                | Added enriched usage and readiness validation with explicit error mapping.                                         |
| `apps/server/src/managers/orchestrationCommandCenter.ts`        | Stored enriched metrics/readiness, refreshed aggregated metrics, and emitted usage updates.                        |
| `apps/server/src/routes/commandCenter.ts`                       | Added usage mutation and refresh behavior with compact updates.                                                    |
| `apps/server/src/server.ts`                                     | Mounted notification routes under root and `/api` command-center paths.                                            |
| `apps/server/src/lib/claudeSessionImport.ts`                    | Exposed bounded provider usage import fields.                                                                      |
| `apps/server/src/lib/codexSessionImport.ts`                     | Exposed bounded provider usage import fields.                                                                      |
| `apps/server/src/lib/localSessionImport.ts`                     | Carried bounded local session metadata into import flows.                                                          |
| `apps/server/src/lib/startupSessionImport.ts`                   | Wired startup import usage fields.                                                                                 |
| `apps/server/src/lib/missionArtifacts.ts`                       | Connected mission artifact estimates to metric aggregation without raw artifact leakage.                           |
| `apps/server/tests/claudeSessionImport.test.ts`                 | Covered bounded Claude usage import fields.                                                                        |
| `apps/server/tests/codexSessionImport.test.ts`                  | Covered bounded Codex usage import fields.                                                                         |
| `apps/server/tests/commandCenterManager.test.ts`                | Covered usage refresh persistence, compact events, and no raw leakage.                                             |
| `apps/server/tests/commandCenterRoutes.test.ts`                 | Covered usage routes, snapshots, refreshes, and WebSocket updates.                                                 |
| `apps/web/src/lib/orchestrationApi.ts`                          | Added metrics refresh, usage mutation, notification preference/readiness, subscribe, and unsubscribe clients.      |
| `apps/web/src/store/useGameStore.ts`                            | Stored preferences/readiness and normalized enriched metric and notification frames.                               |
| `apps/web/src/store/useWsClient.ts`                             | Rejected malformed usage and notification WebSocket frames before mutation.                                        |
| `apps/web/src/lib/notifications.ts`                             | Added command-center notification categories and hidden-tab delivery coverage.                                     |
| `apps/web/src/lib/useNotifications.ts`                          | Subscribed to command-center attention/review changes without stale replay.                                        |
| `apps/web/src/lib/hostedOperations.ts`                          | Updated Web Push readiness copy without active hosted delivery claims.                                             |
| `apps/web/src/lib/commandCenterUi.ts`                           | Added metric status, notification readiness, attention severity, and mobile filter helpers.                        |
| `apps/web/src/components/orchestration/OrchestrationHeader.tsx` | Added compact attention and metrics summary counts.                                                                |
| `apps/web/src/components/orchestration/AttentionWorkbench.tsx`  | Added attention severity and age distribution presentation.                                                        |
| `apps/web/src/components/orchestration/CommandCenterPanes.tsx`  | Mounted the Metrics and Notifications panel.                                                                       |
| `apps/web/src/components/orchestration/OrchestrationShell.tsx`  | Loaded metrics/readiness and wired notification preference, refresh, consent, and unavailable subscribe actions.   |
| `apps/web/src/components/orchestration/OrchestrationTabs.tsx`   | Passed metrics and notification callbacks through tab wiring.                                                      |
| `apps/web/src/components/SettingsDrawer.tsx`                    | Added command-center notification settings entry points.                                                           |
| `apps/web/tests/OrchestrationPanel.test.tsx`                    | Covered Metrics tab wiring, attention header summary, mobile filters, and notification actions.                    |
| `apps/web/tests/orchestrationApi.test.ts`                       | Covered metrics refresh and notification clients.                                                                  |
| `apps/web/tests/commandCenterStore.test.ts`                     | Covered enriched state normalization and malformed frame rejection.                                                |
| `apps/web/tests/notifications.test.ts`                          | Covered command-center notification categories and hidden-tab routing.                                             |
| `apps/web/tests/useNotifications.test.tsx`                      | Covered command-center hook routing without seed replay.                                                           |
| `apps/web/tests/hostedOperations.test.ts`                       | Covered Web Push readiness no-claim copy.                                                                          |
| `apps/web/tests/SettingsHostedAnalytics.test.tsx`               | Covered settings drawer entry-point copy.                                                                          |
| `docs/api/README_api.md`                                        | Documented usage refresh, notification readiness, preference, subscribe, and unsubscribe boundaries.               |
| `apps/server/README_server.md`                                  | Documented metrics manager and notification routing limits.                                                        |
| `apps/web/README_web.md`                                        | Documented Metrics tab, local routing, mobile filters, and Web Push no-claim posture.                              |
| `packages/protocol/README_protocol.md`                          | Documented enriched command-center metrics and notification contracts.                                             |

***

## Technical Decisions

1. **Protocol-first vocabulary**: Metric kinds, rollups, readiness fields, and notification categories live in `packages/protocol` so server and web remain aligned.
2. **Manager-owned aggregation**: Metrics are refreshed through server-managed state instead of client-side analytics capture or raw provider payloads.
3. **Readiness-gated Web Push**: Subscribe/unsubscribe APIs validate consent and configuration, but hosted push delivery remains inactive by default.
4. **Pure web normalization**: API and WebSocket payloads are parsed before Zustand mutation to reject malformed or unsafe frames.

***

## Test Results

| Metric   | Value        |
| -------- | ------------ |
| Tests    | 2946         |
| Passed   | 2945         |
| Failed   | 0            |
| Skipped  | 1            |
| Coverage | Not reported |

***

## Lessons Learned

1. Web Push subscription timestamps need explicit Date-range bounds before formatting, not only finite-number checks.
2. Readiness cards and WebSocket-only clients need action-specific subscription statuses such as `subscribed` and `unsubscribed`, not only top-level readiness states.
3. Local notification routing is easier to verify when candidate derivation, permission handling, duplicate suppression, and delivery are independently testable.

***

## Future Considerations

Items for future sessions:

1. Session 16 should complete ergonomic polish, keyboard shortcuts, final docs, and closeout validation across the command-center surface.
2. Hosted Web Push delivery remains deferred until consent, auth, rate limits, audit trails, payload minimization, production config, tests, and docs are explicitly in scope.
3. Metrics can expand as new executor families become real, but broad views must continue to exclude prompts, transcripts, terminal output, provider payloads, absolute paths, push endpoints, and subscription keys.

***

## Session Statistics

* **Tasks**: 22 completed
* **Files Created**: 12 implementation deliverables plus 6 workflow artifacts
* **Files Modified**: 41 tracked implementation, documentation, test, and state files before updateprd closeout
* **Tests Added**: 6 new test files plus expanded protocol, server, and web suites
* **Blockers**: 0 unresolved


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase19-session15-metrics-and-notifications/implementation_summary.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.