From 36c5edd57409f53d027ebab433f82e0142514a81 Mon Sep 17 00:00:00 2001
From: Monsky <douglas.monsky@gmail.com>
Date: Fri, 17 Jul 2026 12:30:36 -0400
Subject: [PATCH 01/12] docs: design persistent dashboard service

---
 ...-17-persistent-dashboard-service-design.md | 184 ++++++++++++++++++
 1 file changed, 184 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-07-17-persistent-dashboard-service-design.md

diff --git a/docs/superpowers/specs/2026-07-17-persistent-dashboard-service-design.md b/docs/superpowers/specs/2026-07-17-persistent-dashboard-service-design.md
new file mode 100644
index 00000000..42a95062
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-17-persistent-dashboard-service-design.md
@@ -0,0 +1,184 @@
+# Persistent Dashboard Service Design
+
+## Goal
+
+Give the local dashboard one memorable address and keep it available across
+Codex tasks, terminal exits, crashes, and Mac logins. The default address is
+`http://127.0.0.1:47821`.
+
+The IP address is deliberately loopback-only. Port `47821` is preferred over
+the existing interactive default, `8765`, because `8765` is registered by IANA
+for Ultraseek HTTP and is commonly used by development servers. Port `47821`
+is not assigned in the IANA service registry, was unused on the target Mac at
+design time, and is below that Mac's `49152-65535` ephemeral range.
+
+## Approaches Considered
+
+### macOS LaunchAgent (selected)
+
+A user LaunchAgent starts the existing dashboard server at login and restarts
+it after an unexpected exit. This is native to macOS, survives terminal and
+Codex task lifetimes, requires no privileged system service, and can remain
+strictly bound to localhost.
+
+### Detached terminal process
+
+This is easy to start but does not reliably survive logout or reboot, has no
+standard status interface, and tends to leave users unsure which process owns
+the port.
+
+### Codex-started background process
+
+Starting the server when Codex opens still couples dashboard availability to
+Codex and makes duplicate-process handling harder. It does not solve the
+request for an independently persistent local address.
+
+## User Interface
+
+Add a nested CLI command with three actions:
+
+```text
+codex-usage-tracker dashboard-service install [--port 47821]
+codex-usage-tracker dashboard-service status
+codex-usage-tracker dashboard-service uninstall
+```
+
+`install` creates or updates the user LaunchAgent, loads it, and prints the
+fixed dashboard URL. It does not open a browser tab. `status` reports whether
+the agent is installed, loaded, running, and reachable, followed by the URL or
+a concise recovery instruction. `uninstall` unloads the managed agent and
+removes only the plist created by this feature.
+
+The first release is intentionally macOS-only. On another operating system,
+all three actions return a clear unsupported-platform error without writing
+files. Linux systemd support can be added separately if a concrete need
+appears.
+
+## Components and Responsibilities
+
+### CLI parser and dispatcher
+
+The existing argparse CLI owns command discovery and dispatch. It validates
+the action and port, then delegates to a dashboard-service module. Service
+lifecycle logic does not belong in the dashboard HTTP server.
+
+### Dashboard-service module
+
+A focused module owns:
+
+- service paths and the stable LaunchAgent label;
+- deterministic plist construction;
+- target-port availability checks;
+- `launchctl` invocation through argument arrays, never shell strings;
+- atomic installation of the generated plist;
+- service status and localhost HTTP reachability checks; and
+- safe removal of the package-managed plist.
+
+The LaunchAgent label is `com.codex-usage-tracker.dashboard`. Its plist lives
+at `~/Library/LaunchAgents/com.codex-usage-tracker.dashboard.plist`. Logs live
+under `~/.codex-usage-tracker/logs/` and contain process diagnostics only; the
+service must not log prompts, raw context, or usage records.
+
+### LaunchAgent process
+
+The generated plist records the absolute Python interpreter used to run the
+install command and launches:
+
+```text
+python -m codex_usage_tracker serve-dashboard
+  --host 127.0.0.1
+  --port 47821
+  --context-api explicit
+```
+
+The actual plist stores these as separate `ProgramArguments`. It uses
+`RunAtLoad` and `KeepAlive`, sets a restart throttle, supplies an explicit
+`HOME`, and does not inject secrets or broaden network access. The browser-open
+flag is omitted.
+
+Using the install-time interpreter avoids relying on launchd's minimal `PATH`.
+If that interpreter later disappears, `status` explains that the service must
+be reinstalled from the current package environment.
+
+## Lifecycle and Data Flow
+
+1. `install` validates macOS, the interpreter, destination directories, and
+   the requested port.
+2. If an unknown process owns the requested port, installation fails and
+   reports the collision. It never kills an unknown process and never silently
+   chooses a different port.
+3. The command writes the deterministic plist atomically, then bootstraps the
+   LaunchAgent in the current user's `gui/<uid>` domain.
+4. launchd starts the existing localhost dashboard server and restarts it when
+   needed.
+5. The dashboard continues using its existing explicit refresh and lazy
+   context-loading behavior. Persistence does not introduce background log
+   polling beyond behavior already performed by `serve-dashboard`.
+6. `status` combines launchd state with a bounded HTTP probe so a loaded but
+   unreachable process is distinguishable from a healthy service.
+
+Installation is idempotent. Re-running it updates the managed plist and
+restarts only the managed LaunchAgent. A port is not literally reserved while
+the service is stopped; while the agent is active, the server's loopback bind
+holds it. The collision checks and fixed configuration make failures explicit
+rather than changing the URL.
+
+## Error Handling
+
+- Invalid or privileged ports fail before filesystem or launchd mutation.
+- A target-port collision names the port and asks the user to stop the owner or
+  reinstall with an explicit alternative.
+- Missing `launchctl`, an invalid user domain, plist write failures, bootstrap
+  failures, and failed health probes produce distinct concise messages.
+- A failed install preserves any previously valid managed plist whenever
+  possible; atomic replacement prevents partial configuration files.
+- Uninstall is idempotent when the service or plist is already absent.
+- Status is read-only and does not attempt automatic repair.
+
+## Privacy and Security
+
+- The server remains bound to `127.0.0.1`; the service interface does not offer
+  a non-loopback host option.
+- Existing explicit raw-context controls remain unchanged.
+- The plist contains only executable paths, fixed arguments, HOME, and log
+  paths. It contains no credentials, session content, database rows, or copied
+  allowance data.
+- Generated logs and service state remain local and are excluded from package
+  and repository artifacts.
+
+## Verification
+
+Implementation follows test-driven development. Tests use temporary homes,
+synthetic inputs, fake subprocess results, and local disposable sockets; they
+must not load or modify the developer's real LaunchAgent during the automated
+suite.
+
+Coverage includes:
+
+- parser and dispatch behavior for all three actions;
+- deterministic, valid plist generation with localhost-only arguments;
+- default and overridden port validation;
+- collision refusal without killing or replacing an unknown listener;
+- idempotent install and uninstall flows;
+- launchctl error translation and missing-interpreter reporting;
+- status distinctions for absent, loaded, running, and HTTP-reachable states;
+- unsupported-platform behavior; and
+- privacy assertions preventing secrets or raw content in plist/log settings.
+
+Focused service tests run first. Because this changes a CLI surface, packaged
+behavior, dashboard startup, and user documentation, the repository's full
+local CI and release-readiness gates run before the branch is considered
+complete.
+
+## Documentation and Rollout
+
+Update the install guide, dashboard guide, CLI reference, and bundled tracker
+skill with the fixed URL and lifecycle commands. Keep `serve-dashboard` and its
+existing default port backward-compatible for interactive users; only the new
+persistent service defaults to `47821`.
+
+After implementation and verification, install the service for the current
+user, confirm `status` reports it reachable, and probe
+`http://127.0.0.1:47821`. The currently running interactive server on `8765`
+is not killed automatically; it may exit naturally without affecting the new
+service.

From d81e1eb54d6b45c9787916c18ad9a775b0262271 Mon Sep 17 00:00:00 2001
From: Monsky <douglas.monsky@gmail.com>
Date: Fri, 17 Jul 2026 12:36:35 -0400
Subject: [PATCH 02/12] docs: plan persistent dashboard service

---
 ...2026-07-17-persistent-dashboard-service.md | 620 ++++++++++++++++++
 1 file changed, 620 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-07-17-persistent-dashboard-service.md

