From 66a46d0f910b5d4991bf4f2b0110612819a45644 Mon Sep 17 00:00:00 2001
From: placey <theaiguy@cisco.com>
Date: Sun, 2 Aug 2026 16:42:10 -0700
Subject: [PATCH 1/5] Add Windows ARM installation support

---
 CONTRIBUTING.md                 |  27 ++-
 README.md                       |  51 +++--
 meter.py                        | 101 +++++++---
 page.html                       |   8 +-
 scripts/install-windows.ps1     | 341 ++++++++++++++++++++++++++++++++
 scripts/run-token-meter-mcp.cmd |   9 +
 scripts/start-token-meter.ps1   | 125 ++++++++++++
 scripts/uninstall-windows.ps1   |  54 +++++
 scripts/update-windows.ps1      | 123 ++++++++++++
 tests/test_meter.py             | 113 ++++++++---
 10 files changed, 886 insertions(+), 66 deletions(-)
 create mode 100644 scripts/install-windows.ps1
 create mode 100644 scripts/run-token-meter-mcp.cmd
 create mode 100644 scripts/start-token-meter.ps1
 create mode 100644 scripts/uninstall-windows.ps1
 create mode 100644 scripts/update-windows.ps1

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index db913a1..cc887b5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -46,7 +46,17 @@ For the full macOS experience, run the installer from your checkout:
 ./scripts/install
 ```
 
-This starts the local server and menu bar companion. Open
+On Windows, install with the per-user PowerShell workflow:
+
+```powershell
+pwsh -NoProfile -File .\scripts\install-windows.ps1
+```
+
+This stages the browser dashboard under `%LOCALAPPDATA%\Token Meter\runtime`
+and registers automatic startup for the current user. The AppKit menu-bar
+companion is macOS-only.
+
+The macOS installer starts the local server and menu bar companion. Open
 [http://localhost:8722](http://localhost:8722) and check its health with:
 
 ```bash
@@ -54,7 +64,8 @@ curl http://127.0.0.1:8722/health
 ```
 
 Rerun `./scripts/install` after source changes when you want to test the staged
-runtime. For dashboard-only development, when port 8722 is free, run:
+runtime; on Windows, rerun `install-windows.ps1`. For dashboard-only
+development, when port 8722 is free, run:
 
 ```bash
 python3 meter.py
@@ -104,6 +115,18 @@ node -e "const fs=require('fs'); const html=fs.readFileSync('page.html','utf8');
 git diff --check
 ```
 
+On Windows, run the Python commands with the installed Python executable, parse
+the PowerShell scripts, and exercise the Windows installer:
+
+```powershell
+python -m py_compile meter.py token_meter_mcp.py
+python -m unittest discover -s tests -v
+node -e "const fs=require('fs'); const html=fs.readFileSync('page.html','utf8'); const m=html.match(/<script>([\s\S]*)<\/script>/); new Function(m[1]); console.log('js ok')"
+$files = 'scripts/install-windows.ps1','scripts/start-token-meter.ps1','scripts/uninstall-windows.ps1','scripts/update-windows.ps1'
+$files | ForEach-Object { $tokens=$null; $errors=$null; [System.Management.Automation.Language.Parser]::ParseFile((Resolve-Path $_),[ref]$tokens,[ref]$errors) | Out-Null; if ($errors) { throw $errors } }
+pwsh -NoProfile -File .\scripts\install-windows.ps1
+```
+
 For menu bar changes, also run:
 
 ```bash
diff --git a/README.md b/README.md
index d7bd6df..1f5ef6a 100644
--- a/README.md
+++ b/README.md
@@ -49,8 +49,24 @@ without requiring a retry.
 It copies the runtime into `~/Library/Application Support/Token Meter/runtime`,
 so the cloned folder is not used for automatic startup.
 
-Token Meter starts its local server and menu bar widget automatically after
-installation and after future logins. Open the dashboard at:
+On Windows, install Python 3.8 or newer, clone the repository, and run the
+per-user PowerShell installer. The official ARM64 Python build can be installed
+with Winget:
+
+```powershell
+winget install --exact --id Python.Python.3.13 --architecture arm64 --scope user
+git clone https://github.com/Galileo-Agent-Labs/token-meter.git
+pwsh -NoProfile -File .\token-meter\scripts\install-windows.ps1
+```
+
+The Windows installer stages the runtime under
+`%LOCALAPPDATA%\Token Meter\runtime`, starts the local server without a console
+window, and registers a per-user login startup entry. Windows uses the browser
+dashboard; the native AppKit menu-bar companion remains macOS-only.
+
+Token Meter starts its local server automatically after installation and after
+future logins. On macOS, it also starts the menu bar widget. Open the dashboard
+at:
 
 ```text
 http://localhost:8722
@@ -187,17 +203,18 @@ observation establishes a baseline and never sends a catch-up notification.
 ## Requirements
 
 - Python 3.8 or newer. The macOS package first tries `/usr/bin/python3`, then
-  Homebrew and user `python3` installs.
+  Homebrew and user `python3` installs. The Windows installer detects native
+  Python installs under `%LOCALAPPDATA%\Programs\Python` as well as `PATH`.
 - Claude Code CLI, Codex CLI, Claude Desktop Agent/Cowork, and/or the Codex
   desktop app if you want live log data.
-- macOS with the Swift toolchain, usually from Xcode Command Line Tools, when
-  running from source. The macOS package includes a prebuilt menu bar binary.
-- `curl`, used by the helper scripts.
+- macOS with the Swift toolchain, usually from Xcode Command Line Tools, for the
+  native menu-bar companion. The macOS package includes a prebuilt binary.
+- Git. The macOS helper scripts also use `curl`; Windows uses PowerShell's local
+  HTTP client.
 
 The web dashboard has no third-party Python packages. `meter.py` uses only the
-Python standard library. Dashboard-only mode is available for development,
-troubleshooting, and non-macOS use, but the normal experience includes the menu
-bar companion.
+Python standard library. The installed Windows experience uses the browser
+dashboard, while macOS also includes the menu-bar companion.
 
 ## Ask From Codex Or Claude
 
@@ -239,6 +256,10 @@ codex mcp add --env TOKEN_METER_CALLER=codex tokenmeter -- "$PWD/scripts/run-tok
 claude mcp add --transport stdio --scope user tokenmeter --env TOKEN_METER_CALLER=claude -- "$PWD/scripts/run-token-meter-mcp"
 ```
 
+The Windows installer stages an equivalent launcher at
+`%LOCALAPPDATA%\Token Meter\runtime\scripts\run-token-meter-mcp.cmd`; the
+dashboard's connection controls select it automatically.
+
 Remove the connections with:
 
 ```bash
@@ -257,7 +278,7 @@ updates**. Token Meter immediately fetches revision metadata from the Git
 upstream configured during installation, then checks again once per hour while
 the server is running. The installer keeps a dedicated update checkout beside
 the runtime so the background service does not need access to a development
-checkout under a macOS-protected folder such as Documents. You can disable
+checkout instead of the development clone. You can disable
 these checks at any time. Checks do not merge, pull, reinstall, or send
 telemetry.
 
@@ -279,9 +300,17 @@ either process independently if it exits. Remove both login items with:
 "$HOME/Library/Application Support/Token Meter/runtime/scripts/uninstall-launch-agent"
 ```
 
+On Windows, the installer registers the server in the current user's `Run`
+key. Remove that startup entry and stop the server while retaining the staged
+runtime with:
+
+```powershell
+& "$env:LOCALAPPDATA\Token Meter\runtime\scripts\uninstall-windows.ps1"
+```
+
 ## Dashboard-Only Mode
 
