@agfpd/iapeer 0.4.63 → 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/15-fleet-api.md

@@ -106,9 +106,9 @@ GET /fleet/v1/events?replay=50
 - A comment `: connected` marks the transition from replay to live; `: hb` comments every ~15 s keep the connection alive.
 - Latency: live events surface within ~0.5 s (log-tail poll).
 
-Current `ev` vocabulary (grows over time — see obligation 1): `wake`, `supervise` (with `action`: `reaped-idle` = parked, `reaped-ephemeral`, `dead`→fresh/resume classification, `eager-orphan-fresh`, `skipped-error`…), `delivery`, `topic-note`, `ephemeral-drain`, `attach` / `attach-end`, `hosted-deliver`, `pty-host-failed`, `supervise-error`, `composer-queue-failed-notify`, `memory-provision`, `session-exit` (from `exits.log`, with `dead_status`/`dead_signal`).
+Current `ev` vocabulary (grows over time — see obligation 1): `wake`, `supervise` (with `action`: `reaped-idle` = parked, `reaped-ephemeral`, `dead`→fresh/resume classification, `eager-orphan-fresh`, `skipped-error`…), `stopped` / `started` (the stop/start verbs — an operator changed a peer's ✕/○ state; `action` is `stopped`/`started` for warm runtimes, `bootout`/`bootstrap` for always-on, with `reason` on failure), `delivery`, `topic-note`, `ephemeral-drain`, `attach` / `attach-end`, `hosted-deliver`, `pty-host-failed`, `supervise-error`, `composer-queue-failed-notify`, `memory-provision`, `session-exit` (from `exits.log`: `cause=child-exit` with `dead_status`/`dead_signal` when the session's process died on its own, `cause=shutdown-sigterm`/`shutdown-sigint` when the supervisor was torn down — reap/stop/new), `supervisor-uncaught` (a survivable supervisor fault left as forensics; the session keeps serving).
 
-What the headline states look like on the stream: a peer **waking** is `ev=wake`; a peer **parked to sleep** is `ev=supervise action=reaped-idle`; a **death** is `ev=session-exit` (immediately, from the supervisor) followed by the daemon's classification on its next pass.
+What the headline states look like on the stream: a peer **waking** is `ev=wake`; a peer **parked to sleep** is `ev=supervise action=reaped-idle`; an operator **stop/start** is `ev=stopped` / `ev=started`; a **death** is `ev=session-exit` (immediately, from the supervisor) followed by the daemon's classification on its next pass.
 
 ## Commands
 

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/15-fleet-api.md

@@ -106,9 +106,9 @@ GET /fleet/v1/events?replay=50
 - Комментарий `: connected` отмечает переход от replay к live; комментарии `: hb` каждые ~15 с держат соединение.
 - Латентность: живые события всплывают в пределах ~0.5 с (поллинг хвоста лога).
 
