> 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-notes.md).

# Implementation Notes

**Session ID**: `phase19-session15-metrics-and-notifications` **Package**: cross-cutting **Started**: 2026-06-27 01:03 **Last Updated**: 2026-06-27 02:41

***

## Session Progress

| Metric              | Value     |
| ------------------- | --------- |
| Tasks Completed     | 22 / 22   |
| Estimated Remaining | 0 minutes |
| Blockers            | 0         |

***

### Task T022 - Run full validation, runtime smoke, and security handoff

**Started**: 2026-06-27 02:34 **Completed**: 2026-06-27 02:41 **Duration**: 7 minutes

**Notes**:

* Re-ran package typechecks, repository format/lint checks, and the full Vitest suite after the final formatting-only adjustment in `apps/web/src/components/orchestration/OrchestrationShell.tsx`.
* Checked whitespace, added-line ASCII, CRLF line endings, and untracked-file ASCII for the session changes.
* Started the local server on `http://127.0.0.1:2468` and Vite on `http://localhost:5193`, then used Playwright to load the live cockpit, complete the first-run faction picker, open the Orchestration Metrics tab, trigger a metrics refresh, and capture `/tmp/factionos-metrics-smoke.png`.
* Recorded final security/no-claim posture in `security-compliance.md`.

**Files Changed**:

* `.spec_system/specs/phase19-session15-metrics-and-notifications/tasks.md` - marked T022 complete, checked completion checklist, and updated next step to `creview`.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/implementation-notes.md` - recorded final validation and runtime evidence.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/security-compliance.md` - added local-only security, privacy, and no-claim handoff notes.
* `apps/web/src/components/orchestration/OrchestrationShell.tsx` - applied the one-line Biome formatting adjustment found by `npm run format:check`.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm --workspace packages/protocol run typecheck`
  * Result: PASS - protocol package typecheck completed with `tsc --noEmit`.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm --workspace apps/server run typecheck`
  * Result: PASS - server package typecheck completed with `tsc --noEmit`.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm --workspace apps/web run typecheck`
  * Result: PASS - web package typecheck completed with `tsc -b --noEmit`.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm run format:check`
  * Result: PASS - Biome checked 747 files with no fixes needed after the formatting adjustment.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm run lint`
  * Result: PASS - Biome lint checked 749 files with no fixes needed.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm test`
  * Result: PASS - full Vitest run completed.
  * Evidence: Vitest reported 259 files passed, 1 skipped; 2944 tests passed, 1 skipped.
* Command/check: `git diff --check`
  * Result: PASS - no whitespace errors.
* Command/check: added-line non-ASCII scan over `git diff --unified=0`
  * Result: PASS - no non-ASCII additions found.
* Command/check: CRLF scan over changed and untracked files
  * Result: PASS - no CRLF line endings found.
* Command/check: non-ASCII scan over untracked text files
  * Result: PASS - no non-ASCII content found in new untracked files.
* Runtime check: Playwright Chromium against `http://localhost:5193/`
  * Result: PASS - Metrics tab selected and `Metrics and notifications` panel visible after refresh.
  * Evidence: no console errors, no page errors, no failed requests; screenshot saved at `/tmp/factionos-metrics-smoke.png`.
* UI product-surface check: PASS - live cockpit rendered the Metrics tab through the Orchestration shell with local server data and no runtime failures.
* UI craft check: PASS - Metrics panel rendered through the intended tab surface at desktop viewport without the first-run picker blocking after normal setup.

**BQC Fixes**:

* Formatting: Applied the exact Biome wrapping change in `OrchestrationShell.tsx`, then reran typecheck, format, lint, and full tests.
* Runtime setup: Accounted for the normal first-run faction picker in Playwright before interacting with Orchestration.
* Security posture: `security-compliance.md` records bearer-auth local server posture, minimized metrics/readiness payloads, inactive hosted push delivery by default, and unchanged analytics/Web Push no-claim boundaries.

***

### Task T021 - Run focused protocol, server, and web validation

**Started**: 2026-06-27 02:33 **Completed**: 2026-06-27 02:34 **Duration**: 1 minute

**Notes**:

* Ran the focused cross-workspace validation command requested for command-center metric contracts, usage aggregation, notification routing, routes, API helpers, store normalization, Metrics panel behavior, local notifications, and hosted-operation no-claim copy.
* The command also exercised hosted operation diagnostics and server notification routes matched by the Vitest filters.

**Files Changed**:

* `.spec_system/specs/phase19-session15-metrics-and-notifications/tasks.md` - marked T021 complete and updated progress summary.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/implementation-notes.md` - recorded validation evidence.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm test -- orchestrationCommandCenter events usageMetricsManager notificationRouting commandCenterManager commandCenterRoutes commandCenterNotifications commandCenterMetrics commandCenterNotifications MetricsAndNotificationsPanel OrchestrationPanel orchestrationApi commandCenterStore notifications useNotifications hostedOperations`
  * Result: PASS - focused protocol, server, and web suites passed.
  * Evidence: Vitest reported 19 files passed and 194 tests passed.
* UI product-surface check: Covered by OrchestrationPanel and MetricsAndNotificationsPanel focused tests; browser runtime screenshot remains pending T022.
* UI craft check: Component and shell tests passed for labels, states, and controls; screenshot pass remains pending T022.

**BQC Fixes**:

* Cross-layer validation: The same command covered protocol parsers, server aggregation/routing, web API/store/panel, and local notification routing.

***

### Task T020 - Update metrics and notification docs

**Started**: 2026-06-27 02:31 **Completed**: 2026-06-27 02:33 **Duration**: 2 minutes

**Notes**:

* Documented command-center metrics and notification posture as local operational state in the API reference, including no raw provider/push/VAPID/analytics payload boundaries.
* Added API rows for `POST /command-center/usage/refresh`, notification preferences, readiness refresh, subscribe, and unsubscribe routes.
* Added server README notes for `usageMetricsManager`, notification routing helpers, route mounting, duplicate-trigger guards, payload minimization, and inactive hosted delivery by default.
* Added web README notes for the Metrics tab, metric helper ownership, command-center notification routing, local notification permission flow, Web Push consent readiness, and unavailable subscribe guardrail.
* Added protocol README ownership notes for enriched metric and notification vocabularies, safe subscription summaries, compact usage/readiness events, and blocked raw fields.

**Files Changed**:

* `docs/api/README_api.md` - documented metrics/notification boundaries and endpoint rows.
* `apps/server/README_server.md` - documented metrics manager and notification route implementation boundaries.
* `apps/web/README_web.md` - documented Metrics tab, notification routing, and hosted operations readiness/no-claim copy.
* `packages/protocol/README_protocol.md` - documented Session 15 command-center protocol vocabularies and payload boundaries.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/tasks.md` - marked T020 complete and updated progress summary.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/implementation-notes.md` - recorded task evidence.

**Verification**:

* Command/check: `rg -n 'Session 15|usage/refresh|notifications/preferences|notifications/readiness|notifications/subscribe|MetricsAndNotificationsPanel|commandCenterMetrics|Web Push consent|readiness and consent|endpoint hashes|key lengths' docs/api/README_api.md apps/server/README_server.md apps/web/README_web.md packages/protocol/README_protocol.md`
  * Result: PASS - updated docs contain the new route, helper, and boundary references.
  * Evidence: Matches appeared in all four target docs.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npx biome format --write docs/api/README_api.md apps/server/README_server.md apps/web/README_web.md packages/protocol/README_protocol.md`
  * Result: NOT APPLICABLE - Biome ignores these Markdown paths by repository configuration.
  * Evidence: Biome reported no files processed because the provided Markdown paths are ignored.
* Command/check: `git diff --check -- docs/api/README_api.md apps/server/README_server.md apps/web/README_web.md packages/protocol/README_protocol.md`
  * Result: PASS - no whitespace errors in documentation edits.
  * Evidence: `git diff --check` exited 0 with no output.
* UI product-surface check: N/A - T020 changes docs only.
* UI craft check: N/A - T020 does not change rendered UI.

**BQC Fixes**:

* No-claim consistency: Docs explicitly state readiness and consent do not activate hosted Web Push delivery.
* Payload minimization: Docs list raw provider, push endpoint/key, VAPID, prompt, transcript, terminal output, and absolute-path exclusions.

***

### Task T019 - Add web tests for metrics and notification UI/client behavior

**Started**: 2026-06-27 02:20 **Completed**: 2026-06-27 02:31 **Duration**: 11 minutes

**Notes**:

* Added pure helper coverage for metric rollup cards, cost/token/line labels, attention severity buckets, age buckets, mobile filters, and notification readiness no-claim posture.
* Added command-center notification routing tests for candidate derivation, category muting, disabled routing, permission fallbacks, stable tags, and duplicate in-flight suppression.
* Added Metrics panel component tests for metric filters, readiness sections, refresh controls, local notification toggles, Web Push consent/unsubscribe controls, and explicit loading/empty/offline/error copy.
* Extended Orchestration panel tests with Metrics-tab API wiring and no-active-hosted-push assertions.
* Extended API, store, notification, hook, hosted-operation, and Settings drawer tests for the new preference/readiness routes, state hydration, malformed frame rejection, local notification categories, command-center hook routing, no-claim copy, and settings entry point.

**Files Changed**:

* `apps/web/tests/commandCenterMetrics.test.ts` - created pure metrics/readiness helper tests.
* `apps/web/tests/commandCenterNotifications.test.ts` - created command-center notification routing tests.
* `apps/web/tests/MetricsAndNotificationsPanel.test.tsx` - created panel state and action wiring tests.
* `apps/web/tests/OrchestrationPanel.test.tsx` - added Metrics-tab wiring and API mock coverage.
* `apps/web/tests/orchestrationApi.test.ts` - added usage refresh and notification route client tests.
* `apps/web/tests/commandCenterStore.test.ts` - added notification preference/status and compact frame tests.
* `apps/web/tests/notifications.test.ts` - added command-center notification category coverage.
* `apps/web/tests/useNotifications.test.tsx` - added command-center local notification hook routing coverage.
* `apps/web/tests/hostedOperations.test.ts` - asserted updated Web Push readiness no-claim copy.
* `apps/web/tests/SettingsHostedAnalytics.test.tsx` - added Settings drawer entry-point coverage.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/tasks.md` - marked T019 complete and updated progress summary.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/implementation-notes.md` - recorded task evidence.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npx biome format --write apps/web/tests/commandCenterMetrics.test.ts apps/web/tests/commandCenterNotifications.test.ts apps/web/tests/MetricsAndNotificationsPanel.test.tsx apps/web/tests/OrchestrationPanel.test.tsx apps/web/tests/orchestrationApi.test.ts apps/web/tests/commandCenterStore.test.ts apps/web/tests/notifications.test.ts apps/web/tests/useNotifications.test.tsx apps/web/tests/hostedOperations.test.ts apps/web/tests/SettingsHostedAnalytics.test.tsx`
  * Result: PASS - web test files formatted.
  * Evidence: Biome formatted 10 files and later confirmed touched selector fixes required no formatting changes.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm test -- commandCenterMetrics commandCenterNotifications MetricsAndNotificationsPanel OrchestrationPanel orchestrationApi commandCenterStore notifications useNotifications hostedOperations SettingsHostedAnalytics`
  * Result: PASS - focused metric, notification, panel, shell, API, store, hook, and hosted-operation tests passed.
  * Evidence: Vitest reported 14 files passed and 140 tests passed.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm --workspace apps/web run typecheck`
  * Result: PASS - web package compiles with the new test coverage and UI wiring.
  * Evidence: `tsc -b --noEmit` exited 0 for `@factionos/web`.
* UI product-surface check: Covered by component/shell tests for labels and controls; browser screenshot remains pending T022 runtime verification.
* UI craft check: Component tests assert accessible section/button/label entry points; screenshot pass remains pending T022 runtime verification.

**BQC Fixes**:

* Selector stability: Tests intentionally account for repeated metric cards across rollup and family sections.
* Payload minimization: API tests assert UI-only `mutationKey` and `refresh` are not serialized in request bodies.
* No-claim posture: Hosted-operation, Metrics panel, Orchestration shell, and Settings drawer tests assert readiness/consent copy does not claim active hosted push delivery.

***

### Task T018 - Wire Metrics tab and notification controls into Orchestration

**Started**: 2026-06-27 02:13 **Completed**: 2026-06-27 02:20 **Duration**: 7 minutes

**Notes**:

* Wired the Metrics tab to `MetricsAndNotificationsPanel`, including metric filters, usage refresh, readiness refresh, local notification preference updates, Web Push consent, unsubscribe, and an explicit unavailable subscribe guardrail.
* Hydrated notification preferences during command-center load and scoped preference/readiness mutation failures to notification settings state instead of the whole command-center shell.
* Added header attention/metrics summary counts and attention severity distribution in the Attention workbench.
* Added a Settings drawer entry point to Orchestration metrics for command-center notification routing and readiness.
* Updated hosted-operation copy to say readiness/consent can be inspected while hosted push delivery remains inactive by default.

**Files Changed**:

* `apps/web/src/components/orchestration/OrchestrationShell.tsx` - added notification preference hydration, metrics/readiness refresh actions, local notification and Web Push preference controls, and no-claim subscribe copy.
* `apps/web/src/components/orchestration/OrchestrationTabs.tsx` - passed metrics/notification callbacks through to command-center panes.
* `apps/web/src/components/orchestration/CommandCenterPanes.tsx` - replaced the generic Metrics grid with `MetricsAndNotificationsPanel`.
* `apps/web/src/components/orchestration/OrchestrationHeader.tsx` - added attention and metrics summary counts plus local-readiness copy.
* `apps/web/src/components/orchestration/AttentionWorkbench.tsx` - added attention severity distribution.
* `apps/web/src/components/SettingsDrawer.tsx` - added command-center notification settings entry point.
* `apps/web/src/lib/hostedOperations.ts` - updated no-claim Web Push readiness copy.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/tasks.md` - marked T018 complete and updated progress summary.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/implementation-notes.md` - recorded task evidence.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm --workspace apps/web run typecheck`
  * Result: PASS - web package compiles with Metrics tab wiring and notification controls.
  * Evidence: `tsc -b --noEmit` exited 0 for `@factionos/web`.
* UI product-surface check: Pending focused browser/runtime check in T022 after test and doc coverage are complete.
* UI craft check: Typechecked layout adds responsive grid constraints; screenshot pass remains pending T022 runtime verification.

**BQC Fixes**:

* No-claim guardrail: Web Push consent and readiness controls do not claim active delivery; subscribe action surfaces an unavailable local-cockpit guardrail.
* Error scope: Notification preference/readiness failures are displayed in notification settings state without replacing the entire command-center error state.
* Mobile scanability: Metrics tab now uses the purpose-built panel with horizontal mobile filters and responsive summary grids.

***

### Task T012 - Add server route and manager tests

**Started**: 2026-06-27 01:44 **Completed**: 2026-06-27 01:48 **Duration**: 4 minutes

**Notes**:

* Added a command-center manager test for usage refresh persistence, manual metric preservation, enriched compact rollup fields, combined counts, and no raw provider/artifact leakage.
* Added a command-center route test for `POST /command-center/usage`, `POST /command-center/usage/refresh`, `/api/command-center/usage` snapshots, and compact usage WebSocket frames.
* Added a dedicated notification route test for default disabled Web Push readiness, preference persistence, VAPID gating, subscribe success with configured VAPID and explicit consent, unsubscribe with consent revocation, compact usage WebSocket frames, and no raw push endpoint echo.

**Files Changed**:

* `apps/server/tests/commandCenterManager.test.ts` - added usage refresh and compact event coverage.
* `apps/server/tests/commandCenterRoutes.test.ts` - added usage mutation/refresh route and WebSocket coverage.
* `apps/server/tests/commandCenterNotifications.test.ts` - created notification route coverage for readiness, subscribe/unsubscribe gates, and no raw echo.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/tasks.md` - marked T012 complete and updated progress summary.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npx biome format --write apps/server/tests/commandCenterManager.test.ts apps/server/tests/commandCenterRoutes.test.ts apps/server/tests/commandCenterNotifications.test.ts`
  * Result: PASS - server test files formatted.
  * Evidence: Biome reported `Formatted 3 files`.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm --workspace apps/server run typecheck`
  * Result: PASS - server package compiles with new tests.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/server`.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm test -- commandCenterManager commandCenterRoutes commandCenterNotifications usageMetricsManager notificationRouting`
  * Result: PASS - focused server manager, route, notification, and helper suites passed.
  * Evidence: Vitest reported 5 files passed and 28 tests passed.
* UI product-surface check: N/A - T012 changes server tests only.
* UI craft check: N/A - T012 does not change UI.

**BQC Fixes**:

* Duplicate action prevention: Notification route tests cover subscribe/unsubscribe gate paths and usage route tests cover refresh WebSocket behavior.
* Error information boundaries: Tests assert provider/artifact paths and raw push endpoints are not echoed in usage/notification outputs.
* Contract alignment: Tests assert enriched metric `kind`, rollup target, readiness subscription status, consent/VAPID flags, and compact WebSocket frames.

***

### Task T011 - Connect provider usage imports and mission artifact estimates

**Started**: 2026-06-27 01:39 **Completed**: 2026-06-27 01:44 **Duration**: 5 minutes

**Notes**:

* Extended shared local session import results with bounded provider usage summaries containing provider name, stable source/session IDs, start/end timestamps, bounded duration, token counts, and tool-use counts.
* Exposed provider usage summaries through Claude and Codex session import result DTOs.
* Wired startup session import usage summaries into server-owned usage refresh input so `POST /command-center/usage/refresh` aggregates imported provider usage without request clients resending raw session data.
* Added `buildMissionArtifactUsageEstimate` to transform mission artifact token/cost/line estimates into aggregation DTOs with safe IDs, bounded numbers, redacted target labels, and optional generated timestamps.
* Tightened mission artifact label/summary bounding to redact sensitive text before truncation.
* Added focused Claude/Codex import assertions for provider usage summaries and no raw import path leakage in the new usage summaries.

**Files Changed**:

* `apps/server/src/lib/localSessionImport.ts` - added provider usage summary generation for imported local sessions.
* `apps/server/src/lib/claudeSessionImport.ts` - exposed Claude provider usage summaries.
* `apps/server/src/lib/codexSessionImport.ts` - exposed Codex provider usage summaries.
* `apps/server/src/lib/startupSessionImport.ts` - added optional provider usage callback for startup imports.
* `apps/server/src/routes/commandCenter.ts` - merged server-owned provider usage into usage refresh aggregation.
* `apps/server/src/server.ts` - retained startup provider usage summaries for refresh.
* `apps/server/src/lib/missionArtifacts.ts` - added mission artifact usage estimate helper and redacted artifact labels.
* `apps/server/tests/claudeSessionImport.test.ts` - covered Claude provider usage summaries.
* `apps/server/tests/codexSessionImport.test.ts` - covered Codex provider usage summaries.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/tasks.md` - marked T011 complete and updated progress summary.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npx biome format --write apps/server/src/lib/localSessionImport.ts apps/server/src/lib/claudeSessionImport.ts apps/server/src/lib/codexSessionImport.ts apps/server/src/lib/missionArtifacts.ts apps/server/src/lib/startupSessionImport.ts apps/server/src/routes/commandCenter.ts apps/server/src/server.ts`
  * Result: PASS - import, artifact, route, and server files formatted.
  * Evidence: Biome reported `Formatted 7 files`.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm test -- claudeSessionImport codexSessionImport startupSessionImport usageMetricsManager`
  * Result: PASS - focused import and aggregation suites passed.
  * Evidence: Vitest reported 4 files passed and 10 tests passed.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm --workspace apps/server run typecheck`
  * Result: PASS - server package compiles after provider/artifact wiring.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/server`.
* UI product-surface check: N/A - T011 changes server import/aggregation inputs only.
* UI craft check: N/A - T011 does not change UI.

**BQC Fixes**:

* Error information boundaries: Provider usage summaries omit provider homes, transcripts, prompts, assistant text, tool input, tool output, terminal output, and absolute import paths.
* Contract alignment: Provider usage and mission artifact estimate DTOs now feed the usage aggregation manager through the refresh route.
* Privacy boundary: Mission artifact target labels are redacted before truncation, and import tests assert provider usage summaries do not include raw import roots.

***

### Task T010 - Add notification preference, readiness, subscribe, and unsubscribe routes

**Started**: 2026-06-27 01:36 **Completed**: 2026-06-27 01:39 **Duration**: 3 minutes

**Notes**:

* Added `commandCenterNotificationsRouter` with preference, readiness, subscribe, and unsubscribe endpoints under `/command-center/notifications/*`.
* Added shared route state for preferences, minimized subscription summaries, and duplicate-trigger prevention so root and `/api` mounts share the same local notification posture.
* Preference and readiness routes build readiness records from the server notification helper, persist them through the command-center manager, and emit the canonical usage update frame when state changes.
* Subscribe validates explicit Web Push consent, VAPID public/private/subject readiness, blocked top-level fields, minimized subscription payloads, and returns endpoint hashes/key lengths only. It always returns `pushDeliveryActive: false`.
* Unsubscribe clears the local subscription summary, can revoke Web Push consent, persists readiness, and keeps delivery inactive/no-claim.
* Mounted the router inside the existing local API route loop so auth, CORS, rate limits, body caps, root mounting, and `/api` mounting remain inherited from `server.ts`.

**Files Changed**:

* `apps/server/src/routes/commandCenterNotifications.ts` - created notification preference, readiness, subscribe, unsubscribe, VAPID gate, and shared-state routes.
* `apps/server/src/server.ts` - mounted notification routes under root and `/api` with shared state.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/tasks.md` - marked T010 complete and updated progress summary.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npx biome format --write apps/server/src/routes/commandCenterNotifications.ts apps/server/src/server.ts`
  * Result: PASS - new route and server mount formatted.
  * Evidence: Biome reported `Formatted 2 files`.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm --workspace apps/server run typecheck`
  * Result: PASS - server package compiles with notification routes.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/server`.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm test -- commandCenterRoutes notificationRouting`
  * Result: PASS - existing command-center route and notification helper coverage still passes after mount.
  * Evidence: Vitest reported 2 files passed and 15 tests passed.
* UI product-surface check: N/A - T010 changes server routes only.
* UI craft check: N/A - T010 does not change UI.

**BQC Fixes**:

* Duplicate action prevention: Subscribe/unsubscribe use `NotificationRoutingDeduper` around Web Push state changes.
* Error information boundaries: Subscription routes return endpoint hashes and key lengths only, reject blocked top-level fields, and never echo raw subscription endpoints, keys, or VAPID private keys.
* Hosted no-claim posture: Web Push remains disabled/unavailable without consent and VAPID readiness, and route responses keep `pushDeliveryActive: false`.

***

### Task T009 - Add usage mutation and refresh routes

**Started**: 2026-06-27 01:34 **Completed**: 2026-06-27 01:36 **Duration**: 2 minutes

**Notes**:

* Added `POST /command-center/usage` using the existing usage mutation parser, manager save path, router in-flight mutation guard, and canonical `command_center_usage_update` WebSocket event.
* Added `POST /command-center/usage/refresh` using the new refresh parser, explicit `usage:refresh` duplicate-trigger guard, server-side queue snapshot input, manager refresh persistence, and compact usage update broadcast.
* Kept routes inside the existing command-center router so root and `/api` mounting, auth, rate limits, and body caps remain inherited from the established server boundary.

**Files Changed**:

* `apps/server/src/routes/commandCenter.ts` - added usage mutation and refresh routes with WebSocket broadcast behavior.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/tasks.md` - marked T009 complete and updated progress summary.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npx biome format --write apps/server/src/routes/commandCenter.ts`
  * Result: PASS - route file formatted.
  * Evidence: Biome reported `Formatted 1 file`.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm --workspace apps/server run typecheck`
  * Result: PASS - server package compiles after route wiring.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/server`.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm test -- commandCenterRoutes`
  * Result: PASS - existing command-center route coverage still passes.
  * Evidence: Vitest reported 1 file passed and 12 tests passed.
* UI product-surface check: N/A - T009 changes server routes only.
* UI craft check: N/A - T009 does not change UI.

**BQC Fixes**:

* Duplicate action prevention: Usage refresh is guarded by the router in-flight set and manager mutation lock.
* Contract alignment: Usage mutation and refresh routes emit the canonical `command_center_usage_update` frame.
* Error information boundaries: Refresh route only accepts the bounded aggregate DTO parsed in T008 and sources queue records server-side.

***

### Task T008 - Wire usage refresh and mutation manager behavior

**Started**: 2026-06-27 01:26 **Completed**: 2026-06-27 01:34 **Duration**: 8 minutes

**Notes**:

* Added manager-owned `refreshUsageMetrics` behavior that aggregates current command-center plans, tasks, attention, permissions, executors, hero lifecycle commands, executions, review gates, channel commands, queue entries, provider usage summaries, and mission artifact estimates into persisted usage metric records.
* Tracked aggregate metric IDs separately so refreshes remove stale generated metrics without deleting manually posted usage records.
* Added a dedicated refresh result shape with refreshed `items`, combined usage/readiness counts, and one canonical usage-update change object.
* Extended compact usage WebSocket entries to include metric kind, rollup target, and blocked categories.
* Extended compact notification readiness WebSocket entries to include subscription status, routing categories, payload categories, readiness requirements, local/push/consent/VAPID booleans, and blocked categories.
* Added schema validation for usage refresh request bodies with explicit caps for provider usage imports, artifact estimates, timestamps, counts, token/cost/line totals, and safe provider/artifact labels.

**Files Changed**:

* `apps/server/src/managers/orchestrationCommandCenter.ts` - added usage refresh persistence and enriched compact usage/readiness event serialization.
* `apps/server/src/lib/commandCenterValidation.ts` - added `parseUsageRefreshBody` and bounded aggregate DTO validation.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/tasks.md` - marked T008 complete and updated progress summary.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npx biome format --write apps/server/src/managers/orchestrationCommandCenter.ts apps/server/src/lib/commandCenterValidation.ts`
  * Result: PASS - manager and validation files formatted.
  * Evidence: Biome reported `Formatted 2 files`.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm --workspace apps/server run typecheck`
  * Result: PASS - server package compiles after refresh/parser wiring.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/server`.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm test -- commandCenterManager`
  * Result: PASS - existing command-center manager behavior still passes.
  * Evidence: Vitest reported 1 file passed and 8 tests passed.
* UI product-surface check: N/A - T008 changes server manager and validation logic only.
* UI craft check: N/A - T008 does not change UI.

**BQC Fixes**:

* Contract alignment: Manager refresh output and compact WebSocket entries now preserve the enriched protocol fields introduced in T003.
* Duplicate action prevention: Refresh uses the manager mutation lock and returns an explicit conflict for in-flight refreshes.
* Error information boundaries: Refresh request validation accepts bounded aggregate summaries only and rejects unsafe labels, raw blocked fields, unbounded arrays, and unbounded numeric values.

***

### Task T007 - Add focused server helper tests

**Started**: 2026-06-27 01:22 **Completed**: 2026-06-27 01:26 **Duration**: 4 minutes

**Notes**:

* Added focused server tests for deterministic usage aggregation, queue and blocked ages, permission age, execution duration/latency/throughput/retry metrics, executor utilization, artifact estimates, sorted metric IDs, empty-source behavior, and provider-label privacy redaction.
* Added focused notification helper tests for preference normalization, muted-category routing, local/Web Push readiness, VAPID and consent gates, subscription summarization without raw endpoints or keys, blocked raw notification fields, relative URL bounding, redacted payload output, and duplicate-trigger prevention.
* Tightened notification payload redaction after the first focused test run exposed that sanitized payload IDs could preserve sensitive fragments from raw token-like input. Payload text and identifiers now collapse typed redaction placeholders before output.

**Files Changed**:

* `apps/server/tests/usageMetricsManager.test.ts` - added usage aggregation and privacy tests.
* `apps/server/tests/notificationRouting.test.ts` - added notification preference, readiness, subscription, payload, and dedupe tests.
* `apps/server/src/lib/notificationRouting.ts` - tightened notification payload redaction for IDs, tags, titles, and bodies.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/tasks.md` - marked T007 complete and updated progress summary.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npx biome format --write apps/server/tests/usageMetricsManager.test.ts apps/server/tests/notificationRouting.test.ts`
  * Result: PASS - new test files formatted.
  * Evidence: Biome reported `Formatted 2 files`.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm test -- usageMetricsManager notificationRouting`
  * Result: FAIL then PASS - first run caught notification payload ID/text retaining `secret` placeholder text; after tightening payload-specific redaction, focused suites passed.
  * Evidence: Final Vitest run reported 2 files passed and 5 tests passed.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm --workspace apps/server run typecheck`
  * Result: PASS - server package compiles with the new helper tests and redaction fix.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/server`.
* UI product-surface check: N/A - T007 changes server helper tests and helper redaction only.
* UI craft check: N/A - T007 does not change UI.

**BQC Fixes**:

* Error information boundaries: Added regression coverage and a helper fix so notification IDs/tags/titles/bodies do not preserve raw token/path/URL fragments.
* Duplicate action prevention: Added dedicated coverage for the notification routing in-flight dedupe guard.
* Contract alignment: Added focused tests for protocol-owned metric/readiness fields emitted by the new server helpers.

***

### Task T006 - Create notification routing helpers

**Started**: 2026-06-27 01:18 **Completed**: 2026-06-27 01:22 **Duration**: 4 minutes

**Notes**:

* Added pure notification routing helpers for command-center local preferences, routing category allowlists/mutes, VAPID readiness, service-worker/local/Web Push readiness records, subscription validation, payload minimization, relative URL bounding, and in-flight duplicate prevention.
* Web Push readiness stays consent/VAPID/service-worker/secure-context gated, returns `pushDeliveryActive: false`, and includes blocked categories for push subscriptions and VAPID private keys.
* Web Push subscription validation requires explicit consent and VAPID readiness, accepts only bounded HTTPS endpoints and bounded push keys, and returns endpoint hashes plus key lengths instead of raw endpoints or keys.
* Local notification payload builders redact text, bound title/body/tag/url fields, sanitize target labels, map routing categories to payload categories, and reject blocked raw fields before returning payloads.

**Files Changed**:

* `apps/server/src/lib/notificationRouting.ts` - created notification preference, readiness, subscription, payload, and dedupe helpers.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/tasks.md` - marked T006 complete and updated progress summary.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npx biome format --write apps/server/src/lib/notificationRouting.ts`
  * Result: PASS - helper source formatted.
  * Evidence: Biome reported `Formatted 1 file`.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm --workspace apps/server run typecheck`
  * Result: PASS - server package compiles with the new helper.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/server`.
* Command/check: `sed -n '1,620p' apps/server/src/lib/notificationRouting.ts`
  * Result: PASS - targeted source inspection completed.
  * Evidence: File exports preference normalization, VAPID readiness, readiness record builder, subscription validator, payload builder, and `NotificationRoutingDeduper`.
* UI product-surface check: N/A - T006 adds server helper logic only.
* UI craft check: N/A - T006 does not change UI.

**BQC Fixes**:

* Duplicate action prevention: Added `NotificationRoutingDeduper` for single-flight routing keys.
* Trust boundary enforcement: Subscription and notification payload helpers reject blocked raw fields, require consent/VAPID gates, and return minimized summaries.
* Error information boundaries: Subscription output omits raw endpoints and keys, returning a hash and key lengths only.

***

### Task T005 - Create usage metrics manager

**Started**: 2026-06-27 01:13 **Completed**: 2026-06-27 01:18 **Duration**: 5 minutes

**Notes**:

* Added a pure `UsageMetricsManager` that aggregates bounded `CommandCenterUsageMetric` records from plans, tasks, attention, permissions, executors, hero lifecycle commands, executions, review gates, channel commands, queue entries, provider usage imports, and mission artifact estimates.
* Implemented deterministic metric IDs, bounded numeric values, fixed 15-minute default windows, sorted output, safe labels, rollup targets, queue/blocked/pending age metrics, average execution duration/latency, throughput, executor utilization, provider tokens/cost/tool/line totals, and plan/hero/task rollups.
* Kept the manager storage-free and side-effect-free so T008 can wire it into the command-center manager without reaching into private state.
* Reused server privacy redaction for labels before compaction to prevent paths, URLs, or token-like strings from appearing in metric labels.

**Files Changed**:

* `apps/server/src/managers/usageMetricsManager.ts` - created manager-owned usage metric aggregation boundary.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/tasks.md` - marked T005 complete and updated progress summary.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npx biome format --write apps/server/src/managers/usageMetricsManager.ts`
  * Result: PASS - new manager source formatted.
  * Evidence: Biome reported `Formatted 1 file`.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm --workspace apps/server run typecheck`
  * Result: PASS - server package compiles with the new manager.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/server`.
* Command/check: `sed -n '1,220p' apps/server/src/managers/usageMetricsManager.ts`
  * Result: PASS - targeted source inspection completed.
  * Evidence: File exports `UsageMetricsManager`, `aggregateCommandCenterUsageMetrics`, provider/artifact input DTOs, and aggregation helpers for plan/task/attention/permission/execution/review/channel/queue/hero/provider/artifact metrics.
* UI product-surface check: N/A - T005 adds server aggregation logic only.
* UI craft check: N/A - T005 does not change UI.

**BQC Fixes**:

* Contract alignment: Aggregation returns protocol-owned `CommandCenterUsageMetric` DTOs with the enriched kinds, units, families, and rollup targets from T003.
* Error information boundaries: Metric labels are bounded and redacted with `redactSensitiveText`; provider imports expose aggregate counts only.

***

### Task T004 - Add protocol parser and event tests

**Started**: 2026-06-27 01:10 **Completed**: 2026-06-27 01:13 **Duration**: 3 minutes

**Notes**:

* Added vocabulary assertions for new usage metric kinds, notification channels, routing categories, payload categories, subscription statuses, readiness requirements, and blocked push/VAPID payload categories.
* Expanded parser success fixtures to cover usage rollup targets, blocked categories, Web Push readiness fields, subscription status, consent, VAPID posture, routing categories, payload categories, and readiness requirements.
* Added parser rejection cases for raw rollup payload fields, invalid routing categories, raw push subscription objects, and raw VAPID private-key fields.
* Expanded compact `command_center_usage_update` event fixture to include optional metric kind, rollup target, readiness routing/payload requirements, subscription status, consent/VAPID booleans, and blocked categories without raw payload leakage.
* Added matching raw-field names for push subscription and VAPID private-key payloads to the protocol denylist so the new negative parser cases enforce the intended boundary.

**Files Changed**:

* `packages/protocol/src/orchestrationCommandCenter.ts` - added raw-field denylist entries for push subscription and VAPID private-key payload spellings.
* `packages/protocol/tests/orchestrationCommandCenter.test.ts` - added parser and vocabulary coverage for enriched metrics and notifications.
* `packages/protocol/tests/events.test.ts` - added compact event coverage for enriched usage/readiness metadata and raw-field absence.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/tasks.md` - marked T004 complete and updated progress summary.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npx biome format --write packages/protocol/src/orchestrationCommandCenter.ts packages/protocol/tests/orchestrationCommandCenter.test.ts packages/protocol/tests/events.test.ts`
  * Result: PASS - protocol source and tests formatted.
  * Evidence: Biome reported `Formatted 3 files`.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm test -- orchestrationCommandCenter events`
  * Result: PASS - focused protocol suites passed.
  * Evidence: Vitest reported 2 files passed and 32 tests passed.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm --workspace packages/protocol run typecheck`
  * Result: PASS - protocol package compiles after test and denylist updates.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/protocol`.
* UI product-surface check: N/A - T004 changes protocol tests only.
* UI craft check: N/A - T004 does not change UI.

**BQC Fixes**:

* Trust boundary enforcement: Added explicit raw-field rejections for push subscriptions and VAPID private keys before notification payloads cross the protocol boundary.
* Contract alignment: Added compact event and parser test coverage for the enriched optional fields introduced in T003.

***

### Task T003 - Extend command-center protocol contracts

**Started**: 2026-06-27 01:05 **Completed**: 2026-06-27 01:10 **Duration**: 5 minutes

**Notes**:

* Added explicit command-center usage metric kinds for duration, events, tool use, estimated tokens/cost, lines changed, failures, retries, throughput, age, backlog, approvals, latency, utilization, provider usage, rollups, and notification readiness.
* Expanded metric families and units to cover queues, attention, approvals, reviews, executors, providers, plans, heroes, tasks, notifications, throughput, latency, lines, percent, and per-hour values.
* Added rollup target metadata for usage metrics with safe target kind, optional ID/label, and scope labels.
* Added notification-specific channel, routing category, payload category, subscription status, readiness requirement, local-only, push-delivery, consent, VAPID, and blocked-category fields.
* Extended blocked payload categories to include `push_subscription` and `vapid_private_key`.
* Kept new fields optional for backward compatibility while adding parser coverage and blocked raw-field rejection at the DTO boundary.

**Files Changed**:

* `packages/protocol/src/orchestrationCommandCenter.ts` - extended protocol vocabulary, DTOs, type guards, parsers, and optional field normalization.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/implementation-notes.md` - recorded task evidence.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/tasks.md` - marked T003 complete and updated progress summary.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npx biome format --write packages/protocol/src/orchestrationCommandCenter.ts`
  * Result: PASS - protocol source formatted.
  * Evidence: Biome reported `Formatted 1 file`.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm --workspace packages/protocol run typecheck`
  * Result: PASS - protocol package compiles with the extended contracts.
  * Evidence: `tsc --noEmit` exited 0 for `@factionos/protocol`.
* Command/check: `git diff -- packages/protocol/src/orchestrationCommandCenter.ts | sed -n '1,260p'`
  * Result: PASS - targeted diff inspected.
  * Evidence: Diff shows only protocol vocabulary, DTO, parser, and blocked-category changes for usage metrics and notification readiness.
* UI product-surface check: N/A - T003 changes shared protocol contracts only.
* UI craft check: N/A - T003 does not change UI.

**BQC Fixes**:

* Contract alignment: Added parser/type-guard coverage with optional backward-compatible fields so server and web consumers can migrate without schema drift.
* Trust boundary enforcement: Reused blocked-field rejection for rollup targets, usage metrics, and notification readiness; added blocked categories for push subscriptions and VAPID private keys.

***

### Task T002 - Inspect current command-center usage and notification paths

**Started**: 2026-06-27 01:03 **Completed**: 2026-06-27 01:05 **Duration**: 2 minutes

**Notes**:

* Inspected protocol contracts: usage metrics currently have `family`, `unit`, numeric value, window timestamps, generated timestamp, and labels; notification readiness currently has `channel`, `status`, summary, requirements, updated timestamp, and docs path.
* Inspected server storage and event paths: `OrchestrationCommandCenterManager` already owns `usageMetrics` and `notificationReadiness` maps, list methods, save methods, compact event entries, and `command_center_usage_update` emissions.
* Inspected routes and validation: `GET /command-center/usage` and `GET|POST /command-center/notification-readiness` exist, while usage mutation/refresh behavior still needs to be added.
* Inspected web state and API paths: the shell fetches usage/readiness snapshots, WebSocket frames are normalized before Zustand mutation, and the current Metrics tab is a generic `PaneGrid`.
* Inspected local notifications, hosted-operation posture, cost projection, and provider session imports. Notifications are local-only today, hosted Web Push copy is disabled/no-claim, cost projection is a pure mission helper, and session imports expose bounded heroes/missions with token counts and redacted tool previews.

**Files Changed**:

* `.spec_system/specs/phase19-session15-metrics-and-notifications/implementation-notes.md` - recorded inspection evidence.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/tasks.md` - marked T002 complete and updated progress summary.

**Verification**:

* Command/check: `sed -n '720,790p' packages/protocol/src/orchestrationCommandCenter.ts && sed -n '1428,1478p' packages/protocol/src/orchestrationCommandCenter.ts && sed -n '6160,6248p' packages/protocol/src/orchestrationCommandCenter.ts`
  * Result: PASS - current usage/readiness enum, interface, and parser shapes inspected.
  * Evidence: Existing parser rejects blocked fields and validates bounded labels, timestamps, docs paths, notification channel, and readiness status.
* Command/check: `sed -n '500,550p' apps/server/src/managers/orchestrationCommandCenter.ts && sed -n '1168,1190p' apps/server/src/managers/orchestrationCommandCenter.ts && sed -n '1580,1616p' apps/server/src/managers/orchestrationCommandCenter.ts && sed -n '1756,1772p' apps/server/src/managers/orchestrationCommandCenter.ts`
  * Result: PASS - manager storage/list/save/event paths inspected.
  * Evidence: Manager has `listUsage`, `listNotificationReadiness`, `saveUsageMetric`, `saveNotificationReadiness`, `eventUsage`, `eventNotificationReadiness`, and `usageUpdateEvent`.
* Command/check: `sed -n '250,285p' apps/server/src/routes/commandCenter.ts && sed -n '750,785p' apps/server/src/routes/commandCenter.ts && sed -n '1110,1250p' apps/server/src/lib/commandCenterValidation.ts`
  * Result: PASS - route and validation coverage inspected.
  * Evidence: Snapshot routes include usage/readiness; notification readiness mutation exists; usage mutation parser exists but no usage POST route is currently mounted.
* Command/check: `sed -n '400,480p' apps/web/src/components/orchestration/CommandCenterPanes.tsx && sed -n '220,360p' apps/web/src/components/orchestration/OrchestrationShell.tsx && sed -n '1016,1076p' apps/web/src/store/useWsClient.ts`
  * Result: PASS - web metrics tab, snapshot hydration, and WebSocket usage normalization inspected.
  * Evidence: Metrics tab is a generic record grid; shell fetches usage/readiness snapshots; malformed usage frames return `null` before store mutation.
* Command/check: `sed -n '1,360p' apps/web/src/lib/notifications.ts && sed -n '1,220p' apps/web/src/lib/hostedOperations.ts && sed -n '1,220p' apps/web/src/lib/costProjection.ts && sed -n '1,620p' apps/server/src/lib/localSessionImport.ts`
  * Result: PASS - local notification, hosted no-claim, cost, and import boundaries inspected.
  * Evidence: Notification payloads are bounded and local-only; hosted operations set push delivery inactive; cost projection is pure; imports cap file sizes/tool counts and use redacted previews.
* UI product-surface check: N/A - T002 is code inspection only.
* UI craft check: N/A - T002 does not change UI.

***

## Task Log

### Task T017 - Extend local command-center notification routing

**Started**: 2026-06-27 02:09 **Completed**: 2026-06-27 02:13 **Duration**: 4 minutes

**Notes**:

* Extended the browser notification category union for command-center approval, question, blocked-task, failed-task, and review-gate categories while reusing the existing active-tab, hidden-tab service-worker, and throttle paths.
* Added `commandCenterNotifications.ts` with category mapping, safe payload construction, local preference/category/mute checks, permission fallback copy, and duplicate-trigger prevention while routing is in flight.
* Extended `useNotifications` to subscribe to command-center attention, task, and review-gate transitions; it seeds a baseline on enable and only routes newly visible candidates.
* Added in-app fallback toast routing when local OS notification delivery is denied, revoked, restricted, unavailable, throttled, or blocked.

**Files Changed**:

* `apps/web/src/lib/notifications.ts` - added command-center notification categories.
* `apps/web/src/lib/commandCenterNotifications.ts` - created command-center local notification routing helpers and deduper.
* `apps/web/src/lib/useNotifications.ts` - subscribed to command-center notification candidates and fallback toasts.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/tasks.md` - marked T017 complete and updated progress summary.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/implementation-notes.md` - recorded task evidence.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npx biome format --write apps/web/src/lib/notifications.ts apps/web/src/lib/useNotifications.ts apps/web/src/lib/commandCenterNotifications.ts`
  * Result: PASS - notification routing files formatted.
  * Evidence: Biome reported `Formatted 3 files`.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm --workspace apps/web run typecheck`
  * Result: PASS - web package compiles with command-center notification routing.
  * Evidence: `tsc -b --noEmit` exited 0 for `@factionos/web`.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm test -- notifications useNotifications`
  * Result: PASS - focused notification suites passed.
  * Evidence: Vitest reported 4 files passed and 47 tests passed.
* UI product-surface check: N/A - T017 updates notification routing behavior only.
* UI craft check: N/A - T017 does not render UI.

**BQC Fixes**:

* Duplicate action prevention: Command-center notification routing uses an in-flight key deduper before calling the browser notification path.
* Fallback behavior: Denied, revoked, restricted, unavailable, throttled, and constructor-blocked outcomes return bounded fallback copy for in-app toasts.
* Hidden-tab behavior: Command-center categories reuse the existing local service-worker background path; no Web Push subscription or backend is created.

***

### Task T016 - Create Metrics and Notifications panel

**Started**: 2026-06-27 02:05 **Completed**: 2026-06-27 02:09 **Duration**: 4 minutes

**Notes**:

* Created `MetricsAndNotificationsPanel` with top-level metric filters, refresh actions, loading/empty/error/offline states, and detail selection for metric/readiness records.
* Added task/queue, plan/hero, executor/provider, cost/artifact, attention severity, age bucket, local notification, and Web Push readiness sections.
* Added native checkbox controls for local notification routing and Web Push consent plus subscribe/unsubscribe command buttons with disabled states driven by connection, consent, and subscription state.
* Kept API calls outside the component; the panel accepts callback props for refresh, preference changes, subscribe, and unsubscribe wiring in the shell.

**Files Changed**:

* `apps/web/src/components/orchestration/MetricsAndNotificationsPanel.tsx` - created the Metrics and Notifications panel component.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/tasks.md` - marked T016 complete and updated progress summary.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/implementation-notes.md` - recorded task evidence.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npx biome format --write apps/web/src/components/orchestration/MetricsAndNotificationsPanel.tsx`
  * Result: PASS - panel component formatted.
  * Evidence: Biome reported `Formatted 1 file`.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm --workspace apps/web run typecheck`
  * Result: PASS - web package compiles with the new panel.
  * Evidence: `tsc -b --noEmit` exited 0 for `@factionos/web`.
* UI product-surface check: Pending integration screenshot in T018 because the panel is not wired into the shell yet.
* UI craft check: Pending integration screenshot in T018.

**BQC Fixes**:

* State coverage: The panel renders explicit loading, empty, error, and offline states instead of silently showing an empty grid.
* No-claim copy: Web Push readiness copy keeps hosted delivery inactive by default and does not claim active push delivery.

***

### Task T015 - Create pure metric and notification view helpers

**Started**: 2026-06-27 02:00 **Completed**: 2026-06-27 02:05 **Duration**: 5 minutes

**Notes**:

* Added pure metric helpers for command-center rollup cards, compact metric values, cost/token/line labels, mobile metric filters, attention severity buckets, and age buckets.
* Added notification readiness view helpers for channel labels, status/subscription copy, routing/payload labels, posture labels, docs, and active/local-only flags.
* Added product-facing notification readiness and subscription status copy helpers to the shared command-center UI module.
* Kept all helpers React-free and Zustand-free so web tests can exercise behavior without rendering.

**Files Changed**:

* `apps/web/src/lib/commandCenterMetrics.ts` - created pure metric, attention, age, filter, and notification readiness view helpers.
* `apps/web/src/lib/commandCenterUi.ts` - added notification readiness and subscription status copy helpers.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/tasks.md` - marked T015 complete and updated progress summary.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/implementation-notes.md` - recorded task evidence.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npx biome format --write apps/web/src/lib/commandCenterMetrics.ts apps/web/src/lib/commandCenterUi.ts`
  * Result: PASS - metric helper and UI helper files formatted.
  * Evidence: Biome reported `Formatted 2 files`.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm --workspace apps/web run typecheck`
  * Result: PASS - web package compiles with the pure helpers.
  * Evidence: `tsc -b --noEmit` exited 0 for `@factionos/web`.
* UI product-surface check: N/A - T015 adds pure view helpers only.
* UI craft check: N/A - T015 does not render UI.

**BQC Fixes**:

* Product copy consistency: Notification readiness and subscription status copy now route through shared `CommandCenterStatusCopy` tone/description helpers.
* Privacy posture: Metric and notification labels pass through existing command-center safe-label redaction helpers before display.

***

### Task T014 - Extend web store and WebSocket parsing

**Started**: 2026-06-27 01:54 **Completed**: 2026-06-27 02:00 **Duration**: 6 minutes

**Notes**:

* Added a command-center notification settings slice for preferences, safe subscription summary, subscription status, push-delivery activity, generated timestamp, loading, and error state.
* Added store hydrators for notification preferences and notification readiness/status responses, plus notification loading/error setters for the upcoming panel.
* Updated command-center usage WebSocket application to merge event-window metrics and readiness into existing collections instead of replacing the whole collection, preserving selected detail records during refresh frames.
* Updated WebSocket sanitization for enriched usage metrics by validating through `parseCommandCenterUsageMetric` before store mutation.
* Updated notification readiness WebSocket validation to use notification-channel, subscription-status, routing-category, payload-category, and readiness-requirement parsers, replacing the prior generic command-channel check.

**Files Changed**:

* `apps/web/src/store/useGameStore.ts` - added notification settings state, hydrators, setters, status derivation, and event-merge behavior for usage/readiness.
* `apps/web/src/store/useWsClient.ts` - added enriched usage/readiness sanitizers and enum-array validation before event application.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/tasks.md` - marked T014 complete and updated progress summary.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/implementation-notes.md` - recorded task evidence.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npx biome format --write apps/web/src/store/useGameStore.ts apps/web/src/store/useWsClient.ts`
  * Result: PASS - store and WebSocket files formatted.
  * Evidence: Biome reported `Formatted 2 files`.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm --workspace apps/web run typecheck`
  * Result: PASS - web package compiles with the extended store and WebSocket parsing.
  * Evidence: `tsc -b --noEmit` exited 0 for `@factionos/web`.
* UI product-surface check: N/A - T014 adds state and event parsing only.
* UI craft check: N/A - T014 does not change rendered UI.

**BQC Fixes**:

* Malformed frame rejection: Usage metrics now validate through the protocol metric parser, and readiness arrays validate notification-specific enum values before Zustand mutation.
* Selection stability: Usage/readiness WebSocket frames merge into existing collections so event-window refreshes do not drop currently selected records that were not included in the latest compact frame.

***

### Task T013 - Add web API clients for metrics and notification readiness

**Started**: 2026-06-27 01:41 **Completed**: 2026-06-27 01:54 **Duration**: 13 minutes

**Notes**:

* Added typed web API contracts for usage refresh provider imports, mission artifact estimates, notification preferences, readiness refresh, Web Push subscribe, and unsubscribe.
* Added `recordCommandCenterUsageMetric`, `refreshCommandCenterUsageMetrics`, `fetchCommandCenterNotificationPreferences`, `updateCommandCenterNotificationPreferences`, `fetchCommandCenterNotificationReadinessStatus`, `refreshCommandCenterNotificationReadiness`, `subscribeCommandCenterNotifications`, and `unsubscribeCommandCenterNotifications`.
* Routed usage mutations through the existing command-center mutation helper so stale revision, duplicate in-flight, HTTP conflict, offline, timeout, and invalid response handling remain shared.
* Added response guards for usage refresh, preference/readiness responses, subscription summaries, and unsubscribe status; subscription summaries accept only endpoint hashes and key lengths, not raw endpoints or keys.
* Kept body serializers explicit so UI-only `mutationKey` and `refresh` callbacks are not sent to the server.

**Files Changed**:

* `apps/web/src/lib/orchestrationApi.ts` - added usage and notification API types, route helpers, body serializers, mutation family wiring, and response validators.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/tasks.md` - marked T013 complete and updated progress summary.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/implementation-notes.md` - recorded task evidence.

**Verification**:

* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npx biome format --write apps/web/src/lib/orchestrationApi.ts`
  * Result: PASS - API client source formatted.
  * Evidence: Biome reported `Formatted 1 file`.
* Command/check: `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0 >/dev/null && npm --workspace apps/web run typecheck`
  * Result: PASS - web package compiles with the new API clients.
  * Evidence: `tsc -b --noEmit` exited 0 for `@factionos/web`.
* UI product-surface check: N/A - T013 adds API client plumbing only.
* UI craft check: N/A - T013 does not change rendered UI.

**BQC Fixes**:

* Error consistency: Reused `requestCommandCenterMutation` and `requestJson` so the new endpoints inherit existing offline, timeout, stale revision, duplicate-trigger, HTTP, and malformed-response mapping.
* Payload minimization: Web Push response validation accepts only safe subscription summaries and rejects malformed readiness before store/UI mutation.

### 2026-06-27 - Session Start

**Environment verified**:

* [x] Prerequisites confirmed by spec-system prerequisite script
* [x] Tools available: Node v26.2.0 via nvm, npm 11.16.0, jq 1.7, git 2.43.0
* [x] Directory structure ready

***

### Task T001 - Verify Session 15 prerequisites and boundaries

**Started**: 2026-06-27 01:01 **Completed**: 2026-06-27 01:03 **Duration**: 2 minutes

**Notes**:

* Verified analysis state reports current session `phase19-session15-metrics-and-notifications`, Phase 19 in progress, and Sessions 04, 05, 06, 09, 10, and 14 complete.
* Confirmed Session 15 scope requires operational command-center metrics, attention routing, local notification readiness, and Web Push readiness/subscription gating without analytics capture or active hosted push claims by default.
* Confirmed cumulative security posture remains AT RISK because hosted identity, trusted erasure, production-hosted validation, Cloudflare deploy evidence, and legal review are still no-claim boundaries.
* Confirmed implementation must keep metrics and notification payloads bounded, redacted, metadata-only, and local-first.

**Files Changed**:

* `.spec_system/specs/phase19-session15-metrics-and-notifications/implementation-notes.md` - created session progress and task evidence log.
* `.spec_system/specs/phase19-session15-metrics-and-notifications/tasks.md` - marked T001 complete and added progress summary.

**Verification**:

* Command/check: `bash /home/aiwithapex/.codex/plugins/cache/apex-spec-system/apex-spec/2.1.3-codex/skills/apex-spec/scripts/analyze-project.sh --json`
  * Result: PASS - current session resolved and prerequisite sessions appeared in completed session list.
  * Evidence: Output reported `current_session: phase19-session15-metrics-and-notifications`, `current_phase: 19`, and completed Phase 19 sessions 04, 05, 06, 09, 10, and 14.
* Command/check: `bash /home/aiwithapex/.codex/plugins/cache/apex-spec-system/apex-spec/2.1.3-codex/skills/apex-spec/scripts/check-prereqs.sh --json --env`
  * Result: PASS - spec system, jq, git, and npm workspace manager checks passed.
  * Evidence: Output reported `overall: pass`; Node v26.2.0 was selected through `source "$HOME/.nvm/nvm.sh" && nvm use 26.2.0`.
* Command/check: `sed -n '1,260p' .spec_system/PRD/phase_19/session_15_metrics_and_notifications.md .spec_system/CONSIDERATIONS.md .spec_system/SECURITY-COMPLIANCE.md`
  * Result: PASS - prerequisite, scope, and no-claim boundaries inspected.
  * Evidence: Session PRD keeps analytics out of scope and hosted push gated; considerations and security records keep hosted services disabled/default and no-claim without scoped evidence.
* UI product-surface check: N/A - T001 is planning/context verification only.
* UI craft check: N/A - T001 does not change UI.

***


---

# 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-notes.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.