-For development, troubleshooting, or non-macOS use, run only the local web
+For development or troubleshooting, run only the local web
 dashboard:
 
 ```bash
diff --git a/meter.py b/meter.py
index da38f27..c580ef9 100644
--- a/meter.py
+++ b/meter.py
@@ -36,18 +36,40 @@
 import statistics
 import time
 import threading
+from contextlib import closing
 from collections import defaultdict
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
 from urllib.error import HTTPError, URLError
 from urllib.parse import parse_qs, quote, urlparse
 from urllib.request import Request, urlopen
 
+def application_support_root(platform=None, environ=None):
+    """Return the per-user application-data root for the active desktop."""
+    platform = os.name if platform is None else platform
+    environ = os.environ if environ is None else environ
+    if platform == "nt":
+        return os.path.expanduser(environ.get("APPDATA") or "~/AppData/Roaming")
+    return os.path.expanduser("~/Library/Application Support")
+
+
+def session_trash_directory(platform=None, environ=None):
+    """Return Token Meter's recoverable deletion directory for this platform."""
+    platform = os.name if platform is None else platform
+    environ = os.environ if environ is None else environ
+    if platform == "nt":
+        root = os.path.expanduser(environ.get("LOCALAPPDATA") or "~/AppData/Local")
+        return os.path.join(root, "Token Meter", "Trash")
+    return os.path.expanduser("~/.Trash")
+
+
+APPLICATION_SUPPORT_ROOT = application_support_root()
 CLAUDE_PROJECTS = os.path.expanduser("~/.claude/projects")
 CLAUDE_DESKTOP_DATA_ROOTS = [
-    os.path.expanduser("~/Library/Application Support/Claude"),
+    os.path.join(APPLICATION_SUPPORT_ROOT, "Claude"),
     # Claude Desktop's third-party provider builds (including Bedrock-backed
     # Cowork) keep the same metadata and nested Claude trace layout here.
-    os.path.expanduser("~/Library/Application Support/Claude-3p"),
+    os.path.join(APPLICATION_SUPPORT_ROOT, "Claude-3p"),
 ]
 CLAUDE_DESKTOP_SESSIONS = os.path.join(CLAUDE_DESKTOP_DATA_ROOTS[0], "claude-code-sessions")
 CLAUDE_SETTINGS = os.path.expanduser("~/.claude/settings.json")
@@ -58,10 +80,10 @@
 CODEX_AUTH = os.path.expanduser("~/.codex/auth.json")
 CLAUDE_CREDENTIALS = os.path.expanduser("~/.claude/.credentials.json")
 CURSOR_PROJECTS = os.path.expanduser("~/.cursor/projects")
-CURSOR_STATE_DB = os.path.expanduser(
-    "~/Library/Application Support/Cursor/User/globalStorage/state.vscdb"
+CURSOR_STATE_DB = os.path.join(
+    APPLICATION_SUPPORT_ROOT, "Cursor", "User", "globalStorage", "state.vscdb"
 )
-CURSOR_REQUEST_LOGS = os.path.expanduser("~/Library/Application Support/Cursor/logs")
+CURSOR_REQUEST_LOGS = os.path.join(APPLICATION_SUPPORT_ROOT, "Cursor", "logs")
 TOKEN_METER_SETTINGS = os.path.expanduser(
     os.environ.get("TOKEN_METER_SETTINGS", "~/.token-meter/settings.json")
 )
@@ -1410,8 +1432,19 @@ def start_software_update(popen=None, settings_path=None, status_path=None):
     if not status["available"] or not status["can_update"]:
         return {"ok": False, "error": "No safely installable update is available."}
     checkout = source_checkout_path()
-    script = os.path.join(os.path.dirname(os.path.realpath(__file__)), "scripts", "update")
-    if not checkout or not os.path.isfile(script) or not os.access(script, os.X_OK):
+    root = os.path.dirname(os.path.realpath(__file__))
+    target_status_path = status_path or TOKEN_METER_UPDATE_STATUS
+    if os.name == "nt":
+        script = os.path.join(root, "scripts", "update-windows.ps1")
+        shell = shutil.which("pwsh") or shutil.which("powershell")
+        command = ([shell, "-NoLogo", "-NoProfile", "-WindowStyle", "Hidden", "-File",
+                    script, checkout, target_status_path] if shell else [])
+        helper_ready = bool(shell and os.path.isfile(script))
+    else:
+        script = os.path.join(root, "scripts", "update")
+        command = [script, checkout, target_status_path]
+        helper_ready = bool(os.path.isfile(script) and os.access(script, os.X_OK))
+    if not checkout or not helper_ready:
         return {"ok": False, "error": "The installed updater is unavailable."}
     started_at = int(time.time())
     _persist_update_status({
@@ -1426,14 +1459,21 @@ def start_software_update(popen=None, settings_path=None, status_path=None):
     }, status_path)
     popen = popen or subprocess.Popen
     try:
-        popen(
-            [script, checkout, status_path or TOKEN_METER_UPDATE_STATUS],
-            stdin=subprocess.DEVNULL,
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-            close_fds=True,
-            start_new_session=True,
-        )
+        launch_options = {
+            "stdin": subprocess.DEVNULL,
+            "stdout": subprocess.DEVNULL,
+            "stderr": subprocess.DEVNULL,
+            "close_fds": True,
+        }
+        if os.name == "nt":
+            launch_options["creationflags"] = (
+                getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
+                | getattr(subprocess, "DETACHED_PROCESS", 0)
+                | getattr(subprocess, "CREATE_NO_WINDOW", 0)
+            )
+        else:
+            launch_options["start_new_session"] = True
+        popen(command, **launch_options)
     except OSError:
         _persist_update_status({
             "phase": "failed", "error_code": "launch_failed",
@@ -1802,7 +1842,7 @@ def _cursor_json(value, default=None):
 def _cursor_db_connection(path=None):
     """Open Cursor's live database read-only while retaining WAL visibility."""
     path = os.path.abspath(os.path.expanduser(path or CURSOR_STATE_DB))
-    uri = f"file:{quote(path, safe='/')}?mode=ro"
+    uri = f"{Path(path).as_uri()}?mode=ro"
     conn = sqlite3.connect(uri, uri=True, timeout=0.05)
     conn.execute("PRAGMA query_only = ON")
     conn.execute("PRAGMA busy_timeout = 50")
@@ -1844,7 +1884,7 @@ def cursor_metadata_index(db_path=None):
     """Return top-level Cursor Composer metadata in one read-only snapshot."""
     result = {}
     try:
-        with _cursor_db_connection(db_path) as conn:
+        with closing(_cursor_db_connection(db_path)) as conn:
             headers = conn.execute(
                 "SELECT composerId, workspaceId, createdAt, lastUpdatedAt, "
                 "isArchived, isSubagent, checkpointAt, value FROM composerHeaders"
@@ -1882,7 +1922,7 @@ def cursor_metadata_index(db_path=None):
 def cursor_snapshot(composer_id, db_path=None):
     """Read one ordered Cursor conversation, degrading cleanly on schema drift."""
     try:
-        with _cursor_db_connection(db_path) as conn:
+        with closing(_cursor_db_connection(db_path)) as conn:
             row = conn.execute(
                 "SELECT workspaceId, createdAt, lastUpdatedAt, isArchived, "
                 "isSubagent, checkpointAt, value FROM composerHeaders WHERE composerId = ?",
@@ -2306,7 +2346,7 @@ def trash_session_log(session_id, sources=None, trash_dir=None, mover=None):
         return {"ok": False, "error": "The discovered session log is not available.",
                 "error_code": "not_found"}
 
-    trash_dir = os.path.expanduser(trash_dir or "~/.Trash")
+    trash_dir = os.path.expanduser(trash_dir or session_trash_directory())
     mover = mover or shutil.move
     try:
         os.makedirs(trash_dir, exist_ok=True)
@@ -6459,21 +6499,25 @@ def capability_action_capability():
 
 
 def session_action_capability():
+    destination = "Token Meter Trash" if os.name == "nt" else "macOS Trash"
     return {
         "available": True,
         "token": _ACTION_TOKEN,
         "recoverable": True,
-        "destination": "macOS Trash",
+        "destination": destination,
     }
 
 
 def agent_access_launcher():
     root = os.path.dirname(os.path.realpath(__file__))
-    candidates = [
-        os.path.join(root, "scripts", "run-token-meter-mcp"),
-        os.path.join(root, "bin", "token-meter-mcp"),
-        "/Library/Application Support/Token Meter/bin/token-meter-mcp",
-    ]
+    if os.name == "nt":
+        candidates = [os.path.join(root, "scripts", "run-token-meter-mcp.cmd")]
+    else:
+        candidates = [
+            os.path.join(root, "scripts", "run-token-meter-mcp"),
+            os.path.join(root, "bin", "token-meter-mcp"),
+            "/Library/Application Support/Token Meter/bin/token-meter-mcp",
+        ]
     return next((path for path in candidates if os.path.isfile(path) and os.access(path, os.X_OK)), candidates[0])
 
 
@@ -6504,7 +6548,10 @@ def agent_client_environment(cli_path):
     # Keep the wrapper's directory, not the resolved script target. NVM's
     # `codex` is a symlink whose sibling `node` binary is required by env(1).
     preferred = [os.path.dirname(os.path.abspath(cli_path))] if cli_path else []
-    for value in ("/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin"):
+    platform_paths = () if os.name == "nt" else (
+        "/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin",
+    )
+    for value in platform_paths:
         if value not in preferred:
             preferred.append(value)
     env["PATH"] = os.pathsep.join(dict.fromkeys(preferred + current))
@@ -9325,7 +9372,7 @@ def load_claude_quota(now=None, opener=None):
 
 def cursor_auth_session(now=None, db_path=None):
     try:
-        with _cursor_db_connection(db_path) as conn:
+        with closing(_cursor_db_connection(db_path)) as conn:
             row = conn.execute(
                 "SELECT value FROM ItemTable WHERE key = ? LIMIT 1",
                 ("cursorAuth/accessToken",),
diff --git a/page.html b/page.html
index 3e01c1c..ca7e436 100644
--- a/page.html
+++ b/page.html
@@ -3114,7 +3114,8 @@ <h3>Delete session?</h3>
  const sessionActions=s.xsession?.session_actions||{}, deleteButton=$('session-delete');
  deleteButton.hidden=!source.id;
  deleteButton.disabled=!sessionActions.available;
- deleteButton.title=sessionActions.available?'Move this session log to macOS Trash.':'Session deletion is unavailable.';
+ const deleteDestination=sessionActions.destination||'Trash';
+ deleteButton.title=sessionActions.available?`Move this session log to ${deleteDestination}.`:'Session deletion is unavailable.';
  $('frozen').classList.toggle('on',frozen);
  $('live').classList.toggle('dead',frozen);
  $('livetxt').textContent=frozen?(pinned?'pinned':'frozen'):('live · '+idleLabel(s.idle_s));
@@ -3175,7 +3176,8 @@ <h3>Delete session?</h3>
  $('session-delete-sub').textContent=`${target.label||target.provider||'Session'} · ${target.project||'No project'}`;
  $('session-delete-evidence').innerHTML=`<div><b>${esc(target.title||'(untitled log)')}</b></div><div>This removes the underlying local JSONL log from Token Meter.</div>`;
  $('session-delete-id').textContent=target.id;
- $('session-delete-note').textContent=isLive?'This appears to be the live session. Stop its agent first to prevent further writes. The log will be moved to macOS Trash; provider metadata and configuration are not changed.':'The log will be moved to macOS Trash and can be recovered there. Provider metadata and configuration are not changed.';
+ const deleteDestination=actions.destination||'Trash';
+ $('session-delete-note').textContent=isLive?`This appears to be the live session. Stop its agent first to prevent further writes. The log will be moved to ${deleteDestination}; provider metadata and configuration are not changed.`:`The log will be moved to ${deleteDestination} and can be recovered there. Provider metadata and configuration are not changed.`;
  $('session-delete-confirm').disabled=false;
  $('session-delete-confirm').textContent='Move to Trash';
  $('session-delete-dialog').showModal();
@@ -4224,7 +4226,7 @@ <h3>Delete session?</h3>
  renderCurrentSessions(LATEST);
  const sessionSurfaceActive=$('view-session').classList.contains('on');
  if(!pinned&&sessionSurfaceActive&&currentPanel!=='sessions')renderSession(LATEST);
- else if(!sessionSurfaceActive)$('livetxt').textContent='live';
+ else if(!sessionSurfaceActive||currentPanel==='sessions')$('livetxt').textContent='live';
 	 if($('view-logs').classList.contains('on'))renderLogs(LATEST.xsession);
 	 if($('view-logs').classList.contains('on')&&(!logSessionInventory||logSessionInventoryAt!==Number(LATEST.xsession?.generated_at||0)))loadLogSessions();
 	 if($('view-models').classList.contains('on')){renderActiveModelStats();renderFrustration(LATEST.xsession?.language_signals,LATEST.xsession?.sessions);}
diff --git a/scripts/install-windows.ps1 b/scripts/install-windows.ps1
new file mode 100644
index 0000000..a22ea2c
--- /dev/null
+++ b/scripts/install-windows.ps1
@@ -0,0 +1,341 @@
+[CmdletBinding()]
+param(
+    [string]$InstallRoot = "",
+    [int]$ReadinessTimeoutSeconds = 0
+)
+
+$ErrorActionPreference = "Stop"
+Set-StrictMode -Version Latest
+
+function Fail([string]$Message) {
+    throw "Token Meter installation failed: $Message"
+}
+
+function Write-Utf8File([string]$Path, [string]$Value) {
+    [System.IO.File]::WriteAllText(
+        $Path,
+        $Value,
+        [System.Text.UTF8Encoding]::new($false)
+    )
+}
+
+function Test-Python([string]$Path) {
+    if (-not $Path -or -not (Test-Path -LiteralPath $Path -PathType Leaf)) {
+        return $false
+    }
+    try {
+        & $Path -c "import sys; raise SystemExit(0 if sys.version_info >= (3, 8) else 1)" 2>$null
+        return $LASTEXITCODE -eq 0
+    } catch {
+        return $false
+    }
+}
+
+function Stop-InstalledServer([string]$RuntimeRoot) {
+    $PidPath = Join-Path $RuntimeRoot "meter.pid"
+    if (-not (Test-Path -LiteralPath $PidPath -PathType Leaf)) {
+        return
+    }
+    $ServerPid = 0
+    if (-not [int]::TryParse((Get-Content -LiteralPath $PidPath -Raw).Trim(), [ref]$ServerPid)) {
+        Remove-Item -LiteralPath $PidPath -Force
+        return
+    }
+    $Process = Get-CimInstance Win32_Process -Filter "ProcessId = $ServerPid" -ErrorAction SilentlyContinue
+    if (-not $Process) {
+        Remove-Item -LiteralPath $PidPath -Force
+        return
+    }
+    $ExpectedMeter = [System.IO.Path]::GetFullPath((Join-Path $RuntimeRoot "meter.py"))
+    if ([string]$Process.CommandLine -notlike "*$ExpectedMeter*") {
+        Fail "the saved server process ID belongs to a different program."
+    }
+    Stop-Process -Id $ServerPid -Force
+    try {
+        Wait-Process -Id $ServerPid -Timeout 10 -ErrorAction SilentlyContinue
+    } catch {
+        # The process may have exited between Stop-Process and Wait-Process.
+    }
+    Remove-Item -LiteralPath $PidPath -Force -ErrorAction SilentlyContinue
+}
+
+function Copy-Directory([string]$Source, [string]$Destination) {
+    New-Item -ItemType Directory -Path $Destination -Force | Out-Null
+    Get-ChildItem -LiteralPath $Source -Force | ForEach-Object {
+        Copy-Item -LiteralPath $_.FullName -Destination $Destination -Recurse -Force
+    }
+}
+
+if ($env:OS -ne "Windows_NT") {
+    Fail "the Windows installer requires Windows."
+}
+
+$SourceRoot = [System.IO.Path]::GetFullPath((Join-Path $PSScriptRoot ".."))
+if (-not $InstallRoot) {
+    $InstallRoot = $env:TOKEN_METER_INSTALL_ROOT
+}
+if (-not $InstallRoot) {
+    if (-not $env:LOCALAPPDATA) {
+        Fail "LOCALAPPDATA is unavailable."
+    }
+    $InstallRoot = Join-Path $env:LOCALAPPDATA "Token Meter\runtime"
+}
+$InstallRoot = [System.IO.Path]::GetFullPath($InstallRoot)
+$InstallParent = Split-Path -Parent $InstallRoot
+$PathRoot = [System.IO.Path]::GetPathRoot($InstallRoot).TrimEnd('\', '/')
+if (-not $InstallParent -or $InstallRoot.TrimEnd('\', '/') -eq $PathRoot -or
+    (Split-Path -Leaf $InstallRoot) -ne "runtime") {
+    Fail "the runtime path must be a specific directory named runtime."
+}
+if (Test-Path -LiteralPath $InstallRoot -PathType Container) {
+    $ExistingEntries = @(Get-ChildItem -LiteralPath $InstallRoot -Force)
+    $RecognizedRuntime = (
+        (Test-Path -LiteralPath (Join-Path $InstallRoot "meter.py") -PathType Leaf) -and
+        (Test-Path -LiteralPath (Join-Path $InstallRoot "page.html") -PathType Leaf) -and
+        (Test-Path -LiteralPath (Join-Path $InstallRoot "scripts\start-token-meter.ps1") -PathType Leaf)
+    )
+    if ($ExistingEntries.Count -gt 0 -and -not $RecognizedRuntime) {
+        Fail "the runtime path contains files that do not belong to Token Meter."
+    }
+}
+
+if ($ReadinessTimeoutSeconds -le 0) {
+    $ConfiguredTimeout = 0
+    if ($env:TOKEN_METER_READINESS_TIMEOUT_SECONDS) {
+        [int]::TryParse($env:TOKEN_METER_READINESS_TIMEOUT_SECONDS, [ref]$ConfiguredTimeout) | Out-Null
+    }
+    $ReadinessTimeoutSeconds = if ($ConfiguredTimeout -gt 0) { $ConfiguredTimeout } else { 600 }
+}
+
+$Git = Get-Command git.exe -CommandType Application -ErrorAction SilentlyContinue
+if (-not $Git) {
+    Fail "Git is required but was not found."
+}
+
+$PythonCandidates = [System.Collections.Generic.List[string]]::new()
+if ($env:TOKEN_METER_PYTHON) {
+    $PythonCandidates.Add($env:TOKEN_METER_PYTHON)
+}
+foreach ($Name in @("python3.exe", "python.exe")) {
+    $Command = Get-Command $Name -CommandType Application -ErrorAction SilentlyContinue
+    if ($Command) {
+        $PythonCandidates.Add($Command.Source)
+    }
+}
+$PythonBase = Join-Path $env:LOCALAPPDATA "Programs\Python"
+if (Test-Path -LiteralPath $PythonBase -PathType Container) {
+    Get-ChildItem -LiteralPath $PythonBase -Filter python.exe -File -Recurse |
+        Sort-Object FullName -Descending |
+        ForEach-Object { $PythonCandidates.Add($_.FullName) }
+}
+$PythonExe = $PythonCandidates |
+    Select-Object -Unique |
+    Where-Object { Test-Python $_ } |
+    Select-Object -First 1
+if (-not $PythonExe) {
+    Fail "Python 3.8 or newer was not found. Install the native Windows build of Python and rerun this script."
+}
+$PythonExe = [System.IO.Path]::GetFullPath($PythonExe)
+$PythonwCandidate = Join-Path (Split-Path -Parent $PythonExe) "pythonw.exe"
+$PythonwExe = if (Test-Path -LiteralPath $PythonwCandidate -PathType Leaf) {
+    $PythonwCandidate
+} else {
+    $PythonExe
+}
+
+$RequiredPaths = @(
+    "meter.py",
+    "page.html",
+    "token_meter_mcp.py",
+    "scripts\install-windows.ps1",
+    "scripts\start-token-meter.ps1",
+    "scripts\uninstall-windows.ps1",
+    "scripts\update-windows.ps1",
+    "scripts\run-token-meter-mcp.cmd"
+)
+foreach ($RelativePath in $RequiredPaths) {
+    if (-not (Test-Path -LiteralPath (Join-Path $SourceRoot $RelativePath))) {
+        Fail "the repository checkout is incomplete: $RelativePath is missing."
+    }
+}
+
+New-Item -ItemType Directory -Path $InstallParent -Force | Out-Null
+$ManagedSourceRoot = if ($env:TOKEN_METER_SOURCE_ROOT) {
+    [System.IO.Path]::GetFullPath($env:TOKEN_METER_SOURCE_ROOT)
+} else {
+    Join-Path $InstallParent "source"
+}
+$UpdateSourceRoot = $SourceRoot
+$SourceUpstream = (& $Git.Source -C $SourceRoot rev-parse --abbrev-ref --symbolic-full-name '@{upstream}' 2>$null | Out-String).Trim()
+if ($SourceUpstream -like "*/*" -and $SourceRoot -ne $ManagedSourceRoot) {
+    $Slash = $SourceUpstream.IndexOf('/')
+    $SourceRemote = $SourceUpstream.Substring(0, $Slash)
+    $SourceBranch = $SourceUpstream.Substring($Slash + 1)
+    $SourceRemoteUrl = (& $Git.Source -C $SourceRoot remote get-url $SourceRemote 2>$null | Out-String).Trim()
+    if ($SourceRemoteUrl -and $SourceBranch) {
+        if (-not (Test-Path -LiteralPath $ManagedSourceRoot)) {
+            & $Git.Source clone --quiet --no-local $SourceRoot $ManagedSourceRoot
+            if ($LASTEXITCODE -ne 0) {
+                Fail "the managed update checkout could not be created."
+            }
+        }
+        if (-not (Test-Path -LiteralPath (Join-Path $ManagedSourceRoot ".git") -PathType Container)) {
+            Fail "the managed update checkout is not a Git repository."
+        }
+        $ManagedDirty = (& $Git.Source -C $ManagedSourceRoot status --porcelain 2>$null | Out-String).Trim()
+        if ($ManagedDirty) {
+            Fail "the managed update checkout has local changes."
+        }
+        $SourceRevision = (& $Git.Source -C $SourceRoot rev-parse HEAD 2>$null | Out-String).Trim()
+        if ($SourceRevision) {
+            & $Git.Source -C $ManagedSourceRoot fetch --quiet --no-tags $SourceRoot $SourceRevision
+            if ($LASTEXITCODE -ne 0) {
+                Fail "the managed update checkout could not read the installed revision."
+            }
+            & $Git.Source -C $ManagedSourceRoot merge --quiet --ff-only FETCH_HEAD
+            if ($LASTEXITCODE -ne 0) {
+                Fail "the managed update checkout has diverged from the installed source."
+            }
+        }
+        $ManagedRemoteUrl = (& $Git.Source -C $ManagedSourceRoot remote get-url origin 2>$null | Out-String).Trim()
+        if ($ManagedRemoteUrl -ne $SourceRemoteUrl) {
+            $ManagedRemoteIsSource = $false
+            try {
+                $ManagedRemoteIsSource = [System.IO.Path]::GetFullPath($ManagedRemoteUrl) -eq $SourceRoot
+            } catch { }
+            if ($ManagedRemoteIsSource) {
+                & $Git.Source -C $ManagedSourceRoot remote set-url origin $SourceRemoteUrl
+            } else {
+                Fail "the managed update checkout belongs to a different upstream."
+            }
+        }
+        $ManagedBranch = (& $Git.Source -C $ManagedSourceRoot rev-parse --abbrev-ref HEAD 2>$null | Out-String).Trim()
+        if ($ManagedBranch) {
+            & $Git.Source -C $ManagedSourceRoot config "branch.$ManagedBranch.remote" origin
+            & $Git.Source -C $ManagedSourceRoot config "branch.$ManagedBranch.merge" "refs/heads/$SourceBranch"
+        }
+        $UpdateSourceRoot = $ManagedSourceRoot
+    }
+}
+
+Write-Host "Installing Token Meter from:"
+Write-Host "  $SourceRoot"
+Write-Host "Runtime:"
+Write-Host "  $InstallRoot"
+
+$InstallNonce = [Guid]::NewGuid().ToString("N")
+$StagingRoot = "$InstallRoot.installing-$InstallNonce"
+$BackupRoot = "$InstallRoot.previous-$InstallNonce"
+foreach ($TemporaryRoot in @($StagingRoot, $BackupRoot)) {
+    $ResolvedTemporaryParent = [System.IO.Path]::GetFullPath((Split-Path -Parent $TemporaryRoot))
+    if ($ResolvedTemporaryParent -ne [System.IO.Path]::GetFullPath($InstallParent)) {
+        Fail "a temporary runtime path escaped the installation directory."
+    }
+    if (Test-Path -LiteralPath $TemporaryRoot) {
+        Fail "a unique temporary runtime path already exists."
+    }
+}
+
+New-Item -ItemType Directory -Path $StagingRoot -Force | Out-Null
+foreach ($RuntimeFile in @("meter.py", "page.html", "token_meter_mcp.py", "README.md", "LICENSE")) {
+    $SourceFile = Join-Path $SourceRoot $RuntimeFile
+    if (Test-Path -LiteralPath $SourceFile -PathType Leaf) {
+        Copy-Item -LiteralPath $SourceFile -Destination (Join-Path $StagingRoot $RuntimeFile) -Force
+    }
+}
+foreach ($RuntimeDirectory in @("menubar", "scripts", "assets")) {
+    $SourceDirectory = Join-Path $SourceRoot $RuntimeDirectory
+    if (Test-Path -LiteralPath $SourceDirectory -PathType Container) {
+        Copy-Directory $SourceDirectory (Join-Path $StagingRoot $RuntimeDirectory)
+    }
+}
+Write-Utf8File (Join-Path $StagingRoot "SOURCE_CHECKOUT") ($UpdateSourceRoot + [Environment]::NewLine)
+Write-Utf8File (Join-Path $StagingRoot "PYTHON_EXECUTABLE") ($PythonExe + [Environment]::NewLine)
+Write-Utf8File (Join-Path $StagingRoot "PYTHON_WINDOWED_EXECUTABLE") ($PythonwExe + [Environment]::NewLine)
+
+$Commit = (& $Git.Source -C $SourceRoot rev-parse --short HEAD 2>$null | Out-String).Trim()
+if ($Commit) {
+    $DirtyPaths = @(& $Git.Source -C $SourceRoot status --short --untracked-files=all 2>$null) |
+        Where-Object { $_ -and $_ -notmatch '^\?\? plan\.md$' }
+    if ($DirtyPaths.Count -gt 0) {
+        $Commit = "$Commit+local"
+    }
+    Write-Utf8File (Join-Path $StagingRoot "INSTALLED_REVISION") ($Commit + [Environment]::NewLine)
+}
+
+$RunKey = "Registry::HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run"
+$RunName = "Token Meter"
+$PreviousRunValue = $null
+if (Test-Path -LiteralPath $RunKey) {
+    $PreviousRunProperties = Get-ItemProperty -LiteralPath $RunKey -Name $RunName -ErrorAction SilentlyContinue
+    if ($PreviousRunProperties) {
+        $PreviousRunValue = $PreviousRunProperties.$RunName
+    }
+}
+$Swapped = $false
+try {
+    if (Test-Path -LiteralPath $InstallRoot) {
+        Stop-InstalledServer $InstallRoot
+        Move-Item -LiteralPath $InstallRoot -Destination $BackupRoot
+    }
+    Move-Item -LiteralPath $StagingRoot -Destination $InstallRoot
+    $Swapped = $true
+
+    $PowerShellCommand = Get-Command powershell.exe -CommandType Application -ErrorAction Stop
+    $PowerShellExe = $PowerShellCommand.Source
+    $StartScript = Join-Path $InstallRoot "scripts\start-token-meter.ps1"
+    $StartupCommand = "`"$PowerShellExe`" -NoLogo -NoProfile -WindowStyle Hidden -File `"$StartScript`""
+    New-Item -Path $RunKey -Force | Out-Null
+    New-ItemProperty -LiteralPath $RunKey -Name $RunName -PropertyType String -Value $StartupCommand -Force | Out-Null
+
+    & $StartScript -ReadinessTimeoutSeconds $ReadinessTimeoutSeconds
+
+    $Health = Invoke-RestMethod -Uri "http://127.0.0.1:8722/health" -TimeoutSec 5
+    if (-not $Health.ok -or -not $Health.state_ready) {
+        Fail "the local server did not become ready."
+    }
+    $ExpectedPage = [System.IO.Path]::GetFullPath((Join-Path $InstallRoot "page.html"))
+    $ActualPage = [System.IO.Path]::GetFullPath([string]$Health.page_path)
+    if ($ActualPage -ne $ExpectedPage) {
+        Fail "a different Token Meter installation owns port 8722."
+    }
+    $null = Invoke-RestMethod -Uri "http://127.0.0.1:8722/menubar" -TimeoutSec 5
+    $SavedRunValue = (Get-ItemProperty -LiteralPath $RunKey -Name $RunName).$RunName
+    if ($SavedRunValue -ne $StartupCommand) {
+        Fail "automatic login startup could not be verified."
+    }
+
+    if (Test-Path -LiteralPath $BackupRoot) {
+        Remove-Item -LiteralPath $BackupRoot -Recurse -Force
+    }
+} catch {
+    if ($Swapped -and (Test-Path -LiteralPath $InstallRoot)) {
+        try { Stop-InstalledServer $InstallRoot } catch { }
+        Remove-Item -LiteralPath $InstallRoot -Recurse -Force -ErrorAction SilentlyContinue
+    }
+    if (Test-Path -LiteralPath $BackupRoot) {
+        Move-Item -LiteralPath $BackupRoot -Destination $InstallRoot
+    }
+    if ($null -eq $PreviousRunValue) {
+        Remove-ItemProperty -LiteralPath $RunKey -Name $RunName -ErrorAction SilentlyContinue
+    } else {
+        New-ItemProperty -LiteralPath $RunKey -Name $RunName -PropertyType String -Value $PreviousRunValue -Force | Out-Null
+    }
+    throw
+} finally {
+    if (Test-Path -LiteralPath $StagingRoot) {
+        Remove-Item -LiteralPath $StagingRoot -Recurse -Force
+    }
+}
+
+$PythonArchitecture = (& $PythonExe -c "import platform; print(platform.machine())" | Out-String).Trim()
+Write-Host ""
+Write-Host "Token Meter installation complete."
+Write-Host "Dashboard: http://127.0.0.1:8722"
+Write-Host "Starts automatically after you log in."
+Write-Host "Runtime: $InstallRoot"
+Write-Host "Python: $PythonExe ($PythonArchitecture)"
+if ($Commit) {
+    Write-Host "Installed commit: $Commit"
+}
+Write-Host "Uninstall: & `"$InstallRoot\scripts\uninstall-windows.ps1`""
diff --git a/scripts/run-token-meter-mcp.cmd b/scripts/run-token-meter-mcp.cmd
new file mode 100644
index 0000000..1e5feb3
--- /dev/null
+++ b/scripts/run-token-meter-mcp.cmd
@@ -0,0 +1,9 @@
+@echo off
+setlocal
+set "TOKEN_METER_ROOT=%~dp0.."
+set /p "TOKEN_METER_PYTHON="<"%TOKEN_METER_ROOT%\PYTHON_EXECUTABLE"
+if not exist "%TOKEN_METER_PYTHON%" (
+  echo Token Meter MCP failed: configured Python executable is unavailable. 1>&2
+  exit /b 1
+)
+"%TOKEN_METER_PYTHON%" -X utf8 "%TOKEN_METER_ROOT%\token_meter_mcp.py"
diff --git a/scripts/start-token-meter.ps1 b/scripts/start-token-meter.ps1
new file mode 100644
index 0000000..32a2992
--- /dev/null
+++ b/scripts/start-token-meter.ps1
@@ -0,0 +1,125 @@
+[CmdletBinding()]
+param(
+    [int]$ReadinessTimeoutSeconds = 0
+)
+
+$ErrorActionPreference = "Stop"
+Set-StrictMode -Version Latest
+
+function Get-Health {
+    try {
+        return Invoke-RestMethod -Uri "http://127.0.0.1:8722/health" -TimeoutSec 3
+    } catch {
+        return $null
+    }
+}
+
+function Test-OwnedHealth($Health, [string]$ExpectedPage) {
+    if (-not $Health -or -not $Health.page_path) {
+        return $false
+    }
+    try {
+        return [System.IO.Path]::GetFullPath([string]$Health.page_path) -eq $ExpectedPage
+    } catch {
+        return $false
+    }
+}
+
+$RuntimeRoot = [System.IO.Path]::GetFullPath((Join-Path $PSScriptRoot ".."))
+$MeterPath = [System.IO.Path]::GetFullPath((Join-Path $RuntimeRoot "meter.py"))
+$ExpectedPage = [System.IO.Path]::GetFullPath((Join-Path $RuntimeRoot "page.html"))
+$PythonRecord = Join-Path $RuntimeRoot "PYTHON_EXECUTABLE"
+$WindowedPythonRecord = Join-Path $RuntimeRoot "PYTHON_WINDOWED_EXECUTABLE"
+$PidPath = Join-Path $RuntimeRoot "meter.pid"
+$OutputLog = Join-Path $RuntimeRoot "meter.log"
+$ErrorLog = Join-Path $RuntimeRoot "meter.err.log"
+
+if ($ReadinessTimeoutSeconds -le 0) {
+    $ConfiguredTimeout = 0
+    if ($env:TOKEN_METER_READINESS_TIMEOUT_SECONDS) {
+        [int]::TryParse($env:TOKEN_METER_READINESS_TIMEOUT_SECONDS, [ref]$ConfiguredTimeout) | Out-Null
+    }
+    $ReadinessTimeoutSeconds = if ($ConfiguredTimeout -gt 0) { $ConfiguredTimeout } else { 600 }
+}
+
+if (-not (Test-Path -LiteralPath $PythonRecord -PathType Leaf)) {
+    throw "Token Meter's Python runtime record is missing. Reinstall Token Meter."
+}
+$PythonExe = (Get-Content -LiteralPath $PythonRecord -Raw).Trim()
+if (Test-Path -LiteralPath $WindowedPythonRecord -PathType Leaf) {
+    $WindowedPythonExe = (Get-Content -LiteralPath $WindowedPythonRecord -Raw).Trim()
+    if (Test-Path -LiteralPath $WindowedPythonExe -PathType Leaf) {
+        $PythonExe = $WindowedPythonExe
+    }
+}
+if (-not (Test-Path -LiteralPath $PythonExe -PathType Leaf)) {
+    throw "Token Meter's configured Python executable is unavailable. Reinstall Token Meter."
+}
+
+$Health = Get-Health
+if ($Health -and -not (Test-OwnedHealth $Health $ExpectedPage)) {
+    throw "A different server owns http://127.0.0.1:8722."
+}
+
+$Process = $null
+if (-not $Health) {
+    if (Test-Path -LiteralPath $PidPath -PathType Leaf) {
+        $SavedPid = 0
+        if ([int]::TryParse((Get-Content -LiteralPath $PidPath -Raw).Trim(), [ref]$SavedPid)) {
+            $SavedProcess = Get-CimInstance Win32_Process -Filter "ProcessId = $SavedPid" -ErrorAction SilentlyContinue
+            if ($SavedProcess -and [string]$SavedProcess.CommandLine -like "*$MeterPath*") {
+                $Process = Get-Process -Id $SavedPid -ErrorAction SilentlyContinue
+            }
+        }
+        if (-not $Process) {
+            Remove-Item -LiteralPath $PidPath -Force -ErrorAction SilentlyContinue
+        }
+    }
+    if (-not $Process) {
+        $PreviousUtf8 = $env:PYTHONUTF8
+        $env:PYTHONUTF8 = "1"
+        try {
+            $Process = Start-Process -FilePath $PythonExe `
+                -ArgumentList @("-X", "utf8", "`"$MeterPath`"") `
+                -WorkingDirectory $RuntimeRoot `
+                -RedirectStandardOutput $OutputLog `
+                -RedirectStandardError $ErrorLog `
+                -WindowStyle Hidden `
+                -PassThru
+        } finally {
+            if ($null -eq $PreviousUtf8) {
+                Remove-Item Env:PYTHONUTF8 -ErrorAction SilentlyContinue
+            } else {
+                $env:PYTHONUTF8 = $PreviousUtf8
+            }
+        }
+        [System.IO.File]::WriteAllText($PidPath, "$($Process.Id)`r`n", [System.Text.UTF8Encoding]::new($false))
+    }
+}
+
+$Deadline = [DateTime]::UtcNow.AddSeconds($ReadinessTimeoutSeconds)
+$Ready = $false
+do {
+    $Health = Get-Health
+    if ($Health -and -not (Test-OwnedHealth $Health $ExpectedPage)) {
+        throw "A different server owns http://127.0.0.1:8722."
+    }
+    if ($Health -and $Health.ok -and $Health.state_ready) {
+        $Ready = $true
+        break
+    }
+    if ($Process) {
+        $Process.Refresh()
+        if ($Process.HasExited) {
+            $Detail = if (Test-Path -LiteralPath $ErrorLog) {
+                (Get-Content -LiteralPath $ErrorLog -Tail 20 | Out-String).Trim()
+            } else { "" }
+            throw "Token Meter exited before becoming ready. $Detail"
+        }
+    }
+    Start-Sleep -Milliseconds 500
+} while ([DateTime]::UtcNow -lt $Deadline)
+
+if (-not $Ready) {
+    throw "Token Meter did not finish indexing within $ReadinessTimeoutSeconds seconds."
+}
diff --git a/scripts/uninstall-windows.ps1 b/scripts/uninstall-windows.ps1
new file mode 100644
index 0000000..51de1a6
--- /dev/null
+++ b/scripts/uninstall-windows.ps1
@@ -0,0 +1,54 @@
+[CmdletBinding()]
+param(
+    [string]$InstallRoot = ""
+)
+
+$ErrorActionPreference = "Stop"
+Set-StrictMode -Version Latest
+
+if (-not $InstallRoot) {
+    $InstallRoot = $env:TOKEN_METER_INSTALL_ROOT
+}
+if (-not $InstallRoot) {
+    $InstallRoot = Join-Path $env:LOCALAPPDATA "Token Meter\runtime"
+}
+$InstallRoot = [System.IO.Path]::GetFullPath($InstallRoot)
+$StartScript = Join-Path $InstallRoot "scripts\start-token-meter.ps1"
+$RunKey = "Registry::HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run"
+$RunName = "Token Meter"
+
+$RunValue = $null
+if (Test-Path -LiteralPath $RunKey) {
+    $RunProperties = Get-ItemProperty -LiteralPath $RunKey -Name $RunName -ErrorAction SilentlyContinue
+    if ($RunProperties) {
+        $RunValue = $RunProperties.$RunName
+    }
+}
+if ($RunValue) {
+    if ([string]$RunValue -notlike "*$StartScript*") {
+        throw "A different Token Meter installation owns the login startup entry."
+    }
+    Remove-ItemProperty -LiteralPath $RunKey -Name $RunName
+}
+
+$PidPath = Join-Path $InstallRoot "meter.pid"
+if (Test-Path -LiteralPath $PidPath -PathType Leaf) {
+    $ServerPid = 0
+    if ([int]::TryParse((Get-Content -LiteralPath $PidPath -Raw).Trim(), [ref]$ServerPid)) {
+        $Process = Get-CimInstance Win32_Process -Filter "ProcessId = $ServerPid" -ErrorAction SilentlyContinue
+        $ExpectedMeter = [System.IO.Path]::GetFullPath((Join-Path $InstallRoot "meter.py"))
+        if ($Process) {
+            if ([string]$Process.CommandLine -notlike "*$ExpectedMeter*") {
+                throw "The saved server process ID belongs to a different program."
+            }
+            Stop-Process -Id $ServerPid -Force
+            try {
+                Wait-Process -Id $ServerPid -Timeout 10 -ErrorAction SilentlyContinue
+            } catch { }
+        }
+    }
+    Remove-Item -LiteralPath $PidPath -Force -ErrorAction SilentlyContinue
+}
+
+Write-Host "Token Meter automatic startup removed and the local server stopped."
+Write-Host "Runtime retained at: $InstallRoot"
diff --git a/scripts/update-windows.ps1 b/scripts/update-windows.ps1
new file mode 100644
index 0000000..73eea59
--- /dev/null
+++ b/scripts/update-windows.ps1
@@ -0,0 +1,123 @@
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true, Position = 0)]
+    [string]$SourceRoot,
+    [Parameter(Mandatory = $true, Position = 1)]
+    [string]$StatusPath
+)
+
+$ErrorActionPreference = "Stop"
+Set-StrictMode -Version Latest
+
+$RuntimeRoot = [System.IO.Path]::GetFullPath((Join-Path $PSScriptRoot ".."))
+$SourceRoot = [System.IO.Path]::GetFullPath($SourceRoot)
+$StatusPath = [System.IO.Path]::GetFullPath($StatusPath)
+$PreviousStatus = @{}
+try {
+    $Decoded = Get-Content -LiteralPath $StatusPath -Raw | ConvertFrom-Json
+    if ($Decoded) {
+        foreach ($Property in $Decoded.PSObject.Properties) {
+            $PreviousStatus[$Property.Name] = $Property.Value
+        }
+    }
+} catch { }
+
+function Write-UpdateStatus(
+    [string]$Phase,
+    [string]$ErrorCode,
+    [string]$CurrentRevision,
+    [string]$LatestRevision,
+    [string]$PreviousRevision
+) {
+    $Now = [DateTimeOffset]::UtcNow.ToUnixTimeSeconds()
+    $Record = [ordered]@{
+        phase = $Phase
+        error_code = $ErrorCode
+        current_revision = $CurrentRevision
+        latest_revision = $LatestRevision
+        previous_revision = $PreviousRevision
+        checked_at = $Now
+        available = $Phase -in @("fetching", "installing")
+        can_update = $false
+        dirty = $false
+        ahead = 0
+        behind = 0
+    }
+    if ($Phase -eq "complete") {
+        $Record.installed_at = $Now
+    } elseif ($PreviousStatus.ContainsKey("installed_at")) {
+        $Record.installed_at = $PreviousStatus.installed_at
+    }
+    $Parent = Split-Path -Parent $StatusPath
+    New-Item -ItemType Directory -Path $Parent -Force | Out-Null
+    $Temporary = "$StatusPath.tmp-$PID"
+    [System.IO.File]::WriteAllText(
+        $Temporary,
+        (($Record | ConvertTo-Json -Depth 3) + [Environment]::NewLine),
+        [System.Text.UTF8Encoding]::new($false)
+    )
+    Move-Item -LiteralPath $Temporary -Destination $StatusPath -Force
+}
+
+function Fail-Update([string]$Code) {
+    Write-UpdateStatus "failed" $Code $script:CurrentRevision $script:LatestRevision $script:PreviousRevision
+    exit 1
+}
+
+$script:CurrentRevision = ""
+$script:LatestRevision = ""
+$script:PreviousRevision = if ($PreviousStatus.ContainsKey("previous_revision")) {
+    [string]$PreviousStatus.previous_revision
+} else {
+    ""
+}
+
+if (-not (Test-Path -LiteralPath (Join-Path $SourceRoot ".git") -PathType Container) -or
+    -not (Test-Path -LiteralPath (Join-Path $SourceRoot "scripts\install-windows.ps1") -PathType Leaf)) {
+    Fail-Update "source_unavailable"
+}
+$Git = Get-Command git.exe -CommandType Application -ErrorAction SilentlyContinue
+if (-not $Git) {
+    Fail-Update "git_unavailable"
+}
+
+$Upstream = (& $Git.Source -C $SourceRoot rev-parse --abbrev-ref --symbolic-full-name '@{upstream}' 2>$null | Out-String).Trim()
+if ($LASTEXITCODE -ne 0 -or $Upstream -notlike "*/*") {
+    Fail-Update "upstream_unavailable"
+}
+$Remote = $Upstream.Substring(0, $Upstream.IndexOf('/'))
+Write-UpdateStatus "fetching" "" $script:CurrentRevision $script:LatestRevision $script:PreviousRevision
+& $Git.Source -C $SourceRoot fetch --quiet --prune --no-tags $Remote
+if ($LASTEXITCODE -ne 0) {
+    Fail-Update "fetch_failed"
+}
+
+$script:CurrentRevision = (& $Git.Source -C $SourceRoot rev-parse HEAD 2>$null | Out-String).Trim()
+$script:LatestRevision = (& $Git.Source -C $SourceRoot rev-parse '@{upstream}' 2>$null | Out-String).Trim()
+if (-not $script:PreviousRevision) {
+    $script:PreviousRevision = $script:CurrentRevision
+}
+if (-not $script:CurrentRevision -or -not $script:LatestRevision) {
+    Fail-Update "inspect_failed"
+}
+$Dirty = (& $Git.Source -C $SourceRoot status --porcelain 2>$null | Out-String).Trim()
+if ($Dirty) {
+    Fail-Update "dirty_checkout"
+}
+if ($script:CurrentRevision -eq $script:LatestRevision) {
+    Write-UpdateStatus "complete" "" $script:CurrentRevision $script:LatestRevision $script:PreviousRevision
+    exit 0
+}
+
+& $Git.Source -C $SourceRoot merge --ff-only '@{upstream}'
+if ($LASTEXITCODE -ne 0) {
+    Fail-Update "diverged_checkout"
+}
+$script:CurrentRevision = (& $Git.Source -C $SourceRoot rev-parse HEAD 2>$null | Out-String).Trim()
+Write-UpdateStatus "installing" "" $script:CurrentRevision $script:LatestRevision $script:PreviousRevision
+try {
+    & (Join-Path $SourceRoot "scripts\install-windows.ps1") -InstallRoot $RuntimeRoot
+} catch {
+    Fail-Update "install_failed"
+}
+Write-UpdateStatus "complete" "" $script:CurrentRevision $script:LatestRevision $script:PreviousRevision
diff --git a/tests/test_meter.py b/tests/test_meter.py
index a9e55d4..73ee5aa 100644
--- a/tests/test_meter.py
+++ b/tests/test_meter.py
@@ -10,6 +10,21 @@
 import meter
 
 