-Текущий словарь `ev` (растёт со временем — см. обязанность 1): `wake`, `supervise` (с `action`: `reaped-idle` = парковка, `reaped-ephemeral`, классификация `dead`→fresh/resume, `eager-orphan-fresh`, `skipped-error`…), `delivery`, `topic-note`, `ephemeral-drain`, `attach` / `attach-end`, `hosted-deliver`, `pty-host-failed`, `supervise-error`, `composer-queue-failed-notify`, `memory-provision`, `session-exit` (из `exits.log`, с `dead_status`/`dead_signal`).
+Текущий словарь `ev` (растёт со временем — см. обязанность 1): `wake`, `supervise` (с `action`: `reaped-idle` = парковка, `reaped-ephemeral`, классификация `dead`→fresh/resume, `eager-orphan-fresh`, `skipped-error`…), `stopped` / `started` (verb'ы stop/start — оператор изменил ✕/○-состояние пира; `action` — `stopped`/`started` для warm-рантаймов, `bootout`/`bootstrap` для always-on, с `reason` при неудаче), `delivery`, `topic-note`, `ephemeral-drain`, `attach` / `attach-end`, `hosted-deliver`, `pty-host-failed`, `supervise-error`, `composer-queue-failed-notify`, `memory-provision`, `session-exit` (из `exits.log`: `cause=child-exit` с `dead_status`/`dead_signal`, когда процесс сессии умер сам; `cause=shutdown-sigterm`/`shutdown-sigint`, когда супервизор был погашен — reap/stop/new), `supervisor-uncaught` (пережитый сбой супервизора, оставленный как форензика; сессия продолжает работать).
 
-Как выглядят главные состояния на потоке: **пробуждение** пира — `ev=wake`; **парковка в сон** — `ev=supervise action=reaped-idle`; **смерть** — `ev=session-exit` (немедленно, от супервизора), затем классификация демона на его следующем проходе.
+Как выглядят главные состояния на потоке: **пробуждение** пира — `ev=wake`; **парковка в сон** — `ev=supervise action=reaped-idle`; операторский **stop/start** — `ev=stopped` / `ev=started`; **смерть** — `ev=session-exit` (немедленно, от супервизора), затем классификация демона на его следующем проходе.
 
 ## Команды
 

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.63",
+  "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

@@ -253,12 +253,9 @@ export function stopPeer(personality: string, runtime: string | undefined, opts:
       killSession(sock, identity, env)
       const stderrText = (r.stderr ?? '').trim()
       const benign = r.status === 0 || r.status === 3 || /No such process/i.test(stderrText)
-      out.push({
-        personality,
-        runtime: rt,
-        action: 'bootout',
-        reason: benign ? undefined : `launchctl bootout exited ${r.status}${stderrText ? `: ${stderrText}` : ''}`,
-      })
+      const reason = benign ? undefined : `launchctl bootout exited ${r.status}${stderrText ? `: ${stderrText}` : ''}`
+      out.push({ personality, runtime: rt, action: 'bootout', reason })
+      appendLifecycleEvent(cfg.eventLogDir, { ev: 'stopped', identity, personality, runtime: rt, action: 'bootout', reason }, { env })
     } else {
       // A deliberate stop is a CLEAN PARK, not a death (stop→start must survive ≥
       // idle-reap): park-mark BEFORE the kill so the post-`start`
@@ -270,6 +267,12 @@ export function stopPeer(personality: string, runtime: string | undefined, opts:
       killSession(sock, identity, env)
       removeSessionState(cfg, identity)
       out.push({ personality, runtime: rt, action: 'stopped' })
+      // Durable trace (fleet-API follow-up): the verb was SILENT in lifecycle.log — a
+      // CLI stop changed the fleet state (● → ✕) with no event, so an SSE-fed client
+      // (tray class) showed a stale status indefinitely (no event ⇒ no snapshot
+      // re-read; only the initiator knew). One line per state-changing outcome; the
+      // refused-foreign-launchd branch changes nothing and stays silent.
+      appendLifecycleEvent(cfg.eventLogDir, { ev: 'stopped', identity, personality, runtime: rt, action: 'stopped' }, { env })
     }
   }
   return out
@@ -301,17 +304,17 @@ export function startPeer(personality: string, runtime: string | undefined, opts
       // sentinel fleet-guard + sandbox guard the raw spawn never had.)
       const r = launchctlBootstrap(personality, plist, env)
       const ok = r.state === 'loaded' || r.state === 'already-loaded' || r.state === 'skipped-sandbox'
-      out.push({
-        personality,
-        runtime: rt,
-        action: 'bootstrap',
-        reason: ok
-          ? undefined
-          : `launchctl bootstrap FAILED${r.detail ? `: ${r.detail}` : ''} — peer not started; manual rescue: launchctl bootstrap gui/$(id -u) ${plist}`,
-      })
+      const reason = ok
+        ? undefined
+        : `launchctl bootstrap FAILED${r.detail ? `: ${r.detail}` : ''} — peer not started; manual rescue: launchctl bootstrap gui/$(id -u) ${plist}`
+      out.push({ personality, runtime: rt, action: 'bootstrap', reason })
+      appendLifecycleEvent(cfg.eventLogDir, { ev: 'started', identity, personality, runtime: rt, action: 'bootstrap', reason }, { env })
     } else {
       clearStopped(cfg, identity)
       out.push({ personality, runtime: rt, action: 'started' })
+      // Durable trace — mirror of the `stopped` event in stopPeer (✕ → ○ is a state
+      // change an SSE-fed client must hear about).
+      appendLifecycleEvent(cfg.eventLogDir, { ev: 'started', identity, personality, runtime: rt, action: 'started' }, { env })
     }
   }
   return out
@@ -1162,7 +1165,9 @@ const BOOLEAN_FLAGS: ReadonlySet<string> = new Set([
   'no-telegram',
   'no-voice',
   'npx',
+  'plugin-only',
   'remove-codesign-identity',
+  'stream',
   'yes',
 ])
 