diff --git a/docs/superpowers/plans/2026-07-17-persistent-dashboard-service.md b/docs/superpowers/plans/2026-07-17-persistent-dashboard-service.md
new file mode 100644
index 00000000..ea5dcd41
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-17-persistent-dashboard-service.md
@@ -0,0 +1,620 @@
+# Persistent Dashboard Service Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a macOS LaunchAgent workflow that keeps the localhost dashboard available at `http://127.0.0.1:47821` across Codex tasks, crashes, and user logins.
+
+**Architecture:** A focused `dashboard_service` module owns deterministic plist generation, local port checks, atomic managed-file updates, launchctl lifecycle calls, and health status. A thin CLI adapter exposes `dashboard-service install|status|uninstall`; the existing dashboard HTTP server remains unchanged and continues to enforce localhost/privacy controls.
+
+**Tech Stack:** Python 3.10+, standard-library `argparse`, `plistlib`, `socket`, `subprocess`, `urllib.request`, macOS `launchctl`, pytest.
+
+## Global Constraints
+
+- Keep `serve-dashboard` backward-compatible, including its existing default port `8765`.
+- The persistent service defaults to `127.0.0.1:47821` and offers no non-loopback host option.
+- Use LaunchAgent label `com.codex-usage-tracker.dashboard` and plist path `~/Library/LaunchAgents/com.codex-usage-tracker.dashboard.plist`.
+- Start with `--context-api explicit`, never `--open`, and never put credentials or raw usage content in the plist or service logs.
+- Use the absolute install-time Python interpreter and separate `ProgramArguments`; never invoke launchctl through a shell string.
+- Refuse unknown port owners and never silently select another port or kill an unknown process.
+- Automated tests use temporary homes and fakes/disposable sockets; they never load the developer's real LaunchAgent.
+- Keep existing untracked `.idea/` and `.playwright-cli/` paths untouched.
+
+---
+
+## File Structure
+
+- Create `src/codex_usage_tracker/dashboard_service.py`: constants, status model, paths, plist construction, port/HTTP probes, and macOS lifecycle functions.
+- Create `src/codex_usage_tracker/cli/dashboard_service.py`: argparse namespace adapter and concise human-readable output.
+- Modify `src/codex_usage_tracker/cli/parser_data.py`: nested `dashboard-service` parser.
+- Modify `src/codex_usage_tracker/cli/parser.py`: register the new parser builder.
+- Modify `src/codex_usage_tracker/cli/main.py`: dispatch the new command.
+- Modify `src/codex_usage_tracker/cli/help_i18n.py`: localize new help strings consistently with existing CLI behavior.
+- Create `tests/cli/test_dashboard_service.py`: pure configuration, collision, lifecycle, parser, dispatch, and privacy tests.
+- Modify `docs/install.md`, `docs/dashboard-guide.md`, and `docs/cli-reference.md`: document the stable service URL and lifecycle.
+- Modify both `skills/codex-usage-tracker/SKILL.md` and `src/codex_usage_tracker/plugin_data/skills/codex-usage-tracker/SKILL.md`: prefer a healthy persistent service for dashboard-open requests while retaining the foreground fallback.
+
+---
+
+### Task 1: Deterministic LaunchAgent Configuration and Local Probes
+
+**Files:**
+- Create: `src/codex_usage_tracker/dashboard_service.py`
+- Create: `tests/cli/test_dashboard_service.py`
+
+**Interfaces:**
+- Produces: `DEFAULT_SERVICE_PORT: int`, `SERVICE_LABEL: str`, `DashboardServicePaths`, `DashboardServiceStatus`, `service_paths(home: Path)`, `validate_service_port(port: int)`, `build_launch_agent(python: Path, home: Path, port: int)`, `port_is_available(port: int)`, and `dashboard_is_reachable(port: int)`.
+- Consumes: standard-library types only.
+
+- [ ] **Step 1: Write failing tests for paths, plist privacy, port validation, collision detection, and HTTP probing**
+
+```python
+from __future__ import annotations
+
+import contextlib
+import plistlib
+import socket
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from threading import Thread
+
+import pytest
+
+from codex_usage_tracker.dashboard_service import (
+    DEFAULT_SERVICE_PORT,
+    SERVICE_LABEL,
+    build_launch_agent,
+    dashboard_is_reachable,
+    port_is_available,
+    service_paths,
+    validate_service_port,
+)
+
+
+def test_service_paths_stay_in_user_owned_locations(tmp_path: Path) -> None:
+    paths = service_paths(tmp_path)
+    assert paths.plist == tmp_path / "Library/LaunchAgents/com.codex-usage-tracker.dashboard.plist"
+    assert paths.stdout_log == tmp_path / ".codex-usage-tracker/logs/dashboard-service.stdout.log"
+    assert paths.stderr_log == tmp_path / ".codex-usage-tracker/logs/dashboard-service.stderr.log"
+
+
+def test_launch_agent_is_loopback_only_and_contains_no_content(tmp_path: Path) -> None:
+    payload = build_launch_agent(
+        python=Path("/opt/tracker/bin/python"),
+        home=tmp_path,
+        port=DEFAULT_SERVICE_PORT,
+    )
+    encoded = plistlib.dumps(payload).decode("utf-8")
+    assert payload["Label"] == SERVICE_LABEL
+    assert payload["ProgramArguments"] == [
+        "/opt/tracker/bin/python", "-m", "codex_usage_tracker",
+        "serve-dashboard", "--host", "127.0.0.1", "--port", "47821",
+        "--context-api", "explicit",
+    ]
+    assert payload["RunAtLoad"] is True
+    assert payload["KeepAlive"] is True
+    assert "--open" not in encoded
+    assert "prompt" not in encoded.lower()
+    assert "assistant" not in encoded.lower()
+
+
+@pytest.mark.parametrize("port", [0, 1, 1023, 65536])
+def test_service_port_rejects_privileged_or_invalid_values(port: int) -> None:
+    with pytest.raises(ValueError, match="1024 through 65535"):
+        validate_service_port(port)
+
+
+def test_port_check_detects_an_existing_listener() -> None:
+    listener = socket.socket()
+    listener.bind(("127.0.0.1", 0))
+    listener.listen()
+    port = listener.getsockname()[1]
+    try:
+        assert port_is_available(port) is False
+    finally:
+        listener.close()
+    assert port_is_available(port) is True
+
+
+def test_dashboard_probe_distinguishes_reachable_http_server() -> None:
+    class Handler(BaseHTTPRequestHandler):
+        def do_GET(self) -> None:  # noqa: N802
+            self.send_response(200)
+            self.end_headers()
+            self.wfile.write(b"Codex Usage Tracker")
+
+        def log_message(self, *_: object) -> None:
+            return
+
+    server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+    thread = Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    try:
+        assert dashboard_is_reachable(server.server_port) is True
+    finally:
+        server.shutdown()
+        thread.join()
+        server.server_close()
+```
+
+- [ ] **Step 2: Run the focused tests and verify RED**
+
+Run: `PATH=.venv/bin:$PATH python -m pytest tests/cli/test_dashboard_service.py -q`
+
+Expected: collection fails because `codex_usage_tracker.dashboard_service` does not exist.
+
+- [ ] **Step 3: Implement the minimal deterministic configuration and probe API**
+
+```python
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import socket
+from typing import Any
+from urllib.error import URLError
+from urllib.request import urlopen
+
+DEFAULT_SERVICE_PORT = 47821
+SERVICE_HOST = "127.0.0.1"
+SERVICE_LABEL = "com.codex-usage-tracker.dashboard"
+
+
+@dataclass(frozen=True)
+class DashboardServicePaths:
+    plist: Path
+    stdout_log: Path
+    stderr_log: Path
+
+
+@dataclass(frozen=True)
+class DashboardServiceStatus:
+    installed: bool
+    loaded: bool
+    reachable: bool
+    port: int
+    detail: str
+
+    @property
+    def url(self) -> str:
+        return f"http://{SERVICE_HOST}:{self.port}"
+
+
+def service_paths(home: Path) -> DashboardServicePaths:
+    logs = home / ".codex-usage-tracker" / "logs"
+    return DashboardServicePaths(
+        plist=home / "Library" / "LaunchAgents" / f"{SERVICE_LABEL}.plist",
+        stdout_log=logs / "dashboard-service.stdout.log",
+        stderr_log=logs / "dashboard-service.stderr.log",
+    )
+
+
+def validate_service_port(port: int) -> int:
+    if not 1024 <= port <= 65535:
+        raise ValueError("dashboard service port must be 1024 through 65535")
+    return port
+
+
+def build_launch_agent(*, python: Path, home: Path, port: int) -> dict[str, Any]:
+    paths = service_paths(home)
+    return {
+        "Label": SERVICE_LABEL,
+        "ProgramArguments": [
+            str(python), "-m", "codex_usage_tracker", "serve-dashboard",
+            "--host", SERVICE_HOST, "--port", str(validate_service_port(port)),
+            "--context-api", "explicit",
+        ],
+        "EnvironmentVariables": {"HOME": str(home)},
+        "RunAtLoad": True,
+        "KeepAlive": True,
+        "ThrottleInterval": 10,
+        "StandardOutPath": str(paths.stdout_log),
+        "StandardErrorPath": str(paths.stderr_log),
+    }
+
+
+def port_is_available(port: int) -> bool:
+    validate_service_port(port)
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as candidate:
+        try:
+            candidate.bind((SERVICE_HOST, port))
+        except OSError:
+            return False
+    return True
+
+
+def dashboard_is_reachable(port: int, *, timeout: float = 1.0) -> bool:
+    try:
+        with urlopen(f"http://{SERVICE_HOST}:{port}/", timeout=timeout) as response:  # noqa: S310
+            return response.status == 200
+    except (OSError, URLError):
+        return False
+```
+
+- [ ] **Step 4: Run focused tests and verify GREEN**
+
+Run: `PATH=.venv/bin:$PATH python -m pytest tests/cli/test_dashboard_service.py -q`
+
+Expected: all Task 1 tests pass.
+
+- [ ] **Step 5: Commit Task 1**
+
+```bash
+git add -- src/codex_usage_tracker/dashboard_service.py tests/cli/test_dashboard_service.py
+git commit -m "feat: define persistent dashboard service"
+```
+
+---
+
+### Task 2: Safe launchctl Lifecycle
+
+**Files:**
+- Modify: `src/codex_usage_tracker/dashboard_service.py`
+- Modify: `tests/cli/test_dashboard_service.py`
+
+**Interfaces:**
+- Consumes: Task 1 constants, paths, plist builder, port check, and health probe.
+- Produces: `install_dashboard_service`, `dashboard_service_status`, and `uninstall_dashboard_service`, each returning `DashboardServiceStatus` and using the exact keyword-only signatures in Step 3.
+
+- [ ] **Step 1: Add failing lifecycle tests using a fake launchctl runner and temporary home**
+
+Add tests that define a `FakeRunner` recording `list[str]` commands and returning `subprocess.CompletedProcess`. Assert these exact behaviors:
+
+```python
+import subprocess
+
+
+class FakeRunner:
+    def __init__(self, *, print_returncode: int = 1, bootstrap_returncode: int = 0) -> None:
+        self.print_returncode = print_returncode
+        self.bootstrap_returncode = bootstrap_returncode
+        self.commands: list[list[str]] = []
+
+    def __call__(self, command: list[str], **_: object) -> subprocess.CompletedProcess[str]:
+        self.commands.append(command)
+        if command[1] == "print":
+            return subprocess.CompletedProcess(command, self.print_returncode, "", "not loaded")
+        if command[1] == "bootstrap":
+            return subprocess.CompletedProcess(command, self.bootstrap_returncode, "", "bootstrap failed")
+        return subprocess.CompletedProcess(command, 0, "", "")
+
+
+def test_install_writes_valid_plist_and_bootstraps_user_domain(tmp_path: Path) -> None:
+    runner = FakeRunner()
+    python = tmp_path / "python"
+    python.touch()
+    status = install_dashboard_service(
+        home=tmp_path,
+        python=python,
+        port=47821,
+        platform="darwin",
+        uid=501,
+        runner=runner,
+        port_available=lambda _: True,
+        reachable=lambda _: True,
+    )
+    payload = plistlib.loads(service_paths(tmp_path).plist.read_bytes())
+    assert payload["Label"] == SERVICE_LABEL
+    assert runner.commands[-2:] == [
+        ["launchctl", "bootstrap", "gui/501", str(service_paths(tmp_path).plist)],
+        ["launchctl", "kickstart", "-k", f"gui/501/{SERVICE_LABEL}"],
+    ]
+    assert status.installed and status.loaded and status.reachable
+
+
+def test_install_refuses_unknown_port_owner_without_writing(tmp_path: Path) -> None:
+    python = tmp_path / "python"
+    python.touch()
+    with pytest.raises(RuntimeError, match="47821 is already in use"):
+        install_dashboard_service(
+            home=tmp_path,
+            python=python,
+            port=47821,
+            platform="darwin",
+            uid=501,
+            runner=FakeRunner(),
+            port_available=lambda _: False,
+            reachable=lambda _: False,
+        )
+    assert not service_paths(tmp_path).plist.exists()
+
+
+def test_status_is_read_only_and_reports_loaded_but_unreachable(tmp_path: Path) -> None:
+    paths = service_paths(tmp_path)
+    paths.plist.parent.mkdir(parents=True)
+    paths.plist.write_bytes(plistlib.dumps(build_launch_agent(
+        python=Path("/opt/tracker/bin/python"), home=tmp_path, port=47821,
+    )))
+    runner = FakeRunner(print_returncode=0)
+    status = dashboard_service_status(
+        home=tmp_path, platform="darwin", uid=501, runner=runner,
+        reachable=lambda _: False,
+    )
+    assert status == DashboardServiceStatus(True, True, False, 47821, "loaded but unreachable")
+    assert runner.commands == [["launchctl", "print", f"gui/501/{SERVICE_LABEL}"]]
+
+
+def test_uninstall_is_idempotent_and_removes_only_managed_plist(tmp_path: Path) -> None:
+    paths = service_paths(tmp_path)
+    paths.plist.parent.mkdir(parents=True)
+    paths.plist.write_text("managed")
+    unrelated = paths.plist.parent / "other.plist"
+    unrelated.write_text("keep")
+    runner = FakeRunner()
+    status = uninstall_dashboard_service(
+        home=tmp_path, platform="darwin", uid=501, runner=runner,
+    )
+    assert not paths.plist.exists()
+    assert unrelated.read_text() == "keep"
+    assert status.installed is False
+```
+
+Also cover non-darwin refusal, a missing interpreter, repeated install with an identical healthy plist returning without a restart, a changed managed plist being booted out before replacement, atomic restoration after bootstrap failure, and port extraction from an existing plist.
+
+- [ ] **Step 2: Run lifecycle tests and verify RED**
+
+Run: `PATH=.venv/bin:$PATH python -m pytest tests/cli/test_dashboard_service.py -q`
+
+Expected: failures report missing lifecycle functions.
+
+- [ ] **Step 3: Implement the lifecycle with explicit injectable boundaries**
+
+Use these exact keyword-only signatures and command shapes. The implementation body follows the helper algorithm immediately below rather than leaving stub bodies in source:
+
+```python
+Runner = Callable[..., subprocess.CompletedProcess[str]]
+
+INSTALL_SIGNATURE = "install_dashboard_service(*, home: Path, python: Path, port: int = DEFAULT_SERVICE_PORT, platform: str = sys.platform, uid: int | None = None, runner: Runner = subprocess.run, port_available: Callable[[int], bool] = port_is_available, reachable: Callable[[int], bool] = dashboard_is_reachable) -> DashboardServiceStatus"
+STATUS_SIGNATURE = "dashboard_service_status(*, home: Path, platform: str = sys.platform, uid: int | None = None, runner: Runner = subprocess.run, reachable: Callable[[int], bool] = dashboard_is_reachable) -> DashboardServiceStatus"
+UNINSTALL_SIGNATURE = "uninstall_dashboard_service(*, home: Path, platform: str = sys.platform, uid: int | None = None, runner: Runner = subprocess.run) -> DashboardServiceStatus"
+```
+
+Implement small private helpers `_require_macos`, `_domain(uid)`, `_target(uid)`, `_run_launchctl`, `_read_installed_port`, and `_atomic_write_plist`. `runner` receives argument arrays, `check=False`, `capture_output=True`, and `text=True`. Treat `launchctl print gui/<uid>/<label>` return code zero as loaded. For a changed managed config, boot out `gui/<uid>/<label>`, verify the new target port is free, atomically replace the plist, bootstrap it, then kickstart it. Preserve previous bytes and restore/re-bootstrap them if bootstrap fails. Never call `kill`, `pkill`, or inspect raw session logs.
+
+- [ ] **Step 4: Run lifecycle tests and verify GREEN**
+
+Run: `PATH=.venv/bin:$PATH python -m pytest tests/cli/test_dashboard_service.py -q`
+
+Expected: all Task 1 and Task 2 tests pass.
+
+- [ ] **Step 5: Commit Task 2**
+
+```bash
+git add -- src/codex_usage_tracker/dashboard_service.py tests/cli/test_dashboard_service.py
+git commit -m "feat: manage dashboard launch agent lifecycle"
+```
+
+---
+
+### Task 3: CLI Integration and Messages
+
+**Files:**
+- Create: `src/codex_usage_tracker/cli/dashboard_service.py`
+- Modify: `src/codex_usage_tracker/cli/parser_data.py`
+- Modify: `src/codex_usage_tracker/cli/parser.py`
+- Modify: `src/codex_usage_tracker/cli/main.py`
+- Modify: `src/codex_usage_tracker/cli/help_i18n.py`
+- Modify: `tests/cli/test_dashboard_service.py`
+
+**Interfaces:**
+- Consumes: Task 2 lifecycle functions and `DashboardServiceStatus`.
+- Produces: `_add_dashboard_service_parser` and `run_dashboard_service(args: argparse.Namespace) -> int` registered under top-level command `dashboard-service`.
+
+- [ ] **Step 1: Add failing parser and dispatch tests**
+
+```python
+def test_dashboard_service_parser_defaults_install_port() -> None:
+    args = build_parser("en").parse_args(["dashboard-service", "install"])
+    assert args.command == "dashboard-service"
+    assert args.service_action == "install"
+    assert args.port == 47821
+
+
+def test_dashboard_service_status_prints_stable_url(monkeypatch, capsys) -> None:
+    monkeypatch.setattr(
+        cli_dashboard_service,
+        "dashboard_service_status",
+        lambda **_: DashboardServiceStatus(True, True, True, 47821, "healthy"),
+    )
+    args = argparse.Namespace(service_action="status", port=47821)
+    assert cli_dashboard_service.run_dashboard_service(args) == 0
+    assert capsys.readouterr().out == (
+        "Dashboard service is healthy at http://127.0.0.1:47821\n"
+    )
+
+
+def test_main_dispatches_dashboard_service(monkeypatch) -> None:
+    called = []
+    monkeypatch.setattr(cli_main, "run_dashboard_service", lambda args: called.append(args) or 0)
+    monkeypatch.setitem(cli_main._COMMAND_HANDLERS, "dashboard-service", cli_main.run_dashboard_service)
+    monkeypatch.setattr(sys, "argv", ["codex-usage-tracker", "dashboard-service", "status"])
+    assert cli_main._main() == 0
+    assert called[0].service_action == "status"
+```
+
+Also assert `install --port 48123` forwards the override, `uninstall` does not accept `--port`, unhealthy status returns exit code 1, and help contains install/status/uninstall descriptions in English and localized CLI output remains valid.
+
+- [ ] **Step 2: Run CLI tests and verify RED**
+
+Run: `PATH=.venv/bin:$PATH python -m pytest tests/cli/test_dashboard_service.py tests/cli/test_cli_help_i18n.py -q`
+
+Expected: parser rejects `dashboard-service` and the CLI adapter import is missing.
+
+- [ ] **Step 3: Implement parser registration, dispatch, and concise output**
+
+Parser shape:
+
+```python
+def _add_dashboard_service_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    service = subparsers.add_parser("dashboard-service", help="Manage the persistent dashboard service")
+    actions = service.add_subparsers(dest="service_action", required=True)
+    install = actions.add_parser("install", help="Install and start the dashboard service")
+    install.add_argument("--port", type=int, default=DEFAULT_SERVICE_PORT)
+    actions.add_parser("status", help="Show dashboard service health")
+    actions.add_parser("uninstall", help="Stop and remove the dashboard service")
+```
+
+CLI adapter shape:
+
+```python
+def run_dashboard_service(args: argparse.Namespace) -> int:
+    home = Path.home()
+    if args.service_action == "install":
+        status = install_dashboard_service(home=home, python=Path(sys.executable), port=args.port)
+        print(f"Dashboard service installed at {status.url}")
+        return 0 if status.reachable else 1
+    if args.service_action == "status":
+        status = dashboard_service_status(home=home)
+        if status.reachable:
+            print(f"Dashboard service is healthy at {status.url}")
+            return 0
+        print(f"Dashboard service is {status.detail}; expected {status.url}")
+        return 1
+    status = uninstall_dashboard_service(home=home)
+    print("Dashboard service uninstalled")
+    return 0
+```
+
+Import and register `_add_dashboard_service_parser` in `build_parser`, and import/register `run_dashboard_service` in `_COMMAND_HANDLERS`. Add exact new help strings to the Chinese localization mapping, preserving English fallback behavior.
+
+- [ ] **Step 4: Run CLI tests and verify GREEN**
+
+Run: `PATH=.venv/bin:$PATH python -m pytest tests/cli/test_dashboard_service.py tests/cli/test_cli_help_i18n.py -q`
+
+Expected: all selected tests pass.
+
+- [ ] **Step 5: Run static checks for the new Python surface**
+
+Run: `PATH=.venv/bin:$PATH python -m ruff check src/codex_usage_tracker/dashboard_service.py src/codex_usage_tracker/cli/dashboard_service.py tests/cli/test_dashboard_service.py`
+
+Run: `PATH=.venv/bin:$PATH python -m mypy`
+
+Expected: both commands pass with no errors.
+
+- [ ] **Step 6: Commit Task 3**
+
+```bash
+git add -- src/codex_usage_tracker/cli/dashboard_service.py src/codex_usage_tracker/cli/parser_data.py src/codex_usage_tracker/cli/parser.py src/codex_usage_tracker/cli/main.py src/codex_usage_tracker/cli/help_i18n.py tests/cli/test_dashboard_service.py
+git commit -m "feat: expose dashboard service commands"
+```
+
+---
+
+### Task 4: Documentation and Bundled Skill
+
+**Files:**
+- Modify: `docs/install.md`
+- Modify: `docs/dashboard-guide.md`
+- Modify: `docs/cli-reference.md`
+- Modify: `skills/codex-usage-tracker/SKILL.md`
+- Modify: `src/codex_usage_tracker/plugin_data/skills/codex-usage-tracker/SKILL.md`
+
+**Interfaces:**
+- Consumes: the exact Task 3 command names and `http://127.0.0.1:47821` default.
+- Produces: user-facing setup, operation, fallback, and privacy guidance; synchronized packaged skill behavior.
+
+- [ ] **Step 1: Update docs with exact lifecycle workflow**
+
+Document this primary macOS flow in all relevant locations:
+
+```text
+codex-usage-tracker dashboard-service install
+codex-usage-tracker dashboard-service status
+open http://127.0.0.1:47821
+codex-usage-tracker dashboard-service uninstall
+```
+
+State that the service starts at login, restarts after failure, stays localhost-only, does not open browser tabs, and can use `install --port PORT` when the default is occupied. Clarify that foreground `serve-dashboard --open` remains the cross-platform/on-demand fallback and retains port `8765`.
+
+- [ ] **Step 2: Update both skill copies identically**
+
+Change the dashboard-open fast path to check `codex-usage-tracker dashboard-service status` first on macOS. If healthy, open/report `http://127.0.0.1:47821`; otherwise use the existing `serve-dashboard --context-api explicit --open` fallback. Do not add repository inspection or raw-log access to the fast path.
+
+- [ ] **Step 3: Verify documentation and packaged-skill consistency**
+
+Run: `cmp skills/codex-usage-tracker/SKILL.md src/codex_usage_tracker/plugin_data/skills/codex-usage-tracker/SKILL.md`
+
+Expected: exit code 0.
+
+Run: `PATH=.venv/bin:$PATH python scripts/check_release.py`
+
+Run: `git diff --check`
+
+Expected: both checks pass.
+
+- [ ] **Step 4: Commit Task 4**
+
+```bash
+git add -- docs/install.md docs/dashboard-guide.md docs/cli-reference.md skills/codex-usage-tracker/SKILL.md src/codex_usage_tracker/plugin_data/skills/codex-usage-tracker/SKILL.md
+git commit -m "docs: explain persistent dashboard service"
+```
+
+---
+
+### Task 5: Full Verification and Local Installation
+
+**Files:**
+- No intended source edits; fix only failures caused by Tasks 1-4 and commit those fixes separately.
+- Local managed state after checks: `~/Library/LaunchAgents/com.codex-usage-tracker.dashboard.plist` and `~/.codex-usage-tracker/logs/`.
+
+**Interfaces:**
+- Consumes: completed CLI and lifecycle implementation.
+- Produces: verified branch plus a healthy user LaunchAgent at the fixed local URL.
+
+- [ ] **Step 1: Run focused service and CLI regression tests**
+
+Run: `PATH=.venv/bin:$PATH python -m pytest tests/cli/test_dashboard_service.py tests/cli/test_cli_dashboard.py tests/cli/test_cli_lifecycle.py tests/cli/test_cli_help_i18n.py -q`
+
+Expected: all tests pass.
+
+- [ ] **Step 2: Run the repository's full local CI gate**
+
+```bash
+PATH=.venv/bin:$PATH python -m ruff check .
+PATH=.venv/bin:$PATH python -m mypy
+PATH=.venv/bin:$PATH python -m pytest
+PATH=.venv/bin:$PATH python -m pytest --cov=codex_usage_tracker --cov-report=term-missing
+PATH=.venv/bin:$PATH python -m compileall src
+for file in src/codex_usage_tracker/plugin_data/dashboard/dashboard*.js; do node --check "$file"; done
+PATH=.venv/bin:$PATH python scripts/check_release.py
+git diff --check
+```
+
+Expected: every command passes. If an unrelated pre-existing failure appears, record it exactly and do not broaden the patch.
+
+- [ ] **Step 3: Build and validate package artifacts**
+
+```bash
+rm -rf dist build src/codex_usage_tracker.egg-info src/codex_usage_tracking.egg-info
+PATH=.venv/bin:$PATH python -m build
+PATH=.venv/bin:$PATH python -m twine check dist/*
+PATH=.venv/bin:$PATH python scripts/check_release.py --dist
+PATH=.venv/bin:$PATH python scripts/smoke_installed_package.py
+```
+
+Expected: build, twine, distribution inspection, and installed-package smoke checks pass. The cleanup is limited to generated build artifacts named by the repository's documented validation workflow.
+
+- [ ] **Step 4: Review final Git state and privacy**
+
+Run: `git status --short --branch`, `git diff --stat main...HEAD`, and `git diff main...HEAD`.
+
+Expected: only the spec, plan, implementation, synthetic tests, docs, and synchronized skill assets are changed; no plist, logs, database, real prompts, session content, secrets, `.idea/`, or `.playwright-cli/` files are tracked.
+
+- [ ] **Step 5: Install the service from the stable Codex workspace**
+
+Run: `PATH=.venv/bin:$PATH .venv/bin/python -m codex_usage_tracker dashboard-service install`
+
+Expected: `Dashboard service installed at http://127.0.0.1:47821` and exit code 0. This is an explicitly requested non-production local user-service mutation.
+
+- [ ] **Step 6: Verify persistence and reachability**
+
+Run: `PATH=.venv/bin:$PATH .venv/bin/python -m codex_usage_tracker dashboard-service status`
+
+Expected: `Dashboard service is healthy at http://127.0.0.1:47821`.
+
+Run: `/Users/Monsky/.codex/bin/codex-probe-local-url http://127.0.0.1:47821`
+
+Expected: HTTP success from the Codex Usage Tracker dashboard.
+
+- [ ] **Step 7: Report completion**
+
+Report the fixed URL, branch, commits, validation results, any skipped gates, and the exact `status` and `uninstall` commands. Do not stop or remove the existing interactive process on port `8765`; it may exit naturally.

