> 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/phases/phase_19/session_15_metrics_and_notifications.md).

# Session 15: Metrics And Notifications

**Session ID**: `phase19-session15-metrics-and-notifications` **Packages**: apps/server, apps/web **Status**: Not Started **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours

***

## Objective

Add orchestration telemetry and attention routing for desktop, mobile, and hidden-tab operation.

***

## Scope

### In Scope (MVP)

* Metrics for duration, events, tool-use count, estimated tokens/cost, lines changed, failures, retries, throughput, stalled tasks, blocked age, review backlog, pending approvals age, latency, queue age, executor utilization, provider usage imports, and plan/hero/task rollups
* Compact attention count, severity distribution, mobile filters, local notification readiness, Web Push VAPID subscribe/unsubscribe, payload categories, and notification routing
* Notification routing for approvals, questions, blocked tasks, failed tasks, and review gates
* Cost projection links where current helpers own the calculation
* Tests for metric aggregation, notification preferences, subscription validation, severity counts, and hidden-tab behavior

### Out of Scope

* Analytics capture by default
* Hosted push claims without configured VAPID and consent

***

## Prerequisites

* [ ] Sessions 04, 05, 06, 09, 10, and 14 complete
* [ ] Current notification, usage, and cost helper paths inspected

***

## Deliverables

1. Usage metrics manager and metrics panel
2. Header attention summary and mobile filters
3. Local notification and Web Push readiness UI
4. Tests for metrics and notification routing

***

## Source Coverage And Evidence

Source coverage:

* Session Split Plan Session 15: Metrics And Notifications
* Implementation Targets 21 and 22 for attention notifications, mobile states, metrics, cost, and usage links
* Balls-To-The-Wall Track B `usageMetricsManager` routes
* Execution Family Order item 9 for push/mobile attention and metrics/cost/usage

Key EXAMPLES links:

* [Mobile PWA guide](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L294-L305)
* [Push routes](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L126-L128)
* [Mission metrics guide](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L69-L77)
* [Gold Mine usage guide](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L233-L237)
* [Usage and metrics routes](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L21-L31)
* [Usage route](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L197-L197)

***

## Success Criteria

* [ ] Operators can see task, hero, plan, queue, and executor health metrics
* [ ] Attention can notify locally and, when configured, through Web Push
* [ ] Severity, age, timeout, and notification routing are test-covered
* [ ] Token/cost math reuses existing helpers when present


---

# 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/phases/phase_19/session_15_metrics_and_notifications.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.