@agfpd/iapeer 0.4.84 → 0.4.86

package/docs/10-messaging.md

@@ -34,7 +34,25 @@ The daemon finds the recipient in the registry and looks at its state:
 
 The key guarantee: `delivered` means the message actually landed in a live session (the daemon waited for confirmation), not that it was just sent into the void. If the session didn't confirm receipt in the allotted time, the daemon treats it as dead and doesn't lie about success.
 
-In every message's envelope travels the sender's nature (`intelligence`) — the recipient knows whether a human, an agent, or a service process is writing to it.
+In every message's envelope travels the sender's nature (`intelligence`) — the recipient knows whether a human, an agent, or a service process is writing to it — and the dispatch instant (`ts`): the moment the router accepted the send. The same instant is returned to the sender as the `ts` field of its `send_to_peer` result, so both sides of a conversation can literally compare timestamps — which is what makes an async desync (a reply addressing an already-outdated state) visible to the recipient instead of silent.
+
+## Envelope: wire form vs agent presentation
+
+The envelope exists in two renderings of the same content:
+
+- **Wire form** — the canonical durable shape: legacy attribute names (`from-personality` / `from-runtime` / `from-intelligence`), `ts` as a full local ISO instant with offset, the body always CDATA-wrapped, `<message>` tag. This is what travels through disk queues, what bridge runtimes (telegram / notifier / voicetalk) receive and parse, and what their pane logs show. It never slims: its bytes cost no tokens, and every deployed parser keeps working unchanged.
+- **Agent presentation** — rendered at the last hop wherever text enters an LLM context (a live delivery to a claude/codex session, a wake boot first-message, an ephemeral-queue drain):
+
+  ```
+  <iap from="boris" runtime="claude" intelligence="artificial" ts="01:23:45">
+  Reply via send_to_peer.
+  <msg>message body…</msg>
+  </iap>
+  ```
+
+  Short attribute names, `ts` compacted to local host time — time-only when the message was sent the same local calendar day it is delivered, date-prefixed (`2026-07-13 01:23:45`) otherwise, so a queue-drained or long-delayed message can never masquerade as fresh. The body is raw (no CDATA) unless it quotes envelope machinery itself — then it keeps the CDATA wrapping (a cosmetic fallback, nothing parses the presentation). The render is fail-open: any problem delivers the wire form as-is rather than risking the message.
+
+So host logs deliberately show two envelope shapes: bridge-bound pane logs carry the wire form, agent-bound pane logs and transcripts carry the compact presentation. The core decoder reads both name sets (and both `<message>`/`<msg>` tags), so any envelope ever emitted on the host — including historic transcripts — still decodes.
 
 ## Message limits
 

package/docs/16-tray.md

@@ -80,12 +80,12 @@ whole dashboard twice.
 
 | 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, **and register the login-autostart LaunchAgent**. `--plugin-only` writes just the plugin file (no app, no launch, no autostart — what the foundation install does). Idempotent. |