From 0b5dffa6003da755e7f8748f415cd9ff5a85ce26 Mon Sep 17 00:00:00 2001
From: Monsky <douglas.monsky@gmail.com>
Date: Fri, 17 Jul 2026 12:48:17 -0400
Subject: [PATCH 03/12] feat: define persistent dashboard service

---
 src/codex_usage_tracker/dashboard_service.py | 110 +++++++++++++++++++
 tests/cli/test_dashboard_service.py          | 101 +++++++++++++++++
 2 files changed, 211 insertions(+)
 create mode 100644 src/codex_usage_tracker/dashboard_service.py
 create mode 100644 tests/cli/test_dashboard_service.py

diff --git a/src/codex_usage_tracker/dashboard_service.py b/src/codex_usage_tracker/dashboard_service.py
new file mode 100644
index 00000000..e66e53e1
--- /dev/null
+++ b/src/codex_usage_tracker/dashboard_service.py
@@ -0,0 +1,110 @@
+"""Persistent localhost dashboard service support."""
+
+from __future__ import annotations
+
+import socket
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+from urllib.error import URLError
+from urllib.request import urlopen
+
+DEFAULT_SERVICE_PORT = 47821
+SERVICE_HOST = "127.0.0.1"
+SERVICE_LABEL = "com.codex-usage-tracker.dashboard"
+
+
+@dataclass(frozen=True)
+class DashboardServicePaths:
+    """User-owned files managed by the dashboard service commands."""
+
+    plist: Path
+    stdout_log: Path
+    stderr_log: Path
+
+
+@dataclass(frozen=True)
+class DashboardServiceStatus:
+    """Installed, launchd, and HTTP state for the persistent dashboard."""
+
+    installed: bool
+    loaded: bool
+    reachable: bool
+    port: int
+    detail: str
+
+    @property
+    def url(self) -> str:
+        return f"http://{SERVICE_HOST}:{self.port}"
+
+
+def service_paths(home: Path) -> DashboardServicePaths:
+    """Return the LaunchAgent and diagnostic log paths for one user."""
+
+    logs = home / ".codex-usage-tracker" / "logs"
+    return DashboardServicePaths(
+        plist=home / "Library" / "LaunchAgents" / f"{SERVICE_LABEL}.plist",
+        stdout_log=logs / "dashboard-service.stdout.log",
+        stderr_log=logs / "dashboard-service.stderr.log",
+    )
+
+
+def validate_service_port(port: int) -> int:
+    """Reject privileged and invalid service ports."""
+
+    if not 1024 <= port <= 65535:
+        raise ValueError("dashboard service port must be 1024 through 65535")
+    return port
+
+
+def build_launch_agent(*, python: Path, home: Path, port: int) -> dict[str, Any]:
+    """Build a deterministic localhost-only LaunchAgent property list."""
+
+    paths = service_paths(home)
+    return {
+        "Label": SERVICE_LABEL,
+        "ProgramArguments": [
+            str(python),
+            "-m",
+            "codex_usage_tracker",
+            "serve-dashboard",
+            "--host",
+            SERVICE_HOST,
+            "--port",
+            str(validate_service_port(port)),
+            "--context-api",
+            "explicit",
+        ],
+        "EnvironmentVariables": {"HOME": str(home)},
+        "RunAtLoad": True,
+        "KeepAlive": True,
+        "ThrottleInterval": 10,
+        "StandardOutPath": str(paths.stdout_log),
+        "StandardErrorPath": str(paths.stderr_log),
+    }
+
+
+def port_is_available(port: int) -> bool:
+    """Return whether the fixed loopback port can be bound now."""
+
+    validate_service_port(port)
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as candidate:
+        try:
+            candidate.bind((SERVICE_HOST, port))
+        except OSError:
+            return False
+    return True
+
+
+def dashboard_is_reachable(port: int, *, timeout: float = 1.0) -> bool:
+    """Return whether an HTTP server responds at the dashboard root."""
+
+    validate_service_port(port)
+    try:
+        with urlopen(  # noqa: S310 - fixed loopback URL only
+            f"http://{SERVICE_HOST}:{port}/",
+            timeout=timeout,
+        ) as response:
+            return response.status == 200
+    except (OSError, URLError):
+        return False
diff --git a/tests/cli/test_dashboard_service.py b/tests/cli/test_dashboard_service.py
new file mode 100644
index 00000000..12964b8c
--- /dev/null
+++ b/tests/cli/test_dashboard_service.py
@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import plistlib
+import socket
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from threading import Thread
+
+import pytest
+
+from codex_usage_tracker.dashboard_service import (
+    DEFAULT_SERVICE_PORT,
+    SERVICE_LABEL,
+    build_launch_agent,
+    dashboard_is_reachable,
+    port_is_available,
+    service_paths,
+    validate_service_port,
+)
+
+
+def test_service_paths_stay_in_user_owned_locations(tmp_path: Path) -> None:
+    paths = service_paths(tmp_path)
+
+    assert paths.plist == (
+        tmp_path / "Library/LaunchAgents/com.codex-usage-tracker.dashboard.plist"
+    )
+    assert paths.stdout_log == (
+        tmp_path / ".codex-usage-tracker/logs/dashboard-service.stdout.log"
+    )
+    assert paths.stderr_log == (
+        tmp_path / ".codex-usage-tracker/logs/dashboard-service.stderr.log"
+    )
+
+
+def test_launch_agent_is_loopback_only_and_contains_no_content(tmp_path: Path) -> None:
+    payload = build_launch_agent(
+        python=Path("/opt/tracker/bin/python"),
+        home=tmp_path,
+        port=DEFAULT_SERVICE_PORT,
+    )
+
+    encoded = plistlib.dumps(payload).decode("utf-8")
+    assert payload["Label"] == SERVICE_LABEL
+    assert payload["ProgramArguments"] == [
+        "/opt/tracker/bin/python",
+        "-m",
+        "codex_usage_tracker",
+        "serve-dashboard",
+        "--host",
+        "127.0.0.1",
+        "--port",
+        "47821",
+        "--context-api",
+        "explicit",
+    ]
+    assert payload["RunAtLoad"] is True
+    assert payload["KeepAlive"] is True
+    assert "--open" not in encoded
+    assert "prompt" not in encoded.lower()
+    assert "assistant" not in encoded.lower()
+
+
+@pytest.mark.parametrize("port", [0, 1, 1023, 65536])
+def test_service_port_rejects_privileged_or_invalid_values(port: int) -> None:
+    with pytest.raises(ValueError, match="1024 through 65535"):
+        validate_service_port(port)
+
+
+def test_port_check_detects_an_existing_listener() -> None:
+    listener = socket.socket()
+    listener.bind(("127.0.0.1", 0))
+    listener.listen()
+    port = listener.getsockname()[1]
+    try:
+        assert port_is_available(port) is False
+    finally:
+        listener.close()
+
+    assert port_is_available(port) is True
+
+
+def test_dashboard_probe_distinguishes_reachable_http_server() -> None:
+    class Handler(BaseHTTPRequestHandler):
+        def do_GET(self) -> None:  # noqa: N802
+            self.send_response(200)
+            self.end_headers()
+            self.wfile.write(b"Codex Usage Tracker")
+
+        def log_message(self, *_: object) -> None:
+            return
+
+    server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+    thread = Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    try:
+        assert dashboard_is_reachable(server.server_port) is True
+    finally:
+        server.shutdown()
+        thread.join()
+        server.server_close()

