FEA-1504: Finalize gated agent dashboard

Keep the legacy monitor as the default boot path, put the design-system dashboard runtime and storage behind the explicit Labs flag, and package the embedded agent dashboard assets and tests.

Validation: pnpm -r prebuild; pnpm -C apps/desktop lint; pnpm typecheck; pnpm -C apps/desktop assert:design-system-boundary; pnpm -C apps/desktop test:boot:design-system-off; pnpm -C apps/desktop measure:agent-dashboard-storage; pnpm test; pnpm -C apps/desktop build.

Author: shafty023

.github/workflows/test.yml

@@ -45,5 +45,14 @@ jobs:
       - name: Typecheck
         run: pnpm typecheck
 
+      - name: Assert design-system boundary
+        run: pnpm -C apps/desktop assert:design-system-boundary
+
+      - name: Assert design-system flag-off boot
+        run: pnpm -C apps/desktop test:boot:design-system-off
+
+      - name: Measure Agent Dashboard storage
+        run: pnpm -C apps/desktop measure:agent-dashboard-storage
+
       - name: Run tests
         run: pnpm test

.gitignore

@@ -26,6 +26,9 @@ apps/desktop/.generated/
 apps/desktop/test-results/
 apps/desktop/playwright-report/
 
+# Desktop-local workflow/debug artifacts
+apps/desktop/.closedloop-ai/
+
 # UI Numbers Audit generated reports (FEA-1415 / PLN-738)
 # These embed a timestamp; regenerate locally via `pnpm --filter desktop audit:report`
 # or `node apps/desktop/test-e2e/agent-monitor/inventory/scan-tiles.mjs`.

THIRD_PARTY_NOTICES.md

@@ -1,7 +1,51 @@
 # Third-Party Notices
 
 This product bundles third-party open-source software pinned in