-| `iapeer tray uninstall` | Remove the plugin file, refresh SwiftBar, **and tear down the login-autostart LaunchAgent**. **Never touches the fleet** — the daemon, TUI and delivery keep running; SwiftBar.app is left installed (it may host other plugins). |
+| `iapeer tray install [--plugin-only]` | Install SwiftBar.app when absent (owner-sanctioned), point it at the plugin dir, write the plugin, launch + refresh, **and register the tray-host supervisor LaunchAgent** (login autostart + relaunch-on-death). `--plugin-only` writes just the plugin file (no app, no launch, no autostart — what the foundation install does). Idempotent. |
+| `iapeer tray uninstall` | Remove the plugin file, refresh SwiftBar, **and tear down the tray-host supervisor LaunchAgent**. **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 approve <id>` · `iapeer tray deny <id> [reason]` | Resolve a pending human-approval (docs/17) — `POST /fleet/v1/approvals/<id>/(approve\|deny)` over the same unix-first fleet client. The menu's Allow/Deny items call these; the single-queue invariant means the resolution is seen by every channel (CLI, telegram). |
-| `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, **is the login autostart registered**. Repairs nothing. |
+| `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, **is the tray-host supervisor registered**, and **is the menu-bar icon visible right now** (the persisted `NSStatusItem VisibleCC` state — the ground truth to read first when "the icon is gone" is reported; no screen needed). Repairs nothing. |
 
 ## How it is wired
 
@@ -102,25 +102,32 @@ plugin is installed into the user's own dir); otherwise a dedicated
 reads on launch (it is not sandboxed and stores no security-scoped bookmark), so the
 folder picker is skipped.
 
-Login autostart: activating the tray registers a user LaunchAgent
-`~/Library/LaunchAgents/com.agfpd.iapeer.tray.plist` (RunAtLoad, no KeepAlive) whose
-`ProgramArguments` are `open -g -b com.ameba.SwiftBar` — so SwiftBar (and with it the
-fleet dashboard + approval badge) comes back on its own after a reboot, with no manual
-`open -a SwiftBar`. A **LaunchAgent** is used deliberately, not a System Events "Login
-Item" nor SMAppService: a Login Item needs the invoking process to hold Automation TCC
-over System Events (attributed to whatever parent runs the verb — fragile in a headless /
-`iapeer update` context), and SMAppService can only register a helper the *target* app
-ships (we cannot register the third-party SwiftBar with it from a CLI). The LaunchAgent
-needs no TCC and reuses the foundation's idempotent plist lifecycle: the plist is
-byte-stable (write-if-changed), carries the `com.iapeer.managed` ownership sentinel, and
-is bootstrapped/cycled undead-safe — so re-activation never plants a duplicate. It is
-**RunAtLoad-only** (fire once at login) rather than KeepAlive, because the `open` process
-exits immediately once SwiftBar is up (KeepAlive would respawn-storm it) and supervising
-SwiftBar itself would fight the user quitting it. `tray uninstall` boots it out and
-removes the plist (only our own sentinel-marked file — a foreign plist at the label is
-left untouched). The label lives in the foundation's own `com.agfpd.*` namespace, never
-`com.iapeer.<personality>` (the persistent-peer fleet), so the H4 launchd-owned
-sweep-guard can never mistake it for a peer.
+Tray-host supervision: activating the tray registers a user LaunchAgent
+`~/Library/LaunchAgents/com.agfpd.iapeer.tray.plist` (RunAtLoad **and KeepAlive**) that
+runs a tiny `/bin/sh` watchdog loop: every 5 s, if no SwiftBar process exists, `open -g
+-b com.ameba.SwiftBar` (a no-op activation when it is already running — race-safe, never
+a duplicate instance; an absent SwiftBar.app backs off 5 min). So SwiftBar — and with it
+the fleet dashboard + approval badge — comes back on its own after a reboot AND within
+seconds after a crash or a stray kill. The tray is the owner's fleet-visibility surface;
+a silently-dead SwiftBar hides the state of the whole system, so its lifetime is
+supervised, not fire-and-forget. Deliberate consequence: quitting SwiftBar by hand also
+relaunches it — the supported off-switch is `iapeer tray uninstall`. launchd must NOT
+KeepAlive `open` itself (it exits the moment SwiftBar is up — KeepAlive on it is a
+respawn storm); KeepAlive guards the long-lived loop process. A **LaunchAgent** is used
+deliberately, not a System Events "Login Item" nor SMAppService: a Login Item needs the
+invoking process to hold Automation TCC over System Events (attributed to whatever
+parent runs the verb — fragile in a headless / `iapeer update` context), and
+SMAppService can only register a helper the *target* app ships (we cannot register the
+third-party SwiftBar with it from a CLI). The LaunchAgent needs no TCC and reuses the
+foundation's idempotent plist lifecycle: the plist is byte-stable (write-if-changed),
+carries the `com.iapeer.managed` ownership sentinel, and is bootstrapped/cycled
+undead-safe — so re-activation never plants a duplicate, and a foundation install
+(`iapeer update`) upgrades an already-registered agent's plist in place (bytes-changed →
+re-cycle). `tray uninstall` boots it out and removes the plist (only our own
+sentinel-marked file — a foreign plist at the label is left untouched). The label lives
+in the foundation's own `com.agfpd.*` namespace, never `com.iapeer.<personality>` (the
+persistent-peer fleet), so the H4 launchd-owned sweep-guard can never mistake it for a
+peer.
 
 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.
@@ -128,6 +135,38 @@ configured with `IAPEER_BEARER_TOKEN`, the plugin's environment must carry it to
 Config: `IAPEER_TRAY_HEARTBEAT_MS` tunes the heartbeat cadence (default 15 s, clamped
 1 s…10 min).
 
+## Icon visibility (why the stream writes in 512-byte quanta)
+
+SwiftBar v2.0.1 decodes **every pipe chunk independently** (`RunScript.swift`:
+`String(data: availableData, encoding: .utf8)` per readability callback). A chunk
+boundary that lands inside a multi-byte UTF-8 character makes that decode `nil`;
+`StreamablePlugin` treats `nil` as "clear content", and `MenuBarItem._updateMenu` answers
+empty content with `hide()` — the `NSStatusItem` vanishes from the menu bar. Worse, the
+item has an `autosaveName`, so AppKit **persists** the hidden state
+(`NSStatusItem VisibleCC <plugin>` = 0 in SwiftBar's defaults): the icon stays gone
+across SwiftBar restarts until some later update calls `show()`.
+
+The tray's menu block is tens of kilobytes of emoji/box-glyph-rich text; a single
+`write(2)` of it reaches the reader in pipe-buffer-fill chunks (measured live:
+16384+16384+2400 — byte-arbitrary boundaries), so with a static fleet the same bad
+boundary recurred every heartbeat and the icon stayed invisible for hours (owner
+incident 13.07.2026, reproduced deterministically with a probe plugin that split an
+emoji across two writes).
+
+Two layers make the class impossible:
+
+1. **Atomic UTF-8 quanta** — `tray render --stream` writes its output in chunks of
+   ≤512 bytes (`PIPE_BUF`: writes of at most that size into a pipe are atomic,
+   all-or-nothing), each ending on a UTF-8 character boundary. The pipe buffer then only
+   ever contains whole quanta and every chunk SwiftBar can see is valid UTF-8 — the nil
+   decode cannot happen by construction.
+2. **Freshness stamp** — every rendered block (and every daemon-down block) carries a
+   `HH:MM:SS` footer clock, so consecutive emits always differ and SwiftBar runs its
+   update path (which starts with `show()`) on every heartbeat. Any hidden icon —
+   whatever hid it (an accidental ⌘-drag removal, a stale persisted `VisibleCC` flag, a
+   future SwiftBar quirk) — recovers within one heartbeat (≤15 s) instead of staying
+   invisible while the fleet is static.
+
 ## Client obligations
 
 Because the tray is a Fleet API client, it obeys the normative rules in

package/docs/ru/16-tray.md

@@ -76,12 +76,12 @@ SwiftBar.app, если его нет.
 
 | Verb | Что делает |
 |---|---|
-| `iapeer tray install [--plugin-only]` | Доустановит SwiftBar.app, если его нет (санкция владельца), нацелит его на каталог плагинов, запишет плагин, запустит + обновит **и зарегистрирует LaunchAgent автозапуска при логине**. `--plugin-only` пишет только файл плагина (без приложения, запуска и автозапуска — так делает foundation-install). Идемпотентно. |
-| `iapeer tray uninstall` | Удалит файл плагина, обновит SwiftBar **и снесёт LaunchAgent автозапуска**. **Флот не трогает** — демон, TUI и доставка живут; SwiftBar.app остаётся (может держать другие плагины). |
+| `iapeer tray install [--plugin-only]` | Доустановит SwiftBar.app, если его нет (санкция владельца), нацелит его на каталог плагинов, запишет плагин, запустит + обновит **и зарегистрирует LaunchAgent-супервизор tray-хоста** (автозапуск при логине + перезапуск после смерти). `--plugin-only` пишет только файл плагина (без приложения, запуска и автозапуска — так делает foundation-install). Идемпотентно. |
+| `iapeer tray uninstall` | Удалит файл плагина, обновит SwiftBar **и снесёт LaunchAgent-супервизор tray-хоста**. **Флот не трогает** — демон, 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 approve <id>` · `iapeer tray deny <id> [reason]` | Резолв ожидающего human-approval (docs/17) — `POST /fleet/v1/approvals/<id>/(approve\|deny)` через тот же unix-first fleet-клиент. Пункты Allow/Deny меню зовут это; инвариант единой очереди — резолв виден каждому каналу (CLI, telegram). |
-| `iapeer tray status` | Только чтение: жив ли fleet API (из `router.json`), установлен ли SwiftBar и где его каталог плагинов, на месте ли файл плагина, **зарегистрирован ли автозапуск**. Ничего не чинит. |
+| `iapeer tray status` | Только чтение: жив ли fleet API (из `router.json`), установлен ли SwiftBar и где его каталог плагинов, на месте ли файл плагина, **зарегистрирован ли супервизор tray-хоста** и **видима ли иконка в менюбаре прямо сейчас** (персистентное состояние `NSStatusItem VisibleCC` — ground truth, который читают первым при жалобе «иконка пропала»; экран не нужен). Ничего не чинит. |
 
 ## Как устроено
 
@@ -97,24 +97,30 @@ SwiftBar.app, если его нет.
 который SwiftBar читает при запуске (он не sandboxed и не хранит security-scoped bookmark),
 поэтому окно выбора папки пропускается.
 
