Adom Bridge (macOS)

@@ -1,117 +0,0 @@-----name: adom-desktop-presence-description: How Adom Bridge lives quietly on a Mac. Covers the menu-bar agent model (signed-in launches go straight to the menu bar with no window and no Dock icon), summoning the window from the menu-bar item, close-to-menu-bar behavior (the close button hides the window, Bridge keeps serving), launch at login via LaunchAgent (default ON, self-healing), the shared Adom sign-in in the keychain, and the window title markers. Use when a user or AI asks why Bridge is still running after closing the window, where the app went after launch, why there is no Dock icon, how to enable or disable launch at login, why the menu-bar item is missing, or what the window title markers mean.------# Adom Bridge presence: menu-bar agent, hidden window, launch at login--Adom Bridge is a menu-bar agent (since 1.9.186). Its window is hidden most of-its life; the working core is a small native (Rust) process that keeps serving-the relay, direct API, bridges, notifications, and approvals whether or not the-window is on screen.--## The menu-bar agent model--- A SIGNED-IN standalone launch goes straight to the menu bar: no window, and-  no Dock icon. Whenever the window is hidden, Bridge runs under the macOS-  Accessory activation policy (no Dock icon, no Cmd-Tab entry), in BOTH-  standalone and embedded modes. The menu-bar item is the always-present-  control surface.-- A signed-OUT launch still shows the window: the first-run sign-in flow needs-  a surface, and "installed it, nothing happened" on a fresh machine is a bug-  class we never want back.-- The window is a settings-and-approvals surface. It is summoned three ways:-  - the menu-bar item (Show Window / Settings)-  - launching the app a second time (single-instance: the running instance-    shows and focuses its window)-  - automatically, when Bridge needs the human: an approval dialog or the-    sign-in flow flips the app from Accessory to Regular (Dock icon appears)-    and activates the window. Hiding the window again returns to Accessory.-- Closing the window returns Bridge to the menu bar. It does not exit.--The menu-bar item's menu: Show Window, Connect All, Disconnect All, Settings,-Quit.--## Close to menu bar: the close button hides, Bridge keeps serving--- Clicking the window's close button does NOT exit Bridge. The close request-  hides the window and Bridge keeps running and serving (relay, direct API,-  bridges, notifications). This is by design: Bridge must stay reachable as-  the machine's recovery channel.-- It is never silent: the FIRST 3 TIMES the user closes the window, Bridge-  shows a notification explaining that it moved to the menu bar, then stops-  reminding. The counter lives at `~/.adom/tray-notice-count` (a legacy-  one-shot `tray-notice-shown` file seeds the count at 1 so existing users are-  not re-nagged from scratch).-- Launching Bridge again while it is hidden is never a no-op (single-instance):-  - standalone: the existing instance shows and focuses its window-  - embedded with Adom Hydrogen alive: a notification says where Bridge lives-    (inside Hydrogen)-  - embedded but Hydrogen is dead (stale flag): treated as standalone, the-    window shows-- The ONLY thing that exits Bridge is the `desktop_shutdown` verb-  (`POST /command {"command":"shutdown"}` on the direct API) or Quit in the-  menu-bar menu. Closing the window never does.--## The menu-bar item: standalone only--- In STANDALONE mode Bridge has a menu-bar item.-- When EMBEDDED in Adom Hydrogen, Bridge HIDES its menu-bar item; Hydrogen is-  the app the human sees. When Hydrogen goes away, Bridge reverts to-  standalone and the menu-bar item comes back.-- The absence of the menu-bar item plus a running Bridge process is therefore-  the normal embedded state, not a failure.--## The hidden window costs nothing extra--There is no separate renderer-suspension machinery on macOS: a hidden window-is simply hidden, and the Accessory policy keeps Bridge out of the Dock and-Cmd-Tab. The Rust side keeps doing ALL real work while hidden: relay, direct-API, bridges, bridge supervision (persistent respawn plus duplicate collapse),-notifications, and shell approvals. UI-only work (LED probes, status emits-that exist to paint the GUI) is skipped while the window is hidden and-self-heals within one health tick of showing it.--## Launch at login: default ON, self-healing--- The intent is `config.launch_on_boot`, DEFAULT TRUE. The Settings checkbox-  (launch at login) reads and writes this intent and is checked by default.-- The mechanism is a per-user LaunchAgent:-  `~/Library/LaunchAgents/inc.adom.desktop.plist`.-- A reconcile runs on EVERY launch, in BOTH standalone and embedded modes:-  - intent ON and the plist is missing or stale: (re)write it-  - intent OFF and the plist exists: delete it-- This is the self-heal: a plist that was never created, got deleted, points-  at a moved app path, or failed to write is corrected on the next launch. An-  update that relocates the app rewrites the LaunchAgent to the new path.-- Never create the LaunchAgent manually; the reconcile owns it.--## Shared Adom sign-in (keychain)--One Adom sign-in serves both Adom Bridge and Adom Hydrogen: the session token-lives in a SHARED keychain item, and `~/.adom/session.json` is a rebuilt-cache. Consequences:--- Signing in to either app signs in both.-- The sign-in survives uninstall and reinstall (the keychain item persists;-  the file cache is rehydrated from it).-- Signing out deletes the keychain item, so it signs out everywhere.--## Window title markers--The window title carries live version and provenance markers: the running-VERSION (for example `Adom Bridge — v1.9.187 release`), the git SHA and build-timestamp, and a `signed` or `unsigned` marker for the running binary's code-signature. This is the quick truth check for which build is actually running.--## Foreground attribution (v1.9.175)--Bridge never raises its own window silently. Every self-foreground (sign-in-completion, notification click, shell-approve grant, `request_shell_approval`,-menu-bar menu, second launch) is logged to the Activity Log as a `foreground`-event naming the source and reason, and to `startup.log` as a `FOREGROUND:`-line. An update-apply relaunch is deliberately QUIET: the updater drops-`~/.adom/update-quiet-relaunch` and the relaunched Bridge consumes it-(10-minute freshness gate) and stays in the menu bar. If a user reports-"Bridge randomly came to the front", read the Activity Log or startup.log; the-answer is always recorded.