feat: add persistent dashboard service

config/vulture-whitelist.py

@@ -42,6 +42,7 @@
 spans_with_candidates
 spans_without_candidates
 with_vs_without_median_drain_ratio
+installed
 
 # HTTP handlers are selected by BaseHTTPRequestHandler or route dispatch maps.
 _.do_POST
@@ -75,6 +76,7 @@
 _._handle_context
 _._handle_context_settings
 _._handle_open_investigator
+_._handle_health
 _._handle_status
 _._handle_dedupe_diagnostics
 _._handle_calls

docs/cli-reference.md

@@ -81,6 +81,26 @@ codex-usage-tracker serve-dashboard --no-refresh --open
 codex-usage-tracker serve-dashboard --no-context-api --open
 ```
 
+Keep the live dashboard available across terminal and Codex task lifetimes on
+macOS with the user LaunchAgent commands:
+
+```bash
+codex-usage-tracker dashboard-service install
+codex-usage-tracker dashboard-service status
+codex-usage-tracker dashboard-service uninstall
+```
+
+The persistent service defaults to `http://127.0.0.1:47821`, starts at login,
+restarts after failure, and never opens a browser automatically. Installation
+refuses an occupied port rather than silently changing the URL; use
+`dashboard-service install --port PORT` for an explicit alternative. These
+management actions are macOS-only. The foreground `serve-dashboard` command is
+cross-platform and keeps its existing default port `8765`.
+
+The persistent process starts with the cached aggregate index so the fixed URL
+binds promptly. Its Refresh and Live controls remain the explicit way to rescan
+Codex logs.
+
 `serve-dashboard --context-api explicit` is the default and keeps context loading as an explicit per-row action. `serve-dashboard --no-context-api` or `--context-api disabled` starts with context loading off; a token-protected button in the local details panel can enable it without restarting the server.
 
 `open-dashboard` and `serve-dashboard` refresh active-session logs before opening by default. `serve-dashboard --open` opens the React dashboard; the legacy dashboard remains available at `/dashboard.html` on the same localhost server. Use `--no-refresh` only for an intentionally cached snapshot. The lower-level `dashboard` command writes from the current SQLite index and does not rescan logs.

docs/dashboard-guide.md

@@ -6,15 +6,37 @@ This guide uses synthetic aggregate data. The screenshots do not contain real pr
 
 ## Open The Dashboard
 
-For the best experience, run the localhost dashboard server:
+On macOS, install the persistent localhost dashboard once:
 
 ```bash
 codex-usage-tracker setup
 codex-usage-tracker update-pricing
 codex-usage-tracker update-rate-card
+codex-usage-tracker dashboard-service install
+codex-usage-tracker dashboard-service status
+open http://127.0.0.1:47821
+```
+
+The LaunchAgent starts at login, restarts after a failure, stays bound to
+`127.0.0.1`, and does not open browser tabs automatically. If port `47821` is
+already owned by another process, installation refuses the collision; use
+`dashboard-service install --port PORT` to choose and persist a different
+address. Remove the managed service with
+`codex-usage-tracker dashboard-service uninstall`.
+
+Persistent startup serves the cached aggregate index immediately. Use Refresh
+or Live in the dashboard to rescan Codex logs after the page is reachable.
+
+For Linux, Windows, or an on-demand macOS session, run the foreground server:
+
+```bash
+codex-usage-tracker setup
 codex-usage-tracker serve-dashboard --open
 ```
 
+The foreground command retains its existing default port `8765` and stops when
+its process exits.
+
 For optional allowance context, initialize a local template and copy values from Codex Usage or `/status`:
 
 ```bash

docs/install.md

@@ -11,9 +11,15 @@ python -m pip install --user pipx
 python -m pipx ensurepath
 pipx install codex-usage-tracking
 codex-usage-tracker setup
-codex-usage-tracker serve-dashboard --open
+codex-usage-tracker dashboard-service install  # macOS
 ```
 
+On macOS, the persistent service starts at login, restarts after a failure, and
+keeps the live dashboard available at `http://127.0.0.1:47821` without opening
+browser tabs automatically. Check it with
+`codex-usage-tracker dashboard-service status`. On Linux and Windows, or for a
+one-time macOS session, use `codex-usage-tracker serve-dashboard --open`.
+
 Use the Python launcher that is normal for your platform:
 
 - macOS/Linux: `python3` may be the right command instead of `python`.
@@ -112,6 +118,25 @@ codex-usage-tracker install-plugin --python .venv/bin/python --force
 
 ## Local Dashboard
 
+On macOS, install the localhost-only login service once:
+
+```bash
+codex-usage-tracker dashboard-service install
+codex-usage-tracker dashboard-service status
+open http://127.0.0.1:47821
+```
+
+The service uses fixed port `47821` by default and never exposes a non-loopback
+host. If another local process owns that port, installation stops with a clear
+error instead of changing the URL; choose an explicit alternative with
+`codex-usage-tracker dashboard-service install --port PORT`. To remove only the
+tracker-managed LaunchAgent, run
+`codex-usage-tracker dashboard-service uninstall`.
+
+The login service binds promptly from the cached aggregate index. Use the
+dashboard's Refresh or Live controls when you want to rescan Codex logs; the
+initial background process does not hold the port closed during a full rescan.
+
 Generate a static dashboard:
 
 ```bash
@@ -126,6 +151,9 @@ codex-usage-tracker serve-dashboard --open
 codex-usage-tracker serve-dashboard --no-context-api --open
 ```
 
+Foreground `serve-dashboard` remains the cross-platform, on-demand option and
+retains its existing default port `8765`.
+
 The server binds to localhost, requires a per-server token for refresh/context endpoints, and rejects non-loopback `Host` or cross-origin `Origin` headers.
 `--no-context-api` starts context loading off; the details panel can enable it later without restarting the server.