-`apps/desktop/package.json`.
+`apps/desktop/package.json`. Some upstream source is fetched by `pnpm` during
+development/build, and the desktop build generates a runtime tree under
+`apps/desktop/.generated/agent-monitor/` for packaging.
+
+---
+
+## Claude-Code-Agent-Monitor
+
+- **Upstream:** https://github.com/hoangsonww/Claude-Code-Agent-Monitor
+- **Pinned commit:** `840c518d7fa69231de049e41b893938228b67e40`
+- **Imported via:** pnpm dependencies `agent-dashboard` and
+  `agent-dashboard-client`
+- **Usage:** Bundled and run as the default local `127.0.0.1` legacy sidecar
+  dashboard. The desktop build applies local host patches while generating
+  `apps/desktop/.generated/agent-monitor/`.
+- **License:** MIT — © 2026 Son Nguyen.
+
+Bundled runtime dependencies remain pure JS. The generated sidecar runtime uses
+Node's built-in `node:sqlite`; `better-sqlite3` is not used by the shipped
+server, and the packaged desktop runtime strips the hoisted `better-sqlite3`
+module from the staged app tree.
+
+```
+MIT License
+
+Copyright (c) 2026 Son Nguyen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
 
 ---
 

apps/desktop/CLAUDE.md

@@ -136,20 +136,17 @@ Typical log locations:
 
 The Diagnostics tab shows the current in-memory gateway log plus a bounded previous-session tail read from `main.log` at startup. First-run or unreadable log files must not block boot; return an empty previous-session tail and continue.
 
-## Agent Monitor (in-process)
-
-> **Status (FEA-1503):** the agent monitor is FULLY FIRST-PARTY and IN-PROCESS.
-> The third-party agent-monitor vendor tool is GONE — no sidecar, no generated
-> tree, no vendor dependency, no vendor-generated hook handler.
-> `src/main/agent-monitor-listener.ts` (`AgentHookListener`) owns
-> `127.0.0.1:4820` in the main process and writes through the `node:sqlite`
-> repository (`src/main/database/`) via the hook lifecycle state machine
-> (`database/lifecycle.ts`). The renderer is a first-party React app
-> (`src/renderer/`) — there is NO iframe. The first-party collection layer
-> (`src/main/collectors/`) imports historical sessions on boot and watches the
-> live transcript files of all five agent CLIs, writing through the same DB. The
-> cloud relay and cost-reconciliation worker read that DB through the shared
-> connection.
+## Agent Monitor
+
+> **Status (FEA-1504):** Agent Monitor has three boot modes. The default user
+> experience is the legacy sidecar-backed dashboard (`agentMonitorEnabled=true`,
+> `agentDashboardDesignSystemEnabled=false`): pnpm-managed upstream packages are
+> materialized into `.generated/agent-monitor`, shipped unpacked, and rendered in
+> the legacy iframe shell. The in-process design-system dashboard is a Labs
+> opt-in only. When `agentDashboardDesignSystemEnabled` is not the literal
+> boolean `true`, the main process must not load `src/main/database/`,
+> `src/main/collectors/`, `AgentHookListener`, `desktop:db:*`, or the `app://`
+> design renderer path.
 
 The desktop app provides local Claude Code (and opt-in Codex) session/agent
 observability. It powers the **Dashboard** and the agent nav items (Sessions,
@@ -158,22 +155,27 @@ is gated by the persisted `agentMonitorEnabled` desktop setting, which
 **defaults ON**; when disabled, the agent nav items are hidden and only the
 Gateway section remains.
 
-- **Hook listener:** `src/main/agent-monitor-listener.ts` binds `127.0.0.1:4820`
-  in the main process and accepts the hook payload (`POST /api/hooks/event`,
-  `GET /api/health`). Each event is gated by the FEA-1407 sandbox check,
-  harness-stamped from `__provider`, and applied by the lifecycle state machine
-  in one `BEGIN IMMEDIATE` transaction. Started from `startAgentCapture()` (boot
-  + the enable path) **only when `agentMonitorEnabled` is true**, before the
-  gateway-start try-block; a bind failure (EADDRINUSE) degrades to "no monitor"
-  rather than blocking boot.
-- **Collection layer (`src/main/collectors/`):** `CollectorManager` runs a
-  best-effort boot bulk import and live file watchers for all five agent CLIs,
-  writing through the first-party `importSession` into the same in-process DB.
-  It is started/stopped alongside the listener (and stopped in `shutdown()`
-  BEFORE `agentDatabase.close()` so a late fs-watch import can't hit a closed
-  DB). Every parsed session is sandbox-gated (FEA-1407, fail-closed) before any
-  write. Import is idempotent via a per-(session, event_type) high-water-mark on
-  `created_at`. Watchers self-heal if a data dir doesn't exist at boot.
+- **Legacy sidecar (default):** `src/main/agent-monitor-sidecar.ts` launches the
+  generated Claude-Code-Agent-Monitor runtime tree. `build:agent-monitor`
+  materializes the tree from pnpm-managed upstream packages; package/stage logic
+  must keep `.generated/agent-monitor` available for default users.
+- **Design-system runtime (Labs opt-in):** `src/main/agent-dashboard-design-system-runtime.ts`
+  is the only module allowed to import `src/main/database/`,
+  `src/main/collectors/`, `AgentHookListener`, or register `desktop:db:*`. It is
+  reached only through `await import()` after boot mode resolves to
+  `design-system`.
+- **Disabled mode:** `agentMonitorEnabled=false` starts no sidecar, no
+  design-system runtime, no dashboard-derived sync source, and no
+  dashboard-derived cost source.
+- **Hook listener:** in design-system mode, `src/main/agent-monitor-listener.ts`
+  binds `127.0.0.1:4820` in the main process and accepts the hook payload
+  (`POST /api/hooks/event`, `GET /api/health`). Each event is gated by the
+  FEA-1407 sandbox check, harness-stamped from `__provider`, and applied by the
+  lifecycle state machine.
+- **Collection layer (`src/main/collectors/`):** design-system mode uses
+  `CollectorManager` for best-effort boot bulk import and live file watchers for
+  all five agent CLIs, writing through the first-party `importSession` into the
+  same in-process DB.
 - **Fixed port (differs from the gateway):** `127.0.0.1:4820`
   (`AGENT_MONITOR_PORT` in `src/shared/contracts.ts`). It MUST be fixed — the
   hook handler POSTs to `127.0.0.1:${CLAUDE_DASHBOARD_PORT||4820}`, baked into

apps/desktop/ci/README.md

@@ -0,0 +1,46 @@
+# Desktop CI workflow staging
+
+## `audit-gate.yml` — UI Numbers Audit Gate (FEA-1437 Phase 6)
+
+This is the Phase 6 CI gate for the UI Numbers Audit. It lives here, **not** in
+`.github/workflows/`, only because the automation token that opened this PR
+lacks the GitHub `workflow` OAuth scope (pushing a file under
+`.github/workflows/` is rejected without it).
+
+**To activate** (one step, needs a token/UI with `workflow` scope):
+
+```bash
+git mv apps/desktop/ci/audit-gate.yml .github/workflows/audit-gate.yml
+git commit -m "ci: activate UI Numbers Audit gate"
+```
+
+Until moved, the gate does not run automatically, but every check it performs is
+runnable locally and is identical to the existing `test:audit` suite:
+
+```bash
+pnpm -C apps/desktop audit:coverage   # static coverage gate (fast, no build)
+pnpm -C apps/desktop test:audit       # full node-side audit
+pnpm -C apps/desktop test:audit:ui    # headless Playwright tile audit
+```
+
+The workflow has two jobs:
+
+- **coverage** — runs `audit:coverage`: regenerates the tile scan + coverage
+  classification, asserts every scanner detection is classified (no
+  `needs_review`), asserts every harness parser has a `*-parser.contract.test.mjs`,
+  and posts the `by_status` breakdown to the job summary. This is the merge gate
+  that fires when a new route / tile / parser lands without manifest coverage.
+- **ui-audit** — builds the agent-monitor sidecar and runs the headless
+  Playwright tile audits (rendered DOM == oracle).
+
+Real-Electron and visual-regression suites are intentionally excluded (they run
+elsewhere as non-blocking, flaky-by-nature per PLN-760).
+
+### Branch-protection guidance (read before marking required)
+
+Mark **only the `coverage` job** as a required status check. Leave `ui-audit`
+optional (it's heavier — builds the sidecar + Playwright — and shouldn't block on
+infra flake). The workflow has **no `paths:` filter** by design: a required check
+combined with a paths filter deadlocks any PR that doesn't touch `apps/desktop/**`
+(the job never triggers, so the required status sits pending forever). Triggering
+on every PR keeps the required `coverage` check from hanging; the job is fast.

apps/desktop/ci/audit-gate.yml

@@ -0,0 +1,108 @@
+name: UI Numbers Audit Gate
+
+# FEA-1437 Phase 6 — gate PRs on the UI Numbers Audit. Two jobs:
+#   coverage  — fast, static: every scanner detection is classified (no
+#               needs_review), every harness parser has a contract test. This
+#               is the merge gate that fires when a new route / tile / parser
+#               lands without manifest coverage.
+#   ui-audit  — heavier: builds the agent-monitor sidecar and runs the headless
+#               Playwright tile audits (rendered DOM == oracle).
+# Real-Electron + visual-regression suites are intentionally NOT here; they run
+# elsewhere as non-blocking (flaky-by-nature) per PLN-760.
+#
+# NO `paths:` filter on purpose. The `coverage` job is intended to be a REQUIRED
+# status check, and "required check + paths filter" is a classic deadlock: a PR
+# that doesn't touch apps/desktop/** never triggers the job, so the required
+# status sits pending forever and the PR can't merge. Triggering on every PR
+# keeps the required check from hanging. The `coverage` job is fast; only mark
+# `coverage` as required (leave `ui-audit` optional — see apps/desktop/ci/README.md).
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  push:
+    branches: [main]
+
+concurrency:
+  group: audit-gate-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  coverage:
+    name: Coverage gate (static)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      packages: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Generate build info
+        run: pnpm -r prebuild
+      - name: Audit coverage gate
+        run: pnpm -C apps/desktop audit:coverage
+      - name: Coverage summary -> job summary
+        if: always()
+        # Reporting only — never let a summary glitch fail the gate job.
+        continue-on-error: true
+        run: |
+          COV=apps/desktop/test-e2e/agent-monitor/inventory/coverage.json
+          if [ -f "$COV" ]; then
+            {
+              echo "### UI Numbers Audit — coverage"
+              echo ""
+              echo "| status | count |"
+              echo "|---|---|"
+              # Resolve to an absolute path: require() treats a bare relative
+              # string as a node_modules specifier and would throw.
+              node -e '
+                const c = require(require("path").resolve(process.env.COV));
+                for (const [k, v] of Object.entries(c.by_status)) console.log(`| ${k} | ${v} |`);
+                console.log(`| **total** | **${c.total_detections}** |`);
+              '
+            } >> "$GITHUB_STEP_SUMMARY"
+          fi
+        env:
+          COV: apps/desktop/test-e2e/agent-monitor/inventory/coverage.json
+
+  ui-audit:
+    name: UI tile audit (headless Playwright)
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    permissions:
+      contents: read
+      packages: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Generate build info
+        run: pnpm -r prebuild
+      - name: Install Playwright Chromium
+        run: pnpm -C apps/desktop exec playwright install --with-deps chromium
+      - name: Run headless tile audit
+        run: pnpm -C apps/desktop test:audit:ui
+      - name: Upload Playwright report on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-audit-report
+          path: apps/desktop/test-results/
+          retention-days: 7
+          if-no-files-found: ignore

apps/desktop/electron-builder.yml

@@ -14,6 +14,20 @@ extraResources:
     to: trayIconTemplate.png
   - from: resources/trayIconTemplate@2x.png
     to: trayIconTemplate@2x.png
+  # Generated Claude-Code-Agent-Monitor runtime tree, shipped unpacked
+  # (outside the asar) so the spawned Node server, the built client, and the
+  # hook scripts resolve as real files. Built by scripts/build-agent-monitor.mjs
+  # before packaging (chained into `build`). `client/dist/**/*` (NOT
+  # `client/**/*`) — the server resolves ../client/dist relative to server/, so
+  # the server/ <-> client/dist/ layout must be preserved.
+  - from: .generated/agent-monitor
+    to: agent-monitor
+    filter:
+      - server/**/*
+      - client/dist/**/*
+      - scripts/**/*
+      - package.json
+      - LICENSE
   # First-party agent-monitor hook handlers (FEA-1503), shipped unpacked outside
   # the asar so they resolve as real files. agent-monitor-hooks.ts copies them
   # into userData at install time; the installed hook command runs them via the

apps/desktop/package.json

@@ -8,25 +8,44 @@
   "main": "dist/main/index.js",
   "scripts": {
     "dev": "pnpm build && ELECTRON_BIN=$(bash scripts/patch-electron-plist.sh | tail -1) && \"$ELECTRON_BIN\" .",
-    "start": "ELECTRON_BIN=$(bash scripts/patch-electron-plist.sh | tail -1) && \"$ELECTRON_BIN\" .",
-    "clean:dist": "node -e \"require('fs').rmSync('dist/main',{recursive:true,force:true});require('fs').rmSync('dist/server',{recursive:true,force:true})\"",
+    "start": "pnpm build:agent-monitor && ELECTRON_BIN=$(bash scripts/patch-electron-plist.sh | tail -1) && \"$ELECTRON_BIN\" .",
+    "clean:dist": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
     "clean:package": "node -e \"require('fs').rmSync('dist-dmg',{recursive:true,force:true})\"",
     "prebuild": "node -e \"const{execSync:e}=require('child_process'),{writeFileSync:w}=require('fs');const h=e('git rev-parse HEAD').toString().trim();w('src/shared/build-info.ts','// AUTO-GENERATED — do not edit\\nexport const BUILD_COMMIT_HASH = \\\"'+h+'\\\";\\n');\"",
-    "build": "pnpm clean:dist && pnpm prebuild && tsc -p tsconfig.json && pnpm build:renderer",
+    "build": "pnpm clean:dist && pnpm prebuild && tsc -p tsconfig.json && pnpm build:renderer && pnpm build:agent-monitor",
     "build:renderer": "vite build --config vite.renderer.config.ts",
+    "build:agent-monitor": "node scripts/build-agent-monitor.mjs",
     "dashboard:reset": "node scripts/reset-dashboard-db.mjs",
+    "dashboard:reset-packs": "node scripts/reset-dashboard-db.mjs --packs-only",
     "stage:package": "node scripts/stage-packaging-app.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit && pnpm typecheck:renderer",
     "typecheck:renderer": "tsc -p tsconfig.renderer.json --noEmit",
     "lint": "eslint src/",
-    "test": "tsx --test test/*.test.ts",
+    "assert:design-system-boundary": "tsx --test test/agent-dashboard-boundary.test.ts",
+    "test:boot:design-system-off": "node --import tsx scripts/assert-design-system-boot-off.mjs",
+    "measure:agent-dashboard-storage": "node scripts/measure-agent-dashboard-storage.mjs",
+    "test": "tsx --test --test-concurrency=1 test/*.test.ts && node --test \"scripts/agent-monitor-packs/__tests__/*.test.js\" \"scripts/agent-monitor-pull-requests/__tests__/*.test.js\"",
+    "pretest:contract": "pnpm build:agent-monitor",
+    "test:contract": "node --test \"test-e2e/agent-monitor/specs/api-contract/*.test.mjs\"",
+    "pretest:e2e": "pnpm build:agent-monitor",
+    "test:e2e": "playwright test --config test-e2e/agent-monitor/playwright.config.ts",
+    "pretest:audit": "pnpm build:agent-monitor && pnpm audit:scan && pnpm audit:classify",
+    "audit:scan": "node test-e2e/agent-monitor/inventory/scan-tiles.mjs",
+    "audit:classify": "node test-e2e/agent-monitor/inventory/coverage-classifier.mjs",
+    "audit:coverage": "bash scripts/check-audit-coverage.sh",
+    "test:audit": "node --test \"test-e2e/agent-monitor/specs/audit/*.test.mjs\"",
+    "pretest:audit:ui": "pnpm build:agent-monitor",
+    "test:audit:ui": "playwright test --config test-e2e/agent-monitor/playwright.audit.config.ts",
+    "preaudit:report": "pnpm build:agent-monitor",
+    "audit:report": "node test-e2e/agent-monitor/inventory/run-report.mjs",
     "package": "pnpm clean:package && pnpm build && pnpm stage:package && node scripts/run-electron-builder.mjs",
     "release": "pnpm clean:package && pnpm build && pnpm stage:package && node scripts/run-electron-builder.mjs --publish always"
   },
   "dependencies": {
     "@closedloop-ai/design-system": "0.1.1-dev.26892521643.1",
     "@closedloop-ai/loops-api": ">=0.3.1",
     "@pydantic/genai-prices": "0.0.62",
+    "agent-dashboard": "github:hoangsonww/Claude-Code-Agent-Monitor#840c518d7fa69231de049e41b893938228b67e40",
     "busboy": "^1.6.0",
     "electron-log": "^5.4.3",
     "electron-store": "^8.2.0",
@@ -52,10 +71,14 @@
     "@typescript-eslint/eslint-plugin": "^8.57.1",
     "@typescript-eslint/parser": "^8.57.1",
     "@vitejs/plugin-react": "4.3.4",
+    "agent-dashboard-client": "github:hoangsonww/Claude-Code-Agent-Monitor#840c518d7fa69231de049e41b893938228b67e40&path:/client",
+    "autoprefixer": "10.4.20",
     "electron": "^35.0.2",
     "electron-builder": "^26.8.1",
     "eslint": "^10.0.3",
+    "postcss": "8.5.1",
     "tailwindcss": "4.3.0",
+    "tailwindcss-legacy": "npm:tailwindcss@3.4.17",
     "tsx": "^4.19.3",
     "tw-animate-css": "^1.4.0",
     "typescript": "^5.8.2",