From eee2f6f09f3a99ebe53ae3d4cfa2d240d0d87c26 Mon Sep 17 00:00:00 2001
From: Monsky <douglas.monsky@gmail.com>
Date: Fri, 17 Jul 2026 12:51:12 -0400
Subject: [PATCH 04/12] feat: manage dashboard launch agent lifecycle

---
 src/codex_usage_tracker/dashboard_service.py | 249 +++++++++++++++++++
 tests/cli/test_dashboard_service.py          | 240 ++++++++++++++++++
 2 files changed, 489 insertions(+)

diff --git a/src/codex_usage_tracker/dashboard_service.py b/src/codex_usage_tracker/dashboard_service.py
index e66e53e1..5086c92f 100644
--- a/src/codex_usage_tracker/dashboard_service.py
+++ b/src/codex_usage_tracker/dashboard_service.py
@@ -2,7 +2,14 @@
 
 from __future__ import annotations
 
+import os
+import plistlib
 import socket
+import subprocess
+import sys
+import tempfile
+import time
+from collections.abc import Callable
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
@@ -13,6 +20,8 @@
 SERVICE_HOST = "127.0.0.1"
 SERVICE_LABEL = "com.codex-usage-tracker.dashboard"
 
+Runner = Callable[..., subprocess.CompletedProcess[str]]
+
 
 @dataclass(frozen=True)
 class DashboardServicePaths:
@@ -108,3 +117,243 @@ def dashboard_is_reachable(port: int, *, timeout: float = 1.0) -> bool:
             return response.status == 200
     except (OSError, URLError):
         return False