-Автозапуск при логине: активация трея регистрирует пользовательский LaunchAgent
-`~/Library/LaunchAgents/com.agfpd.iapeer.tray.plist` (RunAtLoad, без KeepAlive), чьи
-`ProgramArguments` — `open -g -b com.ameba.SwiftBar`, так что SwiftBar (а с ним fleet-дашборд
-и бейдж аппрувов) сам поднимается после перезагрузки, без ручного `open -a SwiftBar`.
-**LaunchAgent** выбран намеренно, не «Login Item» через System Events и не SMAppService: Login
-Item требует, чтобы вызывающий процесс держал Automation-TCC на System Events (грант
-атрибутируется тому родителю, что запустил verb — хрупко в headless / `iapeer update`
-контексте), а SMAppService умеет регистрировать только хелпер, который несёт *само* целевое
-приложение (сторонний SwiftBar так из CLI не зарегистрировать). LaunchAgent не требует TCC и
-переиспользует идемпотентный plist-жизненный цикл foundation: plist байт-стабилен (пишется
-только при изменении), несёт sentinel владения `com.iapeer.managed` и bootstrap'ится/
-пересоздаётся undead-safe — повторная активация не плодит дубль. Он **RunAtLoad-only** (сработать
-один раз при логине), а не KeepAlive, потому что процесс `open` завершается сразу, как SwiftBar
-поднят (KeepAlive устроил бы respawn-шторм), а супервизия самого SwiftBar боролась бы с
-пользователем, который его закрыл. `tray uninstall` делает bootout и удаляет plist (только наш
-файл с sentinel — чужой plist на этом лейбле не трогается). Лейбл живёт в собственном namespace
-foundation `com.agfpd.*`, никогда не `com.iapeer.<personality>` (флот persistent-пиров), поэтому
-H4-страж launchd-owned пиров не может принять его за пира.
+Супервизия tray-хоста: активация трея регистрирует пользовательский LaunchAgent
+`~/Library/LaunchAgents/com.agfpd.iapeer.tray.plist` (RunAtLoad **и KeepAlive**), который
+крутит крошечный watchdog-цикл `/bin/sh`: раз в 5 с, если процесса SwiftBar нет — `open -g -b
+com.ameba.SwiftBar` (на уже работающем приложении это no-op-активация — гонко-безопасно, дубль
+инстанса невозможен; при отсутствии SwiftBar.app — бэкофф 5 мин). Так SwiftBar — а с ним
+fleet-дашборд и бейдж аппрувов — сам поднимается и после перезагрузки, И за секунды после
+краша или случайного kill. Трей — поверхность видимости флота для владельца; молчаливо
+мёртвый SwiftBar прячет состояние всей системы, поэтому его жизнь супервизируется, а не
+«запустили и забыли». Намеренное следствие: закрытый руками SwiftBar тоже перезапустится —
+штатный выключатель это `iapeer tray uninstall`. launchd НЕ должен KeepAlive'ить сам `open`
+(тот завершается сразу, как SwiftBar поднят — KeepAlive на нём это respawn-шторм); KeepAlive
+сторожит долгоживущий процесс цикла. **LaunchAgent** выбран намеренно, не «Login Item» через
+System Events и не SMAppService: Login Item требует, чтобы вызывающий процесс держал
+Automation-TCC на System Events (грант атрибутируется тому родителю, что запустил verb —
+хрупко в headless / `iapeer update` контексте), а SMAppService умеет регистрировать только
+хелпер, который несёт *само* целевое приложение (сторонний SwiftBar так из CLI не
+зарегистрировать). LaunchAgent не требует TCC и переиспользует идемпотентный plist-жизненный
+цикл foundation: plist байт-стабилен (пишется только при изменении), несёт sentinel владения
+`com.iapeer.managed` и bootstrap'ится/пересоздаётся undead-safe — повторная активация не
+плодит дубль, а foundation-install (`iapeer update`) апгрейдит plist уже зарегистрированного
+агента на месте (байты изменились → пере-cycle). `tray uninstall` делает bootout и удаляет
+plist (только наш файл с sentinel — чужой plist на этом лейбле не трогается). Лейбл живёт в
+собственном namespace foundation `com.agfpd.*`, никогда не `com.iapeer.<personality>` (флот
+persistent-пиров), поэтому H4-страж launchd-owned пиров не может принять его за пира.
 
 Авторизация — как у Fleet API: на open-local хосте bearer не нужен; если демон настроен с
 `IAPEER_BEARER_TOKEN`, окружение плагина тоже должно его нести.
@@ -122,6 +128,38 @@ H4-страж launchd-owned пиров не может принять его з
 Конфиг: `IAPEER_TRAY_HEARTBEAT_MS` настраивает каденцию хартбита (по умолчанию 15 с, зажато
 1 с…10 мин).
 
+## Видимость иконки (почему стрим пишет квантами по 512 байт)
+
+SwiftBar v2.0.1 декодирует **каждый чанк пайпа независимо** (`RunScript.swift`:
+`String(data: availableData, encoding: .utf8)` на каждый readability-коллбек). Граница
+чанка внутри многобайтового UTF-8-символа даёт `nil`; `StreamablePlugin` трактует `nil`
+как «очисти контент», а `MenuBarItem._updateMenu` отвечает на пустой контент `hide()` —
+`NSStatusItem` исчезает из менюбара. Хуже: у айтема есть `autosaveName`, и AppKit
+**персистит** скрытость (`NSStatusItem VisibleCC <plugin>` = 0 в defaults SwiftBar) —
+иконка остаётся скрытой через рестарты SwiftBar, пока какой-нибудь следующий апдейт не
+позовёт `show()`.
+
+Меню-блок трея — десятки килобайт текста, насыщенного эмодзи и бокс-глифами; один
+`write(2)` доезжает до читателя чанками по заполнению пайп-буфера (замерено живьём:
+16384+16384+2400 — границы побайтово произвольны), поэтому при статичном флоте одна и та
+же плохая граница повторялась каждый хартбит и иконка была невидима часами (инцидент
+владельца 13.07.2026, детерминированно воспроизведён probe-плагином, разрезавшим эмодзи
+между двумя write).
+
+Класс закрыт двумя слоями:
+
+1. **Атомарные UTF-8-кванты** — `tray render --stream` пишет вывод кусками ≤512 байт
+   (`PIPE_BUF`: записи не больше этого размера в пайп атомарны, всё-или-ничего), каждый
+   заканчивается на границе UTF-8-символа. В пайп-буфере тогда лежат только целые
+   кванты, и любой чанк, который SwiftBar может увидеть, — валидный UTF-8: nil-декод
+   невозможен по построению.
+2. **Штамп свежести** — каждый отрендеренный блок (и каждый блок daemon-down) несёт в
+   футере часы `HH:MM:SS`, так что соседние emit'ы всегда различаются и SwiftBar гоняет
+   свой update-путь (начинающийся с `show()`) на каждом хартбите. Любая скрытая иконка —
+   чем бы её ни скрыло (случайный ⌘-drag, залипший персистентный флаг `VisibleCC`,
+   будущая причуда SwiftBar) — восстанавливается за один хартбит (≤15 с), а не висит
+   невидимой, пока флот статичен.
+
 ## Обязанности клиента
 
 Поскольку трей — клиент Fleet API, он соблюдает нормативные правила из

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.84",
+  "version": "0.4.86",
   "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

@@ -2607,8 +2607,10 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
                 `  sock: ${s.daemon.sock ?? '—'}\n` +
                 `  tcp:  ${s.daemon.tcp ?? '—'}\n` +
                 `SwiftBar: ${s.swiftbar.installed ? `installed (plugin dir: ${s.swiftbar.pluginDir ?? 'unset'})` : 'not installed'}\n` +
+                // the persisted NSStatusItem visibility — ground truth for "the icon is gone"
+                `menu-bar icon: ${s.swiftbar.iconVisible === undefined ? 'unknown (no persisted state)' : s.swiftbar.iconVisible ? 'visible' : 'HIDDEN (persisted NSStatusItem VisibleCC=0)'}\n` +
                 `plugin: ${s.plugin.installed ? s.plugin.path : 'not installed'}\n` +
-                `login autostart: ${s.autostart.registered ? s.autostart.path : 'not registered'}\n`,
+                `supervisor (autostart): ${s.autostart.registered ? s.autostart.path : 'not registered'}\n`,
             )
             return 0
           }

package/src/codec/index.ts

@@ -30,11 +30,37 @@ export interface EnvelopeInput {
   fromPersonality: string
   fromRuntime: Runtime
   fromIntelligence: Intelligence
+  /** ISO-8601 LOCAL instant with offset (formatSentAt) — the moment the router
+   *  ACCEPTED the send; the same string is returned to the sender as the `ts`
+   *  field of its send_to_peer result, so recipient-side `ts` and sender-side
+   *  `ts` correspond literally. Rendered as the `ts` open-tag attribute.
+   *  ADDITIVE and optional: every known envelope consumer reads attributes by
+   *  NAME and ignores unknown ones; absent on legacy envelopes. On the WIRE this
+   *  is always the FULL date-time (durable stores — disk queues, pane logs —
+   *  must be unambiguous); the agent-facing render compacts it (see
+   *  renderEnvelopeForAgent). */
+  sentAt?: string
   topic?: string
   attachments?: readonly string[]
   message: string
 }
 