+class PlatformPathTests(unittest.TestCase):
+    def test_application_support_root_uses_roaming_app_data_on_windows(self):
+        root = meter.application_support_root("nt", {"APPDATA": r"C:\Users\test\AppData\Roaming"})
+        self.assertEqual(root, r"C:\Users\test\AppData\Roaming")
+
+    def test_windows_deletions_use_a_private_recoverable_trash_directory(self):
+        root = meter.session_trash_directory(
+            "nt", {"LOCALAPPDATA": r"C:\Users\test\AppData\Local"}
+        )
+        self.assertEqual(
+            root,
+            os.path.join(r"C:\Users\test\AppData\Local", "Token Meter", "Trash"),
+        )
+
+
 class SourceDiscoveryCacheTests(unittest.TestCase):
     def test_codex_metadata_is_reused_until_the_trace_changes(self):
         with tempfile.TemporaryDirectory() as tmp:
@@ -691,7 +706,7 @@ def session(session_id, project, output):
         self.assertFalse(unknown["ok"])
         self.assertIn(
             'elif req_path == "/model-stats":',
-            Path(meter.__file__).read_text(),
+            Path(meter.__file__).read_text(encoding="utf-8"),
         )
 
     def test_model_project_options_are_sorted_and_bounded(self):
@@ -1223,7 +1238,7 @@ def test_oversized_manual_history_is_ignored_without_repricing_builtin(self):
         self.assertEqual(row["periods"], 0)
 
     def test_model_pricing_http_action_forwards_bounded_scope_fields(self):