@@ -1272,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
@@ -2272,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
@@ -2288,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`,
         )
@@ -2466,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/supervisor/daemon.ts

@@ -25,6 +25,7 @@ import {
   splitDanglingEscape,
   stripQueries,
 } from './protocol.ts'
+import { formatEventLine } from '../storage/rotatelog.ts'
 import { attachedPath, geometryPath, pidPath, servePath, sockPath, writeGeometry, writePidFile } from './paths.ts'
 import { newStuckGate, nextBootAction, nextNagAction, paneIsStuck, type BootPredicates, type NagPredicate } from './boot.ts'
 import { modelToPlainText } from './render.ts'
@@ -289,6 +290,30 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
     return ok
   }
 
+  // ── death-trace (fleet-API follow-up, 05.07) ──────────────────────────────────
+  // exits.log is the durable «why did this session end» record. Before this, ONLY a
+  // child that died on its own (exit callback below) wrote a line; a SIGTERM'd
+  // supervisor (reap / stop / new / self-fresh — EVERY daemon-initiated teardown)
+  // killed the child and process.exit'ed before the callback could run, and a
+  // supervisor crash left nothing at all — exits.log stayed silent for weeks while
+  // sessions died (live gap: claude-boris server-dead 04.07 23:59 with ZERO forensics;
+  // the supervise classification even points the investigator at exits.log). Now every
+  // in-process exit path writes exactly one line: `exitLogged` dedups the child-exit
+  // callback vs the shutdown path. logfmt via the shared writer (quoted values parse
+  // intact in the fleet SSE stream). Out-of-process deaths (SIGKILL / OOM / Bun panic)
+  // remain unrecordable from here by nature — for those the supervise-tick reaped-gone
+  // classification in lifecycle.log stays the only trace.
+  let exitLogged = false
+  const appendExitEvent = (fields: Record<string, string | number | undefined>): void => {
+    if (!opts.exitLogPath) return
+    try {
+      mkdirSync(dirname(opts.exitLogPath), { recursive: true, mode: 0o700 })
+      appendFileSync(opts.exitLogPath, `${formatEventLine(Date.now(), fields)}\n`)
+    } catch {
+      /* best-effort — the trace must never block serving/teardown */
+    }
+  }
+
   const child = Bun.spawn(CMD, {
     cwd: opts.cwd ?? runDir,
     env,
@@ -337,20 +362,18 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
         // supervise-tick death classification + crash-loop accounting have the cause. host=supervisor
         // distinguishes the source. The Bun-native pty exit callback passes (exitCode, signalCode) like
         // onExit; fall back to the subprocess props. Best-effort — never blocks shutdown.
-        if (opts.exitLogPath) {
-          try {
-            mkdirSync(dirname(opts.exitLogPath), { recursive: true, mode: 0o700 }) // ensure the exits.log dir exists
-            const c = child as { exitCode?: number | null; signalCode?: number | null }
-            const status = exitCode ?? c.exitCode ?? ''
-            const signal = signalCode ?? c.signalCode ?? ''
-            appendFileSync(
-              opts.exitLogPath,
-              `ts=${new Date().toISOString()} ev=session-exit identity=${session} dead_status=${status} dead_signal=${signal} host=supervisor\n`,
-            )
-          } catch {
-            /* best-effort */
-          }
-        }
+        const c = child as { exitCode?: number | null; signalCode?: number | null }
+        const status = exitCode ?? c.exitCode
+        const signal = signalCode ?? c.signalCode
+        exitLogged = true // this IS the death record — shutdown below must not write a second one
+        appendExitEvent({
+          ev: 'session-exit',
+          identity: session,
+          dead_status: status ?? '',
+          dead_signal: signal ?? '',
+          cause: 'child-exit',
+          host: 'supervisor',
+        })
         shutdown()
       },
     },
@@ -554,9 +577,17 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
   writeGeometry(runDir, session, serveCols, serveRows) // initial geometry sidecar (= serve); updated on every real child resize
 
   let down = false
-  function shutdown(): void {
+  function shutdown(cause = 'shutdown'): void {
     if (down) return
     down = true
+    // Death-trace: a signalled shutdown kills the child below and process.exit()s
+    // immediately — the child exit callback never runs, so THIS is the only chance
+    // to record the session's end. `exitLogged` is already set when the child died
+    // on its own (the callback wrote the authoritative dead_status/dead_signal line).
+    if (!exitLogged) {
+      exitLogged = true
+      appendExitEvent({ ev: 'session-exit', identity: session, cause, host: 'supervisor' })
+    }
     if (paneLogFd >= 0)
       try {
         closeSync(paneLogFd)
@@ -582,18 +613,31 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
     }
     process.exit(0)
   }
-  process.on('SIGTERM', shutdown)
-  process.on('SIGINT', shutdown)
+  process.on('SIGTERM', () => shutdown('shutdown-sigterm'))
+  process.on('SIGINT', () => shutdown('shutdown-sigint'))
   process.on('SIGHUP', () => {
     /* daemon survives client window close */
   })
-  process.on('uncaughtException', e => {
+  // A survivable fault must still leave a trace: the console.error goes to the
+  // detached daemon's session log, which sat at 0 bytes for weeks on the live fleet —
+  // effectively invisible. Record it in exits.log too (ev=supervisor-uncaught; the
+  // session keeps serving — killing it here would regress the detach-crash robustness),
+  // so a later wedge/death postmortem can see the fault that preceded it.
+  const traceFault = (kind: string, e: unknown): void => {
     try {
-      console.error('[supervisor-daemon] uncaught', (e && (e as Error).stack) || e)
+      console.error(`[supervisor-daemon] ${kind}`, (e && (e as Error).stack) || e)
     } catch {
       /* */
     }
-  })
+    appendExitEvent({
+      ev: 'supervisor-uncaught',
+      identity: session,
+      kind,
+      reason: String((e as Error)?.stack ?? e).replace(/\s+/g, ' ').slice(0, 300),
+    })
+  }
+  process.on('uncaughtException', e => traceFault('exception', e))
+  process.on('unhandledRejection', e => traceFault('rejection', e))
 
   // ── boot-dialog driver (serving slice a) ────────────────────────────────────────
   // For a real runtime, answer the startup dialogs (codex trust/update/hooks, claude trust/resume)