+/** Format a Date as ISO-8601 LOCAL time with numeric offset, second precision:
+ *  `2026-07-14T01:23:45+03:00`. Local (not UTC-Z) on purpose: the fleet's agents
+ *  compare envelope timestamps against their LOCAL statusline clock — a Z-form
+ *  invites silent off-by-offset misreads by an LLM reader. */
+export function formatSentAt(date: Date): string {
+  const pad = (n: number): string => String(n).padStart(2, '0')
+  const offMin = -date.getTimezoneOffset() // minutes EAST of UTC
+  const sign = offMin >= 0 ? '+' : '-'
+  const abs = Math.abs(offMin)
+  return (
+    `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}` +
+    `T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}` +
+    `${sign}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`
+  )
+}
+
 function escapeAttr(value: string): string {
   return value
     .replace(/&/g, '&')
@@ -49,12 +75,20 @@ function cdata(value: string): string {
   return `<![CDATA[${value.replaceAll(']]>', ']]]]><![CDATA[>')}]]>`
 }
 
+/** WIRE encoder — the canonical durable form (disk queues, bridge deliveries,
+ *  pane logs): legacy attribute names + always-CDATA body, so every deployed
+ *  sibling parser (telegram-/notifier-/voicetalk-runtime) keeps working
+ *  unchanged. `ts` is the only additive attribute (envelope-compaction F).
+ *  Agent-bound deliveries are re-rendered compactly at the LAST hop — see
+ *  renderEnvelopeForAgent; the wire form itself never slims (its bytes cost no
+ *  tokens; only the LLM-context presentation does). */
 export function buildEnvelope(input: EnvelopeInput): string {
   const attrs = [
     `from-personality="${escapeAttr(input.fromPersonality)}"`,
     `from-runtime="${escapeAttr(input.fromRuntime)}"`,
     `from-intelligence="${escapeAttr(input.fromIntelligence)}"`,
   ]
+  if (input.sentAt) attrs.push(`ts="${escapeAttr(input.sentAt)}"`)
   const topic = input.topic?.trim()
   if (topic) {
     attrs.push(`topic="${escapeAttr(topic.slice(0, MAX_TOPIC_LEN))}"`)
@@ -146,13 +180,21 @@ export interface IapEnvelope {
   fromPersonality: string
   fromRuntime: Runtime
   fromIntelligence?: Intelligence
+  /** The sender's dispatch instant (`ts` attribute) — full local ISO on the wire;
+   *  absent on legacy envelopes. */
+  sentAt?: string
   topic?: string
   attachments: string[]
   message: string
 }
 
+/** NAME-ANCHORED attribute lookup. The anchor `(^|\s)` is load-bearing: the old
+ *  unanchored regex made `runtime="` match the TAIL of `from-runtime="…"` (and
+ *  `intelligence="` the tail of `from-intelligence="…"`) — a latent mine that the
+ *  read-both decoder below would have stepped on (the short-name lookup must NOT
+ *  be satisfied by a legacy long-name attribute). */
 function attrValue(attrs: string, name: string): string | undefined {
-  const re = new RegExp(`${name}="([^"]*)"`)
+  const re = new RegExp(`(?:^|\\s)${name}="([^"]*)"`)
   const m = re.exec(attrs)
   return m ? unescapeAttr(m[1]) : undefined
 }
@@ -167,25 +209,34 @@ function unescapeAttr(value: string): string {
     .replace(/&amp;/g, '&')
 }
 
+/** READ-BOTH decoder: accepts the legacy wire names (`from-personality` /
+ *  `from-runtime` / `from-intelligence`, `<message>`) AND the compact
+ *  presentation names (`from` / `runtime` / `intelligence`, `<msg>`) — so any
+ *  envelope form ever emitted on this host (wire, agent-facing render, historic
+ *  transcripts) decodes. Short names win when both are present. */
 export function decodeEnvelope(xml: string): IapEnvelope {
   const open = /^<iap\s+([^>]*)>/.exec(xml.trim())
   if (!open) throw new IapError('invalid IAP envelope: missing <iap ...>')
-  const fromPersonality = attrValue(open[1], 'from-personality')
-  const fromRuntime = attrValue(open[1], 'from-runtime')
+  const fromPersonality = attrValue(open[1], 'from') ?? attrValue(open[1], 'from-personality')
+  const fromRuntime = attrValue(open[1], 'runtime') ?? attrValue(open[1], 'from-runtime')
   if (!fromPersonality || !fromRuntime) {
     throw new IapError('invalid IAP envelope: missing from-personality/from-runtime')
   }
   // READ-COMPAT: a legacy peer (live telegram) may stamp from-intelligence="human";
   // normalize human→natural / scripted→absent, drop a genuinely unknown value.
-  const fromIntelligence = normalizeIntelligenceValue(attrValue(open[1], 'from-intelligence'))
-  const message = readTagContent(xml, 'message')
+  const fromIntelligence = normalizeIntelligenceValue(
+    attrValue(open[1], 'intelligence') ?? attrValue(open[1], 'from-intelligence'),
+  )
+  const message = readTagContent(xml, 'message') ?? readTagContent(xml, 'msg')
   if (message === undefined) throw new IapError('invalid IAP envelope: missing message')
   const attachmentsRaw = readTagContent(xml, 'attachments')
   const topic = attrValue(open[1], 'topic')
+  const sentAt = attrValue(open[1], 'ts')
   return {
     fromPersonality,
     fromRuntime,
     ...(fromIntelligence ? { fromIntelligence } : {}),
+    ...(sentAt ? { sentAt } : {}),
     ...(topic ? { topic } : {}),
     attachments: attachmentsRaw
       ? attachmentsRaw.split('\n').map(item => item.trim()).filter(Boolean)
@@ -209,7 +260,12 @@ function openTagVerdict(candidate: string): 'valid' | 'invalid' | 'incomplete' {
     return unclosed && candidate.length <= MAX_OPEN_TAG_LEN ? 'incomplete' : 'invalid'
   }
   if (m[0].length > MAX_OPEN_TAG_LEN) return 'invalid'
-  return m[1].includes('from-personality="') && m[1].includes('from-runtime="') ? 'valid' : 'invalid'
+  // Read-both (envelope-compaction F): a real open tag carries the required pair
+  // under EITHER naming — legacy wire (from-personality/from-runtime) or compact
+  // presentation (from/runtime, name-anchored so a legacy tail never satisfies it).
+  const hasPersonality = m[1].includes('from-personality="') || /(?:^|\s)from="/.test(m[1])
+  const hasRuntime = m[1].includes('from-runtime="') || /(?:^|\s)runtime="/.test(m[1])
+  return hasPersonality && hasRuntime ? 'valid' : 'invalid'
 }
 
 /**
@@ -257,3 +313,85 @@ export function extractEnvelopes(buffer: string): { envelopes: string[]; rest: s
     rest = rest.slice(envelopeEnd)
   }
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Agent-facing presentation render (envelope-compaction F)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Presentation-hybrid gate: a body that itself contains envelope machinery
+ *  (a quoted envelope, tag markers, CDATA syntax) or a literal CR keeps its
+ *  CDATA wrapping in the presentation too — the cost of the gate firing is
+ *  purely COSMETIC (the agent sees today's CDATA form), whereas rendering such
+ *  a body raw would show the agent a "broken" nested envelope. Plain `<` (code
+ *  snippets etc.) renders raw: nothing parses the presentation. */
+const PRESENTATION_CDATA_MARKERS = [
+  '<iap ',
+  '</iap>',
+  '<message>',
+  '</message>',
+  '<msg>',
+  '</msg>',
+  '<attachments>',
+  '</attachments>',
+  '<![CDATA[',
+  ']]>',
+  '\r',
+] as const
+
+function presentBody(value: string): string {
+  return PRESENTATION_CDATA_MARKERS.some(marker => value.includes(marker)) ? cdata(value) : value
+}
+
+/** Compact the wire `ts` (full local ISO with offset) for the agent's eyes:
+ *  time-only `01:23:45` when the send happened on the SAME local calendar day
+ *  as the render (the normal case), date-prefixed `2026-07-13 01:23:45` when it
+ *  did not (queue drains, long sleeps, midnight crossings) — so a stale message
+ *  can never masquerade as fresh. Renders happen at the LAST delivery hop, so
+ *  "today" is delivery-time local. An unparseable ts passes through verbatim. */
+function renderTsForAgent(sentAt: string, now: Date): string {
+  const d = new Date(sentAt)
+  if (Number.isNaN(d.getTime())) return sentAt
+  const pad = (n: number): string => String(n).padStart(2, '0')
+  const time = `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`
+  const sameLocalDay =
+    d.getFullYear() === now.getFullYear() && d.getMonth() === now.getMonth() && d.getDate() === now.getDate()
+  return sameLocalDay ? time : `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${time}`
+}
+
+/**
+ * Render a WIRE envelope into the compact agent-facing presentation:
+ *
+ *   <iap from="boris" runtime="claude" intelligence="artificial" ts="01:23:45">
+ *   Reply via send_to_peer.
+ *   <msg>raw body…</msg>
+ *   </iap>
+ *
+ * Short attribute names, time-only `ts` (cross-day rule above), raw body
+ * (hybrid CDATA when the body quotes envelope machinery). Called ONLY at the
+ * two hops where text enters an LLM context (composeFirstMessage — wake boot +
+ * ephemeral drain; deliverWarm — live paths, gated on agent runtimes); bridge
+ * targets always receive the wire form their parsers expect.
+ *
+ * FAIL-OPEN: any decode/render problem returns the wire text unchanged — a
+ * presentation hiccup must never lose or mangle a delivery.
+ */
+export function renderEnvelopeForAgent(wire: string, now: Date = new Date()): string {
+  try {
+    const env = decodeEnvelope(wire)
+    const attrs = [`from="${escapeAttr(env.fromPersonality)}"`, `runtime="${escapeAttr(env.fromRuntime)}"`]
+    if (env.fromIntelligence) attrs.push(`intelligence="${escapeAttr(env.fromIntelligence)}"`)
+    if (env.sentAt) attrs.push(`ts="${escapeAttr(renderTsForAgent(env.sentAt, now))}"`)
+    if (env.topic) attrs.push(`topic="${escapeAttr(env.topic)}"`)
+    return [
+      `<iap ${attrs.join(' ')}>`,
+      IAP_INSTRUCTION,
+      ...(env.attachments.length
+        ? [`<attachments>${presentBody(env.attachments.join('\n'))}</attachments>`]
+        : []),
+      `<msg>${presentBody(env.message)}</msg>`,
+      '</iap>',
+    ].join('\n')
+  } catch {
+    return wire // fail-open: deliver the wire form rather than risk the message
+  }
+}

package/src/core/constants.ts

@@ -197,8 +197,9 @@ export const PEERS_HOME_DIR = 'peers'
 export const LAUNCHD_LABEL_PREFIX = 'com.iapeer.'
 export const DAEMON_PLIST_LABEL = 'com.agfpd.iapeer'
 
-export const IAP_INSTRUCTION =
-  'IAP message from known peers. Reply via send_to_peer.'
+// Shortened 0.4.86 (envelope-compaction F): the long preamble duplicated doctrine
+// (origin-routing) for live sessions; the reply-routing cue is the load-bearing part.
+export const IAP_INSTRUCTION = 'Reply via send_to_peer.'
 
 export const ALWAYS_LOAD_META = {
   'anthropic/alwaysLoad': true,

package/src/daemon/index.ts

@@ -121,7 +121,7 @@ export function buildSendDescription(): string {
     'Peers can be agents, humans, or services. Runtime is the delivery surface, not the peer type.',
     'Current delivery supports any runtime endpoint that follows the IAP tmux socket convention. Claude/Codex are built-in local runtimes; external runtimes such as telegram can be exposed by runtime-router packages.',
     '',
-    "Use `personality`, not a runtime-prefixed identity. Set `runtime` to target a specific declared runtime for this send. If that runtime is warm-asleep, the daemon wakes it and delivers there; use this to intentionally bring up a second session of the same peer in parallel to the default runtime (for example codex alongside claude). Inbound peer messages arrive as <iap from-personality=\"...\" from-runtime=\"...\" from-intelligence=\"...\"> blocks. The topic attribute is optional.",
+    "Use `personality`, not a runtime-prefixed identity. Set `runtime` to target a specific declared runtime for this send. If that runtime is warm-asleep, the daemon wakes it and delivers there; use this to intentionally bring up a second session of the same peer in parallel to the default runtime (for example codex alongside claude). Inbound peer messages arrive as <iap from=\"...\" runtime=\"...\" intelligence=\"...\" ts=\"...\"> blocks; `ts` is the sender's dispatch time (local host time; date-prefixed when not sent today) — compare it with the current time to spot a stale/desynced message. The topic attribute is optional.",
   ].join('\n')
 }
 

package/src/daemon/main.ts

@@ -181,7 +181,7 @@ export function makeEphemeralRouteDeps(
 ): EphemeralRouteDeps {
   return {
     isEphemeral: cwd => isEphemeralPeer(cwd),
-    deliver: async ({ peer, envelope, topic, runtime }) => {
+    deliver: async ({ peer, envelope, topic, runtime, sentAt }) => {
       const rt = resolveWakeRuntime(runtime, peer)
       if (!rt.ok) return rt
       const identity = buildProcessAddress(rt.value, peer.personality)
@@ -201,7 +201,7 @@ export function makeEphemeralRouteDeps(
         queued: true,
         queuedBy: 'ephemeral',
         queueDepth: depth,
-        ts: new Date().toISOString(),
+        ts: sentAt ?? new Date().toISOString(),
       })
     },
   }

package/src/lifecycle/index.ts

@@ -25,6 +25,7 @@ import {
   type Runtime,
 } from '../core/constants.ts'
 import { buildProcessAddress, buildSocketPath, parseSessionName } from '../core/socket.ts'
+import { renderEnvelopeForAgent } from '../codec/index.ts'
 import { err, ok, type Result } from '../core/errors.ts'
 import { capPaneLogs, paneLogRotateConfig } from '../launch/cmdlog.ts'
 import { resolveGlobalRoot } from '../storage/index.ts'
@@ -917,17 +918,23 @@ function composePeerPrompt(
  * yields no seed and never blocks the wake (the seed is optional).
  */
 export function composeFirstMessage(cwd: string, task: string, fresh: boolean): string {
-  if (!fresh) return task
+  // Envelope-compaction F: the boot first-message enters an LLM context (wake
+  // targets are agent runtimes by construction — launchd-held bridges are never
+  // woken, H4), so the routed WIRE envelope is rendered into the compact
+  // agent-facing presentation here — the boot-side twin of deliverWarm's render.
+  // fail-open inside the renderer (non-envelope/empty task passes through as-is).
+  const presented = task ? renderEnvelopeForAgent(task) : task
+  if (!fresh) return presented
   let seed: string | undefined
   try {
     seed = readPeerProfile(cwd)?.initial_prompt
   } catch {
     /* invalid/absent profile → no seed */
   }
-  if (!seed) return task
+  if (!seed) return presented
   // seed + the routed message (both delivered, seed first). When there is NO incoming
   // message (an eager /new re-launch, C4b — task is empty), the seed is self-sufficient.
-  return task ? `${seed}\n\n${task}` : seed
+  return presented ? `${seed}\n\n${presented}` : seed
 }
 
 // ─────────────────────────────────────────────────────────────────────────────

package/src/transport/index.ts

@@ -32,7 +32,7 @@ import {
   buildSocketPath,
   type ProcessAddress,
 } from '../core/socket.ts'
-import { buildEnvelope } from '../codec/index.ts'
+import { buildEnvelope, formatSentAt, renderEnvelopeForAgent } from '../codec/index.ts'
 import { resolveGlobalRoot } from '../storage/index.ts'
 import { findPeer, readPeersIndex, type PeerRecord } from '../registry/index.ts'
 import type { ResolvedCaller } from '../identity/index.ts'
@@ -238,12 +238,18 @@ export async function deliverWarm(
   seam: WarmDeliverSeam = {},
   env: NodeJS.ProcessEnv = process.env,
 ): Promise<Result<void>> {
+  // Envelope-compaction F: an AGENT target (claude/codex — an LLM reads the text)
+  // receives the compact presentation; a bridge target (telegram/notifier/…)
+  // receives the WIRE form its parser expects. Rendered BEFORE deliverViaHost so
+  // the transcript-confirm matches the text actually delivered. fail-open inside
+  // the renderer: a render problem degrades to the wire form, never to a loss.
+  const payload = isSupportedLocalRuntime(target.runtime) ? renderEnvelopeForAgent(envelope) : envelope
   const address = target.address
   const prev = deliverTails.get(address) ?? Promise.resolve()
   // run AFTER prev settles (success or failure) — a prior delivery's error must not stall the chain
   const run = prev.then(
-    () => deliverViaHost(target, envelope, cwd, seam, env),
-    () => deliverViaHost(target, envelope, cwd, seam, env),
+    () => deliverViaHost(target, payload, cwd, seam, env),
+    () => deliverViaHost(target, payload, cwd, seam, env),
   )
   deliverTails.set(
     address,
@@ -884,6 +890,9 @@ export interface EphemeralRouteDeps {
     envelope: string
     topic?: string
     runtime?: string
+    /** Router-acceptance instant (formatSentAt) — the enqueue ACK's `ts` mirrors
+     *  it so sender-side ts ≡ envelope ts holds on the queued path too. */
+    sentAt?: string
   }) => Promise<Result<RouteResult>>
 }
 
@@ -904,6 +913,8 @@ export interface ComposerQueueTryEnqueueArgs {
   target: DeliveryTarget
   envelope: string
   topic?: string
+  /** Router-acceptance instant (formatSentAt) — the queued ACK's `ts` mirrors it. */
+  sentAt?: string
 }
 
 export interface ComposerQueueRouteDeps {
@@ -1192,7 +1203,7 @@ export function createComposerDeliveryQueue(opts: ComposerDeliveryQueueOptions):
         queued: true,
         queuedBy: 'composer',
         queueDepth: q.length,
-        ts: new Date().toISOString(),
+        ts: args.sentAt ?? new Date().toISOString(),
       })
     },
     failAll: async reason => {
@@ -1317,12 +1328,19 @@ export async function routeSend(
   const intendedGuard = telegramSenderGuard(caller, runtime ?? peer.runtime, personality)
   if (!intendedGuard.ok) return intendedGuard
 
+  // Stamped ONCE at router acceptance: the same instant travels as the envelope's
+  // `ts` attribute (recipient side) AND is returned as the result's `ts` (sender
+  // side) — the two correspond literally, which is what makes async-desync
+  // visible (the recipient can tell how old the message it is reading is).
+  const sentAt = formatSentAt(new Date())
   // Built once — it is both the live-delivery payload and, on a miss, the wake
-  // first-message (the woken session receives it as its boot task).
+  // first-message (the woken session receives it as its boot task). This is the
+  // WIRE form; agent-bound hops re-render it compactly at delivery.
   const envelope = buildEnvelope({
     fromPersonality: caller.personality,
     fromRuntime: caller.runtime,
     fromIntelligence: caller.intelligence,
+    sentAt,
     topic,
     attachments: attachmentsResult.value,
     message,
@@ -1336,7 +1354,7 @@ export async function routeSend(
   // would deadlock its own die-after-reply reap on a forever-non-empty queue).
   if (deps.ephemeral?.isEphemeral(peer.cwd)) {
     if (caller.personality === peer.personality) return err('cannot send to self')
-    return deps.ephemeral.deliver({ peer, envelope, topic, runtime })
+    return deps.ephemeral.deliver({ peer, envelope, topic, runtime, sentAt })
   }
 
   const target = resolvePeerDeliveryTarget(personality, runtime, peer, env)
@@ -1346,7 +1364,7 @@ export async function routeSend(
     // land on telegram without an override and without telegram being the default).
     const liveGuard = telegramSenderGuard(caller, target.value.runtime, personality)
     if (!liveGuard.ok) return liveGuard
-    const queued = await deps.composerQueue?.tryEnqueue({ caller, peer, target: target.value, envelope, topic })
+    const queued = await deps.composerQueue?.tryEnqueue({ caller, peer, target: target.value, envelope, topic, sentAt })
     if (queued) return queued
     // peer.cwd enables the Ф-B transcript-mtime liveness probe (busy-session case).
     // deliverWarm is HOST-AWARE (spawn-flip Ф0b-2): a supervisor-hosted target delivers over its
@@ -1359,7 +1377,7 @@ export async function routeSend(
       ok: true,
       delivered_to: { personality: target.value.personality, runtime: target.value.runtime },
       woke: false,
-      ts: new Date().toISOString(),
+      ts: sentAt,
     })
   }
 
@@ -1391,7 +1409,7 @@ export async function routeSend(
           ok: true,
           delivered_to: { personality: revived.value.personality, runtime: revived.value.runtime },
           woke: false,
-          ts: new Date().toISOString(),
+          ts: sentAt,
         })
       }
       // resolved but the deliver didn't land (session still settling) → keep polling
@@ -1427,7 +1445,7 @@ export async function routeSend(
   // a false ok:true — the class the contract forbids. A delivery failure here is
   // surfaced loudly (false-FAIL over false-OK).
   if (woke.taskDelivered === false) {
-    const queued = await deps.composerQueue?.tryEnqueue({ caller, peer, target: live.value, envelope, topic })
+    const queued = await deps.composerQueue?.tryEnqueue({ caller, peer, target: live.value, envelope, topic, sentAt })
     if (queued) return queued
     const delivered = await deliverWarm(live.value, envelope, peer.cwd, {}, env)
     if (!delivered.ok) return delivered
@@ -1436,7 +1454,7 @@ export async function routeSend(
       ok: true,
       delivered_to: { personality: live.value.personality, runtime: live.value.runtime },
       woke: false, // honest: this sender's envelope went the LIVE path, not a boot
-      ts: new Date().toISOString(),
+      ts: sentAt,
     })
   }
   // The envelope was delivered as the boot first-message during wake.
@@ -1444,6 +1462,6 @@ export async function routeSend(
     ok: true,
     delivered_to: { personality: live.value.personality, runtime: live.value.runtime },
     woke: true,
-    ts: new Date().toISOString(),
+    ts: sentAt,
   })
 }

package/src/tray/index.ts

@@ -11,6 +11,7 @@
 //     across daemon restarts / down windows. Degrades to the daemon-down block.
 //   • cmd — POST a fleet command (wake/stop/…): dogfoods the command endpoints.
 
+import { writeSync } from 'fs'
 import { resolveFleetAddress, fleetGetJson, fleetPostJson, streamFleetEvents } from './client.ts'
 import { renderSwiftBar, renderDaemonDown, type TraySnapshot } from './render.ts'
 import { iapeerBinPath } from '../install/index.ts'
@@ -52,6 +53,74 @@ export async function renderTrayOnce(env: NodeJS.ProcessEnv): Promise<string> {
   }
 }
 
+// ── UTF-8-atomic stdout sink ─────────────────────────────────────────────────────
+// WHY (root cause of the vanishing menu-bar icon, 13.07.2026): SwiftBar v2.0.1 decodes
+// EVERY pipe chunk independently — RunScript.swift: `String(data: availableData, .utf8)`
+// per readabilityHandler fire. A chunk boundary that lands INSIDE a multi-byte UTF-8
+// character makes that decode nil; StreamablePlugin treats nil as "clear content" and
+// MenuBarItem._updateMenu answers empty content with hide() → the NSStatusItem vanishes
+// (and AppKit PERSISTS the hidden state as `NSStatusItem VisibleCC <plugin>` = 0 via the
+// item's autosaveName, so it survives SwiftBar restarts). Our menu block is ~35 KB of
+// emoji/box-glyph-rich text written in ONE write(2): the kernel delivers it to the reader
+// in pipe-buffer-fill chunks (measured live: 16384+16384+2400 — byte-arbitrary
+// boundaries), so a mid-character split — and a hidden icon — was a stochastic certainty.
+//
+// FIX (kills the class by construction): emit in quanta of ≤512 bytes (PIPE_BUF on
+// macOS — writes ≤PIPE_BUF into a pipe are ATOMIC, all-or-nothing) with every quantum
+// ending on a UTF-8 character boundary. The pipe buffer then only ever contains whole
+// quanta, and a full-drain read (what FileHandle.availableData does — verified with a
+// live harness) always returns a concatenation of whole quanta ⇒ every chunk SwiftBar
+// can ever see is valid UTF-8. See docs/16-tray.md §icon-visibility.
+
+const PIPE_ATOMIC_MAX = 512
+
+/** Split `s` into Buffers of ≤`max` bytes, each ending on a UTF-8 character boundary.
+ *  Exported for tests. */
+export function utf8AtomicQuanta(s: string, max = PIPE_ATOMIC_MAX): Buffer[] {
+  const buf = Buffer.from(s, 'utf8')
+  const quanta: Buffer[] = []
+  let i = 0
+  while (i < buf.length) {
+    let end = Math.min(i + max, buf.length)
+    if (end < buf.length) {
+      // buf[end] is the first byte of the NEXT quantum — it must start a character.
+      // 0b10xxxxxx = UTF-8 continuation byte ⇒ step back to the character's first byte.
+      while (end > i && (buf[end]! & 0xc0) === 0x80) end--
+      // Defensive only (a valid UTF-8 char is ≤4 B < max): never stall on garbage input.
+      if (end === i) end = Math.min(i + max, buf.length)
+    }
+    quanta.push(buf.subarray(i, end))
+    i = end
+  }
+  return quanta
+}
+
+function sleepSyncMs(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+}
+
+/** The default stream sink: synchronous atomic-quantum writes to stdout (fd 1).
+ *  EPIPE ⇒ the reader (SwiftBar) is gone — exit cleanly so a dead tray-host never
+ *  accumulates orphaned `tray render --stream` processes. */
+function writeStdoutAtomic(s: string): void {
+  for (const q of utf8AtomicQuanta(s)) {
+    let off = 0
+    while (off < q.length) {
+      try {
+        off += writeSync(1, q, off, q.length - off)
+      } catch (e) {
+        const code = (e as NodeJS.ErrnoException).code
+        if (code === 'EAGAIN') {
+          sleepSyncMs(2) // pipe full — the reader is momentarily busy
+          continue
+        }
+        if (code === 'EPIPE') process.exit(0)
+        throw e
+      }
+    }
+  }
+}
+
 function sleep(ms: number, signal?: AbortSignal): Promise<void> {
   return new Promise(resolve => {
     if (signal?.aborted) return resolve()
@@ -69,7 +138,10 @@ function sleep(ms: number, signal?: AbortSignal): Promise<void> {
  */
 export async function streamTray(
   env: NodeJS.ProcessEnv,
-  out: (s: string) => void = s => process.stdout.write(s),
+  // Default sink is the UTF-8-atomic quantum writer — NOT a plain stdout.write: a single
+  // big write reaches SwiftBar in byte-arbitrary chunks whose per-chunk UTF-8 decode can
+  // fail and hide the menu-bar icon (see writeStdoutAtomic above).
+  out: (s: string) => void = writeStdoutAtomic,
   signal?: AbortSignal,
 ): Promise<void> {
   // Serialize all emits through a promise chain so a `~~~`+block is never interleaved.

package/src/tray/install.ts

@@ -133,8 +133,12 @@ export function buildPluginShim(binPath: string): string {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// Login autostart — a RunAtLoad LaunchAgent that brings SwiftBar up at login, so the
-// fleet dashboard + approval badge survive a reboot without a manual `open -a SwiftBar`.
+// Tray-host supervision — a KeepAlive LaunchAgent running a tiny /bin/sh watchdog loop
+// that brings SwiftBar up at login AND brings it back within seconds whenever it dies.
+// The tray is the owner's fleet-visibility surface: a silently-dead SwiftBar hides the
+// state of the whole system (owner incident 13.07.2026), so its lifetime is supervised,
+// not fire-and-forget. The deliberate consequence: quitting SwiftBar by hand also
+// relaunches it — the supported off-switch is `iapeer tray uninstall`.
 //
 // MECHANISM CHOICE (owner-relevant): a user LaunchAgent, not a System Events "Login
 // Item" and not SMAppService.
@@ -149,11 +153,12 @@ export function buildPluginShim(binPath: string): string {
 //     (write-if-changed + undead-safe bootstrap/cycle, sandbox-guarded) and carries the
 //     ownership sentinel so uninstall can recognize + remove exactly our artifact.
 //
-// RunAtLoad-ONLY, no KeepAlive: the ProgramArguments launch SwiftBar via `open` (which
-// exits immediately once SwiftBar is up), so KeepAlive would respawn-storm `open` every
-// throttle window. A login-autostart only needs to fire once per session; keeping
-// SwiftBar itself supervised (relaunch-on-quit) would fight the user quitting it and
-// duplicate SwiftBar's own launch-at-login — out of scope for "start it at login".
+// WATCHDOG SHAPE: launchd must NOT KeepAlive `open` itself — `open` exits the moment
+// SwiftBar is up, so KeepAlive on it is a respawn storm (the 0.4.82 lesson). Instead the
+// job runs a long-lived poll loop: every 5 s, if no SwiftBar process exists, `open -g -b`
+// it (a no-op activation when it IS running — race-safe, never a duplicate instance;
+// absolute /usr/bin//bin paths — launchd's PATH is minimal). An absent SwiftBar.app
+// backs off 5 min instead of churning. KeepAlive guards the LOOP process itself.
 // ─────────────────────────────────────────────────────────────────────────────
 
 /** Absolute path of the tray autostart LaunchAgent plist (IAPEER_LAUNCHAGENTS_DIR
@@ -162,11 +167,17 @@ export function swiftBarAutostartPlistPath(env: NodeJS.ProcessEnv = process.env)
   return join(launchAgentsDir(env), `${SWIFTBAR_AUTOSTART_LABEL}.plist`)
 }
 
-/** Render the RunAtLoad SwiftBar-autostart plist. PURE/deterministic (golden-testable).
+/** Render the SwiftBar tray-host supervisor plist. PURE/deterministic (golden-testable).
  *  Launch is `open -g -b <bundleid>`: LaunchServices activates the app correctly as a
  *  menu-bar agent (`-g` = don't steal focus), and bundle-id targeting survives the app
  *  moving. Carries the foundation ownership sentinel (inert `<key>` launchd ignores). */
 export function renderSwiftBarAutostartPlist(): string {
+  // Single-line sh loop (see WATCHDOG SHAPE above): 5 s liveness poll, no-op when
+  // SwiftBar runs, 5 min backoff when the app is not installed at all.
+  const loop =
+    'while :; do ' +
+    `if ! /usr/bin/pgrep -xq SwiftBar; then /usr/bin/open -g -b ${SWIFTBAR_BUNDLE_ID} || /bin/sleep 300; fi; ` +
+    '/bin/sleep 5; done'
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -177,13 +188,16 @@ export function renderSwiftBarAutostartPlist(): string {
     <true/>
     <key>ProgramArguments</key>
     <array>
-        <string>/usr/bin/open</string>
-        <string>-g</string>
-        <string>-b</string>
-        <string>${SWIFTBAR_BUNDLE_ID}</string>
+        <string>/bin/sh</string>
+        <string>-c</string>
+        <string>${loop}</string>
     </array>
     <key>RunAtLoad</key>
     <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>ProcessType</key>
+    <string>Background</string>
 </dict>
 </plist>
 `
@@ -302,7 +316,8 @@ export interface InstallTrayResult {
   app: 'present' | 'installed' | 'install-failed' | 'absent'
   appReason?: string
   launched: boolean
-  /** Login-autostart registration outcome (only when launched + SwiftBar present). */
+  /** Tray-host supervisor (autostart) registration outcome: set when activated
+   *  (launch && SwiftBar present) OR upgraded in place (our plist already on disk). */
   autostart?: EnsureAutostartResult
 }
 
@@ -369,7 +384,8 @@ export function installTray(opts: InstallTrayOptions = {}): InstallTrayResult {
     }
   }
 
-  // 4 — launch + refresh + register login autostart (so a reboot brings the tray back).
+  // 4 — launch + refresh + register the tray-host supervisor (login autostart +
+  // relaunch-on-death), so a reboot or a SwiftBar crash brings the tray back by itself.
   let launched = false
   let autostart: EnsureAutostartResult | undefined
   if (opts.launch && present) {
@@ -380,6 +396,13 @@ export function installTray(opts: InstallTrayOptions = {}): InstallTrayResult {
     // Idempotent: the plist is byte-stable and the bootstrap is a no-op when loaded, so
     // re-activation never plants a duplicate autostart.
     autostart = ensureSwiftBarAutostart(env)
+  } else if (existsSync(swiftBarAutostartPlistPath(env)) && isFoundationOwnedPlist(swiftBarAutostartPlistPath(env))) {
+    // UPGRADE-IN-PLACE: this host opted into the autostart earlier (our plist is on
+    // disk). The foundation `install` verb runs installTray with launch:false — without
+    // this branch a deploy (`iapeer update` → install) would leave an OUTDATED agent
+    // (e.g. the 0.4.82 one-shot RunAtLoad plist) registered forever. ensure() rewrites
+    // the plist only when its bytes changed and re-cycles the job onto the new content.
+    autostart = ensureSwiftBarAutostart(env)
   }
 
   return { pluginFile, pluginDir, wrote, dir, app, appReason, launched, autostart }
@@ -463,9 +486,18 @@ export function trayAttachTerm(opts: {
 
 export interface TrayStatus {
   daemon: { fleet: boolean; version?: string; sock?: string; tcp?: string }
-  swiftbar: { installed: boolean; pluginDir?: string }
+  swiftbar: {
+    installed: boolean
+    pluginDir?: string
+    /** GROUND TRUTH of the menu-bar icon: AppKit persists NSStatusItem visibility per
+     *  autosaveName in SwiftBar's defaults (`NSStatusItem VisibleCC <plugin>`). false =
+     *  the icon is hidden RIGHT NOW (whatever hid it — a mid-chunk decode nil on an old
+     *  binary, a ⌘-drag removal); undefined = key absent / SwiftBar not installed. The
+     *  first thing to read when "the icon is gone" is reported — no screen needed. */
+    iconVisible?: boolean
+  }
   plugin: { installed: boolean; path?: string }
-  /** Login-autostart LaunchAgent: registered (our plist present) + its path. */
+  /** Tray-host supervisor LaunchAgent: registered (our plist present) + its path. */
   autostart: { registered: boolean; path?: string }
 }
 
@@ -480,9 +512,14 @@ export function trayStatus(opts: { env?: NodeJS.ProcessEnv; run?: Runner; probeA
   const found = searchDirs.map(d => join(d, PLUGIN_BASENAME)).find(f => existsSync(f))
   const autostartPath = swiftBarAutostartPlistPath(env)
   const autostartOurs = existsSync(autostartPath) && isFoundationOwnedPlist(autostartPath)
+  let iconVisible: boolean | undefined
+  if (installed) {
+    const r = run('defaults', ['read', SWIFTBAR_DOMAIN, `NSStatusItem VisibleCC ${PLUGIN_BASENAME}`])
+    if (r.status === 0) iconVisible = r.stdout.trim() === '1'
+  }
   return {
     daemon: { fleet: addr.fleet === 1, version: addr.version, sock: addr.sock, tcp: addr.tcp },
-    swiftbar: { installed, pluginDir: cfgDir },
+    swiftbar: { installed, pluginDir: cfgDir, iconVisible },
     plugin: { installed: Boolean(found), path: found },
     autostart: { registered: autostartOurs, path: autostartOurs ? autostartPath : undefined },
   }

package/src/tray/render.ts

@@ -125,6 +125,13 @@ export function fmtAge(ms: number, now: number): string {
   return `${Math.floor(h / 24)}d ago`
 }
 
+/** Local wall-clock `HH:MM:SS` for the footer freshness stamp. */
+export function fmtClock(now: number): string {
+  const d = new Date(now)
+  const p = (n: number): string => String(n).padStart(2, '0')
+  return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`
+}
+
 // ── peer status aggregation ─────────────────────────────────────────────────────
 
 function aggregate(p: TrayPeer): 'live' | 'asleep' | 'stopped' {
@@ -214,8 +221,17 @@ export function renderSwiftBar(snapshot: TraySnapshot, opts: RenderOptions): str
   // always current on open — a manual refresh gives the user nothing and (being a
   // SwiftBar refresh) just closes the dropdown. The emergency "restart the plugin" lever
   // lives in SwiftBar's own service menu (right-click → Refresh).
+  //
+  // The trailing clock is LOAD-BEARING, not cosmetic: it makes every rendered block
+  // unique, so each streamable heartbeat emit DIFFERS from the previous one and
+  // SwiftBar's content-change publisher fires every time. SwiftBar's _updateMenu()
+  // starts with show() (NSStatusItem.isVisible = true) — that is the tray's self-heal:
+  // a menu-bar icon hidden for ANY reason (SwiftBar's per-chunk UTF-8 decode nil
+  // hiding the item, an accidental ⌘-drag removal, a stale persisted
+  // `NSStatusItem VisibleCC` flag) comes back within one heartbeat (≤15 s) instead of
+  // staying invisible until the fleet next changes. See docs/16-tray.md §icon-visibility.
   lines.push('---')
-  lines.push(line(0, `iapeer · fleet dashboard`, { color: COLOR.meta, size: 11 }))
+  lines.push(line(0, `iapeer · fleet dashboard · ${fmtClock(now)}`, { color: COLOR.meta, size: 11 }))
   return lines.join('\n') + '\n'
 }
 
@@ -396,6 +412,7 @@ function renderApprovals(approvals: TrayApproval[], bin: string): string[] {
  *  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 now = opts.now ?? Date.now()
   const lines: string[] = []
   lines.push(line(0, '', { sfimage: 'exclamationmark.triangle.fill', color: COLOR.down }))
   lines.push('---')
@@ -403,5 +420,10 @@ export function renderDaemonDown(reason: string, opts: RenderOptions): string {
   lines.push(line(0, reason, { color: COLOR.meta }))
   lines.push('---')
   lines.push(line(0, 'Refresh', { refresh: true, sfimage: 'arrow.clockwise' }))
+  // Same load-bearing uniqueness stamp as renderSwiftBar's footer: the down-block is
+  // re-emitted every few seconds while the daemon is away — the changing clock keeps
+  // the ⚠ icon visible (show() fires per update) instead of a stale hidden item.
+  lines.push('---')
+  lines.push(line(0, `iapeer · ${fmtClock(now)}`, { color: COLOR.meta, size: 11 }))
   return lines.join('\n') + '\n'
 }