-        source = Path(meter.__file__).read_text()
+        source = Path(meter.__file__).read_text(encoding="utf-8")
         self.assertIn(
             'apply_to_all_history=payload.get("apply_to_all_history") is True',
             source,
@@ -1712,7 +1727,7 @@ def row(source):
 class DashboardLayoutTests(unittest.TestCase):
     @classmethod
     def setUpClass(cls):
-        cls.page = Path(meter.__file__).with_name("page.html").read_text()
+        cls.page = Path(meter.__file__).with_name("page.html").read_text(encoding="utf-8")
 
     def test_current_tabs_exclude_efficiency_panel(self):
         self.assertNotIn("data-panel=efficiency", self.page)
@@ -2441,6 +2456,7 @@ def test_session_delete_actions_require_confirmation_and_use_trash_endpoint(self
         self.assertIn("event.stopPropagation()", self.page)
         self.assertIn("X-Token-Meter-Action", self.page)
         self.assertIn("Provider metadata and configuration are not changed", self.page)
+        self.assertIn("const deleteDestination=actions.destination||'Trash';", self.page)
 
     def test_bulk_unused_action_has_confirmation_and_exact_control_ids(self):
         self.assertIn("id=c-disable-unused", self.page)
@@ -2591,6 +2607,12 @@ def test_sessions_overview_is_bounded_routed_and_accessible(self):
         self.assertNotIn("currentSessionOpen", self.page)
         self.assertNotIn(">Open →</span>", self.page)
 
+    def test_loaded_sessions_overview_replaces_the_connecting_status(self):
+        self.assertIn(
+            "else if(!sessionSurfaceActive||currentPanel==='sessions')$('livetxt').textContent='live';",
+            self.page,
+        )
+
     def test_session_cards_use_compact_readable_metrics(self):
         for marker in (
             ".currentSessionGrid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:14px}",
@@ -2755,7 +2777,7 @@ def test_cursor_provenance_is_integrated_across_dashboard_views(self):
             self.assertIn(marker, self.page)
 
     def test_handler_swallows_browser_disconnects(self):
-        source = Path(meter.__file__).read_text()
+        source = Path(meter.__file__).read_text(encoding="utf-8")
         self.assertIn("except (BrokenPipeError, ConnectionResetError):", source)
 
     def test_dashboard_live_updates_do_not_hold_event_stream_connections(self):
@@ -2763,7 +2785,7 @@ def test_dashboard_live_updates_do_not_hold_event_stream_connections(self):
         self.assertIn("const LIVE_STATE_POLL_MS=1000", self.page)
         self.assertIn("setInterval(refreshLiveState,LIVE_STATE_POLL_MS)", self.page)
         self.assertIn("if(statePollBusy)return", self.page)
-        source = Path(meter.__file__).read_text()
+        source = Path(meter.__file__).read_text(encoding="utf-8")
         events = source.index('elif req_path == "/events":')
         self.assertIn("self.send_response(204)", source[events:events + 700])
 
@@ -2783,7 +2805,9 @@ def test_dynamic_responses_cannot_be_reused_from_an_http_cache(self):
 class MenubarSourceTests(unittest.TestCase):
     @classmethod
     def setUpClass(cls):
-        cls.source = Path(meter.__file__).with_name("menubar").joinpath("TokenMeterMenuBar.swift").read_text()
+        cls.source = Path(meter.__file__).with_name("menubar").joinpath(
+            "TokenMeterMenuBar.swift"
+        ).read_text(encoding="utf-8")
 
     def test_daily_brief_action_opens_cross_session_daily_route(self):
         self.assertIn('addAction("Open Daily Brief", #selector(openDailyBrief))', self.source)
@@ -2807,7 +2831,7 @@ def test_model_prices_setting_opens_dashboard_pricing_editor(self):
     def test_output_speed_is_a_dedicated_honest_metric_row(self):
         self.assertIn('addMetricRow("Output speed", snapshot.outputSpeedLabel', self.source)
         self.assertIn('addMetricRow("Model", snapshot.model)', self.source)
-        self.assertIn('· \(outputSpeedLabel) · \(model)', self.source)
+        self.assertIn(r'· \(outputSpeedLabel) · \(model)', self.source)
         self.assertIn('formatTokenRate(rate)', self.source)
         self.assertIn('Tool execution time may be included.', self.source)
         self.assertIn('print(snapshot.outputSpeedLabel)', self.source)
@@ -3684,7 +3708,7 @@ def test_update_setting_defaults_on_and_preserves_an_explicit_off_choice(self):
         self.assertIn("model_pricing", stored)
 
     def test_update_watcher_preserves_terminal_install_result_for_the_dashboard(self):
-        source = Path(meter.__file__).read_text()
+        source = Path(meter.__file__).read_text(encoding="utf-8")
         self.assertIn('if phase in {"complete", "failed"}:', source)
         self.assertIn("_update_wake.wait(UPDATE_CHECK_INTERVAL_S)", source)
 
@@ -3764,7 +3788,8 @@ def test_explicit_install_starts_only_the_bounded_detached_helper(self):
             popen = mock.Mock()
             with (mock.patch.object(meter, "source_checkout_path", return_value=tmp),
                   mock.patch.object(meter.os.path, "isfile", return_value=True),
-                  mock.patch.object(meter.os, "access", return_value=True)):
+                  mock.patch.object(meter.os, "access", return_value=True),
+                  mock.patch.object(meter.shutil, "which", return_value=r"C:\Program Files\PowerShell\7\pwsh.exe")):
                 result = meter.start_software_update(
                     popen=popen,
                     settings_path=str(settings_path),
@@ -3773,9 +3798,17 @@ def test_explicit_install_starts_only_the_bounded_detached_helper(self):
             command = popen.call_args.args[0]
             kwargs = popen.call_args.kwargs
         self.assertTrue(result["ok"])
-        self.assertTrue(command[0].endswith("/scripts/update"))
-        self.assertEqual(command[1:], [tmp, str(status_path)])
-        self.assertTrue(kwargs["start_new_session"])
+        if os.name == "nt":
+            self.assertTrue(command[0].lower().endswith("pwsh.exe"))
+            self.assertEqual(command[1:6], ["-NoLogo", "-NoProfile", "-WindowStyle", "Hidden", "-File"])
+            self.assertTrue(command[6].endswith(os.path.join("scripts", "update-windows.ps1")))
+            self.assertEqual(command[7:], [tmp, str(status_path)])
+            self.assertGreater(kwargs["creationflags"], 0)
+            self.assertNotIn("start_new_session", kwargs)
+        else:
+            self.assertTrue(command[0].endswith("/scripts/update"))
+            self.assertEqual(command[1:], [tmp, str(status_path)])
+            self.assertTrue(kwargs["start_new_session"])
         self.assertTrue(kwargs["close_fds"])
         self.assertNotIn(tmp, json.dumps(result))
 
@@ -3803,7 +3836,7 @@ def test_manual_check_cannot_overwrite_an_install_in_progress(self):
 class InstallationTests(unittest.TestCase):
     def test_user_installer_waits_for_both_supervised_runtime_jobs_and_returns_control(self):
         root = Path(__file__).resolve().parents[1]
-        script = (root / "scripts" / "install").read_text()
+        script = (root / "scripts" / "install").read_text(encoding="utf-8")
         server_start = script.index(
             '"$INSTALL_ROOT/scripts/install-launch-agent" server-only'
         )
@@ -3842,7 +3875,7 @@ def test_user_installer_waits_for_both_supervised_runtime_jobs_and_returns_contr
 
     def test_update_helper_requires_clean_fast_forward_then_reuses_installer(self):
         root = Path(__file__).resolve().parents[1]
-        script = (root / "scripts" / "update").read_text()
+        script = (root / "scripts" / "update").read_text(encoding="utf-8")
         self.assertIn("git -C \"$SOURCE_ROOT\" fetch --quiet --prune --no-tags", script)
         self.assertIn("git -C \"$SOURCE_ROOT\" status --porcelain", script)
         self.assertIn("git -C \"$SOURCE_ROOT\" merge --ff-only '@{upstream}'", script)
@@ -3855,7 +3888,7 @@ def test_update_helper_requires_clean_fast_forward_then_reuses_installer(self):
 
     def test_launch_agents_supervise_server_and_menu_bar_independently(self):
         root = Path(__file__).resolve().parents[1]
-        script = (root / "scripts" / "install-launch-agent").read_text()
+        script = (root / "scripts" / "install-launch-agent").read_text(encoding="utf-8")
         self.assertIn('SERVER_LABEL="com.token-meter.server"', script)
         self.assertIn('MENUBAR_LABEL="com.token-meter.menubar"', script)
         self.assertIn("<string>$SERVER_PROGRAM</string>", script)
@@ -3878,7 +3911,7 @@ def test_launch_agents_supervise_server_and_menu_bar_independently(self):
 
     def test_foreground_launcher_waits_for_indexing_before_starting_menubar(self):
         root = Path(__file__).resolve().parents[1]
-        script = (root / "scripts" / "start-token-meter").read_text()
+        script = (root / "scripts" / "start-token-meter").read_text(encoding="utf-8")
         readiness_check = script.index('"state_ready": true')
         menubar_start = script.index('exec "$ROOT/scripts/run-menubar"')
         self.assertLess(readiness_check, menubar_start)
@@ -3888,18 +3921,47 @@ def test_foreground_launcher_waits_for_indexing_before_starting_menubar(self):
 
     def test_uninstaller_removes_both_supervised_jobs(self):
         root = Path(__file__).resolve().parents[1]
-        script = (root / "scripts" / "uninstall-launch-agent").read_text()
+        script = (root / "scripts" / "uninstall-launch-agent").read_text(encoding="utf-8")
         self.assertIn('launchctl bootout "gui/$UID/$SERVER_LABEL"', script)
         self.assertIn('launchctl bootout "gui/$UID/$MENUBAR_LABEL"', script)
         self.assertIn('rm -f "$MENUBAR_PLIST" "$SERVER_PLIST"', script)
 
+    def test_windows_installer_stages_runtime_and_registers_per_user_startup(self):
+        root = Path(__file__).resolve().parents[1]
+        installer = (root / "scripts" / "install-windows.ps1").read_text(encoding="utf-8")
+        starter = (root / "scripts" / "start-token-meter.ps1").read_text(encoding="utf-8")
+        uninstaller = (root / "scripts" / "uninstall-windows.ps1").read_text(encoding="utf-8")
+        updater = (root / "scripts" / "update-windows.ps1").read_text(encoding="utf-8")
+        launcher = (root / "scripts" / "run-token-meter-mcp.cmd").read_text(encoding="utf-8")
+
+        self.assertIn('Join-Path $env:LOCALAPPDATA "Token Meter\\runtime"', installer)
+        self.assertIn("HKEY_CURRENT_USER\\Software\\Microsoft\\Windows\\CurrentVersion\\Run", installer)
+        self.assertIn("Get-Command powershell.exe -CommandType Application", installer)
+        self.assertIn('(Split-Path -Leaf $InstallRoot) -ne "runtime"', installer)
+        self.assertIn("the runtime path contains files that do not belong to Token Meter", installer)
+        self.assertIn('$InstallNonce = [Guid]::NewGuid().ToString("N")', installer)
+        self.assertIn('Write-Utf8File (Join-Path $StagingRoot "PYTHON_EXECUTABLE")', installer)
+        self.assertIn('Write-Utf8File (Join-Path $StagingRoot "SOURCE_CHECKOUT")', installer)
+        self.assertIn('& $StartScript -ReadinessTimeoutSeconds', installer)
+        self.assertIn("Token Meter installation complete.", installer)
+        self.assertIn("$Health.state_ready", starter)
+        self.assertIn("$Ready = $true", starter)
+        self.assertIn("if (-not $Ready)", starter)
+        self.assertIn("A different server owns http://127.0.0.1:8722", starter)
+        self.assertIn("Remove-ItemProperty", uninstaller)
+        self.assertIn("merge --ff-only '@{upstream}'", updater)
+        self.assertIn("token_meter_mcp.py", launcher)
+
 
 class AgentAccessTests(unittest.TestCase):
     def test_client_environment_prepends_wrapper_runtime_directory(self):
-        with mock.patch.dict(meter.os.environ, {"PATH": "/usr/bin:/bin"}, clear=False):
-            env = meter.agent_client_environment("/Users/test/.nvm/versions/node/v24/bin/codex")
-        self.assertEqual(env["PATH"].split(":" )[0], "/Users/test/.nvm/versions/node/v24/bin")
-        self.assertIn("/usr/bin", env["PATH"].split(":"))
+        cli_path = "/Users/test/.nvm/versions/node/v24/bin/codex"
+        existing = os.pathsep.join(("/usr/bin", "/bin"))
+        with mock.patch.dict(meter.os.environ, {"PATH": existing}, clear=False):
+            env = meter.agent_client_environment(cli_path)
+        entries = env["PATH"].split(os.pathsep)
+        self.assertEqual(entries[0], os.path.dirname(os.path.abspath(cli_path)))
+        self.assertIn("/usr/bin", entries)
 
     def test_client_environment_keeps_symlink_directory_for_sibling_node(self):
         with tempfile.TemporaryDirectory() as tmp:
@@ -3910,9 +3972,14 @@ def test_client_environment_keeps_symlink_directory_for_sibling_node(self):
             target = target_dir / "codex.js"
             target.write_text("#!/usr/bin/env node\n")
             wrapper = wrapper_dir / "codex"
-            wrapper.symlink_to(target)
+            try:
+                wrapper.symlink_to(target)
+            except OSError as error:
+                if os.name == "nt" and getattr(error, "winerror", None) == 1314:
+                    self.skipTest("Windows Developer Mode is required for unprivileged symlinks")
+                raise
             env = meter.agent_client_environment(str(wrapper))
-        self.assertEqual(env["PATH"].split(":")[0], str(wrapper_dir))
+        self.assertEqual(env["PATH"].split(os.pathsep)[0], str(wrapper_dir))
 
     def test_client_discovery_checks_user_bin_when_service_path_is_minimal(self):
         with tempfile.TemporaryDirectory() as tmp:

From 9a1f37f6f0ecb96c04602572dd075e88206ffa58 Mon Sep 17 00:00:00 2001
From: placey <theaiguy@cisco.com>
Date: Sun, 2 Aug 2026 16:43:03 -0700
Subject: [PATCH 2/5] Handle clean Windows reinstall

---
 scripts/install-windows.ps1 | 6 ++++--
 tests/test_meter.py         | 1 +
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/scripts/install-windows.ps1 b/scripts/install-windows.ps1
index a22ea2c..d607975 100644
--- a/scripts/install-windows.ps1
+++ b/scripts/install-windows.ps1
@@ -255,8 +255,10 @@ Write-Utf8File (Join-Path $StagingRoot "PYTHON_WINDOWED_EXECUTABLE") ($PythonwEx
 
 $Commit = (& $Git.Source -C $SourceRoot rev-parse --short HEAD 2>$null | Out-String).Trim()
 if ($Commit) {
-    $DirtyPaths = @(& $Git.Source -C $SourceRoot status --short --untracked-files=all 2>$null) |
-        Where-Object { $_ -and $_ -notmatch '^\?\? plan\.md$' }
+    $DirtyPaths = @(
+        & $Git.Source -C $SourceRoot status --short --untracked-files=all 2>$null |
+            Where-Object { $_ -and $_ -notmatch '^\?\? plan\.md$' }
+    )
     if ($DirtyPaths.Count -gt 0) {
         $Commit = "$Commit+local"
     }
diff --git a/tests/test_meter.py b/tests/test_meter.py
index 73ee5aa..0879bfd 100644
--- a/tests/test_meter.py
+++ b/tests/test_meter.py
@@ -3940,6 +3940,7 @@ def test_windows_installer_stages_runtime_and_registers_per_user_startup(self):
         self.assertIn('(Split-Path -Leaf $InstallRoot) -ne "runtime"', installer)
         self.assertIn("the runtime path contains files that do not belong to Token Meter", installer)
         self.assertIn('$InstallNonce = [Guid]::NewGuid().ToString("N")', installer)
+        self.assertIn("$DirtyPaths = @(", installer)
         self.assertIn('Write-Utf8File (Join-Path $StagingRoot "PYTHON_EXECUTABLE")', installer)
         self.assertIn('Write-Utf8File (Join-Path $StagingRoot "SOURCE_CHECKOUT")', installer)
         self.assertIn('& $StartScript -ReadinessTimeoutSeconds', installer)

From 188a4bb5b329dc1104b385ed7a329f8a982589d2 Mon Sep 17 00:00:00 2001
From: placey <theaiguy@cisco.com>
Date: Sun, 2 Aug 2026 17:17:18 -0700
Subject: [PATCH 3/5] Add Windows system tray widget

---
 CONTRIBUTING.md               |  14 +-
 README.md                     |  35 ++--
 scripts/install-windows.ps1   |  44 +++++
 scripts/run-tray.ps1          | 337 ++++++++++++++++++++++++++++++++++
 scripts/start-token-meter.ps1 |  72 ++++++++
 scripts/uninstall-windows.ps1 |  22 ++-
 tests/test_meter.py           |  36 ++++
 7 files changed, 538 insertions(+), 22 deletions(-)
 create mode 100644 scripts/run-tray.ps1

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index cc887b5..d2c710d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -53,8 +53,9 @@ pwsh -NoProfile -File .\scripts\install-windows.ps1
 ```
 
 This stages the browser dashboard under `%LOCALAPPDATA%\Token Meter\runtime`
-and registers automatic startup for the current user. The AppKit menu-bar
-companion is macOS-only.
+and registers automatic startup for the server and Windows system-tray widget.
+The AppKit menu-bar companion is macOS-only; the Windows companion uses the
+built-in PowerShell and WinForms runtime.
 
 The macOS installer starts the local server and menu bar companion. Open
 [http://localhost:8722](http://localhost:8722) and check its health with:
@@ -122,8 +123,9 @@ the PowerShell scripts, and exercise the Windows installer:
 python -m py_compile meter.py token_meter_mcp.py
 python -m unittest discover -s tests -v
 node -e "const fs=require('fs'); const html=fs.readFileSync('page.html','utf8'); const m=html.match(/<script>([\s\S]*)<\/script>/); new Function(m[1]); console.log('js ok')"
-$files = 'scripts/install-windows.ps1','scripts/start-token-meter.ps1','scripts/uninstall-windows.ps1','scripts/update-windows.ps1'
+$files = 'scripts/install-windows.ps1','scripts/start-token-meter.ps1','scripts/run-tray.ps1','scripts/uninstall-windows.ps1','scripts/update-windows.ps1'
 $files | ForEach-Object { $tokens=$null; $errors=$null; [System.Management.Automation.Language.Parser]::ParseFile((Resolve-Path $_),[ref]$tokens,[ref]$errors) | Out-Null; if ($errors) { throw $errors } }
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\run-tray.ps1 -SmokeTest
 pwsh -NoProfile -File .\scripts\install-windows.ps1
 ```
 
@@ -134,9 +136,9 @@ swiftc menubar/TokenMeterMenuBar.swift -o /private/tmp/token-meter-menubar
 TOKEN_METER_MENUBAR_SMOKE=1 /private/tmp/token-meter-menubar
 ```
 
-For visible dashboard or menu bar changes, test the behavior in the running app
-and include a screenshot. If you cannot run a check—for example, because the
-Swift toolchain is unavailable—say so in the pull request.
+For visible dashboard, menu bar, or tray changes, test the behavior in the
+running app and include a screenshot. If you cannot run a check—for example,
+because the Swift toolchain is unavailable—say so in the pull request.
 
 ## Pull request checklist
 
diff --git a/README.md b/README.md
index 1f5ef6a..22fe795 100644
--- a/README.md
+++ b/README.md
@@ -61,12 +61,13 @@ pwsh -NoProfile -File .\token-meter\scripts\install-windows.ps1
 
 The Windows installer stages the runtime under
 `%LOCALAPPDATA%\Token Meter\runtime`, starts the local server without a console
-window, and registers a per-user login startup entry. Windows uses the browser
-dashboard; the native AppKit menu-bar companion remains macOS-only.
+window, starts a Windows system-tray widget, and registers one per-user login
+startup entry for both processes. The AppKit menu-bar companion remains
+macOS-only; Windows uses its own built-in `NotifyIcon` companion.
 
 Token Meter starts its local server automatically after installation and after
-future logins. On macOS, it also starts the menu bar widget. Open the dashboard
-at:
+future logins. It also starts the menu bar widget on macOS or the system-tray
+widget on Windows. Open the dashboard at:
 
 ```text
 http://localhost:8722
@@ -213,8 +214,9 @@ observation establishes a baseline and never sends a catch-up notification.
   HTTP client.
 
 The web dashboard has no third-party Python packages. `meter.py` uses only the
-Python standard library. The installed Windows experience uses the browser
-dashboard, while macOS also includes the menu-bar companion.
+Python standard library. The Windows tray uses the Windows PowerShell and
+WinForms components included with Windows; the macOS menu-bar companion uses
+AppKit.
 
 ## Ask From Codex Or Claude
 
@@ -300,9 +302,9 @@ either process independently if it exits. Remove both login items with:
 "$HOME/Library/Application Support/Token Meter/runtime/scripts/uninstall-launch-agent"
 ```
 
-On Windows, the installer registers the server in the current user's `Run`
-key. Remove that startup entry and stop the server while retaining the staged
-runtime with:
+On Windows, the installer registers a launcher for the server and tray widget in
+the current user's `Run` key. Remove that startup entry and stop both processes
+while retaining the staged runtime with:
 
 ```powershell
 & "$env:LOCALAPPDATA\Token Meter\runtime\scripts\uninstall-windows.ps1"
@@ -317,12 +319,12 @@ dashboard:
 python3 meter.py
 ```
 
-The menu bar companion polls the local `/menubar` endpoint. Run shows compact
-status for the active log; All and the provider tabs show cached account quota
-snapshots. The Recent sessions section labels each entry as Claude, Codex, or
-Cursor, uses the session title or project as an identifier, and keeps a selected
-pin in macOS preferences. Choose `Follow Latest` to resume automatic tracking.
-The companion does not parse logs or read provider credentials directly.
+The macOS menu bar and Windows tray companions poll the local `/menubar`
+endpoint. The Windows tray tooltip shows compact estimated spend and guidance;
+its menu provides live activity, recent-session selection, dashboard deep
+links, refresh, and quit actions. The macOS companion also shows cached provider
+quota snapshots. Choose `Follow Latest` to resume automatic tracking. Neither
+companion parses logs or reads provider credentials directly.
 
 ## How It Finds Logs
 
@@ -666,8 +668,11 @@ The final command requires at least one supported local Claude, Codex, or Cursor
 |   `-- TokenMeterMenuBar.swift      # native macOS menu bar companion
 |-- scripts/
 |   |-- install                      # install the local runtime and login items
+|   |-- install-windows.ps1          # install the Windows runtime and startup
 |   |-- run-menubar                  # build and run the menu bar companion
+|   |-- run-tray.ps1                 # run the Windows system-tray companion
 |   |-- start-token-meter            # start server if needed, then menu bar
+|   |-- start-token-meter.ps1        # start Windows server and tray
 |   |-- install-launch-agent         # install server and menu login items
 |   `-- uninstall-launch-agent       # remove both macOS login items
 |-- REQUIREMENTS.md                  # product rationale and historical notes
diff --git a/scripts/install-windows.ps1 b/scripts/install-windows.ps1
index d607975..de2f517 100644
--- a/scripts/install-windows.ps1
+++ b/scripts/install-windows.ps1
@@ -59,6 +59,33 @@ function Stop-InstalledServer([string]$RuntimeRoot) {
     Remove-Item -LiteralPath $PidPath -Force -ErrorAction SilentlyContinue
 }
 
+function Stop-InstalledTray([string]$RuntimeRoot) {
+    $PidPath = Join-Path $RuntimeRoot "tray.pid"
+    if (-not (Test-Path -LiteralPath $PidPath -PathType Leaf)) {
+        return
+    }
+    $TrayPid = 0
+    if (-not [int]::TryParse((Get-Content -LiteralPath $PidPath -Raw).Trim(), [ref]$TrayPid)) {
+        Remove-Item -LiteralPath $PidPath -Force
+        return
+    }
+    $Process = Get-CimInstance Win32_Process -Filter "ProcessId = $TrayPid" -ErrorAction SilentlyContinue
+    if (-not $Process) {
+        Remove-Item -LiteralPath $PidPath -Force
+        return
+    }
+    $ExpectedTray = [System.IO.Path]::GetFullPath((Join-Path $RuntimeRoot "scripts\run-tray.ps1"))
+    if ([string]$Process.CommandLine -notlike "*$ExpectedTray*") {
+        Fail "the saved tray process ID belongs to a different program."
+    }
+    Stop-Process -Id $TrayPid -Force
+    try {
+        Wait-Process -Id $TrayPid -Timeout 10 -ErrorAction SilentlyContinue
+    } catch { }
+    Remove-Item -LiteralPath $PidPath -Force -ErrorAction SilentlyContinue
+    Remove-Item -LiteralPath (Join-Path $RuntimeRoot "tray.status.json") -Force -ErrorAction SilentlyContinue
+}
+
 function Copy-Directory([string]$Source, [string]$Destination) {
     New-Item -ItemType Directory -Path $Destination -Force | Out-Null
     Get-ChildItem -LiteralPath $Source -Force | ForEach-Object {
@@ -149,6 +176,7 @@ $RequiredPaths = @(
     "token_meter_mcp.py",
     "scripts\install-windows.ps1",
     "scripts\start-token-meter.ps1",
+    "scripts\run-tray.ps1",
     "scripts\uninstall-windows.ps1",
     "scripts\update-windows.ps1",
     "scripts\run-token-meter-mcp.cmd"
@@ -277,6 +305,7 @@ if (Test-Path -LiteralPath $RunKey) {
 $Swapped = $false
 try {
     if (Test-Path -LiteralPath $InstallRoot) {
+        Stop-InstalledTray $InstallRoot
         Stop-InstalledServer $InstallRoot
         Move-Item -LiteralPath $InstallRoot -Destination $BackupRoot
     }
@@ -302,6 +331,19 @@ try {
         Fail "a different Token Meter installation owns port 8722."
     }
     $null = Invoke-RestMethod -Uri "http://127.0.0.1:8722/menubar" -TimeoutSec 5
+    $TrayStatusPath = Join-Path $InstallRoot "tray.status.json"
+    if (-not (Test-Path -LiteralPath $TrayStatusPath -PathType Leaf)) {
+        Fail "the Windows tray widget did not publish its status."
+    }
+    $TrayStatus = Get-Content -LiteralPath $TrayStatusPath -Raw | ConvertFrom-Json
+    if (-not $TrayStatus.ready -or -not $TrayStatus.connected) {
+        Fail "the Windows tray widget did not become ready."
+    }
+    $TrayProcess = Get-CimInstance Win32_Process -Filter "ProcessId = $([int]$TrayStatus.pid)" -ErrorAction SilentlyContinue
+    $ExpectedTray = [System.IO.Path]::GetFullPath((Join-Path $InstallRoot "scripts\run-tray.ps1"))
+    if (-not $TrayProcess -or [string]$TrayProcess.CommandLine -notlike "*$ExpectedTray*") {
+        Fail "the Windows tray widget process could not be verified."
+    }
     $SavedRunValue = (Get-ItemProperty -LiteralPath $RunKey -Name $RunName).$RunName
     if ($SavedRunValue -ne $StartupCommand) {
         Fail "automatic login startup could not be verified."
@@ -312,6 +354,7 @@ try {
     }
 } catch {
     if ($Swapped -and (Test-Path -LiteralPath $InstallRoot)) {
+        try { Stop-InstalledTray $InstallRoot } catch { }
         try { Stop-InstalledServer $InstallRoot } catch { }
         Remove-Item -LiteralPath $InstallRoot -Recurse -Force -ErrorAction SilentlyContinue
     }
@@ -334,6 +377,7 @@ $PythonArchitecture = (& $PythonExe -c "import platform; print(platform.machine(
 Write-Host ""
 Write-Host "Token Meter installation complete."
 Write-Host "Dashboard: http://127.0.0.1:8722"
+Write-Host "Tray widget: running"
 Write-Host "Starts automatically after you log in."
 Write-Host "Runtime: $InstallRoot"
 Write-Host "Python: $PythonExe ($PythonArchitecture)"
diff --git a/scripts/run-tray.ps1 b/scripts/run-tray.ps1
new file mode 100644
index 0000000..4c1a62c
--- /dev/null
+++ b/scripts/run-tray.ps1
@@ -0,0 +1,337 @@
+[CmdletBinding()]
+param(
+    [switch]$SmokeTest
+)
+
+$ErrorActionPreference = "Stop"
+Set-StrictMode -Version Latest
+
+if ($env:OS -ne "Windows_NT") {
+    throw "The Token Meter tray requires Windows."
+}
+
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+
+function Limit-Text([string]$Value, [int]$Maximum) {
+    $Value = ([string]$Value -replace '\s+', ' ').Trim()
+    if ($Value.Length -le $Maximum) {
+        return $Value
+    }
+    return $Value.Substring(0, [Math]::Max(0, $Maximum - 3)) + "..."
+}
+
+function Get-Value($Object, [string]$Name, $Default = $null) {
+    if ($null -eq $Object) {
+        return $Default
+    }
+    $Property = $Object.PSObject.Properties[$Name]
+    if ($null -eq $Property -or $null -eq $Property.Value) {
+        return $Default
+    }
+    return $Property.Value
+}
+
+function Format-CompactNumber($Value) {
+    $Number = 0.0
+    if (-not [double]::TryParse(
+        [string]$Value,
+        [System.Globalization.NumberStyles]::Any,
+        [System.Globalization.CultureInfo]::InvariantCulture,
+        [ref]$Number
+    )) {
+        return "0"
+    }
+    if ($Number -ge 1000000) {
+        return ($Number / 1000000).ToString("0.0M", [System.Globalization.CultureInfo]::InvariantCulture)
+    }
+    if ($Number -ge 1000) {
+        return ($Number / 1000).ToString("0.0K", [System.Globalization.CultureInfo]::InvariantCulture)
+    }
+    return $Number.ToString("0", [System.Globalization.CultureInfo]::InvariantCulture)
+}
+
+function Format-TrayText($State) {
+    if (-not $State -or -not [bool](Get-Value $State "ok" $false)) {
+        return "Token Meter - waiting for the local server"
+    }
+    $Cost = 0.0
+    [double]::TryParse(
+        [string](Get-Value $State "total_cost" 0),
+        [System.Globalization.NumberStyles]::Any,
+        [System.Globalization.CultureInfo]::InvariantCulture,
+        [ref]$Cost
+    ) | Out-Null
+    $Verdict = Get-Value $State "verdict" $null
+    $VerdictLabel = [string](Get-Value $Verdict "label" "Live")
+    return Limit-Text (
+        "Token Meter - `$$($Cost.ToString('0.00', [System.Globalization.CultureInfo]::InvariantCulture)) est - $VerdictLabel"
+    ) 63
+}
+
+function Format-MenuStatus($State) {
+    if (-not $State -or -not [bool](Get-Value $State "ok" $false)) {
+        return "Waiting for local usage data"
+    }
+    $Cost = 0.0
+    [double]::TryParse(
+        [string](Get-Value $State "total_cost" 0),
+        [System.Globalization.NumberStyles]::Any,
+        [System.Globalization.CultureInfo]::InvariantCulture,
+        [ref]$Cost
+    ) | Out-Null
+    $Tokens = Format-CompactNumber (Get-Value $State "total_tokens" 0)
+    return "`$$($Cost.ToString('0.00', [System.Globalization.CultureInfo]::InvariantCulture)) est | $Tokens tokens"
+}
+
+if ($SmokeTest) {
+    $Sample = [pscustomobject]@{
+        ok = $true
+        total_cost = 1.25
+        total_tokens = 125000
+        verdict = [pscustomobject]@{ label = "Healthy" }
+    }
+    $Probe = New-Object System.Windows.Forms.NotifyIcon
+    try {
+        $Probe.Icon = [System.Drawing.SystemIcons]::Information
+        $Probe.Text = Format-TrayText $Sample
+        $Probe.Visible = $true
+        [System.Windows.Forms.Application]::DoEvents()
+        [ordered]@{
+            ok = $Probe.Visible
+            platform = "windows"
+            widget = "NotifyIcon"
+            tooltip = $Probe.Text
+            menu_status = Format-MenuStatus $Sample
+        } | ConvertTo-Json -Compress
+    } finally {
+        $Probe.Visible = $false
+        $Probe.Dispose()
+    }
+    return
+}
+
+$RuntimeRoot = [System.IO.Path]::GetFullPath((Join-Path $PSScriptRoot ".."))
+$PidPath = Join-Path $RuntimeRoot "tray.pid"
+$StatusPath = Join-Path $RuntimeRoot "tray.status.json"
+$script:BaseUrl = "http://127.0.0.1:8722"
+$script:SelectedSessionId = ""
+$script:LastState = $null
+$script:Connected = $false
+
+function Write-TrayStatus([bool]$Ready, [bool]$Connected) {
+    $Record = [ordered]@{
+        ready = $Ready
+        connected = $Connected
+        pid = $PID
+        updated_at = [DateTimeOffset]::UtcNow.ToUnixTimeSeconds()
+    }
+    $Temporary = "$StatusPath.tmp-$PID"
+    [System.IO.File]::WriteAllText(
+        $Temporary,
+        (($Record | ConvertTo-Json -Compress) + [Environment]::NewLine),
+        [System.Text.UTF8Encoding]::new($false)
+    )
+    Move-Item -LiteralPath $Temporary -Destination $StatusPath -Force
+}
+
+function Open-TokenMeterUrl([string]$Url) {
+    Start-Process -FilePath $Url | Out-Null
+}
+
+function Current-DashboardUrl {
+    if ($script:SelectedSessionId) {
+        $Escaped = [Uri]::EscapeDataString($script:SelectedSessionId)
+        return "$($script:BaseUrl)/sessions/$Escaped#summary"
+    }
+    return "$($script:BaseUrl)/#sessions"
+}
+
+function Select-RecentSession($Sender) {
+    $script:SelectedSessionId = [string]$Sender.Tag
+    Invoke-TrayRefresh
+}
+
+function Follow-LatestSession {
+    $script:SelectedSessionId = ""
+    Invoke-TrayRefresh
+}
+
+function Update-RecentSessions($State) {
+    $script:RecentMenu.DropDownItems.Clear()
+
+    $Follow = New-Object System.Windows.Forms.ToolStripMenuItem
+    $Follow.Text = "Follow latest"
+    $Follow.Checked = -not [bool]$script:SelectedSessionId
+    $Follow.add_Click({ Follow-LatestSession })
+    $script:RecentMenu.DropDownItems.Add($Follow) | Out-Null
+    $script:RecentMenu.DropDownItems.Add((New-Object System.Windows.Forms.ToolStripSeparator)) | Out-Null
+
+    $Rows = @(Get-Value $State "recent_sessions" @())
+    if ($Rows.Count -eq 0) {
+        $Empty = New-Object System.Windows.Forms.ToolStripMenuItem
+        $Empty.Text = "No recent sessions"
+        $Empty.Enabled = $false
+        $script:RecentMenu.DropDownItems.Add($Empty) | Out-Null
+        return
+    }
+
+    foreach ($Row in $Rows) {
+        $Id = [string](Get-Value $Row "id" "")
+        if (-not $Id) {
+            continue
+        }
+        $Label = [string](Get-Value $Row "label" "Session")
+        $Name = [string](Get-Value $Row "name" "Untitled")
+        $Item = New-Object System.Windows.Forms.ToolStripMenuItem
+        $Item.Text = Limit-Text "$Label - $Name" 80
+        $Item.Tag = $Id
+        $Item.Checked = $script:SelectedSessionId -eq $Id
+        $Item.add_Click({ Select-RecentSession $this })
+        $script:RecentMenu.DropDownItems.Add($Item) | Out-Null
+    }
+}
+
+function Update-TrayMenu($State) {
+    $script:NotifyIcon.Text = Format-TrayText $State
+    $script:StatusItem.Text = Format-MenuStatus $State
+
+    $Recommendation = Get-Value $State "recommendation" $null
+    $RecommendationLabel = [string](Get-Value $Recommendation "label" "Waiting for guidance")
+    $script:GuidanceItem.Text = Limit-Text "Guidance: $RecommendationLabel" 100
+
+    $Activity = Get-Value $State "activity" $null
+    $ActivityTitle = [string](Get-Value $Activity "title" "Waiting for activity")
+    $script:ActivityItem.Text = Limit-Text "Activity: $ActivityTitle" 100
+
+    Update-RecentSessions $State
+}
+
+function Invoke-TrayRefresh {
+    try {
+        $Url = "$($script:BaseUrl)/menubar"
+        if ($script:SelectedSessionId) {
+            $Url += "?id=$([Uri]::EscapeDataString($script:SelectedSessionId))"
+        }
+        $State = Invoke-RestMethod -Uri $Url -TimeoutSec 4
+        $Selection = Get-Value $State "selection" $null
+        if ([bool](Get-Value $Selection "missing" $false)) {
+            $script:SelectedSessionId = ""
+            $State = Invoke-RestMethod -Uri "$($script:BaseUrl)/menubar" -TimeoutSec 4
+        }
+        $script:LastState = $State
+        $script:Connected = $true
+        Update-TrayMenu $State
+    } catch {
+        $script:Connected = $false
+        $script:NotifyIcon.Text = "Token Meter - local server unavailable"
+        $script:StatusItem.Text = "Local server unavailable"
+        $script:GuidanceItem.Text = "Guidance: reconnecting"
+        $script:ActivityItem.Text = "Activity: unavailable"
+    }
+    Write-TrayStatus $true $script:Connected
+}
+
+$CreatedNew = $false
+$Mutex = New-Object System.Threading.Mutex($true, "Local\TokenMeterTray", [ref]$CreatedNew)
+if (-not $CreatedNew) {
+    $Mutex.Dispose()
+    exit 0
+}
+
+[System.Windows.Forms.Application]::EnableVisualStyles()
+$script:NotifyIcon = New-Object System.Windows.Forms.NotifyIcon
+$script:NotifyIcon.Icon = [System.Drawing.SystemIcons]::Information
+$script:NotifyIcon.Text = "Token Meter - starting"
+$script:NotifyIcon.Visible = $true
+
+$Menu = New-Object System.Windows.Forms.ContextMenuStrip
+$TitleItem = New-Object System.Windows.Forms.ToolStripMenuItem
+$TitleItem.Text = "Token Meter"
+$TitleItem.Enabled = $false
+$TitleItem.Font = New-Object System.Drawing.Font($TitleItem.Font, [System.Drawing.FontStyle]::Bold)
+$Menu.Items.Add($TitleItem) | Out-Null
+
+$script:StatusItem = New-Object System.Windows.Forms.ToolStripMenuItem
+$script:StatusItem.Text = "Waiting for local usage data"
+$script:StatusItem.Enabled = $false
+$Menu.Items.Add($script:StatusItem) | Out-Null
+
+$script:GuidanceItem = New-Object System.Windows.Forms.ToolStripMenuItem
+$script:GuidanceItem.Text = "Guidance: loading"
+$script:GuidanceItem.Enabled = $false
+$Menu.Items.Add($script:GuidanceItem) | Out-Null
+
+$script:ActivityItem = New-Object System.Windows.Forms.ToolStripMenuItem
+$script:ActivityItem.Text = "Activity: loading"
+$script:ActivityItem.Enabled = $false
+$Menu.Items.Add($script:ActivityItem) | Out-Null
+$Menu.Items.Add((New-Object System.Windows.Forms.ToolStripSeparator)) | Out-Null
+
+$OpenDashboard = New-Object System.Windows.Forms.ToolStripMenuItem
+$OpenDashboard.Text = "Open dashboard"
+$OpenDashboard.add_Click({ Open-TokenMeterUrl (Current-DashboardUrl) })
+$Menu.Items.Add($OpenDashboard) | Out-Null
+
+$OpenDaily = New-Object System.Windows.Forms.ToolStripMenuItem
+$OpenDaily.Text = "Open daily brief"
+$OpenDaily.add_Click({ Open-TokenMeterUrl "$($script:BaseUrl)/#daily" })
+$Menu.Items.Add($OpenDaily) | Out-Null
+
+$OpenBudgets = New-Object System.Windows.Forms.ToolStripMenuItem
+$OpenBudgets.Text = "Open monthly budgets"
+$OpenBudgets.add_Click({ Open-TokenMeterUrl "$($script:BaseUrl)/#settings-budgets" })
+$Menu.Items.Add($OpenBudgets) | Out-Null
+
+$script:RecentMenu = New-Object System.Windows.Forms.ToolStripMenuItem
+$script:RecentMenu.Text = "Recent sessions"
+$Menu.Items.Add($script:RecentMenu) | Out-Null
+$Menu.Items.Add((New-Object System.Windows.Forms.ToolStripSeparator)) | Out-Null
+
+$Refresh = New-Object System.Windows.Forms.ToolStripMenuItem
+$Refresh.Text = "Refresh now"
+$Refresh.add_Click({ Invoke-TrayRefresh })
+$Menu.Items.Add($Refresh) | Out-Null
+
+$Quit = New-Object System.Windows.Forms.ToolStripMenuItem
+$Quit.Text = "Quit tray widget"
+$Quit.add_Click({ $script:Context.ExitThread() })
+$Menu.Items.Add($Quit) | Out-Null
+
+$script:NotifyIcon.ContextMenuStrip = $Menu
+$script:NotifyIcon.add_DoubleClick({ Open-TokenMeterUrl (Current-DashboardUrl) })
+$Menu.add_Opening({ Invoke-TrayRefresh })
+
+$Timer = New-Object System.Windows.Forms.Timer
+$Timer.Interval = 10000
+$Timer.add_Tick({ Invoke-TrayRefresh })
+$script:Context = New-Object System.Windows.Forms.ApplicationContext
+
+try {
+    [System.IO.File]::WriteAllText($PidPath, "$PID`r`n", [System.Text.UTF8Encoding]::new($false))
+    Invoke-TrayRefresh
+    $Timer.Start()
+    [System.Windows.Forms.Application]::Run($script:Context)
+} finally {
+    $Timer.Stop()
+    $Timer.Dispose()
+    $script:NotifyIcon.Visible = $false
+    $script:NotifyIcon.Dispose()
+    $Menu.Dispose()
+    $script:Context.Dispose()
+    foreach ($Path in @($PidPath, $StatusPath)) {
+        if (Test-Path -LiteralPath $Path -PathType Leaf) {
+            $SavedPid = 0
+            $Value = if ($Path -eq $PidPath) {
+                (Get-Content -LiteralPath $Path -Raw).Trim()
+            } else {
+                try { [string](Get-Value (Get-Content -LiteralPath $Path -Raw | ConvertFrom-Json) "pid" 0) } catch { "0" }
+            }
+            if ([int]::TryParse($Value, [ref]$SavedPid) -and $SavedPid -eq $PID) {
+                Remove-Item -LiteralPath $Path -Force -ErrorAction SilentlyContinue
+            }
+        }
+    }
+    $Mutex.ReleaseMutex()
+    $Mutex.Dispose()
+}
diff --git a/scripts/start-token-meter.ps1 b/scripts/start-token-meter.ps1
index 32a2992..03d204d 100644
--- a/scripts/start-token-meter.ps1
+++ b/scripts/start-token-meter.ps1
@@ -33,6 +33,11 @@ $WindowedPythonRecord = Join-Path $RuntimeRoot "PYTHON_WINDOWED_EXECUTABLE"
 $PidPath = Join-Path $RuntimeRoot "meter.pid"
 $OutputLog = Join-Path $RuntimeRoot "meter.log"
 $ErrorLog = Join-Path $RuntimeRoot "meter.err.log"
+$TrayScript = [System.IO.Path]::GetFullPath((Join-Path $RuntimeRoot "scripts\run-tray.ps1"))
+$TrayPidPath = Join-Path $RuntimeRoot "tray.pid"
+$TrayStatusPath = Join-Path $RuntimeRoot "tray.status.json"
+$TrayOutputLog = Join-Path $RuntimeRoot "tray.log"
+$TrayErrorLog = Join-Path $RuntimeRoot "tray.err.log"
 
 if ($ReadinessTimeoutSeconds -le 0) {
     $ConfiguredTimeout = 0
@@ -123,3 +128,70 @@ do {
 if (-not $Ready) {
     throw "Token Meter did not finish indexing within $ReadinessTimeoutSeconds seconds."
 }
+
+if (-not (Test-Path -LiteralPath $TrayScript -PathType Leaf)) {
+    throw "Token Meter's Windows tray launcher is missing. Reinstall Token Meter."
+}
+
+$TrayProcess = $null
+if (Test-Path -LiteralPath $TrayPidPath -PathType Leaf) {
+    $SavedTrayPid = 0
+    if ([int]::TryParse((Get-Content -LiteralPath $TrayPidPath -Raw).Trim(), [ref]$SavedTrayPid)) {
+        $SavedTrayProcess = Get-CimInstance Win32_Process -Filter "ProcessId = $SavedTrayPid" -ErrorAction SilentlyContinue
+        if ($SavedTrayProcess) {
+            if ([string]$SavedTrayProcess.CommandLine -notlike "*$TrayScript*") {
+                throw "The saved tray process ID belongs to a different program."
+            }
+            $TrayProcess = Get-Process -Id $SavedTrayPid -ErrorAction SilentlyContinue
+        }
+    }
+    if (-not $TrayProcess) {
+        Remove-Item -LiteralPath $TrayPidPath -Force -ErrorAction SilentlyContinue
+        Remove-Item -LiteralPath $TrayStatusPath -Force -ErrorAction SilentlyContinue
+    }
+}
+
+if (-not $TrayProcess) {
+    $PowerShellCommand = Get-Command powershell.exe -CommandType Application -ErrorAction Stop
+    $TrayProcess = Start-Process -FilePath $PowerShellCommand.Source `
+        -ArgumentList @(
+            "-NoLogo",
+            "-NoProfile",
+            "-STA",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-File",
+            "`"$TrayScript`""
+        ) `
+        -WorkingDirectory $RuntimeRoot `
+        -RedirectStandardOutput $TrayOutputLog `
+        -RedirectStandardError $TrayErrorLog `
+        -WindowStyle Hidden `
+        -PassThru
+}
+
+$TrayDeadline = [DateTime]::UtcNow.AddSeconds(20)
+$TrayReady = $false
+do {
+    $TrayProcess.Refresh()
+    if ($TrayProcess.HasExited) {
+        $TrayDetail = if (Test-Path -LiteralPath $TrayErrorLog -PathType Leaf) {
+            (Get-Content -LiteralPath $TrayErrorLog -Tail 20 | Out-String).Trim()
+        } else { "" }
+        throw "Token Meter's tray widget exited before becoming ready. $TrayDetail"
+    }
+    if (Test-Path -LiteralPath $TrayStatusPath -PathType Leaf) {
+        try {
+            $TrayStatus = Get-Content -LiteralPath $TrayStatusPath -Raw | ConvertFrom-Json
+            if ($TrayStatus.ready -and $TrayStatus.connected -and [int]$TrayStatus.pid -eq $TrayProcess.Id) {
+                $TrayReady = $true
+                break
+            }
+        } catch { }
+    }
+    Start-Sleep -Milliseconds 250
+} while ([DateTime]::UtcNow -lt $TrayDeadline)
+
+if (-not $TrayReady) {
+    throw "Token Meter's tray widget did not connect to the local server."
+}
diff --git a/scripts/uninstall-windows.ps1 b/scripts/uninstall-windows.ps1
index 51de1a6..159eb54 100644
--- a/scripts/uninstall-windows.ps1
+++ b/scripts/uninstall-windows.ps1
@@ -31,6 +31,26 @@ if ($RunValue) {
     Remove-ItemProperty -LiteralPath $RunKey -Name $RunName
 }
 
+$TrayPidPath = Join-Path $InstallRoot "tray.pid"
+if (Test-Path -LiteralPath $TrayPidPath -PathType Leaf) {
+    $TrayPid = 0
+    if ([int]::TryParse((Get-Content -LiteralPath $TrayPidPath -Raw).Trim(), [ref]$TrayPid)) {
+        $TrayProcess = Get-CimInstance Win32_Process -Filter "ProcessId = $TrayPid" -ErrorAction SilentlyContinue
+        $ExpectedTray = [System.IO.Path]::GetFullPath((Join-Path $InstallRoot "scripts\run-tray.ps1"))
+        if ($TrayProcess) {
+            if ([string]$TrayProcess.CommandLine -notlike "*$ExpectedTray*") {
+                throw "The saved tray process ID belongs to a different program."
+            }
+            Stop-Process -Id $TrayPid -Force
+            try {
+                Wait-Process -Id $TrayPid -Timeout 10 -ErrorAction SilentlyContinue
+            } catch { }
+        }
+    }
+    Remove-Item -LiteralPath $TrayPidPath -Force -ErrorAction SilentlyContinue
+    Remove-Item -LiteralPath (Join-Path $InstallRoot "tray.status.json") -Force -ErrorAction SilentlyContinue
+}
+
 $PidPath = Join-Path $InstallRoot "meter.pid"
 if (Test-Path -LiteralPath $PidPath -PathType Leaf) {
     $ServerPid = 0
@@ -50,5 +70,5 @@ if (Test-Path -LiteralPath $PidPath -PathType Leaf) {
     Remove-Item -LiteralPath $PidPath -Force -ErrorAction SilentlyContinue
 }
 
-Write-Host "Token Meter automatic startup removed and the local server stopped."
+Write-Host "Token Meter automatic startup removed; the tray widget and local server stopped."
 Write-Host "Runtime retained at: $InstallRoot"
diff --git a/tests/test_meter.py b/tests/test_meter.py
index 0879bfd..d0a4d42 100644
--- a/tests/test_meter.py
+++ b/tests/test_meter.py
@@ -3930,6 +3930,7 @@ def test_windows_installer_stages_runtime_and_registers_per_user_startup(self):
         root = Path(__file__).resolve().parents[1]
         installer = (root / "scripts" / "install-windows.ps1").read_text(encoding="utf-8")
         starter = (root / "scripts" / "start-token-meter.ps1").read_text(encoding="utf-8")
+        tray = (root / "scripts" / "run-tray.ps1").read_text(encoding="utf-8")
         uninstaller = (root / "scripts" / "uninstall-windows.ps1").read_text(encoding="utf-8")
         updater = (root / "scripts" / "update-windows.ps1").read_text(encoding="utf-8")
         launcher = (root / "scripts" / "run-token-meter-mcp.cmd").read_text(encoding="utf-8")
@@ -3940,6 +3941,8 @@ def test_windows_installer_stages_runtime_and_registers_per_user_startup(self):
         self.assertIn('(Split-Path -Leaf $InstallRoot) -ne "runtime"', installer)
         self.assertIn("the runtime path contains files that do not belong to Token Meter", installer)
         self.assertIn('$InstallNonce = [Guid]::NewGuid().ToString("N")', installer)
+        self.assertIn('"scripts\\run-tray.ps1"', installer)
+        self.assertIn("Stop-InstalledTray $InstallRoot", installer)
         self.assertIn("$DirtyPaths = @(", installer)
         self.assertIn('Write-Utf8File (Join-Path $StagingRoot "PYTHON_EXECUTABLE")', installer)
         self.assertIn('Write-Utf8File (Join-Path $StagingRoot "SOURCE_CHECKOUT")', installer)
@@ -3949,10 +3952,43 @@ def test_windows_installer_stages_runtime_and_registers_per_user_startup(self):
         self.assertIn("$Ready = $true", starter)
         self.assertIn("if (-not $Ready)", starter)
         self.assertIn("A different server owns http://127.0.0.1:8722", starter)
+        self.assertIn("Get-Command powershell.exe -CommandType Application", starter)
+        self.assertIn("$TrayStatus.ready -and $TrayStatus.connected", starter)
+        self.assertIn("System.Windows.Forms.NotifyIcon", tray)
+        self.assertIn('Invoke-RestMethod -Uri $Url -TimeoutSec 4', tray)
+        self.assertIn('"Recent sessions"', tray)
+        self.assertIn('"Quit tray widget"', tray)
         self.assertIn("Remove-ItemProperty", uninstaller)
+        self.assertIn('$ExpectedTray', uninstaller)
         self.assertIn("merge --ff-only '@{upstream}'", updater)
         self.assertIn("token_meter_mcp.py", launcher)
 
+    @unittest.skipUnless(os.name == "nt", "Windows tray smoke test")
+    def test_windows_tray_notify_icon_smoke(self):
+        root = Path(__file__).resolve().parents[1]
+        command = meter.shutil.which("powershell.exe")
+        self.assertTrue(command)
+        result = meter.subprocess.run(
+            [
+                command,
+                "-NoProfile",
+                "-ExecutionPolicy",
+                "Bypass",
+                "-File",
+                str(root / "scripts" / "run-tray.ps1"),
+                "-SmokeTest",
+            ],
+            capture_output=True,
+            text=True,
+            timeout=30,
+            check=False,
+        )
+        self.assertEqual(result.returncode, 0, result.stderr)
+        payload = json.loads(result.stdout)
+        self.assertTrue(payload["ok"])
+        self.assertEqual(payload["widget"], "NotifyIcon")
+        self.assertIn("est", payload["tooltip"])
+
 
 class AgentAccessTests(unittest.TestCase):
     def test_client_environment_prepends_wrapper_runtime_directory(self):

From 21ec41d52ce120369ee89efe14d6abdd5cb7265c Mon Sep 17 00:00:00 2001
From: placey <theaiguy@cisco.com>
Date: Sun, 2 Aug 2026 17:59:19 -0700
Subject: [PATCH 4/5] Fix Windows tray icon and click action

---
 README.md            |   8 +-
 scripts/run-tray.ps1 | 200 ++++++++++++++++++++++++++++++++++++-------
 tests/test_meter.py  |   7 ++
 3 files changed, 182 insertions(+), 33 deletions(-)

diff --git a/README.md b/README.md
index 22fe795..68c3613 100644
--- a/README.md
+++ b/README.md
@@ -322,9 +322,11 @@ python3 meter.py
 The macOS menu bar and Windows tray companions poll the local `/menubar`
 endpoint. The Windows tray tooltip shows compact estimated spend and guidance;
 its menu provides live activity, recent-session selection, dashboard deep
-links, refresh, and quit actions. The macOS companion also shows cached provider
-quota snapshots. Choose `Follow Latest` to resume automatic tracking. Neither
-companion parses logs or reads provider credentials directly.
+links, refresh, and quit actions. Left-click the Token Meter tray icon to open
+the dashboard; right-click it to open the tray menu. The macOS companion also
+shows cached provider quota snapshots. Choose `Follow Latest` to resume
+automatic tracking. Neither companion parses logs or reads provider credentials
+directly.
 
 ## How It Finds Logs
 
diff --git a/scripts/run-tray.ps1 b/scripts/run-tray.ps1
index 4c1a62c..bb6c0df 100644
--- a/scripts/run-tray.ps1
+++ b/scripts/run-tray.ps1
@@ -1,6 +1,7 @@
 [CmdletBinding()]
 param(
-    [switch]$SmokeTest
+    [switch]$SmokeTest,
+    [string]$OpenProbePath = ""
 )
 
 $ErrorActionPreference = "Stop"
@@ -12,6 +13,16 @@ if ($env:OS -ne "Windows_NT") {
 
 Add-Type -AssemblyName System.Windows.Forms
 Add-Type -AssemblyName System.Drawing
+Add-Type -TypeDefinition @"
+using System;
+using System.Runtime.InteropServices;
+
+public static class TokenMeterNativeIcon {
+    [DllImport("user32.dll")]
+    [return: MarshalAs(UnmanagedType.Bool)]
+    public static extern bool DestroyIcon(IntPtr handle);
+}
+"@
 
 function Limit-Text([string]$Value, [int]$Maximum) {
     $Value = ([string]$Value -replace '\s+', ' ').Trim()
@@ -32,6 +43,83 @@ function Get-Value($Object, [string]$Name, $Default = $null) {
     return $Property.Value
 }
 
+function New-TokenMeterIcon {
+    $Bitmap = New-Object System.Drawing.Bitmap(
+        32,
+        32,
+        [System.Drawing.Imaging.PixelFormat]::Format32bppArgb
+    )
+    $Graphics = [System.Drawing.Graphics]::FromImage($Bitmap)
+    $Path = New-Object System.Drawing.Drawing2D.GraphicsPath
+    $Brush = $null
+    $Pen = $null
+    try {
+        $Graphics.SmoothingMode = [System.Drawing.Drawing2D.SmoothingMode]::AntiAlias
+        $Graphics.Clear([System.Drawing.Color]::Transparent)
+
+        $Path.AddArc(0, 0, 14, 14, 180, 90)
+        $Path.AddArc(18, 0, 14, 14, 270, 90)
+        $Path.AddArc(18, 18, 14, 14, 0, 90)
+        $Path.AddArc(0, 18, 14, 14, 90, 90)
+        $Path.CloseFigure()
+
+        $Bounds = New-Object System.Drawing.Rectangle(0, 0, 32, 32)
+        $Brush = New-Object System.Drawing.Drawing2D.LinearGradientBrush(
+            $Bounds,
+            [System.Drawing.Color]::FromArgb(0, 188, 235),
+            [System.Drawing.Color]::FromArgb(127, 219, 242),
+            45.0
+        )
+        $Blend = New-Object System.Drawing.Drawing2D.ColorBlend(3)
+        $Blend.Colors = [System.Drawing.Color[]]@(
+            [System.Drawing.Color]::FromArgb(0, 188, 235),
+            [System.Drawing.Color]::FromArgb(27, 160, 225),
+            [System.Drawing.Color]::FromArgb(127, 219, 242)
+        )
+        $Blend.Positions = [single[]]@(0.0, 0.55, 1.0)
+        $Brush.InterpolationColors = $Blend
+        $Graphics.FillPath($Brush, $Path)
+
+        $Pen = New-Object System.Drawing.Pen(
+            [System.Drawing.Color]::FromArgb(6, 36, 48),
+            2.1
+        )
+        $Pen.StartCap = [System.Drawing.Drawing2D.LineCap]::Round
+        $Pen.EndCap = [System.Drawing.Drawing2D.LineCap]::Round
+        foreach ($Line in @(
+            @(7.0, 18.0, 7.0, 15.0),
+            @(10.0, 18.0, 10.0, 11.0),
+            @(13.0, 18.0, 13.0, 14.0),
+            @(16.0, 18.0, 16.0, 8.0),
+            @(19.0, 18.0, 19.0, 14.0),
+            @(22.0, 18.0, 22.0, 11.0),
+            @(25.0, 18.0, 25.0, 15.0),
+            @(6.5, 22.5, 25.5, 22.5)
+        )) {
+            $Graphics.DrawLine(
+                $Pen,
+                [single]$Line[0],
+                [single]$Line[1],
+                [single]$Line[2],
+                [single]$Line[3]
+            )
+        }
+
+        $Handle = $Bitmap.GetHicon()
+        try {
+            return [System.Drawing.Icon]([System.Drawing.Icon]::FromHandle($Handle).Clone())
+        } finally {
+            [TokenMeterNativeIcon]::DestroyIcon($Handle) | Out-Null
+        }
+    } finally {
+        if ($Pen) { $Pen.Dispose() }
+        if ($Brush) { $Brush.Dispose() }
+        $Path.Dispose()
+        $Graphics.Dispose()
+        $Bitmap.Dispose()
+    }
+}
+
 function Format-CompactNumber($Value) {
     $Number = 0.0
     if (-not [double]::TryParse(
@@ -84,33 +172,6 @@ function Format-MenuStatus($State) {
     return "`$$($Cost.ToString('0.00', [System.Globalization.CultureInfo]::InvariantCulture)) est | $Tokens tokens"
 }
 
-if ($SmokeTest) {
-    $Sample = [pscustomobject]@{
-        ok = $true
-        total_cost = 1.25
-        total_tokens = 125000
-        verdict = [pscustomobject]@{ label = "Healthy" }
-    }
-    $Probe = New-Object System.Windows.Forms.NotifyIcon
-    try {
-        $Probe.Icon = [System.Drawing.SystemIcons]::Information
-        $Probe.Text = Format-TrayText $Sample
-        $Probe.Visible = $true
-        [System.Windows.Forms.Application]::DoEvents()
-        [ordered]@{
-            ok = $Probe.Visible
-            platform = "windows"
-            widget = "NotifyIcon"
-            tooltip = $Probe.Text
-            menu_status = Format-MenuStatus $Sample
-        } | ConvertTo-Json -Compress
-    } finally {
-        $Probe.Visible = $false
-        $Probe.Dispose()
-    }
-    return
-}
-
 $RuntimeRoot = [System.IO.Path]::GetFullPath((Join-Path $PSScriptRoot ".."))
 $PidPath = Join-Path $RuntimeRoot "tray.pid"
 $StatusPath = Join-Path $RuntimeRoot "tray.status.json"
@@ -118,6 +179,7 @@ $script:BaseUrl = "http://127.0.0.1:8722"
 $script:SelectedSessionId = ""
 $script:LastState = $null
 $script:Connected = $false
+$script:OpenProbePath = $OpenProbePath
 
 function Write-TrayStatus([bool]$Ready, [bool]$Connected) {
     $Record = [ordered]@{
@@ -136,6 +198,14 @@ function Write-TrayStatus([bool]$Ready, [bool]$Connected) {
 }
 
 function Open-TokenMeterUrl([string]$Url) {
+    if ($script:OpenProbePath) {
+        [System.IO.File]::WriteAllText(
+            $script:OpenProbePath,
+            $Url,
+            [System.Text.UTF8Encoding]::new($false)
+        )
+        return
+    }
     Start-Process -FilePath $Url | Out-Null
 }
 
@@ -147,6 +217,74 @@ function Current-DashboardUrl {
     return "$($script:BaseUrl)/#sessions"
 }
 
+function Invoke-TrayMouseClick($EventArgs) {
+    if ($EventArgs.Button -eq [System.Windows.Forms.MouseButtons]::Left) {
+        Open-TokenMeterUrl (Current-DashboardUrl)
+    }
+}
+
+if ($SmokeTest) {
+    $Sample = [pscustomobject]@{
+        ok = $true
+        total_cost = 1.25
+        total_tokens = 125000
+        verdict = [pscustomobject]@{ label = "Healthy" }
+    }
+    $OwnProbe = -not [bool]$script:OpenProbePath
+    if ($OwnProbe) {
+        $script:OpenProbePath = Join-Path $env:TEMP "token-meter-tray-click-$PID.txt"
+    }
+    Remove-Item -LiteralPath $script:OpenProbePath -Force -ErrorAction SilentlyContinue
+    $Probe = New-Object System.Windows.Forms.NotifyIcon
+    $ProbeIcon = New-TokenMeterIcon
+    $IconBitmap = $null
+    try {
+        $Probe.Icon = $ProbeIcon
+        $Probe.Text = Format-TrayText $Sample
+        $Probe.add_MouseClick({ Invoke-TrayMouseClick $_ })
+        $Probe.Visible = $true
+        [System.Windows.Forms.Application]::DoEvents()
+
+        $Click = New-Object System.Windows.Forms.MouseEventArgs(
+            [System.Windows.Forms.MouseButtons]::Left,
+            1,
+            0,
+            0,
+            0
+        )
+        $MouseClickMethod = $Probe.GetType().GetMethod(
+            "OnMouseClick",
+            [System.Reflection.BindingFlags]::Instance -bor [System.Reflection.BindingFlags]::NonPublic
+        )
+        $MouseClickMethod.Invoke($Probe, [object[]]@($Click.PSObject.BaseObject)) | Out-Null
+        $OpenedUrl = if (Test-Path -LiteralPath $script:OpenProbePath -PathType Leaf) {
+            (Get-Content -LiteralPath $script:OpenProbePath -Raw).Trim()
+        } else { "" }
+
+        $IconBitmap = $ProbeIcon.ToBitmap()
+        $BrandPixel = $IconBitmap.GetPixel(4, 4)
+        [ordered]@{
+            ok = $Probe.Visible -and $OpenedUrl -eq "$($script:BaseUrl)/#sessions"
+            platform = "windows"
+            widget = "NotifyIcon"
+            icon = "TokenMeterSpectrum"
+            icon_brand_color = $BrandPixel.B -gt 100 -and $BrandPixel.G -gt 100
+            left_click_url = $OpenedUrl
+            tooltip = $Probe.Text
+            menu_status = Format-MenuStatus $Sample
+        } | ConvertTo-Json -Compress
+    } finally {
+        $Probe.Visible = $false
+        $Probe.Dispose()
+        if ($IconBitmap) { $IconBitmap.Dispose() }
+        $ProbeIcon.Dispose()
+        if ($OwnProbe) {
+            Remove-Item -LiteralPath $script:OpenProbePath -Force -ErrorAction SilentlyContinue
+        }
+    }
+    return
+}
+
 function Select-RecentSession($Sender) {
     $script:SelectedSessionId = [string]$Sender.Tag
     Invoke-TrayRefresh
@@ -241,7 +379,8 @@ if (-not $CreatedNew) {
 
 [System.Windows.Forms.Application]::EnableVisualStyles()
 $script:NotifyIcon = New-Object System.Windows.Forms.NotifyIcon
-$script:NotifyIcon.Icon = [System.Drawing.SystemIcons]::Information
+$script:TrayIcon = New-TokenMeterIcon
+$script:NotifyIcon.Icon = $script:TrayIcon
 $script:NotifyIcon.Text = "Token Meter - starting"
 $script:NotifyIcon.Visible = $true
 
@@ -299,7 +438,7 @@ $Quit.add_Click({ $script:Context.ExitThread() })
 $Menu.Items.Add($Quit) | Out-Null
 
 $script:NotifyIcon.ContextMenuStrip = $Menu
-$script:NotifyIcon.add_DoubleClick({ Open-TokenMeterUrl (Current-DashboardUrl) })
+$script:NotifyIcon.add_MouseClick({ Invoke-TrayMouseClick $_ })
 $Menu.add_Opening({ Invoke-TrayRefresh })
 
 $Timer = New-Object System.Windows.Forms.Timer
@@ -317,6 +456,7 @@ try {
     $Timer.Dispose()
     $script:NotifyIcon.Visible = $false
     $script:NotifyIcon.Dispose()
+    $script:TrayIcon.Dispose()
     $Menu.Dispose()
     $script:Context.Dispose()
     foreach ($Path in @($PidPath, $StatusPath)) {
diff --git a/tests/test_meter.py b/tests/test_meter.py
index d0a4d42..5033568 100644
--- a/tests/test_meter.py
+++ b/tests/test_meter.py
@@ -3955,6 +3955,10 @@ def test_windows_installer_stages_runtime_and_registers_per_user_startup(self):
         self.assertIn("Get-Command powershell.exe -CommandType Application", starter)
         self.assertIn("$TrayStatus.ready -and $TrayStatus.connected", starter)
         self.assertIn("System.Windows.Forms.NotifyIcon", tray)
+        self.assertIn("function New-TokenMeterIcon", tray)
+        self.assertNotIn("SystemIcons]::Information", tray)
+        self.assertIn(".add_MouseClick({ Invoke-TrayMouseClick $_ })", tray)
+        self.assertIn("MouseButtons]::Left", tray)
         self.assertIn('Invoke-RestMethod -Uri $Url -TimeoutSec 4', tray)
         self.assertIn('"Recent sessions"', tray)
         self.assertIn('"Quit tray widget"', tray)
@@ -3987,6 +3991,9 @@ def test_windows_tray_notify_icon_smoke(self):
         payload = json.loads(result.stdout)
         self.assertTrue(payload["ok"])
         self.assertEqual(payload["widget"], "NotifyIcon")
+        self.assertEqual(payload["icon"], "TokenMeterSpectrum")
+        self.assertTrue(payload["icon_brand_color"])
+        self.assertEqual(payload["left_click_url"], "http://127.0.0.1:8722/#sessions")
         self.assertIn("est", payload["tooltip"])
 
 

From a1295c003123613e6d46099c23eabc475267e81c Mon Sep 17 00:00:00 2001
From: placey <theaiguy@cisco.com>
Date: Sun, 2 Aug 2026 23:08:03 -0700
Subject: [PATCH 5/5] Windows: hide console window on 60s provider quota CLI
 calls

The claude auth-status and codex app-server quota refreshes (every QUOTA_REFRESH_S=60s)
shelled out to the provider CLIs without CREATE_NO_WINDOW, so on Windows a cmd/console
window flashed once a minute. Add a shared _NO_WINDOW creationflag (matching the updater)
and apply it to both calls.
---
 meter.py | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/meter.py b/meter.py
index c580ef9..5d01de2 100644
--- a/meter.py
+++ b/meter.py
@@ -180,6 +180,9 @@ def session_trash_directory(platform=None, environ=None):
 MENUBAR_CONTEXT_INTERVENE_PCT = 0.85
 MENUBAR_COST_SPIKE = 0.50
 QUOTA_REFRESH_S = 60.0
+# Hide the console window that a provider-CLI subprocess would otherwise flash on
+# Windows every refresh cycle. Token Meter runs headless, so these are noise.
+_NO_WINDOW = getattr(subprocess, "CREATE_NO_WINDOW", 0) if os.name == "nt" else 0
 QUOTA_STALE_S = 10 * 60.0
 QUOTA_HTTP_TIMEOUT_S = 8.0
 QUOTA_PROCESS_TIMEOUT_S = 8.0
@@ -9083,6 +9086,7 @@ def codex_app_server_rate_limits(timeout=QUOTA_PROCESS_TIMEOUT_S):
             [executable, "-s", "read-only", "-a", "untrusted", "app-server"],
             stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
             text=True, bufsize=1, env=agent_client_environment(executable),
+            creationflags=_NO_WINDOW,
         )
     except OSError:
         raise QuotaUnavailable("Codex could not start its account quota service.") from None
@@ -9235,6 +9239,7 @@ def claude_auth_status(timeout=3.0):
             [executable, "auth", "status", "--json"], capture_output=True,
             text=True, timeout=timeout, check=False,
             env=agent_client_environment(executable),
+            creationflags=_NO_WINDOW,
         )
         value = json.loads(result.stdout or "{}")
         return value if isinstance(value, dict) else {}