feat: menu bar / system tray companion app (macOS, Windows, Linux)

[VasiHemanth]

Adds a menu bar / system tray companion under src-tauri/. It starts the local
server on login so there is no terminal to keep open, keeps today's spend in the
menu bar, and opens the existing dashboard in the browser.

It is a launcher, not a replacement. Every menu item opens the same web UI —
the trace view in particular is where you backtrack through a whole agent run,
which does not collapse into a dropdown, and keeping it on the web keeps it
reachable from any device.

How it works

It spawns one child, node bin/cli.js, rather than reimplementing venv
creation, the SHA-stamped pip install --require-hashes, npm ci and the port
pre-flight in Rust. That keeps one source of truth for how the services start;
a Rust reimplementation would have been a second one that drifts.

The parts that were easy to get wrong

• Today's figure comes from /analytics?from=<local date>&to=<same>, read
  off total.cost. The date is built from local Y/M/D, and to is a bare
  YYYY-MM-DD because the backend decides whether to merge today's in-flight
  sessions using a lexicographic string compare. by_day is [] on a
  zero-spend day, so total.cost is the only safe field to read.
• Liveness is GET /. Not /version, which shells out to git and makes an
  outbound HTTPS call to api.github.com. Not /budgets, where reading status
  emits persistent notification records.
• Interpreters are resolved through a login shell and stored as absolute
  paths. A login-launched GUI app inherits a minimal PATH, so a bare node
  works under tauri dev from a terminal and fails on the first real login —
  the single most likely way this would have broken in the field.
• It attaches instead of colliding. If a server is already listening it uses
  that one and leaves it running on quit. A server left behind by a previous
  tray process is reaped via a pidfile before the ports are touched, because
  bin/cli.js hard-exits on a busy port and a tray app has no console to print
  that to.
• Config lives in ~/.tokentelemetry/, not Tauri's app_data_dir(), so
  tray state sits beside every other TokenTelemetry file rather than in
  ~/Library/Application Support.
• The reqwest client is built without TLS. This app only ever talks to
  127.0.0.1, and dropping TLS makes an outbound HTTPS call impossible rather
  than merely discouraged.

Platform reality

	Menu bar text	Tooltip
macOS	yes	yes
Windows	no (unsupported by the OS)	yes
Linux	no	no

Tray title text is macOS-only, so the spend figure is the first menu item on
every platform and the title/tooltip are additive. Linux needs
libayatana-appindicator3-1; on stock GNOME there is no tray at all without an
extension, so tray creation failure logs and degrades instead of aborting — it
keeps supervising and still opens the dashboard.

Verification

• total.cost for today matched an independent re-bucketing of /sessions
  by local day to 7e-15 (float summation order): $55.28579432962963 vs
  $55.28579432962964 across 27 sessions.
• The running app polled exactly
  GET /analytics?from=2026-08-02&to=2026-08-02&granularity=day and GET /,
  and nothing else — confirmed in the backend access log.
• cargo fmt --check, cargo clippy --all-targets -- -D warnings, and 9 tests
  pass. The .app and .dmg bundle, with LSUIElement present.

Tested on macOS only. Windows and Linux pass fmt, clippy -D warnings and
the test suite in CI, and a dispatched run produced real installers on all three
(tray-macos-latest 3MB, tray-windows-latest 1MB, tray-ubuntu-22.04 78MB) —
but nobody has run them on Windows or Linux hardware. Builds are unsigned, so
macOS needs right-click → Open and Windows will show a SmartScreen warning.

Also here

• .rs added to the pre-push reviewer's suffix list — without it every Rust
  file in this PR would have shipped past that gate unread.
• src-tauri/target/ and gen/ gitignored. Cargo.lock is committed: this
  is a binary, not a library. That cuts against the repo's npm lockfile
  convention, which exists for the security-audit.yml job, so it is a
  deliberate exception rather than an oversight.
• No @tauri-apps/cli entry in the root package.json — that file is a path
  trigger for security-audit.yml, whose npm ci would fail against the
  current zero-dependency lock. CI drives the bundle through npx instead.

Follow-ups not in this PR

• A Windows Job Object with KILL_ON_JOB_CLOSE would beat the pidfile reap for
  crash cleanup, but it is unsafe code I cannot exercise here.
• Starting the frontend lazily on first "Open dashboard" click would make login
  cheaper; it needs a --no-frontend mode in bin/cli.js to do cleanly.
• Signing and notarization have no precedent in this repo.

---

Review pass (commit 32c3cdb)

A multi-agent adversarial review over the first commit produced 33 candidate
findings; 22 survived an independent refutation pass. Fixed in the follow-up
commit — the ones with a real failure mode:

• Deadlock. refresh_tray held the menu mutex across set_text, which
  dispatches to the main thread and blocks on a reply. A menu click landing in
  that window hung both threads with no timeout.
• The IPv6 port probe never ran. "::1:8000" is not a valid SocketAddr
  (v6 literals need brackets), so the parse failed and the loop silently
  skipped it — the cross-stack check the code claimed to do was never happening.
• reap_stale killed by PID alone. That record survives reboots and PIDs
  get recycled, so it could have SIGTERM'd (or tree-killed, on Windows) an
  unrelated process.
• Windows quit stalled. Graceful taskkill /T only posts WM_CLOSE, which a
  windowless node process can never receive.
• The spend figure survived midnight still labelled "Today".
• The tray icon was invisible off macOS — a black template asset on a dark
  taskbar.