+
+
+def install_dashboard_service(
+    *,
+    home: Path,
+    python: Path,
+    port: int = DEFAULT_SERVICE_PORT,
+    platform: str = sys.platform,
+    uid: int | None = None,
+    runner: Runner = subprocess.run,
+    port_available: Callable[[int], bool] = port_is_available,
+    reachable: Callable[[int], bool] = dashboard_is_reachable,
+) -> DashboardServiceStatus:
+    """Install or update the current user's persistent dashboard service."""
+
+    _require_macos(platform)
+    validate_service_port(port)
+    if not python.is_file():
+        raise FileNotFoundError(f"dashboard service Python interpreter not found: {python}")
+
+    paths = service_paths(home)
+    desired = plistlib.dumps(
+        build_launch_agent(python=python, home=home, port=port),
+        sort_keys=True,
+    )
+    previous = paths.plist.read_bytes() if paths.plist.exists() else None
+    target_uid = os.getuid() if uid is None else uid
+    loaded = _is_loaded(target_uid, runner)
+
+    if previous == desired and loaded:
+        healthy = reachable(port)
+        return DashboardServiceStatus(
+            True,
+            True,
+            healthy,
+            port,
+            "healthy" if healthy else "loaded but unreachable",
+        )
+
+    if loaded:
+        result = _run_launchctl(runner, "bootout", _target(target_uid))
+        if result.returncode != 0:
+            raise RuntimeError(_launchctl_error("bootout", result))
+
+    if not port_available(port):
+        if loaded and previous is not None:
+            _restore_previous(paths, previous, target_uid, runner)
+        raise RuntimeError(
+            f"dashboard service port {port} is already in use; "
+            "stop its owner or install with --port PORT"
+        )
+
+    paths.plist.parent.mkdir(parents=True, exist_ok=True)
+    paths.stdout_log.parent.mkdir(parents=True, exist_ok=True)
+    _atomic_write(paths.plist, desired)
+
+    result = _run_launchctl(runner, "bootstrap", _domain(target_uid), str(paths.plist))
+    if result.returncode != 0:
+        _restore_after_failure(paths, previous, loaded, target_uid, runner)
+        raise RuntimeError(_launchctl_error("bootstrap", result))
+
+    result = _run_launchctl(runner, "kickstart", "-k", _target(target_uid))
+    if result.returncode != 0:
+        _restore_after_failure(paths, previous, loaded, target_uid, runner)
+        raise RuntimeError(_launchctl_error("kickstart", result))
+
+    healthy = _wait_until_reachable(port, reachable)
+    return DashboardServiceStatus(
+        True,
+        True,
+        healthy,
+        port,
+        "healthy" if healthy else "loaded but unreachable",
+    )
+
+
+def dashboard_service_status(
+    *,
+    home: Path,
+    platform: str = sys.platform,
+    uid: int | None = None,
+    runner: Runner = subprocess.run,
+    reachable: Callable[[int], bool] = dashboard_is_reachable,
+) -> DashboardServiceStatus:
+    """Inspect managed plist, launchd state, and localhost reachability."""
+
+    _require_macos(platform)
+    paths = service_paths(home)
+    target_uid = os.getuid() if uid is None else uid
+    loaded = _is_loaded(target_uid, runner)
+    if not paths.plist.exists():
+        detail = "loaded without managed plist" if loaded else "not installed"
+        return DashboardServiceStatus(False, loaded, False, DEFAULT_SERVICE_PORT, detail)
+
+    port, python = _read_installed_config(paths.plist)
+    if not python.is_file():
+        return DashboardServiceStatus(
+            True,
+            loaded,
+            False,
+            port,
+            f"interpreter missing: {python}",
+        )
+    if not loaded:
+        return DashboardServiceStatus(True, False, False, port, "installed but not loaded")
+
+    healthy = reachable(port)
+    return DashboardServiceStatus(
+        True,
+        True,
+        healthy,
+        port,
+        "healthy" if healthy else "loaded but unreachable",
+    )
+
+
+def uninstall_dashboard_service(
+    *,
+    home: Path,
+    platform: str = sys.platform,
+    uid: int | None = None,
+    runner: Runner = subprocess.run,
+) -> DashboardServiceStatus:
+    """Unload the managed agent and remove only its package-owned plist."""
+
+    _require_macos(platform)
+    paths = service_paths(home)
+    target_uid = os.getuid() if uid is None else uid
+    loaded = _is_loaded(target_uid, runner)
+    port = DEFAULT_SERVICE_PORT
+    if paths.plist.exists():
+        port, _ = _read_installed_config(paths.plist)
+    if loaded:
+        result = _run_launchctl(runner, "bootout", _target(target_uid))
+        if result.returncode != 0:
+            raise RuntimeError(_launchctl_error("bootout", result))
+    paths.plist.unlink(missing_ok=True)
+    return DashboardServiceStatus(False, False, False, port, "not installed")
+
+
+def _require_macos(platform: str) -> None:
+    if platform != "darwin":
+        raise RuntimeError("persistent dashboard service management is macOS only")
+
+
+def _domain(uid: int) -> str:
+    return f"gui/{uid}"
+
+
+def _target(uid: int) -> str:
+    return f"{_domain(uid)}/{SERVICE_LABEL}"
+
+
+def _run_launchctl(runner: Runner, *arguments: str) -> subprocess.CompletedProcess[str]:
+    return runner(
+        ["launchctl", *arguments],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+
+
+def _is_loaded(uid: int, runner: Runner) -> bool:
+    return _run_launchctl(runner, "print", _target(uid)).returncode == 0
+
+
+def _launchctl_error(action: str, result: subprocess.CompletedProcess[str]) -> str:
+    detail = result.stderr.strip() or result.stdout.strip() or f"exit {result.returncode}"
+    return f"launchctl {action} failed: {detail}"
+
+
+def _read_installed_config(plist_path: Path) -> tuple[int, Path]:
+    try:
+        payload = plistlib.loads(plist_path.read_bytes())
+        if payload.get("Label") != SERVICE_LABEL:
+            raise ValueError("unexpected service label")
+        arguments = payload["ProgramArguments"]
+        if not isinstance(arguments, list) or not all(isinstance(item, str) for item in arguments):
+            raise ValueError("invalid ProgramArguments")
+        port_index = arguments.index("--port") + 1
+        port = validate_service_port(int(arguments[port_index]))
+        python = Path(arguments[0])
+    except (IndexError, KeyError, TypeError, ValueError, plistlib.InvalidFileException) as exc:
+        raise RuntimeError(f"invalid managed dashboard service plist: {plist_path}") from exc
+    return port, python
+
+
+def _atomic_write(path: Path, content: bytes) -> None:
+    descriptor, temporary_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    temporary_path = Path(temporary_name)
+    try:
+        with os.fdopen(descriptor, "wb") as handle:
+            handle.write(content)
+        temporary_path.chmod(0o600)
+        os.replace(temporary_path, path)
+    finally:
+        temporary_path.unlink(missing_ok=True)
+
+
+def _restore_previous(
+    paths: DashboardServicePaths,
+    previous: bytes,
+    uid: int,
+    runner: Runner,
+) -> None:
+    _atomic_write(paths.plist, previous)
+    _run_launchctl(runner, "bootstrap", _domain(uid), str(paths.plist))
+    _run_launchctl(runner, "kickstart", "-k", _target(uid))
+
+
+def _restore_after_failure(
+    paths: DashboardServicePaths,
+    previous: bytes | None,
+    was_loaded: bool,
+    uid: int,
+    runner: Runner,
+) -> None:
+    _run_launchctl(runner, "bootout", _target(uid))
+    if previous is None:
+        paths.plist.unlink(missing_ok=True)
+        return
+    _atomic_write(paths.plist, previous)
+    if was_loaded:
+        _run_launchctl(runner, "bootstrap", _domain(uid), str(paths.plist))
+        _run_launchctl(runner, "kickstart", "-k", _target(uid))
+
+
+def _wait_until_reachable(
+    port: int,
+    reachable: Callable[[int], bool],
+    *,
+    attempts: int = 20,
+    delay: float = 0.1,
+) -> bool:
+    for attempt in range(attempts):
+        if reachable(port):
+            return True
+        if attempt + 1 < attempts:
+            time.sleep(delay)
+    return False
diff --git a/tests/cli/test_dashboard_service.py b/tests/cli/test_dashboard_service.py
index 12964b8c..f545b043 100644
--- a/tests/cli/test_dashboard_service.py
+++ b/tests/cli/test_dashboard_service.py
@@ -2,6 +2,7 @@
 
 import plistlib
 import socket
+import subprocess
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from pathlib import Path
 from threading import Thread
@@ -11,14 +12,52 @@
 from codex_usage_tracker.dashboard_service import (
     DEFAULT_SERVICE_PORT,
     SERVICE_LABEL,
+    DashboardServiceStatus,
     build_launch_agent,
     dashboard_is_reachable,
+    dashboard_service_status,
+    install_dashboard_service,
     port_is_available,
     service_paths,
+    uninstall_dashboard_service,
     validate_service_port,
 )
 
 
+class FakeRunner:
+    def __init__(
+        self,
+        *,
+        print_returncode: int = 1,
+        bootstrap_returncode: int = 0,
+    ) -> None:
+        self.print_returncode = print_returncode
+        self.bootstrap_returncode = bootstrap_returncode
+        self.commands: list[list[str]] = []
+
+    def __call__(
+        self,
+        command: list[str],
+        **_: object,
+    ) -> subprocess.CompletedProcess[str]:
+        self.commands.append(command)
+        if command[1] == "print":
+            return subprocess.CompletedProcess(
+                command,
+                self.print_returncode,
+                "",
+                "not loaded",
+            )
+        if command[1] == "bootstrap":
+            return subprocess.CompletedProcess(
+                command,
+                self.bootstrap_returncode,
+                "",
+                "bootstrap failed",
+            )
+        return subprocess.CompletedProcess(command, 0, "", "")
+
+
 def test_service_paths_stay_in_user_owned_locations(tmp_path: Path) -> None:
     paths = service_paths(tmp_path)
 
@@ -99,3 +138,204 @@ def log_message(self, *_: object) -> None:
         server.shutdown()
         thread.join()
         server.server_close()
+
+
+def test_install_writes_valid_plist_and_bootstraps_user_domain(tmp_path: Path) -> None:
+    runner = FakeRunner()
+    python = tmp_path / "python"
+    python.touch()
+
+    status = install_dashboard_service(
+        home=tmp_path,
+        python=python,
+        port=DEFAULT_SERVICE_PORT,
+        platform="darwin",
+        uid=501,
+        runner=runner,
+        port_available=lambda _: True,
+        reachable=lambda _: True,
+    )
+
+    paths = service_paths(tmp_path)
+    payload = plistlib.loads(paths.plist.read_bytes())
+    assert payload["Label"] == SERVICE_LABEL
+    assert runner.commands[-2:] == [
+        ["launchctl", "bootstrap", "gui/501", str(paths.plist)],
+        ["launchctl", "kickstart", "-k", f"gui/501/{SERVICE_LABEL}"],
+    ]
+    assert status == DashboardServiceStatus(True, True, True, 47821, "healthy")
+
+
+def test_install_refuses_unknown_port_owner_without_writing(tmp_path: Path) -> None:
+    python = tmp_path / "python"
+    python.touch()
+
+    with pytest.raises(RuntimeError, match="47821 is already in use"):
+        install_dashboard_service(
+            home=tmp_path,
+            python=python,
+            port=DEFAULT_SERVICE_PORT,
+            platform="darwin",
+            uid=501,
+            runner=FakeRunner(),
+            port_available=lambda _: False,
+            reachable=lambda _: False,
+        )
+
+    assert not service_paths(tmp_path).plist.exists()
+
+
+def test_install_reuses_identical_healthy_service_without_restart(tmp_path: Path) -> None:
+    python = tmp_path / "python"
+    python.touch()
+    paths = service_paths(tmp_path)
+    paths.plist.parent.mkdir(parents=True)
+    paths.plist.write_bytes(
+        plistlib.dumps(
+            build_launch_agent(python=python, home=tmp_path, port=DEFAULT_SERVICE_PORT),
+            sort_keys=True,
+        )
+    )
+    runner = FakeRunner(print_returncode=0)
+
+    status = install_dashboard_service(
+        home=tmp_path,
+        python=python,
+        platform="darwin",
+        uid=501,
+        runner=runner,
+        port_available=lambda _: False,
+        reachable=lambda _: True,
+    )
+
+    assert status.detail == "healthy"
+    assert runner.commands == [
+        ["launchctl", "print", f"gui/501/{SERVICE_LABEL}"],
+    ]
+
+
+def test_install_restores_previous_plist_when_bootstrap_fails(tmp_path: Path) -> None:
+    python = tmp_path / "python"
+    python.touch()
+    paths = service_paths(tmp_path)
+    paths.plist.parent.mkdir(parents=True)
+    previous = plistlib.dumps(
+        build_launch_agent(python=python, home=tmp_path, port=48123),
+        sort_keys=True,
+    )
+    paths.plist.write_bytes(previous)
+
+    with pytest.raises(RuntimeError, match="launchctl bootstrap failed"):
+        install_dashboard_service(
+            home=tmp_path,
+            python=python,
+            platform="darwin",
+            uid=501,
+            runner=FakeRunner(bootstrap_returncode=5),
+            port_available=lambda _: True,
+            reachable=lambda _: False,
+        )
+
+    assert paths.plist.read_bytes() == previous
+
+
+def test_status_is_read_only_and_reports_loaded_but_unreachable(tmp_path: Path) -> None:
+    python = tmp_path / "python"
+    python.touch()
+    paths = service_paths(tmp_path)
+    paths.plist.parent.mkdir(parents=True)
+    paths.plist.write_bytes(
+        plistlib.dumps(
+            build_launch_agent(
+                python=python,
+                home=tmp_path,
+                port=DEFAULT_SERVICE_PORT,
+            )
+        )
+    )
+    runner = FakeRunner(print_returncode=0)
+
+    status = dashboard_service_status(
+        home=tmp_path,
+        platform="darwin",
+        uid=501,
+        runner=runner,
+        reachable=lambda _: False,
+    )
+
+    assert status == DashboardServiceStatus(
+        True,
+        True,
+        False,
+        DEFAULT_SERVICE_PORT,
+        "loaded but unreachable",
+    )
+    assert runner.commands == [
+        ["launchctl", "print", f"gui/501/{SERVICE_LABEL}"],
+    ]
+
+
+def test_status_reports_missing_installed_interpreter(tmp_path: Path) -> None:
+    paths = service_paths(tmp_path)
+    paths.plist.parent.mkdir(parents=True)
+    paths.plist.write_bytes(
+        plistlib.dumps(
+            build_launch_agent(
+                python=tmp_path / "missing-python",
+                home=tmp_path,
+                port=DEFAULT_SERVICE_PORT,
+            )
+        )
+    )
+
+    status = dashboard_service_status(
+        home=tmp_path,
+        platform="darwin",
+        uid=501,
+        runner=FakeRunner(print_returncode=0),
+        reachable=lambda _: True,
+    )
+
+    assert status.reachable is False
+    assert status.detail == f"interpreter missing: {tmp_path / 'missing-python'}"
+
+
+def test_uninstall_is_idempotent_and_removes_only_managed_plist(tmp_path: Path) -> None:
+    paths = service_paths(tmp_path)
+    paths.plist.parent.mkdir(parents=True)
+    paths.plist.write_bytes(
+        plistlib.dumps(
+            build_launch_agent(
+                python=Path("/opt/tracker/bin/python"),
+                home=tmp_path,
+                port=DEFAULT_SERVICE_PORT,
+            )
+        )
+    )
+    unrelated = paths.plist.parent / "other.plist"
+    unrelated.write_text("keep")
+    runner = FakeRunner(print_returncode=0)
+
+    status = uninstall_dashboard_service(
+        home=tmp_path,
+        platform="darwin",
+        uid=501,
+        runner=runner,
+    )
+
+    assert not paths.plist.exists()
+    assert unrelated.read_text() == "keep"
+    assert status == DashboardServiceStatus(False, False, False, 47821, "not installed")
+    assert runner.commands[-1] == [
+        "launchctl",
+        "bootout",
+        f"gui/501/{SERVICE_LABEL}",
+    ]
+
+
+def test_lifecycle_refuses_unsupported_platform(tmp_path: Path) -> None:
+    python = tmp_path / "python"
+    python.touch()
+
+    with pytest.raises(RuntimeError, match="macOS only"):
+        install_dashboard_service(home=tmp_path, python=python, platform="linux")

From 954555c12aefbcb2b6992dd970a6ebe71e37af11 Mon Sep 17 00:00:00 2001
From: Monsky <douglas.monsky@gmail.com>
Date: Fri, 17 Jul 2026 12:53:28 -0400
Subject: [PATCH 05/12] feat: expose dashboard service commands

---
 .../cli/dashboard_service.py                  | 39 ++++++++
 src/codex_usage_tracker/cli/help_i18n.py      |  5 +
 src/codex_usage_tracker/cli/main.py           |  2 +
 src/codex_usage_tracker/cli/parser.py         |  2 +
 src/codex_usage_tracker/cli/parser_data.py    | 26 +++++
 tests/cli/test_dashboard_service.py           | 97 +++++++++++++++++++
 6 files changed, 171 insertions(+)
 create mode 100644 src/codex_usage_tracker/cli/dashboard_service.py

diff --git a/src/codex_usage_tracker/cli/dashboard_service.py b/src/codex_usage_tracker/cli/dashboard_service.py
new file mode 100644
index 00000000..1675354f
--- /dev/null
+++ b/src/codex_usage_tracker/cli/dashboard_service.py
@@ -0,0 +1,39 @@
+"""CLI adapter for the persistent dashboard service lifecycle."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from codex_usage_tracker.dashboard_service import (
+    dashboard_service_status,
+    install_dashboard_service,
+    uninstall_dashboard_service,
+)
+
+
+def run_dashboard_service(args: argparse.Namespace) -> int:
+    """Run one persistent dashboard service action."""
+
+    home = Path.home()
+    if args.service_action == "install":
+        status = install_dashboard_service(
+            home=home,
+            python=Path(sys.executable),
+            port=args.port,
+        )
+        print(f"Dashboard service installed at {status.url}")
+        return 0 if status.reachable else 1
+    if args.service_action == "status":
+        status = dashboard_service_status(home=home)
+        if status.reachable:
+            print(f"Dashboard service is healthy at {status.url}")
+            return 0
+        print(f"Dashboard service is {status.detail}; expected {status.url}")
+        return 1
+    if args.service_action == "uninstall":
+        uninstall_dashboard_service(home=home)
+        print("Dashboard service uninstalled")
+        return 0
+    raise ValueError(f"unknown dashboard service action: {args.service_action}")
diff --git a/src/codex_usage_tracker/cli/help_i18n.py b/src/codex_usage_tracker/cli/help_i18n.py
index 06ed852c..5d7fec6e 100644
--- a/src/codex_usage_tracker/cli/help_i18n.py
+++ b/src/codex_usage_tracker/cli/help_i18n.py
@@ -88,6 +88,11 @@
     "Generate static dashboard": "生成静态仪表盘",
     "Generate the default dashboard and open it": "生成并打开默认仪表盘",
     "Serve dashboard with lazy localhost context loading": "启动仪表盘服务，并按需从本机加载上下文",
+    "Manage the persistent dashboard service": "管理常驻仪表盘服务",
+    "Install and start the dashboard service": "安装并启动常驻仪表盘服务",
+    "Show dashboard service health": "显示常驻仪表盘服务状态",
+    "Stop and remove the dashboard service": "停止并移除常驻仪表盘服务",
+    "Persistent dashboard port": "常驻仪表盘端口",
     "Show copied clone usage rows excluded from billable totals": "显示已从计费汇总中排除的克隆复制记录",
     "Show largest last-call usage rows": "显示末次调用用量最大的记录",
     "Show priced, estimated, and unpriced token coverage": "显示已定价、估算和未定价token的覆盖情况",
diff --git a/src/codex_usage_tracker/cli/main.py b/src/codex_usage_tracker/cli/main.py
index 934a6997..1596ca55 100644
--- a/src/codex_usage_tracker/cli/main.py
+++ b/src/codex_usage_tracker/cli/main.py
@@ -51,6 +51,7 @@
     run_open_dashboard,
     run_serve_dashboard,
 )
+from codex_usage_tracker.cli.dashboard_service import run_dashboard_service
 from codex_usage_tracker.cli.diagnostics import run_diagnostics
 from codex_usage_tracker.cli.help_i18n import localized_cli_error_prefix, requested_cli_language
 from codex_usage_tracker.cli.inspect_log_output import print_inspect_log_summary
@@ -120,6 +121,7 @@ def _run_inspect_log(args: argparse.Namespace) -> int:
     "dashboard": run_dashboard,
     "open-dashboard": run_open_dashboard,
     "serve-dashboard": run_serve_dashboard,
+    "dashboard-service": run_dashboard_service,
     "expensive": _run_expensive,
     "pricing-coverage": _run_pricing_coverage,
     "source-coverage": _run_source_coverage,
diff --git a/src/codex_usage_tracker/cli/parser.py b/src/codex_usage_tracker/cli/parser.py
index 3ea78056..185b4d4d 100644
--- a/src/codex_usage_tracker/cli/parser.py
+++ b/src/codex_usage_tracker/cli/parser.py
@@ -11,6 +11,7 @@
     _add_allowance_intelligence_parsers,
     _add_allowance_parser,
     _add_dashboard_parsers,
+    _add_dashboard_service_parser,
     _add_dedupe_diagnostics_parser,
     _add_expensive_parser,
     _add_export_parser,
@@ -100,6 +101,7 @@ def build_parser(language: str | None = None) -> argparse.ArgumentParser:
     _add_session_parser(subparsers)
     _add_context_parser(subparsers)
     _add_dashboard_parsers(subparsers)
+    _add_dashboard_service_parser(subparsers)
     _add_dedupe_diagnostics_parser(subparsers)
     _add_expensive_parser(subparsers)
     _add_pricing_coverage_parser(subparsers)
diff --git a/src/codex_usage_tracker/cli/parser_data.py b/src/codex_usage_tracker/cli/parser_data.py
index 765a66df..5036e41b 100644
--- a/src/codex_usage_tracker/cli/parser_data.py
+++ b/src/codex_usage_tracker/cli/parser_data.py
@@ -12,6 +12,7 @@
     DEFAULT_PRICING_PATH,
     DEFAULT_SUPPORT_BUNDLE_PATH,
 )
+from codex_usage_tracker.dashboard_service import DEFAULT_SERVICE_PORT
 from codex_usage_tracker.pricing.api import OPENAI_PRICING_MD_URL, VALID_PRICING_TIERS
 from codex_usage_tracker.reports.api import (
     EXPENSIVE_PRESET_CHOICES,
@@ -103,6 +104,31 @@ def _add_dashboard_parsers(
     )
 
 
+def _add_dashboard_service_parser(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    service = subparsers.add_parser(
+        "dashboard-service",
+        help="Manage the persistent dashboard service",
+    )
+    actions = service.add_subparsers(dest="service_action", required=True)
+    install = actions.add_parser(
+        "install",
+        help="Install and start the dashboard service",
+    )
+    install.add_argument(
+        "--port",
+        type=int,
+        default=DEFAULT_SERVICE_PORT,
+        help="Persistent dashboard port",
+    )
+    actions.add_parser("status", help="Show dashboard service health")
+    actions.add_parser(
+        "uninstall",
+        help="Stop and remove the dashboard service",
+    )
+
+
 def _add_expensive_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
     expensive = subparsers.add_parser("expensive", help="Show largest last-call usage rows")
     expensive.add_argument("--limit", type=int, default=20)
diff --git a/tests/cli/test_dashboard_service.py b/tests/cli/test_dashboard_service.py
index f545b043..df30cd60 100644
--- a/tests/cli/test_dashboard_service.py
+++ b/tests/cli/test_dashboard_service.py
@@ -4,11 +4,14 @@
 import socket
 import subprocess
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from importlib import import_module
 from pathlib import Path
 from threading import Thread
 
 import pytest
 
+from codex_usage_tracker.cli import dashboard_service as cli_dashboard_service
+from codex_usage_tracker.cli.parser import build_parser
 from codex_usage_tracker.dashboard_service import (
     DEFAULT_SERVICE_PORT,
     SERVICE_LABEL,
@@ -23,6 +26,8 @@
     validate_service_port,
 )
 
+cli_main = import_module("codex_usage_tracker.cli.main")
+
 
 class FakeRunner:
     def __init__(
@@ -339,3 +344,95 @@ def test_lifecycle_refuses_unsupported_platform(tmp_path: Path) -> None:
 
     with pytest.raises(RuntimeError, match="macOS only"):
         install_dashboard_service(home=tmp_path, python=python, platform="linux")
+
+
+def test_dashboard_service_parser_defaults_install_port() -> None:
+    args = build_parser("en").parse_args(["dashboard-service", "install"])
+
+    assert args.command == "dashboard-service"
+    assert args.service_action == "install"
+    assert args.port == DEFAULT_SERVICE_PORT
+
+
+def test_dashboard_service_parser_accepts_install_port_override() -> None:
+    args = build_parser("en").parse_args(
+        ["dashboard-service", "install", "--port", "48123"]
+    )
+
+    assert args.port == 48123
+
+
+def test_dashboard_service_uninstall_rejects_port_override() -> None:
+    with pytest.raises(SystemExit):
+        build_parser("en").parse_args(
+            ["dashboard-service", "uninstall", "--port", "48123"]
+        )
+
+
+def test_dashboard_service_status_prints_stable_url(monkeypatch, capsys) -> None:
+    monkeypatch.setattr(
+        cli_dashboard_service,
+        "dashboard_service_status",
+        lambda **_: DashboardServiceStatus(True, True, True, 47821, "healthy"),
+    )
+
+    args = build_parser("en").parse_args(["dashboard-service", "status"])
+
+    assert cli_dashboard_service.run_dashboard_service(args) == 0
+    assert capsys.readouterr().out == (
+        "Dashboard service is healthy at http://127.0.0.1:47821\n"
+    )
+
+
+def test_dashboard_service_unhealthy_status_returns_one(monkeypatch, capsys) -> None:
+    monkeypatch.setattr(
+        cli_dashboard_service,
+        "dashboard_service_status",
+        lambda **_: DashboardServiceStatus(
+            True,
+            True,
+            False,
+            47821,
+            "loaded but unreachable",
+        ),
+    )
+
+    args = build_parser("en").parse_args(["dashboard-service", "status"])
+
+    assert cli_dashboard_service.run_dashboard_service(args) == 1
+    assert capsys.readouterr().out == (
+        "Dashboard service is loaded but unreachable; "
+        "expected http://127.0.0.1:47821\n"
+    )
+
+
+def test_dashboard_service_install_forwards_port(monkeypatch, capsys) -> None:
+    captured: dict[str, object] = {}
+
+    def install(**kwargs: object) -> DashboardServiceStatus:
+        captured.update(kwargs)
+        return DashboardServiceStatus(True, True, True, 48123, "healthy")
+
+    monkeypatch.setattr(cli_dashboard_service, "install_dashboard_service", install)
+    args = build_parser("en").parse_args(
+        ["dashboard-service", "install", "--port", "48123"]
+    )
+
+    assert cli_dashboard_service.run_dashboard_service(args) == 0
+    assert captured["port"] == 48123
+    assert capsys.readouterr().out == (
+        "Dashboard service installed at http://127.0.0.1:48123\n"
+    )
+
+
+def test_dashboard_service_command_is_registered() -> None:
+    assert (
+        cli_main._COMMAND_HANDLERS["dashboard-service"]
+        is cli_dashboard_service.run_dashboard_service
+    )
+
+
+def test_dashboard_service_help_is_localized() -> None:
+    help_text = build_parser("zh-Hans").format_help()
+
+    assert "管理常驻仪表盘服务" in help_text

From 940129cdb5e5e0f710a6ebdcac4aead21912551f Mon Sep 17 00:00:00 2001
From: Monsky <douglas.monsky@gmail.com>
Date: Fri, 17 Jul 2026 12:54:54 -0400
Subject: [PATCH 06/12] docs: explain persistent dashboard service

---
 docs/cli-reference.md                         | 16 ++++++++++++
 docs/dashboard-guide.md                       | 21 ++++++++++++++-
 docs/install.md                               | 26 ++++++++++++++++++-
 skills/codex-usage-tracker/SKILL.md           |  2 +-
 .../skills/codex-usage-tracker/SKILL.md       |  2 +-
 5 files changed, 63 insertions(+), 4 deletions(-)

diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 261105b4..6771b5bb 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -81,6 +81,22 @@ 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`.
+
 `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.
diff --git a/docs/dashboard-guide.md b/docs/dashboard-guide.md
index 3418353b..2ffb74f8 100644
--- a/docs/dashboard-guide.md
+++ b/docs/dashboard-guide.md
@@ -6,15 +6,34 @@ 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`.
+
+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
diff --git a/docs/install.md b/docs/install.md
index 52ba0413..a5d404bf 100644
--- a/docs/install.md
+++ b/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,21 @@ 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`.
+
 Generate a static dashboard:
 
 ```bash
@@ -126,6 +147,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.
 
diff --git a/skills/codex-usage-tracker/SKILL.md b/skills/codex-usage-tracker/SKILL.md
index 2a8cba08..fa51cea7 100644
--- a/skills/codex-usage-tracker/SKILL.md
+++ b/skills/codex-usage-tracker/SKILL.md
@@ -17,7 +17,7 @@ The only exception is `usage_call_context`, which intentionally reads one select
 
 ## Fast Paths
 
-- For "Open dashboard" or similar dashboard-open requests, do not inspect repository files, plugin manifests, tool registries, git status, or local logs first. Start the live localhost dashboard with `codex-usage-tracker serve-dashboard --context-api explicit --open` so Refresh, Live, load-limit, and history-scope controls can call the local API. Refresh is the default for dashboard launch commands; use `--no-refresh` only when the user explicitly asks for a cached snapshot. Keep the server running while the user is using the dashboard. Use `codex-usage-tracker open-dashboard` only when the user explicitly asks for a static/offline snapshot or when the current environment cannot keep a server process running, and say that the result is static and Live requires `serve-dashboard`.
+- For "Open dashboard" or similar dashboard-open requests, do not inspect repository files, plugin manifests, tool registries, git status, or local logs first. On macOS, first run `codex-usage-tracker dashboard-service status`. If it is healthy, open or report its persisted localhost URL (default `http://127.0.0.1:47821`) without starting another server. If it is absent or unhealthy, start the live localhost dashboard with `codex-usage-tracker serve-dashboard --context-api explicit --open` so Refresh, Live, load-limit, and history-scope controls can call the local API. Refresh is the default for dashboard launch commands; use `--no-refresh` only when the user explicitly asks for a cached snapshot. Keep a foreground server running while the user is using it. Use `codex-usage-tracker open-dashboard` only when the user explicitly asks for a static/offline snapshot or when the current environment cannot keep a server process running, and say that the result is static and Live requires `serve-dashboard`.
 - For "Heaviest thread?", "Thread leaderboard", or similar thread-ranking requests, do not inspect repository files, SQLite schemas, plugin manifests, process lists, dashboard servers, or local logs manually. Use the tracker API: refresh the aggregate index, then rank threads with `usage_summary(group_by="thread", limit=10, response_format="json")`.
 - If MCP tools are unavailable for thread-ranking requests, run `codex-usage-tracker refresh --json` and `codex-usage-tracker summary --group-by thread --limit 10 --json`. The summary is already ordered by `total_tokens` descending.
 - Answer thread-ranking requests directly from the summary rows. For the heaviest-thread question, lead with the first row's thread and total tokens; for leaderboard requests, show a compact ranked list.
diff --git a/src/codex_usage_tracker/plugin_data/skills/codex-usage-tracker/SKILL.md b/src/codex_usage_tracker/plugin_data/skills/codex-usage-tracker/SKILL.md
index 2a8cba08..fa51cea7 100644
--- a/src/codex_usage_tracker/plugin_data/skills/codex-usage-tracker/SKILL.md
+++ b/src/codex_usage_tracker/plugin_data/skills/codex-usage-tracker/SKILL.md
@@ -17,7 +17,7 @@ The only exception is `usage_call_context`, which intentionally reads one select
 
 ## Fast Paths
 
-- For "Open dashboard" or similar dashboard-open requests, do not inspect repository files, plugin manifests, tool registries, git status, or local logs first. Start the live localhost dashboard with `codex-usage-tracker serve-dashboard --context-api explicit --open` so Refresh, Live, load-limit, and history-scope controls can call the local API. Refresh is the default for dashboard launch commands; use `--no-refresh` only when the user explicitly asks for a cached snapshot. Keep the server running while the user is using the dashboard. Use `codex-usage-tracker open-dashboard` only when the user explicitly asks for a static/offline snapshot or when the current environment cannot keep a server process running, and say that the result is static and Live requires `serve-dashboard`.
+- For "Open dashboard" or similar dashboard-open requests, do not inspect repository files, plugin manifests, tool registries, git status, or local logs first. On macOS, first run `codex-usage-tracker dashboard-service status`. If it is healthy, open or report its persisted localhost URL (default `http://127.0.0.1:47821`) without starting another server. If it is absent or unhealthy, start the live localhost dashboard with `codex-usage-tracker serve-dashboard --context-api explicit --open` so Refresh, Live, load-limit, and history-scope controls can call the local API. Refresh is the default for dashboard launch commands; use `--no-refresh` only when the user explicitly asks for a cached snapshot. Keep a foreground server running while the user is using it. Use `codex-usage-tracker open-dashboard` only when the user explicitly asks for a static/offline snapshot or when the current environment cannot keep a server process running, and say that the result is static and Live requires `serve-dashboard`.
 - For "Heaviest thread?", "Thread leaderboard", or similar thread-ranking requests, do not inspect repository files, SQLite schemas, plugin manifests, process lists, dashboard servers, or local logs manually. Use the tracker API: refresh the aggregate index, then rank threads with `usage_summary(group_by="thread", limit=10, response_format="json")`.
 - If MCP tools are unavailable for thread-ranking requests, run `codex-usage-tracker refresh --json` and `codex-usage-tracker summary --group-by thread --limit 10 --json`. The summary is already ordered by `total_tokens` descending.
 - Answer thread-ranking requests directly from the summary rows. For the heaviest-thread question, lead with the first row's thread and total tokens; for leaderboard requests, show a compact ranked list.

From c9a2af004b5cde23fd537abfe86bd36aff81687b Mon Sep 17 00:00:00 2001
From: Monsky <douglas.monsky@gmail.com>
Date: Fri, 17 Jul 2026 12:57:44 -0400
Subject: [PATCH 07/12] test: register dashboard service CLI contract

---
 scripts/smoke_installed_package.py | 1 +
 tests/cli/test_cli_release.py      | 1 +
 2 files changed, 2 insertions(+)

diff --git a/scripts/smoke_installed_package.py b/scripts/smoke_installed_package.py
index ed898988..72e5601e 100644
--- a/scripts/smoke_installed_package.py
+++ b/scripts/smoke_installed_package.py
@@ -58,6 +58,7 @@
     "dashboard",
     "open-dashboard",
     "serve-dashboard",
+    "dashboard-service",
     "expensive",
     "pricing-coverage",
     "source-coverage",
diff --git a/tests/cli/test_cli_release.py b/tests/cli/test_cli_release.py
index 7ac378ac..7a50b34f 100644
--- a/tests/cli/test_cli_release.py
+++ b/tests/cli/test_cli_release.py
@@ -34,6 +34,7 @@
     "dashboard",
     "open-dashboard",
     "serve-dashboard",
+    "dashboard-service",
     "expensive",
     "pricing-coverage",
     "source-coverage",

From a40e86d52bb932a1596faa2780f61ee9540fc70f Mon Sep 17 00:00:00 2001
From: Monsky <douglas.monsky@gmail.com>
Date: Fri, 17 Jul 2026 13:06:35 -0400
Subject: [PATCH 08/12] fix: avoid blocking dashboard service startup

---
 docs/cli-reference.md                                     | 4 ++++
 docs/dashboard-guide.md                                   | 3 +++
 docs/install.md                                           | 4 ++++
 .../plans/2026-07-17-persistent-dashboard-service.md      | 6 +++---
 .../2026-07-17-persistent-dashboard-service-design.md     | 8 +++++---
 src/codex_usage_tracker/dashboard_service.py              | 1 +
 tests/cli/test_dashboard_service.py                       | 1 +
 7 files changed, 21 insertions(+), 6 deletions(-)

diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 6771b5bb..a5b3916d 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -97,6 +97,10 @@ refuses an occupied port rather than silently changing the URL; use
 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.
diff --git a/docs/dashboard-guide.md b/docs/dashboard-guide.md
index 2ffb74f8..2076d761 100644
--- a/docs/dashboard-guide.md
+++ b/docs/dashboard-guide.md
@@ -24,6 +24,9 @@ already owned by another process, installation refuses the collision; use
 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
diff --git a/docs/install.md b/docs/install.md
index a5d404bf..b74bbe41 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -133,6 +133,10 @@ error instead of changing the URL; choose an explicit alternative with
 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
diff --git a/docs/superpowers/plans/2026-07-17-persistent-dashboard-service.md b/docs/superpowers/plans/2026-07-17-persistent-dashboard-service.md
index ea5dcd41..1ded0398 100644
--- a/docs/superpowers/plans/2026-07-17-persistent-dashboard-service.md
+++ b/docs/superpowers/plans/2026-07-17-persistent-dashboard-service.md
@@ -13,7 +13,7 @@
 - Keep `serve-dashboard` backward-compatible, including its existing default port `8765`.
 - The persistent service defaults to `127.0.0.1:47821` and offers no non-loopback host option.
 - Use LaunchAgent label `com.codex-usage-tracker.dashboard` and plist path `~/Library/LaunchAgents/com.codex-usage-tracker.dashboard.plist`.
-- Start with `--context-api explicit`, never `--open`, and never put credentials or raw usage content in the plist or service logs.
+- Start with `--context-api explicit --no-refresh`, never `--open`, and never put credentials or raw usage content in the plist or service logs.
 - Use the absolute install-time Python interpreter and separate `ProgramArguments`; never invoke launchctl through a shell string.
 - Refuse unknown port owners and never silently select another port or kill an unknown process.
 - Automated tests use temporary homes and fakes/disposable sockets; they never load the developer's real LaunchAgent.
@@ -88,7 +88,7 @@ def test_launch_agent_is_loopback_only_and_contains_no_content(tmp_path: Path) -
     assert payload["ProgramArguments"] == [
         "/opt/tracker/bin/python", "-m", "codex_usage_tracker",
         "serve-dashboard", "--host", "127.0.0.1", "--port", "47821",
-        "--context-api", "explicit",
+        "--context-api", "explicit", "--no-refresh",
     ]
     assert payload["RunAtLoad"] is True
     assert payload["KeepAlive"] is True
@@ -201,7 +201,7 @@ def build_launch_agent(*, python: Path, home: Path, port: int) -> dict[str, Any]
         "ProgramArguments": [
             str(python), "-m", "codex_usage_tracker", "serve-dashboard",
             "--host", SERVICE_HOST, "--port", str(validate_service_port(port)),
-            "--context-api", "explicit",
+            "--context-api", "explicit", "--no-refresh",
         ],
         "EnvironmentVariables": {"HOME": str(home)},
         "RunAtLoad": True,
diff --git a/docs/superpowers/specs/2026-07-17-persistent-dashboard-service-design.md b/docs/superpowers/specs/2026-07-17-persistent-dashboard-service-design.md
index 42a95062..a5972a73 100644
--- a/docs/superpowers/specs/2026-07-17-persistent-dashboard-service-design.md
+++ b/docs/superpowers/specs/2026-07-17-persistent-dashboard-service-design.md
@@ -89,6 +89,7 @@ python -m codex_usage_tracker serve-dashboard
   --host 127.0.0.1
   --port 47821
   --context-api explicit
+  --no-refresh
 ```
 
 The actual plist stores these as separate `ProgramArguments`. It uses
@@ -111,9 +112,10 @@ be reinstalled from the current package environment.
    LaunchAgent in the current user's `gui/<uid>` domain.
 4. launchd starts the existing localhost dashboard server and restarts it when
    needed.
-5. The dashboard continues using its existing explicit refresh and lazy
-   context-loading behavior. Persistence does not introduce background log
-   polling beyond behavior already performed by `serve-dashboard`.
+5. The service binds promptly from the cached aggregate index instead of
+   blocking its port on a startup rescan. The dashboard's existing explicit
+   Refresh and Live controls update the index after it is reachable, and lazy
+   context-loading behavior remains unchanged.
 6. `status` combines launchd state with a bounded HTTP probe so a loaded but
    unreachable process is distinguishable from a healthy service.
 
diff --git a/src/codex_usage_tracker/dashboard_service.py b/src/codex_usage_tracker/dashboard_service.py
index 5086c92f..4aa59edb 100644
--- a/src/codex_usage_tracker/dashboard_service.py
+++ b/src/codex_usage_tracker/dashboard_service.py
@@ -83,6 +83,7 @@ def build_launch_agent(*, python: Path, home: Path, port: int) -> dict[str, Any]
             str(validate_service_port(port)),
             "--context-api",
             "explicit",
+            "--no-refresh",
         ],
         "EnvironmentVariables": {"HOME": str(home)},
         "RunAtLoad": True,
diff --git a/tests/cli/test_dashboard_service.py b/tests/cli/test_dashboard_service.py
index df30cd60..252243e3 100644
--- a/tests/cli/test_dashboard_service.py
+++ b/tests/cli/test_dashboard_service.py
@@ -97,6 +97,7 @@ def test_launch_agent_is_loopback_only_and_contains_no_content(tmp_path: Path) -
         "47821",
         "--context-api",
         "explicit",
+        "--no-refresh",
     ]
     assert payload["RunAtLoad"] is True
     assert payload["KeepAlive"] is True

From ee0047dbce6b5195cc2ad4c2abde66589ae19534 Mon Sep 17 00:00:00 2001
From: Monsky <douglas.monsky@gmail.com>
Date: Fri, 17 Jul 2026 13:07:45 -0400
Subject: [PATCH 09/12] fix: wait for dashboard service readiness

---
 src/codex_usage_tracker/dashboard_service.py |  4 +--
 tests/cli/test_dashboard_service.py          | 26 ++++++++++++++++++++
 2 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/src/codex_usage_tracker/dashboard_service.py b/src/codex_usage_tracker/dashboard_service.py
index 4aa59edb..1d044b73 100644
--- a/src/codex_usage_tracker/dashboard_service.py
+++ b/src/codex_usage_tracker/dashboard_service.py
@@ -349,8 +349,8 @@ def _wait_until_reachable(
     port: int,
     reachable: Callable[[int], bool],
     *,
-    attempts: int = 20,
-    delay: float = 0.1,
+    attempts: int = 60,
+    delay: float = 0.25,
 ) -> bool:
     for attempt in range(attempts):
         if reachable(port):
diff --git a/tests/cli/test_dashboard_service.py b/tests/cli/test_dashboard_service.py
index 252243e3..c2387cc3 100644
--- a/tests/cli/test_dashboard_service.py
+++ b/tests/cli/test_dashboard_service.py
@@ -220,6 +220,32 @@ def test_install_reuses_identical_healthy_service_without_restart(tmp_path: Path
     ]
 
 
+def test_install_waits_for_cached_dashboard_to_bind(tmp_path: Path, monkeypatch) -> None:
+    python = tmp_path / "python"
+    python.touch()
+    attempts = 0
+
+    def reachable(_: int) -> bool:
+        nonlocal attempts
+        attempts += 1
+        return attempts == 25
+
+    monkeypatch.setattr("codex_usage_tracker.dashboard_service.time.sleep", lambda _: None)
+
+    status = install_dashboard_service(
+        home=tmp_path,
+        python=python,
+        platform="darwin",
+        uid=501,
+        runner=FakeRunner(),
+        port_available=lambda _: True,
+        reachable=reachable,
+    )
+
+    assert status.reachable is True
+    assert attempts == 25
+
+
 def test_install_restores_previous_plist_when_bootstrap_fails(tmp_path: Path) -> None:
     python = tmp_path / "python"
     python.touch()

From 4fbc84b529e86a355eeb33dccb35dcb03d0df125 Mon Sep 17 00:00:00 2001
From: Monsky <douglas.monsky@gmail.com>
Date: Fri, 17 Jul 2026 13:13:02 -0400
Subject: [PATCH 10/12] fix: use lightweight dashboard health check

---
 src/codex_usage_tracker/dashboard_service.py         |  4 ++--
 src/codex_usage_tracker/server/handler.py            |  7 +++++++
 src/codex_usage_tracker/server/route_inventory.py    | 10 ++++++++++
 src/codex_usage_tracker/server/routes.py             |  1 +
 tests/cli/test_dashboard_service.py                  |  1 +
 tests/dashboard/test_dashboard_server_live_slices.py |  6 ++++++
 6 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/src/codex_usage_tracker/dashboard_service.py b/src/codex_usage_tracker/dashboard_service.py
index 1d044b73..9f85f1e3 100644
--- a/src/codex_usage_tracker/dashboard_service.py
+++ b/src/codex_usage_tracker/dashboard_service.py
@@ -107,12 +107,12 @@ def port_is_available(port: int) -> bool:
 
 
 def dashboard_is_reachable(port: int, *, timeout: float = 1.0) -> bool:
-    """Return whether an HTTP server responds at the dashboard root."""
+    """Return whether the dashboard's lightweight health endpoint responds."""
 
     validate_service_port(port)
     try:
         with urlopen(  # noqa: S310 - fixed loopback URL only
-            f"http://{SERVICE_HOST}:{port}/",
+            f"http://{SERVICE_HOST}:{port}/api/health",
             timeout=timeout,
         ) as response:
             return response.status == 200
diff --git a/src/codex_usage_tracker/server/handler.py b/src/codex_usage_tracker/server/handler.py
index 3413acb5..98af41f7 100644
--- a/src/codex_usage_tracker/server/handler.py
+++ b/src/codex_usage_tracker/server/handler.py
@@ -227,6 +227,13 @@ def _handle_status(self, query: str) -> None:
             send_json=self._send_json,
         )
 
