@agfpd/iapeer 0.4.64 → 0.4.65

package/docs/12-cli-reference.md

@@ -94,3 +94,15 @@ Commands an agent runs in its own session (require `PEER_IDENTITY` in the enviro
 | `run-infra <name> <runtime>` | An infrastructure peer's entry point; launched from its launchd plist. |
 
 These two commands are invoked by launchd, not the operator directly.
+
+## Tray (menu-bar dashboard)
+
+| Command | What it does |
+|---|---|
+| `tray install [--plugin-only]` | Install the SwiftBar fleet dashboard: install SwiftBar.app when absent (owner-sanctioned), write the plugin, launch + refresh. `--plugin-only` writes just the plugin file. Idempotent. |
+| `tray uninstall` | Remove the plugin file + refresh SwiftBar. Never touches the fleet; leaves SwiftBar.app installed. |
+| `tray render [--stream]` | Print the SwiftBar plugin output (`--stream` = the streamable loop the plugin runs). |
+| `tray cmd <command> <peer> [runtime]` | POST a fleet command (`wake`/`stop`/`start`/`new`/`refresh`/`interrupt`/`compact`) — the menu's lifecycle actions. |
+| `tray status` | Read-only: fleet API reachability, SwiftBar install + plugin dir, plugin file presence. |
+
+The tray is the first external [Fleet API](15-fleet-api.md) client — see [16 — Tray](16-tray.md).

package/docs/16-tray.md

@@ -0,0 +1,88 @@
+# 16 — Tray (menu-bar fleet dashboard)
+
+A macOS menu-bar dashboard of the fleet — the peer list of `iapeer list` rendered as a
+[SwiftBar](https://github.com/swiftbar/SwiftBar) plugin. It is the **first external
+client of the [Fleet API](15-fleet-api.md)**: it discovers the daemon via `router.json`,
+reads `/fleet/v1/snapshot`, follows `/fleet/v1/events`, and issues commands over
+`/fleet/v1/peers/<peer>/<cmd>` — all over HTTP, against the normative contract, with no
+knowledge of daemon internals. If the daemon and the contract ever diverge, the tray is
+the second consumer that feels it (the first being the daemon itself, which wrote the
+snapshot).
+
+Packaging: the tray ships **with the foundation** — it is another face of the daemon, the
+same class as the `iapeer list` TUI, not a separate project. `iapeer install` drops the
+plugin file (inert until SwiftBar is present); `iapeer tray install` is the one-time
+activation that also installs SwiftBar.app when it is absent.
+
+## What you see
+
+- **Menu bar:** an antenna glyph + the count of peers with a live session. When no
+  advertised daemon address answers, a red warning triangle instead (the daemon is down —
+  a purely API-fed dashboard cannot show a broken daemon any other way; the built-in TUI
+  keeps its direct read path for that case, see [15](15-fleet-api.md)).
+- **Dropdown:** a host header (`iapeer <version> · up <uptime>`) and the memory/voice
+  provider heartbeats, then one row per peer:
+  - `<peer>  <runtime><glyph> …  <age>` with the same glyph semantics as the CLI —
+    `●` live · `○` asleep · `✕` stopped — green when any runtime is live. Badges: `👤`
+    a human is attached, `🔒` launchd-managed (H4 read-only), `⏳N` an ephemeral peer's
+    queue depth.
+  - **Click a peer → Terminal.app running `iapeer attach <peer>`.** Attach is a terminal
+    handoff the API deliberately keeps client-side (a PTY inside a GUI is out of scope);
+    the same row's submenu carries the lifecycle actions (Wake / Stop / Start / New /
+    Interrupt / Refresh / Compact), each a `POST /fleet/v1/peers/<peer>/<cmd>` via
+    `iapeer tray cmd`.
+
+The list updates itself: the plugin is **streamable** — it subscribes to the event stream
+and re-fetches the snapshot on every change (a peer waking, an operator stop/start, a
+death), coalescing bursts. A ~15 s heartbeat keeps ages fresh and self-heals a missed
+event; the stream reconnects across daemon restarts. No manual refresh needed (there is a
+Refresh item anyway).
+
+## Verbs
+
+| Verb | What it does |
+|---|---|
+| `iapeer tray install [--plugin-only]` | Install SwiftBar.app when absent (owner-sanctioned), point it at the plugin dir, write the plugin, launch + refresh. `--plugin-only` writes just the plugin file (no app, no launch — what the foundation install does). Idempotent. |
+| `iapeer tray uninstall` | Remove the plugin file and refresh SwiftBar. **Never touches the fleet** — the daemon, TUI and delivery keep running; SwiftBar.app is left installed (it may host other plugins). |
+| `iapeer tray render [--stream]` | Print the SwiftBar plugin output. `--stream` is the streamable loop the plugin runs; the one-shot form is the poll fallback and the test surface. |
+| `iapeer tray cmd <command> <peer> [runtime]` | POST a fleet command (`wake`/`stop`/`start`/`new`/`refresh`/`interrupt`/`compact`) — the menu's lifecycle actions call this. |
+| `iapeer tray status` | Read-only: is the fleet API up (from `router.json`), is SwiftBar installed and where is its plugin dir, is the plugin file present. Repairs nothing. |
+
+## How it is wired
+
+The SwiftBar plugin file (`iapeer.10s.sh` in the plugin dir) is a thin shim: SwiftBar
+metadata (`<swiftbar.type>streamable</swiftbar.type>`) plus one line —
+`exec "<~/.local/bin/iapeer>" tray render --stream`. All rendering, streaming and
+command logic lives in the compiled binary (typed, tested); the `.sh` is stable and
+carries no logic, so an `iapeer update` never has to rewrite it.
+
+Plugin directory: an already-configured SwiftBar `PluginDirectory` is respected (the
+plugin is installed into the user's own dir); otherwise a dedicated
+`~/.iapeer/tray/plugins/`, and SwiftBar is pointed at it via
+`defaults write com.ameba.SwiftBar PluginDirectory` — a plain-string default SwiftBar
+reads on launch (it is not sandboxed and stores no security-scoped bookmark), so the
+folder picker is skipped.
+
+Auth follows the Fleet API: on an open-local host no bearer is needed; when the daemon is
+configured with `IAPEER_BEARER_TOKEN`, the plugin's environment must carry it too.
+
+Config: `IAPEER_TRAY_HEARTBEAT_MS` tunes the heartbeat cadence (default 15 s, clamped
+1 s…10 min).
+
+## Client obligations
+
+Because the tray is a Fleet API client, it obeys the normative rules in
+[15 — Fleet API §Client obligations](15-fleet-api.md): unknown `ev` kinds and unknown
+JSON fields are ignored (additive evolution), events are at-least-once (the snapshot is
+the state, events are change hints), and a missing `fleet: 1` marker in `router.json`
+means "no fleet API" — the tray degrades to the daemon-down state rather than probing
+endpoints.
+
+## Boundaries
+
+- **GUI teardown ≠ fleet teardown.** Removing the plugin (or quitting SwiftBar) leaves the
+  daemon, the fleet and the CLI/TUI fully working — the dashboard is an optional face.
+- **Attach is not an API command** — it is a terminal handoff the client performs.
+- Native app, pet overlay and approval buttons are later phases (a native `iapeer-tray`
+  Swift app is considered only if the SwiftBar version proves insufficient); all would be
+  further thin clients of the same Fleet API.

package/docs/README.md

@@ -77,6 +77,7 @@ The sections are layered: from "install and use" to "understand the architecture
 - [13 — Architecture and contract](13-architecture-and-contract.md) — for plugin and runtime-package developers
 - [14 — Configuration and logs](14-configuration-and-logs.md) — environment variables, logs, diagnostics
 - [15 — Fleet API](15-fleet-api.md) — the daemon's HTTP surface for operator clients (dashboards, tray apps, scripts): snapshot, event stream, commands
+- [16 — Tray](16-tray.md) — the macOS menu-bar fleet dashboard (SwiftBar plugin), the first external Fleet API client
 
 ## Status
 

package/docs/ru/16-tray.md

@@ -0,0 +1,83 @@
+# 16 — Трей (дашборд флота в меню-баре)
+
+Дашборд флота в меню-баре macOS — список пиров `iapeer list`, отрисованный как плагин
+[SwiftBar](https://github.com/swiftbar/SwiftBar). Это **первый внешний клиент
+[Fleet API](15-fleet-api.md)**: он находит демон через `router.json`, читает
+`/fleet/v1/snapshot`, следит за `/fleet/v1/events` и шлёт команды через
+`/fleet/v1/peers/<peer>/<cmd>` — целиком по HTTP, против нормативного контракта, без знания
+внутренностей демона. Если демон и контракт разойдутся, трей — второй потребитель, который
+это почувствует (первый — сам демон, который снапшот и пишет).
+
+Упаковка: трей поставляется **вместе с фундаментом** — это ещё одно «лицо» демона, тот же
+класс, что TUI `iapeer list`, а не отдельный проект. `iapeer install` кладёт файл плагина
+(инертен, пока нет SwiftBar); `iapeer tray install` — разовая активация, которая доустановит
+SwiftBar.app, если его нет.
+
+## Что видно
+
+- **Меню-бар:** глиф-антенна + число пиров с живой сессией. Если ни один объявленный адрес
+  демона не отвечает — красный треугольник (демон недоступен; чисто API-дашборд иначе не
+  покажет сломанный демон — встроенный TUI держит прямой путь чтения для этого случая, см.
+  [15](15-fleet-api.md)).
+- **Выпадашка:** шапка хоста (`iapeer <версия> · up <аптайм>`) и хартбиты провайдеров памяти
+  и голоса, затем строка на пира:
+  - `<peer>  <рантайм><глиф> …  <возраст>` с той же семантикой глифов, что в CLI —
+    `●` живой · `○` спит · `✕` остановлен — зелёный, если хоть один рантайм живой. Бейджи:
+    `👤` подключён человек, `🔒` под launchd (H4 read-only), `⏳N` глубина очереди эфемерного
+    пира.
+  - **Клик по пиру → Terminal.app с `iapeer attach <peer>`.** Attach — терминальная передача,
+    которую API намеренно оставляет клиенту (PTY внутри GUI вне рамок); подменю той же строки
+    несёт lifecycle-действия (Wake / Stop / Start / New / Interrupt / Refresh / Compact),
+    каждое — `POST /fleet/v1/peers/<peer>/<cmd>` через `iapeer tray cmd`.
+
+Список обновляется сам: плагин **streamable** — подписан на поток событий и перечитывает
+снапшот на каждое изменение (пробуждение пира, стоп/старт оператором, смерть), склеивая
+всплески. Хартбит ~15 с держит возрасты свежими и самозалечивает пропущенное событие; поток
+переподключается через рестарты демона. Ручной refresh не нужен (пункт Refresh всё же есть).
+
+## Verb'ы
+
+| Verb | Что делает |
+|---|---|
+| `iapeer tray install [--plugin-only]` | Доустановит SwiftBar.app, если его нет (санкция владельца), нацелит его на каталог плагинов, запишет плагин, запустит + обновит. `--plugin-only` пишет только файл плагина (без приложения и запуска — так делает foundation-install). Идемпотентно. |
+| `iapeer tray uninstall` | Удалит файл плагина и обновит SwiftBar. **Флот не трогает** — демон, TUI и доставка живут; SwiftBar.app остаётся (может держать другие плагины). |
+| `iapeer tray render [--stream]` | Печатает вывод плагина SwiftBar. `--stream` — streamable-цикл, который крутит плагин; одноразовая форма — поллинг-фолбэк и тест-поверхность. |
+| `iapeer tray cmd <command> <peer> [runtime]` | POST fleet-команды (`wake`/`stop`/`start`/`new`/`refresh`/`interrupt`/`compact`) — lifecycle-пункты меню зовут это. |
+| `iapeer tray status` | Только чтение: жив ли fleet API (из `router.json`), установлен ли SwiftBar и где его каталог плагинов, на месте ли файл плагина. Ничего не чинит. |
+
+## Как устроено
+
+Файл плагина SwiftBar (`iapeer.10s.sh` в каталоге плагинов) — тонкий шим: метаданные SwiftBar
+(`<swiftbar.type>streamable</swiftbar.type>`) плюс одна строка —
+`exec "<~/.local/bin/iapeer>" tray render --stream`. Вся отрисовка, стриминг и команды живут
+в скомпилированном бинаре (типизировано, покрыто тестами); `.sh` стабилен и логики не несёт,
+поэтому `iapeer update` его не переписывает.
+
+Каталог плагинов: уже настроенный `PluginDirectory` SwiftBar уважается (плагин ставится в
+каталог пользователя); иначе — выделенный `~/.iapeer/tray/plugins/`, и SwiftBar нацеливается на
+него через `defaults write com.ameba.SwiftBar PluginDirectory` — обычный строковый default,
+который SwiftBar читает при запуске (он не sandboxed и не хранит security-scoped bookmark),
+поэтому окно выбора папки пропускается.
+
+Авторизация — как у Fleet API: на open-local хосте bearer не нужен; если демон настроен с
+`IAPEER_BEARER_TOKEN`, окружение плагина тоже должно его нести.
+
+Конфиг: `IAPEER_TRAY_HEARTBEAT_MS` настраивает каденцию хартбита (по умолчанию 15 с, зажато
+1 с…10 мин).
+
+## Обязанности клиента
+
+Поскольку трей — клиент Fleet API, он соблюдает нормативные правила из
+[15 — Fleet API §Client obligations](15-fleet-api.md): неизвестные виды `ev` и неизвестные
+поля JSON игнорируются (аддитивная эволюция), события at-least-once (снапшот — состояние,
+события — подсказки об изменении), а отсутствие маркера `fleet: 1` в `router.json` означает
+«нет fleet API» — трей деградирует в состояние «демон недоступен», а не зондирует эндпоинты.
+
+## Границы
+
+- **Снос GUI ≠ снос флота.** Удаление плагина (или выход из SwiftBar) оставляет демон, флот
+  и CLI/TUI полностью рабочими — дашборд опционален.
+- **Attach — не команда API**, это терминальная передача, которую выполняет клиент.
+- Нативное приложение, питомец-оверлей и кнопки подтверждений — более поздние фазы (нативное
+  Swift-приложение `iapeer-tray` рассматривается, только если версии на SwiftBar не хватит);
+  все они — тоже тонкие клиенты того же Fleet API.

package/docs/ru/README.md

@@ -77,6 +77,7 @@ iapeer send assistant --message "привет, ты на связи?"
 - [13 — Архитектура и контракт](13-архитектура-и-контракт.md) — для разработчиков плагинов и рантайм-пакетов
 - [14 — Конфигурация и журналы](14-конфигурация-и-журналы.md) — переменные окружения, журналы, диагностика
 - [15 — Fleet API](15-fleet-api.md) — HTTP-поверхность демона для операторских клиентов (дашборды, tray-приложения, скрипты): снапшот, поток событий, команды
+- [16 — Трей](16-tray.md) — дашборд флота в меню-баре macOS (плагин SwiftBar), первый внешний клиент Fleet API
 
 ## Статус
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.64",
+  "version": "0.4.65",
   "description": "Run Claude Code and Codex CLI as local background agents that message each other, wake on demand, and share one memory.",
   "license": "Apache-2.0",
   "author": "agfpd",

package/src/cli/index.ts

@@ -1165,7 +1165,9 @@ const BOOLEAN_FLAGS: ReadonlySet<string> = new Set([
   'no-telegram',
   'no-voice',
   'npx',
+  'plugin-only',
   'remove-codesign-identity',
+  'stream',
   'yes',
 ])
 
@@ -1275,6 +1277,10 @@ const VERBS: ReadonlyArray<{ sig: string; desc: string }> = [
     sig: 'supervisor up|start|attach|list|kill <sess> [runtime]',
     desc: 'DARK (cutover Block 2): detach-persistent pty-supervisor PoC port; serves nothing on the live fleet (throwaway validation only)',
   },
+  {
+    sig: 'tray install|uninstall|render [--stream]|cmd <c> <peer>|status',
+    desc: 'the macOS menu-bar fleet dashboard (SwiftBar plugin) — first external Fleet API client; install activates it (installs SwiftBar when absent). See docs/16.',
+  },
 ]
 
 /** Greedy word-wrap to `width` columns. A token longer than `width` keeps its own
@@ -2275,6 +2281,19 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         // docs on its OWN install, version = its binary). install runs from source, so
         // docs/ sits at <entry>/../../docs. Best-effort: never fails the install.
         const docs = scaffoldHostDocs('iapeer', join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'docs'), env)
+        // Ship the tray face WITH the foundation (owner decision — same class as the
+        // `iapeer list` TUI). Plugin-file ONLY: drop/refresh the SwiftBar plugin shim
+        // (into a configured SwiftBar dir if present, else the dedicated ~/.iapeer dir).
+        // Inert without SwiftBar; NEVER auto-installs the GUI here (that is the explicit
+        // `iapeer tray install`). Best-effort — a hiccup never fails the foundation install.
+        let trayLine = ''
+        try {
+          const { installTray } = await import('../tray/index.ts')
+          const t = installTray({ env, installApp: false, launch: false })
+          trayLine = `  tray plugin: ${t.wrote ? 'written' : 'unchanged'} → ${t.pluginFile} (${t.dir})\n`
+        } catch (e) {
+          trayLine = `  tray plugin: skipped (${e instanceof Error ? e.message : String(e)})\n`
+        }
         const { path: plist, changed: plistChanged } = installDaemonPlist({ env })
         const signingLine =
           r.signing == null
@@ -2291,6 +2310,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
             `  scaffold: ~/.iapeer/ ensured (peers/, state, logs, cache, runtimes)\n` +
             `  host doctrine: ${hostDoctrine.path}${hostDoctrine.created ? ' (stub created — fill it in)' : ' (kept)'}\n` +
             `  docs: ${docs.copied ? docs.dest : `skipped (${docs.reason})`}\n` +
+            trayLine +
             `  daemon plist ${plistChanged ? 'written' : 'unchanged (byte-identical — no write, no BTM notification)'}: ${plist}\n` +
             `  (NOT loaded — a live daemon migration is a separate step: launchctl bootstrap gui/$(id -u) ${plist})\n`,
         )
@@ -2469,6 +2489,82 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         const { runSupervisorCli } = await import('../supervisor/index.ts')
         return await runSupervisorCli(rest)
       }
+      case 'tray': {
+        // Ф1 of iapeer-tray — the SwiftBar fleet dashboard, an EXTERNAL fleet-API
+        // client (docs/15). Subcommands: render[--stream] · cmd · install · uninstall
+        // · status. The plugin file is a shim that execs `tray render --stream`; all
+        // rendering/streaming lives here (tested TS), the .sh carries only metadata.
+        const tray = await import('../tray/index.ts')
+        const sub = positionals[0]
+        switch (sub) {
+          case 'render': {
+            if (flags.stream === true) {
+              await tray.streamTray(env) // SwiftBar streamable loop — runs until the process is killed
+              return 0
+            }
+            out(await tray.renderTrayOnce(env))
+            return 0
+          }
+          case 'cmd': {
+            const command = positionals[1]
+            const peer = positionals[2]
+            const runtime = positionals[3]
+            if (!command || !peer) {
+              return argErr(errOut, 'usage: iapeer tray cmd <wake|stop|start|new|refresh|interrupt|compact> <peer> [runtime]')
+            }
+            let r: Awaited<ReturnType<typeof tray.trayCmd>>
+            try {
+              r = await tray.trayCmd(env, command, peer, runtime)
+            } catch (e) {
+              errOut(`tray cmd: ${e instanceof Error ? e.message : String(e)}\n`)
+              return 1
+            }
+            out(`${JSON.stringify(r.body)}\n`)
+            return r.ok ? 0 : 1
+          }
+          case 'install': {
+            // Explicit activation verb: installs SwiftBar.app when absent
+            // (owner-sanctioned) + launches, unless --plugin-only (file only).
+            const pluginOnly = flags['plugin-only'] === true
+            const r = tray.installTray({ env, installApp: !pluginOnly, launch: !pluginOnly })
+            out(
+              `tray plugin ${r.wrote ? 'written' : 'unchanged'}: ${r.pluginFile}\n` +
+                `  plugin dir: ${r.pluginDir} (${r.dir})\n` +
+                `  SwiftBar: ${r.app}${r.appReason ? ` — ${r.appReason}` : ''}\n` +
+                (r.launched ? '  launched + refreshed SwiftBar\n' : '') +
+                (r.app === 'absent' || r.app === 'install-failed'
+                  ? '  (SwiftBar not active — run `iapeer tray install` to install it, then it appears in the menu bar)\n'
+                  : ''),
+            )
+            return 0
+          }
+          case 'uninstall': {
+            const r = tray.uninstallTray({ env, launch: true })
+            out(
+              (r.removed.length ? `removed:\n${r.removed.map(f => `  ${f}`).join('\n')}\n` : 'no tray plugin file found\n') +
+                (r.refreshed ? '  refreshed SwiftBar\n' : '') +
+                '  fleet untouched (daemon / TUI / delivery unaffected)\n',
+            )
+            return 0
+          }
+          case 'status': {
+            const s = tray.trayStatus({ env })
+            out(
+              `daemon fleet API: ${s.daemon.fleet ? `up (v${s.daemon.version ?? '?'})` : 'DOWN / no fleet:1'}\n` +
+                `  sock: ${s.daemon.sock ?? '—'}\n` +
+                `  tcp:  ${s.daemon.tcp ?? '—'}\n` +
+                `SwiftBar: ${s.swiftbar.installed ? `installed (plugin dir: ${s.swiftbar.pluginDir ?? 'unset'})` : 'not installed'}\n` +
+                `plugin: ${s.plugin.installed ? s.plugin.path : 'not installed'}\n`,
+            )
+            return 0
+          }
+          default:
+            return argErr(
+              errOut,
+              'usage: iapeer tray <render [--stream] | cmd <command> <peer> [runtime] | install [--plugin-only] | uninstall | status>',
+            )
+        }
+      }
       default: {
         // `iapeer <runtime>` (launch) — folder-launch the cwd's peer, ALWAYS fresh. On a TTY this is
         // the human "start a fresh session and work in it" verb (parallel to `attach`, which resumes):

package/src/tray/client.ts

@@ -0,0 +1,233 @@
+// tray/client — the fleet-API HTTP client. Ф1 of iapeer-tray is the FIRST EXTERNAL
+// client of the daemon's fleet API, and it is written ONLY against the normative
+// contract docs/15-fleet-api.md — NOT against daemon source. This module therefore
+// imports NOTHING from src/daemon: it discovers the daemon via router.json, speaks
+// plain HTTP+JSON (+SSE) over the two advertised listeners, and models the snapshot
+// with its OWN local interfaces (client obligation 2: unknown fields ignored). If the
+// doc and the daemon ever diverge, this client feels it — that is the whole point of
+// dogfooding the contract through a real second client.
+//
+// Transport: prefer the 0600 unix socket (same-uid, same trust class as the CLI),
+// fall back to the TCP loopback. Bun's fetch carries the `unix` option; the compiled
+// `iapeer` binary bundles the Bun runtime, so this works when SwiftBar execs it.
+
+import { readFileSync } from 'fs'
+import { join } from 'path'
+import { pluginStateDir, type StorageOptions } from '../storage/index.ts'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Discovery — router.json (docs/15 §Surface and transport)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface FleetAddress {
+  /** Unix-socket path (preferred). */
+  sock?: string
+  /** TCP origin, e.g. `http://127.0.0.1:8765` (derived from router.json `tcp`). */
+  tcp?: string
+  /** The daemon's advertised version, when present. */
+  version?: string
+  /** The fleet capability marker: `1` when the daemon serves /fleet/v1. Absent ⇒
+   *  a pre-fleet daemon ⇒ the client must degrade (docs/15 §Discovery). */
+  fleet?: number
+}
+
+/** Read `~/.iapeer/state/iapeer/router.json`. Absent/unreadable ⇒ empty address
+ *  (daemon down) — the caller renders the down state. Never throws. */
+export function resolveFleetAddress(opts: StorageOptions = {}): FleetAddress {
+  const routerJson = join(pluginStateDir('iapeer', opts), 'router.json')
+  try {
+    const parsed = JSON.parse(readFileSync(routerJson, 'utf8')) as {
+      sock?: unknown
+      tcp?: unknown
+      version?: unknown
+      fleet?: unknown
+    }
+    const addr: FleetAddress = {}
+    if (typeof parsed.sock === 'string' && parsed.sock) addr.sock = parsed.sock
+    // router.json advertises the MCP url (…/mcp); the fleet surface lives on the SAME
+    // origin under /fleet/v1 — keep only the origin.
+    if (typeof parsed.tcp === 'string' && parsed.tcp) {
+      try {
+        addr.tcp = new URL(parsed.tcp).origin
+      } catch {
+        /* malformed tcp url → no tcp fallback */
+      }
+    }
+    if (typeof parsed.version === 'string') addr.version = parsed.version
+    if (typeof parsed.fleet === 'number') addr.fleet = parsed.fleet
+    return addr
+  } catch {
+    return {}
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Requests — unix-first, TCP-fallback, optional bearer
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** The bearer, when the host configured H8 auth (docs/15 §Auth). Read from the
+ *  env the client runs under; open-local hosts have none. */
+function bearerHeader(env: NodeJS.ProcessEnv): Record<string, string> {
+  const t = env.IAPEER_BEARER_TOKEN?.trim()
+  return t ? { authorization: `Bearer ${t}` } : {}
+}
+
+export class FleetUnreachableError extends Error {
+  constructor(readonly detail: string) {
+    super(`fleet daemon unreachable: ${detail}`)
+    this.name = 'FleetUnreachableError'
+  }
+}
+
+interface FetchAttempt {
+  url: string
+  init: RequestInit & { unix?: string }
+}
+
+/** Build the ordered transport attempts for a fleet path: unix socket first, TCP
+ *  second. `unix` is Bun's fetch option (routes the HTTP request over the socket). */
+function attempts(addr: FleetAddress, path: string, base: RequestInit, env: NodeJS.ProcessEnv): FetchAttempt[] {
+  const headers = { ...(base.headers as Record<string, string> | undefined), ...bearerHeader(env) }
+  const list: FetchAttempt[] = []
+  if (addr.sock) list.push({ url: `http://iapeer${path}`, init: { ...base, headers, unix: addr.sock } })
+  if (addr.tcp) list.push({ url: `${addr.tcp}${path}`, init: { ...base, headers } })
+  return list
+}
+
+async function fetchFleet(
+  addr: FleetAddress,
+  path: string,
+  init: RequestInit,
+  env: NodeJS.ProcessEnv,
+): Promise<Response> {
+  const tries = attempts(addr, path, init, env)
+  if (tries.length === 0) throw new FleetUnreachableError('no advertised address (router.json missing sock/tcp)')
+  let lastErr = ''
+  for (const a of tries) {
+    try {
+      const res = await fetch(a.url, a.init as RequestInit)
+      return res
+    } catch (e) {
+      lastErr = e instanceof Error ? e.message : String(e)
+      // try the next transport
+    }
+  }
+  throw new FleetUnreachableError(lastErr || 'all transports failed')
+}
+
+export async function fleetGetJson<T = unknown>(addr: FleetAddress, path: string, env: NodeJS.ProcessEnv): Promise<T> {
+  const res = await fetchFleet(addr, path, { method: 'GET' }, env)
+  const text = await res.text()
+  if (!res.ok) throw new Error(`GET ${path} → ${res.status}: ${text.slice(0, 300)}`)
+  return JSON.parse(text) as T
+}
+
+export async function fleetPostJson<T = unknown>(
+  addr: FleetAddress,
+  path: string,
+  body: Record<string, unknown>,
+  env: NodeJS.ProcessEnv,
+): Promise<{ status: number; body: T }> {
+  const res = await fetchFleet(
+    addr,
+    path,
+    { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) },
+    env,
+  )
+  const text = await res.text()
+  let parsed: T
+  try {
+    parsed = JSON.parse(text) as T
+  } catch {
+    parsed = text as unknown as T
+  }
+  return { status: res.status, body: parsed }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SSE — GET /fleet/v1/events (docs/15 §GET /fleet/v1/events)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface SseEvent {
+  /** The event name (`event:` line) — the `ev` vocabulary. Unknown kinds MUST be
+   *  tolerated by the caller (client obligation 1). */
+  event: string
+  /** Epoch-ms of the event (`id:` line) — for at-least-once dedup. */
+  id?: number
+  /** The parsed `data:` JSON payload. */
+  data: Record<string, unknown>
+}
+
+/**
+ * Open the SSE stream and invoke `onEvent` per frame until the signal aborts or the
+ * connection drops (then this resolves — the caller decides whether to reconnect).
+ * Parses the `event:` / `id:` / `data:` triplet; comments (`: connected`, `: hb`) are
+ * skipped. Deliberately minimal — no reconnect here (the render loop owns that).
+ */
+export async function streamFleetEvents(
+  addr: FleetAddress,
+  onEvent: (e: SseEvent) => void,
+  opts: { replay?: number; signal?: AbortSignal; env: NodeJS.ProcessEnv },
+): Promise<void> {
+  const replay = Math.max(0, Math.min(500, opts.replay ?? 0))
+  const res = await fetchFleet(
+    addr,
+    `/fleet/v1/events?replay=${replay}`,
+    { method: 'GET', headers: { accept: 'text/event-stream' }, signal: opts.signal },
+    opts.env,
+  )
+  if (!res.ok || !res.body) throw new Error(`events stream → ${res.status}`)
+  const reader = res.body.getReader()
+  const decoder = new TextDecoder()
+  let buf = ''
+  try {
+    for (;;) {
+      const { value, done } = await reader.read()
+      if (done) break
+      buf += decoder.decode(value, { stream: true })
+      // Frames are separated by a blank line.
+      let sep: number
+      while ((sep = buf.indexOf('\n\n')) !== -1) {
+        const frame = buf.slice(0, sep)
+        buf = buf.slice(sep + 2)
+        const parsed = parseSseFrame(frame)
+        if (parsed) onEvent(parsed)
+      }
+    }
+  } finally {
+    try {
+      reader.releaseLock()
+    } catch {
+      /* already released */
+    }
+  }
+}
+
+/** Parse one SSE frame (the text between blank-line separators). Returns null for
+ *  comment-only frames (`: connected`, `: hb`) or frames without a data payload. */
+export function parseSseFrame(frame: string): SseEvent | null {
+  let event = 'message'
+  let id: number | undefined
+  const dataLines: string[] = []
+  for (const raw of frame.split('\n')) {
+    const line = raw.replace(/\r$/, '')
+    if (!line || line.startsWith(':')) continue // comment or blank
+    const colon = line.indexOf(':')
+    const field = colon === -1 ? line : line.slice(0, colon)
+    const val = colon === -1 ? '' : line.slice(colon + 1).replace(/^ /, '')
+    if (field === 'event') event = val
+    else if (field === 'id') {
+      const n = parseInt(val, 10)
+      if (Number.isFinite(n)) id = n
+    } else if (field === 'data') dataLines.push(val)
+  }
+  if (dataLines.length === 0) return null
+  let data: Record<string, unknown> = {}
+  try {
+    const parsed = JSON.parse(dataLines.join('\n'))
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) data = parsed as Record<string, unknown>
+  } catch {
+    return null
+  }
+  return { event, ...(id !== undefined ? { id } : {}), data }
+}

package/src/tray/index.ts

@@ -0,0 +1,146 @@
+// tray/index — the fleet dashboard's runtime entry points, called by the `tray` CLI
+// verb. Ф1 of iapeer-tray: the FIRST external client of the daemon fleet API, written
+// strictly against docs/15-fleet-api.md.
+//
+//   • render (one-shot) — fetch /snapshot once, print one SwiftBar block. Used by the
+//     poll-fallback plugin and by tests.
+//   • render --stream — the SwiftBar streamable loop: print a block, subscribe to
+//     /events, and re-fetch the snapshot on each change (the canonical docs/15 loop
+//     "snapshot is state, events are hints"). Coalesces event bursts, heartbeats a
+//     refresh every 15 s (ages stay fresh + a missed event self-heals), and reconnects
+//     across daemon restarts / down windows. Degrades to the daemon-down block.
+//   • cmd — POST a fleet command (wake/stop/…): dogfoods the command endpoints.
+
+import { resolveFleetAddress, fleetGetJson, fleetPostJson, streamFleetEvents } from './client.ts'
+import { renderSwiftBar, renderDaemonDown, type TraySnapshot } from './render.ts'
+import { iapeerBinPath } from '../install/index.ts'
+
+export * from './install.ts'
+export { resolveFleetAddress } from './client.ts'
+
+const SNAPSHOT_PATH = '/fleet/v1/snapshot'
+const DEFAULT_HEARTBEAT_MS = 15_000
+const COALESCE_MS = 200
+const RECONNECT_BACKOFF_MS = 1_000
+const DOWN_RETRY_MS = 3_000
+
+/** Heartbeat cadence: re-render even without an event so ages stay fresh and a missed
+ *  event self-heals. Tunable via IAPEER_TRAY_HEARTBEAT_MS (clamped 1s…10m). */
+function heartbeatMs(env: NodeJS.ProcessEnv): number {
+  const raw = parseInt(env.IAPEER_TRAY_HEARTBEAT_MS ?? '', 10)
+  if (!Number.isFinite(raw)) return DEFAULT_HEARTBEAT_MS
+  return Math.max(1_000, Math.min(600_000, raw))
+}
+
+export const TRAY_COMMANDS = ['wake', 'stop', 'start', 'new', 'refresh', 'interrupt', 'compact'] as const
+export type TrayCommand = (typeof TRAY_COMMANDS)[number]
+
+/** Fetch the snapshot and render one SwiftBar block, or the degraded down-block when
+ *  no advertised address answers / the daemon predates the fleet API. Never throws. */
+export async function renderTrayOnce(env: NodeJS.ProcessEnv): Promise<string> {
+  const binPath = iapeerBinPath(env)
+  const addr = resolveFleetAddress({ env })
+  if (addr.fleet !== 1 || (!addr.sock && !addr.tcp)) {
+    const reason = addr.sock || addr.tcp ? 'daemon predates the fleet API (no fleet:1 in router.json)' : 'no daemon address (router.json missing)'
+    return renderDaemonDown(reason, { binPath })
+  }
+  try {
+    const snap = await fleetGetJson<TraySnapshot>(addr, SNAPSHOT_PATH, env)
+    return renderSwiftBar(snap, { binPath })
+  } catch (e) {
+    return renderDaemonDown(e instanceof Error ? e.message : String(e), { binPath })
+  }
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise(resolve => {
+    if (signal?.aborted) return resolve()
+    const t = setTimeout(resolve, ms)
+    ;(t as { unref?: () => void }).unref?.()
+    signal?.addEventListener('abort', () => { clearTimeout(t); resolve() }, { once: true })
+  })
+}
+
+/**
+ * The SwiftBar streamable loop (docs/16 §streaming). Emits a full menu block, then a
+ * `~~~` separator before every subsequent block. Drives updates off the SSE stream
+ * with burst-coalescing + a heartbeat; reconnects forever. `out` defaults to stdout;
+ * `signal` (tests) stops the loop.
+ */
+export async function streamTray(
+  env: NodeJS.ProcessEnv,
+  out: (s: string) => void = s => process.stdout.write(s),
+  signal?: AbortSignal,
+): Promise<void> {
+  let first = true
+  // Serialize all emits through a promise chain so a `~~~`+block is never interleaved.
+  let chain: Promise<void> = Promise.resolve()
+  const emit = (): Promise<void> => {
+    chain = chain.then(async () => {
+      const block = await renderTrayOnce(env)
+      out(first ? block : `~~~\n${block}`)
+      first = false
+    })
+    return chain
+  }
+  // Coalesce event bursts into a single re-render.
+  let coalesceTimer: ReturnType<typeof setTimeout> | undefined
+  const requestEmit = (): void => {
+    if (coalesceTimer) return
+    coalesceTimer = setTimeout(() => {
+      coalesceTimer = undefined
+      void emit()
+    }, COALESCE_MS)
+    ;(coalesceTimer as { unref?: () => void }).unref?.()
+  }
+
+  await emit() // initial block
+
+  while (!signal?.aborted) {
+    const addr = resolveFleetAddress({ env })
+    if (addr.fleet !== 1 || (!addr.sock && !addr.tcp)) {
+      await sleep(DOWN_RETRY_MS, signal)
+      await emit() // keep the down-block current until the daemon returns
+      continue
+    }
+    const heartbeat = setInterval(requestEmit, heartbeatMs(env))
+    ;(heartbeat as { unref?: () => void }).unref?.()
+    try {
+      // Blocks until the stream ends (daemon restart / network drop). Each event just
+      // marks the menu dirty — the snapshot re-fetch is the source of truth.
+      await streamFleetEvents(addr, () => requestEmit(), { replay: 0, signal, env })
+    } catch {
+      /* connection failed → fall through to a refresh + backoff + reconnect */
+    } finally {
+      clearInterval(heartbeat)
+    }
+    if (signal?.aborted) break
+    await emit() // reflect whatever changed across the drop
+    await sleep(RECONNECT_BACKOFF_MS, signal)
+  }
+}
+
+export interface TrayCmdResult {
+  ok: boolean
+  status: number
+  body: unknown
+}
+
+/** POST a fleet command for a peer (dogfoods POST /fleet/v1/peers/<peer>/<cmd>). */
+export async function trayCmd(
+  env: NodeJS.ProcessEnv,
+  command: string,
+  personality: string,
+  runtime?: string,
+): Promise<TrayCmdResult> {
+  if (!(TRAY_COMMANDS as readonly string[]).includes(command)) {
+    throw new Error(`unknown tray command "${command}" — one of: ${TRAY_COMMANDS.join(', ')}`)
+  }
+  const addr = resolveFleetAddress({ env })
+  if (addr.fleet !== 1 || (!addr.sock && !addr.tcp)) {
+    return { ok: false, status: 0, body: { error: 'fleet daemon unreachable (no fleet:1 in router.json)' } }
+  }
+  const path = `/fleet/v1/peers/${encodeURIComponent(personality)}/${command}`
+  const { status, body } = await fleetPostJson(addr, path, runtime ? { runtime } : {}, env)
+  return { ok: status < 400, status, body }
+}

package/src/tray/install.ts

@@ -0,0 +1,266 @@
+// tray/install — idempotent lifecycle of the SwiftBar plugin that hosts the fleet
+// dashboard. The plugin FILE is a thin shim: it execs the installed `iapeer` binary
+// (`iapeer tray render --stream`), so ALL rendering/streaming logic lives in the
+// binary (TypeScript, tested) rather than in brittle shell — the .sh is stable and
+// carries only SwiftBar metadata.
+//
+// SwiftBar facts (verified against SwiftBar/PreferencesStore.swift):
+//   • PluginDirectory is a PLAIN String default (read via expandingTildeInPath), NOT
+//     a security-scoped bookmark — `defaults write com.ameba.SwiftBar PluginDirectory
+//     -string <dir>` set BEFORE first launch is honored and skips the folder picker.
+//   • SwiftBar is not sandboxed (it runs arbitrary scripts), so a hidden ~/.iapeer
+//     path is readable without a TCC prompt.
+//
+// Packaging (owner decision 05.07.2026): the tray ships WITH the foundation (same
+// class as the `iapeer list` TUI — another face of the daemon). `iapeer install`
+// drops the plugin file (inert without SwiftBar); `iapeer tray install [--app]` is
+// the activation verb that also installs SwiftBar.app when absent (owner-sanctioned)
+// and launches it. Tearing down the GUI layer NEVER touches the fleet.
+//
+// Paths route through cfg/env (the dedicated plugin dir is under resolveGlobalRoot,
+// so IAPEER_ROOT isolates it in tests); every external side-effect (defaults / brew /
+// open) goes through an injectable Runner so tests stay hermetic.
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { spawnSync } from 'child_process'
+import { homedir } from 'os'
+import { join } from 'path'
+import { resolveGlobalRoot } from '../storage/index.ts'
+import { iapeerBinPath } from '../install/index.ts'
+import { resolveFleetAddress } from './client.ts'
+
+/** Streamable plugin: the `.10s.` token is the RESPAWN cadence SwiftBar uses if the
+ *  streaming process exits (daemon-down backoff); while the stream is alive it is
+ *  ignored. The basename is stable — install rewrites the same file (idempotent). */
+export const PLUGIN_BASENAME = 'iapeer.10s.sh'
+const SWIFTBAR_DOMAIN = 'com.ameba.SwiftBar'
+const SWIFTBAR_APP_PATHS = ['/Applications/SwiftBar.app', join(homedir(), 'Applications', 'SwiftBar.app')]
+
+export type RunResult = { status: number | null; stdout: string; stderr: string }
+export type Runner = (cmd: string, args: string[]) => RunResult
+
+const defaultRun: Runner = (cmd, args) => {
+  const r = spawnSync(cmd, args, { encoding: 'utf8' })
+  return { status: r.status, stdout: r.stdout ?? '', stderr: r.stderr ?? '' }
+}
+
+/** The dedicated iapeer-owned plugin dir under ~/.iapeer (IAPEER_ROOT-isolated). */
+export function dedicatedPluginDir(env: NodeJS.ProcessEnv = process.env): string {
+  return join(resolveGlobalRoot(env), 'tray', 'plugins')
+}
+
+/** Is SwiftBar.app installed? (either /Applications or ~/Applications). */
+export function swiftBarInstalled(): boolean {
+  return SWIFTBAR_APP_PATHS.some(p => existsSync(p))
+}
+
+/** The plugin-dir SwiftBar is currently configured with (plain-string default,
+ *  ~-expanded), or undefined when unset/unreadable. */
+export function readSwiftBarPluginDir(run: Runner = defaultRun): string | undefined {
+  const r = run('defaults', ['read', SWIFTBAR_DOMAIN, 'PluginDirectory'])
+  if (r.status !== 0) return undefined
+  const raw = r.stdout.trim()
+  if (!raw) return undefined
+  return raw.startsWith('~') ? join(homedir(), raw.slice(1)) : raw
+}
+
+function setSwiftBarPluginDir(dir: string, run: Runner): RunResult {
+  return run('defaults', ['write', SWIFTBAR_DOMAIN, 'PluginDirectory', '-string', dir])
+}
+
+function installSwiftBarApp(run: Runner): RunResult {
+  return run('brew', ['install', '--cask', 'swiftbar'])
+}
+
+function launchSwiftBar(run: Runner): void {
+  run('open', ['-g', '-a', 'SwiftBar'])
+}
+
+function refreshSwiftBar(run: Runner): void {
+  run('open', ['-g', 'swiftbar://refreshallplugins'])
+}
+
+/** The plugin shim: SwiftBar metadata + exec of the streaming renderer. binPath is
+ *  embedded absolute (SwiftBar's PATH is minimal, like launchd). */
+export function buildPluginShim(binPath: string): string {
+  return [
+    '#!/bin/bash',
+    '# <xbar.title>iapeer fleet</xbar.title>',
+    '# <xbar.version>v1</xbar.version>',
+    '# <xbar.author>iapeer</xbar.author>',
+    '# <xbar.desc>iapeer multi-agent fleet — live peer dashboard over the daemon fleet API.</xbar.desc>',
+    '# <swiftbar.type>streamable</swiftbar.type>',
+    '# <swiftbar.hideRunInTerminal>true</swiftbar.hideRunInTerminal>',
+    '# <swiftbar.hideLastUpdated>true</swiftbar.hideLastUpdated>',
+    '# <swiftbar.hideDisablePlugin>true</swiftbar.hideDisablePlugin>',
+    `exec "${binPath}" tray render --stream`,
+    '',
+  ].join('\n')
+}
+
+/** Fail-closed sandbox guard (in spirit with install/scaffoldHostDocs): never write
+ *  into the REAL ~/.iapeer under a sandboxed test that forgot to set IAPEER_ROOT. */
+function assertTraySandboxIsolated(env: NodeJS.ProcessEnv): void {
+  if (env.IAPEER_TEST_SANDBOX === '1' && resolveGlobalRoot(env) === join(homedir(), '.iapeer')) {
+    throw new Error('refusing to install the tray plugin into the REAL ~/.iapeer under IAPEER_TEST_SANDBOX=1 — set IAPEER_ROOT')
+  }
+}
+
+export interface InstallTrayOptions {
+  env?: NodeJS.ProcessEnv
+  /** Install SwiftBar.app via brew when absent (owner-sanctioned). Default false. */
+  installApp?: boolean
+  /** Launch + refresh SwiftBar after writing the plugin. Default false. */
+  launch?: boolean
+  run?: Runner
+  /** Injectable app-presence probe (tests). Default: swiftBarInstalled(). */
+  probeApp?: () => boolean
+}
+
+export interface InstallTrayResult {
+  pluginFile: string
+  pluginDir: string
+  /** Whether the plugin file bytes changed (false = already current). */
+  wrote: boolean
+  /** How the plugin dir was chosen. */
+  dir: 'existing-swiftbar' | 'dedicated-configured' | 'dedicated-only'
+  app: 'present' | 'installed' | 'install-failed' | 'absent'
+  appReason?: string
+  launched: boolean
+}
+
+/**
+ * Idempotently install the tray plugin. Steps (each safe to repeat):
+ *   1. install SwiftBar.app if absent && installApp (best-effort — a brew failure is
+ *      reported, not thrown; the plugin file still lands so it activates later).
+ *   2. resolve the target dir: an already-configured SwiftBar PluginDirectory is
+ *      RESPECTED (install into the user's dir); otherwise the dedicated ~/.iapeer dir,
+ *      and — only when SwiftBar is present — point SwiftBar at it via defaults.
+ *   3. write the plugin shim (skip if byte-identical; always ensure +x).
+ *   4. launch + refresh SwiftBar when launch && SwiftBar present.
+ */
+export function installTray(opts: InstallTrayOptions = {}): InstallTrayResult {
+  const env = opts.env ?? process.env
+  const run = opts.run ?? defaultRun
+  const probeApp = opts.probeApp ?? swiftBarInstalled
+  assertTraySandboxIsolated(env)
+  const binPath = iapeerBinPath(env)
+
+  // 1 — app
+  let app: InstallTrayResult['app'] = probeApp() ? 'present' : 'absent'
+  let appReason: string | undefined
+  if (app === 'absent' && opts.installApp) {
+    const r = installSwiftBarApp(run)
+    if (r.status === 0 || probeApp()) app = 'installed'
+    else {
+      app = 'install-failed'
+      appReason = (r.stderr || r.stdout || `brew exit ${r.status}`).trim().slice(0, 300)
+    }
+  }
+  const present = app === 'present' || app === 'installed'
+
+  // 2 — target dir
+  const existing = present ? readSwiftBarPluginDir(run) : undefined
+  let pluginDir: string
+  let dir: InstallTrayResult['dir']
+  if (existing && existsSync(existing)) {
+    pluginDir = existing
+    dir = 'existing-swiftbar'
+  } else {
+    pluginDir = dedicatedPluginDir(env)
+    if (present) {
+      setSwiftBarPluginDir(pluginDir, run)
+      dir = 'dedicated-configured'
+    } else {
+      dir = 'dedicated-only'
+    }
+  }
+  mkdirSync(pluginDir, { recursive: true })
+
+  // 3 — plugin file (idempotent write; always +x)
+  const pluginFile = join(pluginDir, PLUGIN_BASENAME)
+  const content = buildPluginShim(binPath)
+  let wrote = false
+  if (!existsSync(pluginFile) || readFileSync(pluginFile, 'utf8') !== content) {
+    writeFileSync(pluginFile, content, { mode: 0o755 })
+    wrote = true
+  } else {
+    try {
+      chmodSync(pluginFile, 0o755)
+    } catch {
+      /* best-effort */
+    }
+  }
+
+  // 4 — launch + refresh
+  let launched = false
+  if (opts.launch && present) {
+    launchSwiftBar(run)
+    refreshSwiftBar(run)
+    launched = true
+  }
+
+  return { pluginFile, pluginDir, wrote, dir, app, appReason, launched }
+}
+
+export interface UninstallTrayResult {
+  removed: string[]
+  /** SwiftBar was refreshed to drop the now-missing plugin. */
+  refreshed: boolean
+}
+
+/**
+ * Remove the tray plugin file from EVERY dir it could live in (the dedicated dir and
+ * a configured SwiftBar dir) and refresh SwiftBar. DELIBERATELY leaves SwiftBar.app
+ * installed (the user may run other plugins) and NEVER touches the fleet — the daemon,
+ * TUI and delivery keep running (acceptance criterion: GUI teardown ≠ fleet teardown).
+ */
+export function uninstallTray(
+  opts: { env?: NodeJS.ProcessEnv; launch?: boolean; run?: Runner; probeApp?: () => boolean } = {},
+): UninstallTrayResult {
+  const env = opts.env ?? process.env
+  const run = opts.run ?? defaultRun
+  assertTraySandboxIsolated(env)
+  const present = (opts.probeApp ?? swiftBarInstalled)()
+  const dirs = new Set<string>([dedicatedPluginDir(env)])
+  if (present) {
+    const existing = readSwiftBarPluginDir(run)
+    if (existing) dirs.add(existing)
+  }
+  const removed: string[] = []
+  for (const d of dirs) {
+    const f = join(d, PLUGIN_BASENAME)
+    if (existsSync(f)) {
+      rmSync(f, { force: true })
+      removed.push(f)
+    }
+  }
+  let refreshed = false
+  if (opts.launch && present) {
+    refreshSwiftBar(run)
+    refreshed = true
+  }
+  return { removed, refreshed }
+}
+
+export interface TrayStatus {
+  daemon: { fleet: boolean; version?: string; sock?: string; tcp?: string }
+  swiftbar: { installed: boolean; pluginDir?: string }
+  plugin: { installed: boolean; path?: string }
+}
+
+/** Read-only diagnostics — never repairs anything. */
+export function trayStatus(opts: { env?: NodeJS.ProcessEnv; run?: Runner; probeApp?: () => boolean } = {}): TrayStatus {
+  const env = opts.env ?? process.env
+  const run = opts.run ?? defaultRun
+  const addr = resolveFleetAddress({ env })
+  const installed = (opts.probeApp ?? swiftBarInstalled)()
+  const cfgDir = installed ? readSwiftBarPluginDir(run) : undefined
+  const searchDirs = [cfgDir, dedicatedPluginDir(env)].filter(Boolean) as string[]
+  const found = searchDirs.map(d => join(d, PLUGIN_BASENAME)).find(f => existsSync(f))
+  return {
+    daemon: { fleet: addr.fleet === 1, version: addr.version, sock: addr.sock, tcp: addr.tcp },
+    swiftbar: { installed, pluginDir: cfgDir },
+    plugin: { installed: Boolean(found), path: found },
+  }
+}

package/src/tray/render.ts

@@ -0,0 +1,243 @@
+// tray/render — PURE SwiftBar-format renderer for the fleet snapshot. No IO, fully
+// deterministic (a fixed snapshot + `now` → a fixed string), so it is unit-tested
+// directly. It consumes a snapshot modelled by its OWN local interfaces (the docs/15
+// shape) and ignores every field it does not name — client obligation 2 (additive
+// evolution: a new snapshot field must never break an old client). This module is the
+// second consumer of docs/15 after fleet.ts wrote it — the contract dogfood.
+//
+// SwiftBar output grammar (see docs/16-tray.md): lines before the first `---` are the
+// menu-bar title; lines after are the dropdown. Item params follow ` | key=value`.
+// Submenu depth is a `--` prefix per level. Click actions: `bash=<bin> paramN=…
+// terminal=<bool>` runs the binary (terminal=true opens Terminal.app — that is how a
+// peer row hands off to `iapeer attach`, the terminal-handoff the API deliberately
+// keeps client-side).
+
+const GLYPH: Record<'live' | 'asleep' | 'stopped', string> = { live: '●', asleep: '○', stopped: '✕' }
+
+const COLOR = {
+  meta: '#8b949e',
+  live: '#3fb950',
+  down: '#f85149',
+} as const
+
+// ── docs/15 snapshot shape (only the fields the tray reads) ───────────────────
+
+export interface TrayRuntime {
+  runtime: string
+  status: 'live' | 'asleep' | 'stopped'
+  attached?: boolean
+}
+
+export interface TrayPeer {
+  personality: string
+  intelligence?: string
+  runtimes: TrayRuntime[]
+  last_active_runtime?: string
+  last_active_ms?: number
+  attached?: boolean
+  launchd_managed?: boolean
+  wake_policy?: 'warm' | 'ephemeral'
+  queue_depth?: number
+}
+
+export interface TraySnapshot {
+  version?: string
+  host?: {
+    version?: string
+    uptimeSecs?: number
+    memory?: { provider: string; version: string; heartbeatAgeSecs: number | null } | null
+    voice?: { provider: string; version: string; heartbeatAgeSecs: number | null } | null
+    fda?: boolean | null
+  }
+  peers: TrayPeer[]
+}
+
+export interface RenderOptions {
+  /** Absolute path to the installed `iapeer` binary (embedded into click actions). */
+  binPath: string
+  /** Clock for age rendering (injectable for tests). */
+  now?: number
+}
+
+// ── param serialization ───────────────────────────────────────────────────────
+
+/** Serialize SwiftBar item params. Simple tokens stay bare; anything else is
+ *  double-quoted with embedded quotes escaped (SwiftBar accepts quoted values). */
+function params(pairs: Record<string, string | number | boolean | undefined>): string {
+  const parts: string[] = []
+  for (const [k, v] of Object.entries(pairs)) {
+    if (v === undefined) continue
+    const s = String(v)
+    const val = /^[\w.#/@-]+$/.test(s) ? s : `"${s.replace(/"/g, '\\"')}"`
+    parts.push(`${k}=${val}`)
+  }
+  return parts.length ? ` | ${parts.join(' ')}` : ''
+}
+
+/** One dropdown line at submenu `depth` (0 = top level). */
+function line(depth: number, text: string, p: Record<string, string | number | boolean | undefined> = {}): string {
+  return `${'--'.repeat(depth)}${text}${params(p)}`
+}
+
+/** A menu separator at submenu `depth`: the `--`×depth prefix + `---` (SwiftBar: a
+ *  top-level separator is `---`, a depth-1 one is `-----`, etc.). */
+function separator(depth: number): string {
+  return `${'--'.repeat(depth)}---`
+}
+
+// ── time helpers ────────────────────────────────────────────────────────────────
+
+export function fmtUptime(secs: number): string {
+  if (!Number.isFinite(secs) || secs < 0) return '?'
+  const d = Math.floor(secs / 86400)
+  const h = Math.floor((secs % 86400) / 3600)
+  const m = Math.floor((secs % 3600) / 60)
+  if (d > 0) return `${d}d ${h}h`
+  if (h > 0) return `${h}h ${m}m`
+  if (m > 0) return `${m}m`
+  return `${Math.floor(secs)}s`
+}
+
+export function fmtAge(ms: number, now: number): string {
+  const secs = Math.floor((now - ms) / 1000)
+  if (!Number.isFinite(secs)) return ''
+  if (secs < 45) return 'now'
+  const m = Math.floor(secs / 60)
+  if (m < 60) return `${m}m ago`
+  const h = Math.floor(m / 60)
+  if (h < 24) return `${h}h ago`
+  return `${Math.floor(h / 24)}d ago`
+}
+
+// ── peer status aggregation ─────────────────────────────────────────────────────
+
+function aggregate(p: TrayPeer): 'live' | 'asleep' | 'stopped' {
+  if (p.runtimes.some(r => r.status === 'live')) return 'live'
+  if (p.runtimes.some(r => r.status === 'asleep')) return 'asleep'
+  return 'stopped'
+}
+
+const RANK: Record<'live' | 'asleep' | 'stopped', number> = { live: 0, asleep: 1, stopped: 2 }
+
+// ── renderers ─────────────────────────────────────────────────────────────────
+
+const MANAGE_COMMANDS: Array<{ cmd: string; label: string }> = [
+  { cmd: 'wake', label: 'Wake' },
+  { cmd: 'stop', label: 'Stop' },
+  { cmd: 'start', label: 'Start' },
+  { cmd: 'new', label: 'New session (fresh)' },
+  { cmd: 'interrupt', label: 'Interrupt' },
+  { cmd: 'refresh', label: 'Refresh (soft-reload)' },
+  { cmd: 'compact', label: 'Compact dialogue' },
+]
+
+/** The full SwiftBar plugin output for a reachable daemon. */
+export function renderSwiftBar(snapshot: TraySnapshot, opts: RenderOptions): string {
+  const now = opts.now ?? Date.now()
+  const bin = opts.binPath
+  const peers = [...snapshot.peers].sort((a, b) => {
+    const r = RANK[aggregate(a)] - RANK[aggregate(b)]
+    return r !== 0 ? r : a.personality.localeCompare(b.personality)
+  })
+  const liveCount = snapshot.peers.filter(p => aggregate(p) === 'live').length
+
+  const lines: string[] = []
+  // ── menu-bar title: antenna icon + live-peer count ──
+  lines.push(line(0, String(liveCount), { sfimage: 'antenna.radiowaves.left.and.right' }))
+  lines.push('---')
+
+  // ── host header ──
+  const ver = snapshot.host?.version ?? snapshot.version ?? '?'
+  const up = snapshot.host?.uptimeSecs !== undefined ? ` · up ${fmtUptime(snapshot.host.uptimeSecs)}` : ''
+  lines.push(line(0, `iapeer ${ver}${up}`, { color: COLOR.meta }))
+  const providers = renderProviders(snapshot.host)
+  if (providers) lines.push(line(0, providers, { color: COLOR.meta }))
+  lines.push('---')
+
+  // ── peers ──
+  if (peers.length === 0) {
+    lines.push(line(0, 'no peers registered', { color: COLOR.meta }))
+  }
+  for (const p of peers) {
+    lines.push(...renderPeerRow(p, bin, now))
+  }
+
+  // ── footer ──
+  lines.push('---')
+  lines.push(line(0, 'Refresh', { refresh: true, sfimage: 'arrow.clockwise' }))
+  lines.push(line(0, `iapeer · fleet dashboard`, { color: COLOR.meta, size: 11 }))
+  return lines.join('\n') + '\n'
+}
+
+function renderProviders(host: TraySnapshot['host']): string {
+  if (!host) return ''
+  const seg: string[] = []
+  const one = (label: string, slot: { version: string; heartbeatAgeSecs: number | null } | null | undefined): void => {
+    if (!slot) return
+    // fresh heartbeat (< 90s) → ●, declared-but-silent → ○
+    const glyph = slot.heartbeatAgeSecs !== null && slot.heartbeatAgeSecs < 90 ? '●' : '○'
+    seg.push(`${label} ${glyph} ${slot.version}`)
+  }
+  one('mem', host.memory)
+  one('voice', host.voice)
+  if (host.fda === false) seg.push('⚠ no full-disk-access')
+  return seg.join(' · ')
+}
+
+function renderPeerRow(p: TrayPeer, bin: string, now: number): string[] {
+  const agg = aggregate(p)
+  const detail = p.runtimes.map(r => `${r.runtime}${GLYPH[r.status]}`).join(' ')
+  const badges =
+    (p.attached ? ' 👤' : '') +
+    (p.launchd_managed ? ' 🔒' : '') +
+    (p.wake_policy === 'ephemeral' && (p.queue_depth ?? 0) > 0 ? ` ⏳${p.queue_depth}` : '')
+  const ageStr = p.last_active_ms ? `  ${fmtAge(p.last_active_ms, now)}` : ''
+  const label = `${p.personality}  ${detail}${badges}${ageStr}`
+  const rowColor = agg === 'live' ? COLOR.live : COLOR.meta
+
+  const out: string[] = []
+  // The peer row IS the attach action: click → Terminal.app running `iapeer attach
+  // <peer>` (attach resolves its own runtime — default-anchored last-active, same as
+  // the CLI). terminal=true is the terminal-handoff docs/15 keeps client-side.
+  out.push(
+    line(0, label, {
+      color: rowColor,
+      bash: bin,
+      param1: 'attach',
+      param2: p.personality,
+      terminal: true,
+    }),
+  )
+  // Lifecycle controls live in a submenu (they route through the fleet command
+  // endpoints via `iapeer tray cmd …` — dogfooding POST /fleet/v1/peers/<p>/<cmd>).
+  out.push(line(1, 'Attach…', { bash: bin, param1: 'attach', param2: p.personality, terminal: true, sfimage: 'terminal' }))
+  out.push(separator(1))
+  for (const c of MANAGE_COMMANDS) {
+    out.push(
+      line(1, c.label, {
+        bash: bin,
+        param1: 'tray',
+        param2: 'cmd',
+        param3: c.cmd,
+        param4: p.personality,
+        terminal: false,
+        refresh: true,
+      }),
+    )
+  }
+  return out
+}
+
+/** The degraded output when no advertised daemon address answers (docs/15: "A
+ *  dashboard that cannot reach any advertised address should render the daemon as
+ *  down"). Distinct menu-bar icon + a red header; a Refresh item to retry. */
+export function renderDaemonDown(reason: string, opts: RenderOptions): string {
+  const lines: string[] = []
+  lines.push(line(0, '', { sfimage: 'exclamationmark.triangle.fill', color: COLOR.down }))
+  lines.push('---')
+  lines.push(line(0, 'iapeer daemon unreachable', { color: COLOR.down }))
+  lines.push(line(0, reason, { color: COLOR.meta }))
+  lines.push('---')
+  lines.push(line(0, 'Refresh', { refresh: true, sfimage: 'arrow.clockwise' }))
+  return lines.join('\n') + '\n'
+}