• TOKENTELEMETRY_DATA_DIR was dropped at login, splitting the data store.
• No way to quit without a tray (stock GNOME).
• Plus a single-instance guard, detection moved off the startup path, a
  POSIX-sh fallback for csh/tcsh users, and a CI fix: a paths filter applies
  to tag pushes too, so the release job would never have fired.

Verification of the spawn path

The numeric checks above all ran against attach mode. The spawn half was
exercised separately on macOS, end to end:

• Cold start created the venv, ran the installs and bound both ports.
• tray-runtime.json recorded the real PID; ps confirms it is
  node .../bin/cli.js, in its own process group (so setsid took effect),
  with node resolved to an absolute /opt/homebrew path rather than a bare
  name — which is the whole point of the login-shell probing.
• kill -9 on the tray left cli.js running, as designed.
• Relaunching reaped that orphan and both its children, leaving exactly one
  cli.js — this is the code path that exercises terminate() +
  wait_ports_free() for real.
• SIGTERM frees both ports with nothing left listening.

Not yet exercised: a clean Quit through the tray menu (it needs a click I
can't script), and the Windows/Linux teardown paths.

---

Dropdown panel (commit ae95a58)

Left-click the tray icon opens a 380px panel; the menu moves to right-click. A
native menu can only render text rows, which is why v1 looked sparse next to
what the data already supports.

Shows today's spend as the headline, a 7-day bar chart, tokens / cache-hit /
agent-count tiles, per-agent and per-model breakdowns with share bars, and chips
for skills, MCP servers, subagent types and energy. All of it already existed in
/analytics.

Costs two /analytics calls, issued only when the panel is opened — the 30s
background poll is unchanged. Deliberately avoids /projects (5.3s, all-time)
and /budgets (reading it writes notification records).

A backend bug this works around. The sparkline is built from one multi-day
response rather than seven single-day queries, because a cached single-day query
for 2026-08-02 returned $152.76 while a fresh scan of the same window
returned $6.72. Reproducible, a 22× error: a cache entry built while that
date was still "today" (carrying the live-scan merge) keeps being served as a
historical figure. The multi-day response is internally consistent and agrees
with an independent re-bucketing of /sessions. Worth fixing in the backend on
its own.

Charting: every bar is one hue with identity carried by the text label beside
it, so there is no categorical palette that could fail a colour-vision check.
Today's bar is a darker step of the same hue and the only direct label.

Panel placement on mixed-DPI desktops

Everything macOS reports here — the tray anchor rect, Monitor::position() and
Monitor::size() — is points multiplied by the scale of the monitor it
describes, despite the Physical type name (tao builds all of them with
from_logical(.., scale_factor())). Each value is consistent within its own
monitor but not comparable across monitors of different scale.

On a 2x built-in at (0,0) plus a 1x external to its right, the two displays
therefore overlap in that space, so an anchor's x alone cannot say which screen
it is on. The icon height disambiguates: a menu-bar item is ~22-40pt tall, so
only the correct scale yields a plausible height. An anchor matching nothing —
macOS reports a zero-size rect while the status item is still being drawn —
falls back to the primary display for both the scale and the clamp, so the panel
always lands on a real screen.

The move is applied asynchronously, and reading the position straight back
returns the value from the previous show, so the position is set again after
show().

TT_TRAY_SELFTEST="x,y,w,h;…" replays synthetic anchors through the real
placement path and logs computed vs settled for each; TT_TRAY_DEBUG=1 prints
the read-back on ordinary clicks. Placement depends on the live monitor
arrangement, so it cannot be unit-tested and otherwise needs one click per
display per attempt. Verified 6/6 on a 2x built-in plus a 1x external — both
displays, alternating between them, and both edge clamps.

Note: this workflow stopped running on pushes

Tray app ran on pull_request for the first pushes to this branch and then
stopped firing on later ones, leaving the head commit with no checks at all
despite src-tauri/** changes. Runs triggered by workflow_dispatch still
work, and that is how the cross-platform check was run here. Worth working out
before merge, otherwise tray pushes go unchecked silently.

The poll interval is a CPU decision, not a freshness one

Caught by the machine running hot with the tray installed.

/analytics is served from the backend's session cache, whose TTL is 30s. A
miss runs _scan_sessions_sync across every session of every harness plus a
history write — on a ~1,200 session history that measured 25-35 CPU-seconds.
There is no serve-stale-and-refresh path, so a client polling at or slower than
30s misses every single time, and the poll interval is really "how often do
I force a full rescan".

The original 30s default therefore asked for scans faster than one could finish
and the backend never returned to idle. Measured per 45s of wall clock:

	backend CPU-seconds
tray polling at 30s	56.7 (~126% of a core)
no tray at all (clean 60s baseline)	0

The backend is completely idle otherwise, so this was entirely the tray's doing.

Now: default 300s, a 60s floor, and any value below the floor falls back to the
default rather than the floor — every existing tray.json says 30, so raising
the default alone would have left installs on the old value, and snapping to 60s
would still rescan for a large part of every minute. The relationship between
the interval and the cache TTL is a compile-time assertion, not a test, because
the failure mode is silent: nothing breaks, the machine just gets hot.

Freshness is unaffected in practice — opening the panel always refreshes on the
spot, so the interval only governs the menu bar number while nobody is looking
at it.

Worth fixing in the backend separately: serving stale data while refreshing
in the background would make the cost of a poll proportional to how often the
data actually changes, rather than to how often anyone asks.