+    def _handle_health(self, query: str) -> None:
+        del query
+        self._send_json(
+            HTTPStatus.OK,
+            {"schema": "codex-usage-tracker-health-v1", "status": "ok"},
+        )
+
     def _handle_calls(self, query: str) -> None:
         handle_calls_request(
             query,
diff --git a/src/codex_usage_tracker/server/route_inventory.py b/src/codex_usage_tracker/server/route_inventory.py
index ef7ab10b..568d9f09 100644
--- a/src/codex_usage_tracker/server/route_inventory.py
+++ b/src/codex_usage_tracker/server/route_inventory.py
@@ -79,6 +79,16 @@
         "One action payload.",
         "No persisted result.",
     ),
+    _profile(
+        "GET",
+        "/api/health",
+        "_handle_health",
+        "server.health",
+        "interactive",
+        "Reads in-memory process health.",
+        "One constant-size health payload.",
+        "No persisted state.",
+    ),
     _profile(
         "GET",
         "/api/status",
diff --git a/src/codex_usage_tracker/server/routes.py b/src/codex_usage_tracker/server/routes.py
index eea0ac4c..7ae62493 100644
--- a/src/codex_usage_tracker/server/routes.py
+++ b/src/codex_usage_tracker/server/routes.py
@@ -10,6 +10,7 @@
         "/api/context": "_handle_context",
         "/api/context-settings": "_handle_context_settings",
         "/api/open-investigator": "_handle_open_investigator",
+        "/api/health": "_handle_health",
         "/api/status": "_handle_status",
         "/api/calls": "_handle_calls",
         "/api/call": "_handle_call",
diff --git a/tests/cli/test_dashboard_service.py b/tests/cli/test_dashboard_service.py
index c2387cc3..838c28aa 100644
--- a/tests/cli/test_dashboard_service.py
+++ b/tests/cli/test_dashboard_service.py
@@ -128,6 +128,7 @@ def test_port_check_detects_an_existing_listener() -> None:
 def test_dashboard_probe_distinguishes_reachable_http_server() -> None:
     class Handler(BaseHTTPRequestHandler):
         def do_GET(self) -> None:  # noqa: N802
+            assert self.path == "/api/health"
             self.send_response(200)
             self.end_headers()
             self.wfile.write(b"Codex Usage Tracker")
diff --git a/tests/dashboard/test_dashboard_server_live_slices.py b/tests/dashboard/test_dashboard_server_live_slices.py
index 59d4cd88..cb37786a 100644
--- a/tests/dashboard/test_dashboard_server_live_slices.py
+++ b/tests/dashboard/test_dashboard_server_live_slices.py
@@ -60,6 +60,12 @@ def test_dashboard_server_live_sql_api_slices_are_aggregate_only(tmp_path: Path)
     try:
         base_url = f"http://127.0.0.1:{server.server_port}"
 
+        health_payload = _as_json_object(_read_json(f"{base_url}/api/health"))
+        assert health_payload == {
+            "schema": "codex-usage-tracker-health-v1",
+            "status": "ok",
+        }
+
         status_payload = _as_json_object(_read_json(f"{base_url}/api/status"))
         calls_payload = _as_json_object(
             _read_json(f"{base_url}/api/calls?limit=2&sort=tokens&direction=desc&q=Codex")

From 48596ca842cdcfce5b26ad8d90956d510040850a Mon Sep 17 00:00:00 2001
From: Monsky <douglas.monsky@gmail.com>
Date: Fri, 17 Jul 2026 13:27:13 -0400
Subject: [PATCH 11/12] chore: whitelist dynamic dashboard service symbols

---
 config/vulture-whitelist.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/config/vulture-whitelist.py b/config/vulture-whitelist.py
index 820dd1eb..e49da481 100644
--- a/config/vulture-whitelist.py
+++ b/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

From 3e49f5679b146a6acfa3eb2d0a62ca1d3be342d9 Mon Sep 17 00:00:00 2001
From: Monsky <douglas.monsky@gmail.com>
Date: Fri, 17 Jul 2026 13:30:06 -0400
Subject: [PATCH 12/12] chore: document dashboard service security boundaries

---
 src/codex_usage_tracker/dashboard_service.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/codex_usage_tracker/dashboard_service.py b/src/codex_usage_tracker/dashboard_service.py
index 9f85f1e3..2709dd52 100644
--- a/src/codex_usage_tracker/dashboard_service.py
+++ b/src/codex_usage_tracker/dashboard_service.py
@@ -5,7 +5,7 @@
 import os
 import plistlib
 import socket
-import subprocess
+import subprocess  # nosec B404 - launchctl receives fixed argv without a shell.
 import sys
 import tempfile
 import time
@@ -111,7 +111,7 @@ def dashboard_is_reachable(port: int, *, timeout: float = 1.0) -> bool:
 
     validate_service_port(port)
     try:
-        with urlopen(  # noqa: S310 - fixed loopback URL only
+        with urlopen(  # nosec B310  # noqa: S310 - fixed loopback URL only
             f"http://{SERVICE_HOST}:{port}/api/health",
             timeout=timeout,
         ) as response: