@agfpd/iapeer 0.4.69 → 0.4.70

package/docs/15-fleet-api.md

@@ -58,6 +58,11 @@ The full fleet state. The peer rows are produced by the **same in-process functi
       "wake_policy": "warm",
       "approval_mode": "yolo"
     }
+  ],
+  "approvals": [
+    { "id": "a1", "personality": "boris", "runtime": "claude", "kind": "circuit-breaker",
+      "tool": "dangerous-rm", "summary": "rm -rf /tmp/x",
+      "content": "cmd=\"rm -rf /tmp/x\" target=\"/tmp/x\"", "createdMs": 1751731100000, "expiresMs": 1751731400000 }
   ]
 }
 ```
@@ -75,6 +80,7 @@ Field notes:
 - `host.fda` — Full Disk Access of the binary: `true` / `false` / `null` (undeterminable).
 - The daemon answering **is** the health signal: there is no `healthy` boolean. A dashboard that cannot reach any advertised address should render the daemon as down (this is also why a purely API-fed dashboard is insufficient when the daemon itself is broken — the built-in TUI keeps its direct in-process read path for exactly that case).
 - The peer's **LLM model is deliberately absent**: the effective model of a live session is not an observable registry fact (static launch pins exist, but reporting a pin as «the model» would lie under runtime auto-switching). If it ever becomes observable, it will appear as an additive field.
+- `approvals` (top-level, docs/17-approval) — the pending human-approval queue, the SAME items `GET /fleet/v1/approvals` returns, carried in the snapshot so a client that already re-fetches `/snapshot` on every event renders the queue with no extra call. **ADDITIVE + OMITTED when the queue is empty** — a client MUST treat its absence as an empty queue (the same rule as `approval_mode`). Each item: `id` (broker id, the target of `POST /fleet/v1/approvals/<id>/(approve|deny)`), `personality` + `runtime` (whose action), `kind` (`tool`|`plan`|`question`|`circuit-breaker`), `tool` (the tool / breaker name), `summary` (a one-line badge string), `content` (the FULL verbatim action — command / diff / plan; criterion #7), `createdMs` / `expiresMs`. The broker's item is a superset — unknown extra fields (`title`, `approvers`) MUST be ignored (obligation 2).
 
 ## GET /fleet/v1/peers/&lt;personality&gt;
 
@@ -134,7 +140,7 @@ What the headline states look like on the stream: a peer **waking** is `ev=wake`
 
 `from` is optional: a full `<runtime>-<personality>`, or a bare personality (its default runtime). Default: the **single natural-intelligence peer** of the registry — a GUI-originated message is the human's. With zero or several natural peers the request is refused (`400`) with an instruction to pass `from`.
 
-Not part of the API, deliberately: **attach** (a terminal handoff — a client opens the system terminal with `iapeer attach <peer>`), registry/host **admin verbs** (`create`/`remove`/`update`/`uninstall` — will be added when a client actually needs them), **approve** (no approval broker exists yet; it will arrive as new endpoints + `ev` kinds under this same contract).
+Not part of the *command* API, deliberately: **attach** (a terminal handoff — a client opens the system terminal with `iapeer attach <peer>`), registry/host **admin verbs** (`create`/`remove`/`update`/`uninstall` — will be added when a client actually needs them). The **human-approval broker** now lives under `/fleet/v1/approvals*` (`GET` the queue / one item, `POST /<id>/(approve|deny)`) with the `approval-request` / `approval-resolved` SSE `ev` kinds and the `approvals` snapshot field above — the full contract is **docs/17-approval**.
 
 Errors are always `{"error": "…"}` with an honest status: `400` malformed request, `401` bearer required, `404` unknown peer/endpoint, `405` wrong method, `502` the verb itself failed, `500` internal.
 

package/docs/16-tray.md

@@ -16,10 +16,13 @@ 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)).
+- **Menu bar:** an antenna glyph + the count of peers with a live session. When one or more
+  **human-approval** requests are pending, the menu bar instead shows a **red `N.circle.fill`
+  badge** (the iOS-notification look — a red circle with the count) so the owner sees an
+  awaiting request at a glance. 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 —
@@ -36,6 +39,16 @@ activation that also installs SwiftBar.app when it is absent.
     peers (telegram / notifier, `🔒`) are not pty-attachable** — their rows are plain status
     lines. Lifecycle actions (Wake / Stop / Start / New / Interrupt / Refresh / Compact) live
     in the **Manage** submenu, each a `POST /fleet/v1/peers/<peer>/<cmd>` via `iapeer tray cmd`.
+- **Pending approvals (docs/17):** when the queue is non-empty, the **top of the dropdown** shows
+  each pending request **expanded, with no extra clicks** — a header (`<peer> · <tool>`), the
+  **verbatim action content** (the command / diff / plan, monospace, capped for the menu; the FULL
+  content stays in `iapeer approvals`), then **Allow** / **Deny** items directly below. Clicking runs
+  `iapeer tray approve|deny <id>` in the background → the broker resolves → the stream re-renders (the
+  badge clears). The peer with a pending request is **highlighted in the fleet list** (a `⚠` prefix, a
+  red `🔴N` count, the row painted red) so the owner sees *which* peer is waiting. This channel is
+  **always on** — the approval queue is reflected whenever it is non-empty, independent of everything
+  else; an empty queue shows no section and no badge. (A true *pulse* animation is not possible in a
+  static SwiftBar menu — the highlight + badge is its equivalent.)
 
 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
@@ -54,6 +67,7 @@ whole dashboard twice.
 | `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 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. Repairs nothing. |
 
 ## How it is wired

package/docs/17-approval.md

@@ -37,7 +37,7 @@ The bypass is a **launch argument**, different per runtime, and the mode is a co
 
 **Why matcher-free `PermissionRequest`, not `PreToolUse`.** `PermissionRequest` fires **only when the runtime's permission config decided to prompt** — a call not covered by an allow/deny rule. So the policy of *what to ask* stays 100% at the runtime: a user tunes it with ordinary permission rules (a tool in `permissions.allow` is never asked → the hook never fires → auto-allowed). No class matcher to drift, no new tool slipping through, no hang. iapeer only seeds the hook + the one allow-rule for the peer's own MCP tool.
 
-**codex** (`PreToolUse` hook — structural; live-verify pending):
+**codex** (`PreToolUse` hook — verified live, codex-cli 0.142.5):
 
 | # | Surface | yolo | gated |
 |---|---|---|---|
@@ -62,7 +62,7 @@ All surfaces are read/applied **at session start**. A **live session keeps its l
 Both runtimes carry a Claude-compatible **hook** system that intercepts an approval programmatically and returns `allow`/`deny` + a reason + the structured action content. That is the primary mechanism. **pty screen-scrape is a backstop for one class only** — claude's `dangerous-rm` circuit-breaker, which sits *above* the permission layer and no hook can see.
 
 - **claude `PermissionRequest`** — stdin carries `{tool_name, tool_input, …}`; the hook prints `{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow|deny","message":"…"}}}`. A `deny` carries `message` to the model. Fires only on prompt-worthy calls.
-- **codex `PreToolUse`** — same stdin shape; prints `{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow|deny","permissionDecisionReason":"…"}}`. `exit 2` (+ stderr) also denies.
+- **codex `PreToolUse`** — same stdin shape; prints `{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow|deny","permissionDecisionReason":"…"}}`. `exit 2` (+ stderr) also denies. Verified live (0.142.5): codex fires `PreToolUse` (not `PermissionRequest`) for tool calls with `tool_name:"Bash"` for shell; a `deny` hard-blocks the tool and the reason reaches the model even under `sandbox_mode=danger-full-access` — so under the gated config (danger-full-access + on-request → `permission_mode=bypassPermissions`) the hook is the SOLE gate.
 - **supervisor circuit-breaker** — claude's `dangerous-rm`/`rmdir` guard (and the standard command-approval prompt a no-bypass session shows) is a TUI select the hook never sees. The pty supervisor reads it off its authoritative model and, under gated, POSTs it to the broker (below); under yolo it auto-presses YES with an audit line.
 
 The hook binary is the `iapeer approval-hook` subcommand: it reads the runtime's hook JSON on stdin, resolves `PEER_PERSONALITY`/`PEER_RUNTIME` from its session env and the daemon URL from `router.json`, POSTs a blocking request to the broker, and prints the runtime-appropriate decision JSON.

package/docs/ru/15-fleet-api.md

@@ -57,6 +57,11 @@ HTTP-поверхность демона для **операторских кл
       "launchd_managed": false,
       "wake_policy": "warm"
     }
+  ],
+  "approvals": [
+    { "id": "a1", "personality": "boris", "runtime": "claude", "kind": "circuit-breaker",
+      "tool": "dangerous-rm", "summary": "rm -rf /tmp/x",
+      "content": "cmd=\"rm -rf /tmp/x\" target=\"/tmp/x\"", "createdMs": 1751731100000, "expiresMs": 1751731400000 }
   ]
 }
 ```
@@ -73,6 +78,7 @@ HTTP-поверхность демона для **операторских кл
 - `host.fda` — Full Disk Access бинаря: `true` / `false` / `null` (неопределимо).
 - Сам факт ответа демона **и есть** сигнал здоровья: булева `healthy` нет. Дашборд, не достучавшийся ни до одного объявленного адреса, обязан рисовать демона лежачим (поэтому же дашборд, питающийся только API, недостаточен, когда сломан сам демон — встроенный TUI сохраняет прямой in-process путь чтения ровно на этот случай).
 - **LLM-модель пира отсутствует намеренно**: эффективная модель живой сессии — не наблюдаемый факт реестра (статические пины запуска существуют, но выдавать пин за «модель» — врать при рантаймном автопереключении). Станет наблюдаемой — появится аддитивным полем.
+- `approvals` (top-level, docs/17-approval) — очередь ожидающих human-approval, ТЕ ЖЕ item'ы, что отдаёт `GET /fleet/v1/approvals`, в снапшоте — чтобы клиент, уже перефетчащий `/snapshot` на каждое событие, рендерил очередь без доп. вызова. **АДДИТИВНО + ОПУСКАЕТСЯ при пустой очереди** — клиент ОБЯЗАН трактовать отсутствие как пустую очередь (то же правило, что `approval_mode`). Поля item: `id` (broker-id, цель `POST /fleet/v1/approvals/<id>/(approve|deny)`), `personality` + `runtime` (чьё действие), `kind` (`tool`|`plan`|`question`|`circuit-breaker`), `tool` (имя инструмента / breaker'а), `summary` (однострочник для бейджа), `content` (ПОЛНОЕ дословное действие — команда / диф / план; крит №7), `createdMs` / `expiresMs`. Item брокера — суперсет: неизвестные лишние поля (`title`, `approvers`) ОБЯЗАНЫ игнорироваться (обязательство 2).
 
 ## GET /fleet/v1/peers/&lt;personality&gt;
 
@@ -132,7 +138,7 @@ GET /fleet/v1/events?replay=50
 
 `from` опционален: полный `<runtime>-<personality>` или голая personality (её default-рантайм). По умолчанию — **единственный natural-intelligence пир** реестра: сообщение из GUI принадлежит человеку. При нуле или нескольких natural-пирах запрос отклоняется (`400`) с указанием передать `from`.
 
-Не входит в API, намеренно: **attach** (передача терминала — клиент открывает системный терминал с `iapeer attach <peer>`), реестровые/хостовые **admin-verb'ы** (`create`/`remove`/`update`/`uninstall` — добавятся, когда появится клиент с реальной потребностью), **approve** (брокера подтверждений ещё не существует; он придёт новыми эндпоинтами + видами `ev` в рамках этого же контракта).
+Не входит в *командный* API, намеренно: **attach** (передача терминала — клиент открывает системный терминал с `iapeer attach <peer>`), реестровые/хостовые **admin-verb'ы** (`create`/`remove`/`update`/`uninstall` — добавятся, когда появится клиент с реальной потребностью). **Брокер human-approval** теперь живёт под `/fleet/v1/approvals*` (`GET` очередь / один item, `POST /<id>/(approve|deny)`) с видами SSE `approval-request` / `approval-resolved` и полем `approvals` в снапшоте выше — полный контракт в **docs/17-approval**.
 
 Ошибки — всегда `{"error": "…"}` с честным статусом: `400` некорректный запрос, `401` требуется bearer, `404` неизвестный пир/эндпоинт, `405` не тот метод, `502` сам verb упал, `500` внутренняя.
 

package/docs/ru/16-tray.md

@@ -15,8 +15,10 @@ SwiftBar.app, если его нет.
 
 ## Что видно
 
-- **Меню-бар:** глиф-антенна + число пиров с живой сессией. Если ни один объявленный адрес
-  демона не отвечает — красный треугольник (демон недоступен; чисто API-дашборд иначе не
+- **Меню-бар:** глиф-антенна + число пиров с живой сессией. Когда есть ожидающие запросы
+  **human-approval**, меню-бар вместо этого показывает **красный бейдж `N.circle.fill`** (iOS-look —
+  красный круг с числом), чтобы владелец сразу видел ожидающий запрос. Если ни один объявленный
+  адрес демона не отвечает — красный треугольник (демон недоступен; чисто API-дашборд иначе не
   покажет сломанный демон — встроенный TUI держит прямой путь чтения для этого случая, см.
   [15](15-fleet-api.md)).
 - **Выпадашка:** шапка хоста (`iapeer <версия> · up <аптайм>`) и хартбиты провайдеров памяти
@@ -34,6 +36,15 @@ SwiftBar.app, если его нет.
     (telegram / notifier, `🔒`) не pty-аттачатся** — их строки просто статус. Lifecycle-действия
     (Wake / Stop / Start / New / Interrupt / Refresh / Compact) — в подменю **Manage**, каждое —
     `POST /fleet/v1/peers/<peer>/<cmd>` через `iapeer tray cmd`.
+- **Ожидающие подтверждения (docs/17):** когда очередь непуста, **вверху выпадашки** каждый
+  ожидающий запрос показан **раскрытым, без доп. кликов** — заголовок (`<peer> · <tool>`),
+  **дословное содержимое действия** (команда / диф / план, моноширинно, усечено для меню; ПОЛНОЕ
+  содержимое — в `iapeer approvals`), затем пункты **Allow** / **Deny** прямо под ним. Клик запускает
+  `iapeer tray approve|deny <id>` в фоне → брокер резолвит → стрим ре-рендерит (бейдж гаснет). Пир с
+  ожидающим запросом **выделен в списке флота** (префикс `⚠`, красный счётчик `🔴N`, строка красная),
+  чтобы владелец видел, *какой* пир ждёт. Канал **always-on** — очередь отражается всегда, когда
+  непуста, независимо от прочего; пустая очередь — ни секции, ни бейджа. (Настоящая *пульс*-анимация в
+  статичном SwiftBar-меню невозможна — highlight + бейдж это её эквивалент.)
 
 Список обновляется сам: плагин **streamable** — подписан на поток событий и перечитывает
 снапшот на каждое изменение (пробуждение пира, стоп/старт оператором, смерть), склеивая
@@ -51,6 +62,7 @@ SwiftBar.app, если его нет.
 | `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 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 и где его каталог плагинов, на месте ли файл плагина. Ничего не чинит. |
 
 ## Как устроено

package/docs/ru/17-approval.md

@@ -37,7 +37,7 @@ Bypass — это **аргумент запуска**, у каждого ран
 
 **Почему matcher-free `PermissionRequest`, а не `PreToolUse`.** `PermissionRequest` фаярит **только когда permission-конфиг рантайма решил спросить** — вызов, не покрытый allow/deny-правилом. Значит политика *что спрашивать* остаётся на 100% у рантайма: юзер настраивает её обычными permission-правилами (инструмент в `permissions.allow` не спрашивается никогда → хук не фаярит → авто-allow). Нет матчера классов, который дрейфует, нет проскакивающего нового инструмента, нет зависания. iapeer лишь сеет хук + одно allow-правило для собственного MCP-инструмента пира.
 
-**codex** (хук `PreToolUse` — структурно; живая верификация ожидается):
+**codex** (хук `PreToolUse` — проверено живьём, codex-cli 0.142.5):
 
 | # | Поверхность | yolo | gated |
 |---|---|---|---|
@@ -62,7 +62,7 @@ codex-хук матчится по регекспу имён инструмен
 У обоих рантаймов есть Claude-совместимая **hook-система**, которая перехватывает подтверждение программно и возвращает `allow`/`deny` + причину + структурное содержимое действия. Это первичный механизм. **Экранный pty-скрейп — бэкстоп только для одного класса** — claude-circuit-breaker `dangerous-rm`, который живёт *выше* permission-слоя и не виден ни одному хуку.
 
 - **claude `PermissionRequest`** — на stdin `{tool_name, tool_input, …}`; хук печатает `{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow|deny","message":"…"}}}`. `deny` доносит `message` до модели. Фаярит только на вопрос-достойных вызовах.
-- **codex `PreToolUse`** — тот же shape stdin; печатает `{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow|deny","permissionDecisionReason":"…"}}`. `exit 2` (+ stderr) тоже отклоняет.
+- **codex `PreToolUse`** — тот же shape stdin; печатает `{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow|deny","permissionDecisionReason":"…"}}`. `exit 2` (+ stderr) тоже отклоняет. Проверено живьём (0.142.5): codex фаярит `PreToolUse` (не `PermissionRequest`) на tool-вызовах с `tool_name:"Bash"` для shell; `deny` жёстко блокирует тул и причина доходит до модели даже под `sandbox_mode=danger-full-access` — так что под gated-конфигом (danger-full-access + on-request → `permission_mode=bypassPermissions`) хук — ЕДИНСТВЕННЫЙ гейт.
 - **супервизор circuit-breaker** — гард `dangerous-rm`/`rmdir` claude (и стандартный command-approval-промпт, который показывает no-bypass-сессия) — это TUI-селект, невидимый хуку. pty-супервизор читает его со своей авторитетной модели и под gated POSTит брокеру (ниже); под yolo авто-жмёт YES с аудит-строкой.
 
 Хук-бинарь — сабкоманда `iapeer approval-hook`: читает hook-JSON рантайма со stdin, резолвит `PEER_PERSONALITY`/`PEER_RUNTIME` из session-env и URL демона из `router.json`, POSTит блокирующий запрос брокеру и печатает рантайм-специфичный JSON решения.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.69",
+  "version": "0.4.70",
   "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/approval/install.ts

@@ -25,7 +25,13 @@ import { preSeedCodexHooksTrust, removeCodexHooksTrustUnder, type HooksTrustOutc
 // never asked → the hook never fires → auto-allowed). No class matcher, no drift, no hang: a new
 // tool the runtime prompts for is intercepted the same way. iapeer only seeds the hook + the
 // allow-rule for its own MCP tool (else the runtime would prompt on the peer's own IAP channel).
-/** codex tool-name regex (codex PreToolUse path — structural, live-verify pending). */
+// codex tool-name regex (codex PreToolUse path). VERIFIED LIVE (codex-cli 0.142.5, Unit 3): codex
+// fires `PreToolUse` (NOT PermissionRequest) for tool calls, with `tool_name:"Bash"` for shell exec +
+// `tool_input.command` = the full command; a PreToolUse `deny` HARD-BLOCKS the tool AND the
+// `permissionDecisionReason` reaches the model — even under `sandbox_mode=danger-full-access`
+// (permission_mode=bypassPermissions), so under the gated config the hook is the SOLE gate. `Bash`
+// confirmed live; `apply_patch` (the patch tool) per the codex hooks docs. The extra alternatives are a
+// forward-compatible superset (a future codex rename still matches) — harmless, never over-matches.
 export const CODEX_APPROVAL_MATCHER = '^(Bash|Shell|shell|local_shell|exec|apply_patch|ApplyPatch)$'
 /** The peer's own IAP tool — allow-listed so a gated peer's send_to_peer is not itself gated. */
 export const IAPEER_MCP_ALLOW = 'mcp__iapeer__send_to_peer'

package/src/cli/index.ts

@@ -1278,8 +1278,8 @@ const VERBS: ReadonlyArray<{ sig: string; desc: string }> = [
     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.',
+    sig: 'tray install|uninstall|render [--stream]|cmd <c> <peer>|approve <id>|deny <id> [reason]|status',
+    desc: 'the macOS menu-bar fleet dashboard (SwiftBar plugin) — first external Fleet API client; renders the approval queue (badge + Allow/Deny), install activates it (installs SwiftBar when absent). See docs/16.',
   },
   { sig: 'approval-mode <peer> [gated|yolo]', desc: 'read/flip a peer\'s human-approval mode (docs/17): yolo=current bypass; gated=blocking runtime approvals routed to a human. Persists + brings runtime surfaces to the mode; applies on next fresh session' },
   { sig: 'approvals [--json]', desc: 'list pending human-approval requests (verbatim action content); the host answer channel to the daemon broker' },
@@ -2542,6 +2542,23 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
             out(`${JSON.stringify(r.body)}\n`)
             return r.ok ? 0 : 1
           }
+          case 'approve':
+          case 'deny': {
+            // Tray click → resolve a pending approval over the unix-first fleet client (docs/17). The
+            // menu Allow/Deny items run these; the broker resolution is seen by every channel.
+            const id = positionals[1]
+            if (!id) return argErr(errOut, `usage: iapeer tray ${sub} <approval-id> [reason]`)
+            const reason = sub === 'deny' ? positionals.slice(2).join(' ') || undefined : undefined
+            let r: Awaited<ReturnType<typeof tray.trayResolveApproval>>
+            try {
+              r = await tray.trayResolveApproval(env, sub, id, reason)
+            } catch (e) {
+              errOut(`tray ${sub}: ${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).

package/src/daemon/fleet.ts

@@ -111,12 +111,32 @@ export interface FleetHost {
   fda: boolean | null
 }
 
+/** A pending human-approval request as the snapshot exposes it (docs/17). The SAME items
+ *  `GET /fleet/v1/approvals` returns (broker.list()) — carried in the snapshot so a client
+ *  that already fetches `/snapshot` on every event renders the queue with no extra call. The
+ *  compact `summary` fuels a badge/one-liner; the verbatim `content` (criterion #7 — the full
+ *  command / diff / plan) rides along for inline display, capped by the client if it wishes. */
+export interface FleetApproval {
+  id: string
+  personality: string
+  runtime: string
+  kind: string
+  tool: string
+  summary: string
+  content: string
+  createdMs: number
+  expiresMs: number
+}
+
 export interface FleetSnapshot {
   api: typeof FLEET_API_VERSION
   version: string
   ts: string
   host: FleetHost
   peers: FleetPeer[]
+  /** Pending human-approval requests (docs/17). ADDITIVE + omitted when the queue is empty —
+   *  a client MUST treat its absence as an empty queue (same rule as `approval_mode`). */
+  approvals?: FleetApproval[]
 }
 
 // The CLI op functions, injectable for tests. Defaults LAZY-load cli/index.ts at
@@ -152,6 +172,7 @@ export function buildFleetSnapshot(
   ops: Pick<FleetOps, 'listPeers'>,
   startedAtMs: number,
   nowMs: number = Date.now(),
+  approvals: FleetApproval[] = [],
 ): FleetSnapshot {
   const peers: FleetPeer[] = ops.listPeers({ env }).map(r => {
     const runtimes: FleetRuntimeStatus[] = r.runtimes.map(s => {
@@ -208,6 +229,10 @@ export function buildFleetSnapshot(
       fda: probeFullDiskAccess(env),
     },
     peers,
+    // ADDITIVE + omitted when empty (absence ⇒ empty queue, docs/15). broker.list() is a
+    // superset of FleetApproval — the named fields are the contract; extras ride along and
+    // clients ignore them (obligation 2).
+    ...(approvals.length ? { approvals } : {}),
   }
 }
 
@@ -484,7 +509,9 @@ export function buildFleetHandler(opts: FleetHandlerOptions = {}): FleetHandler
       // ── reads ────────────────────────────────────────────────────────────
       if (path === '/fleet/v1/snapshot') {
         if (method !== 'GET') return sendJson(res, 405, { error: 'method not allowed — GET /fleet/v1/snapshot' })
-        return sendJson(res, 200, buildFleetSnapshot(env, cfg, await getOps(), startedAtMs))
+        // broker.list() is PendingApproval[] — structurally a superset of FleetApproval, so it
+        // satisfies the snapshot contract (extra fields serialize + are ignored by clients).
+        return sendJson(res, 200, buildFleetSnapshot(env, cfg, await getOps(), startedAtMs, undefined, broker.list()))
       }
       if (path === '/fleet/v1/events') {
         if (method !== 'GET') return sendJson(res, 405, { error: 'method not allowed — GET /fleet/v1/events' })

package/src/tray/index.ts

@@ -150,3 +150,28 @@ export async function trayCmd(
   const { status, body } = await fleetPostJson(addr, path, runtime ? { runtime } : {}, env)
   return { ok: status < 400, status, body }
 }
+
+export type ApprovalVerb = 'approve' | 'deny'
+
+/**
+ * Resolve a pending human-approval from the tray: POST /fleet/v1/approvals/<id>/(approve|deny) over
+ * the SAME unix-first fleet client trayCmd uses — the proxy-safe transport (the absolute-form-misroute
+ * grabli: a peer's Happ proxy would otherwise mangle a loopback POST). Tags `via:'tray'` for the audit
+ * trail; the single-queue invariant means this resolution is seen by every channel (CLI/telegram). A
+ * 404 (already resolved / expired) surfaces as ok=false with the daemon's message — the caller reports
+ * it (the request the user saw was answered elsewhere first).
+ */
+export async function trayResolveApproval(
+  env: NodeJS.ProcessEnv,
+  decision: ApprovalVerb,
+  id: string,
+  reason?: string,
+): Promise<TrayCmdResult> {
+  const addr = resolveFleetAddress({ env })
+  if (addr.fleet !== 1 || (!addr.sock && !addr.tcp)) {
+    return { ok: false, status: 0, body: { error: 'fleet daemon unreachable (no fleet:1 in router.json)' } }
+  }
+  const path = `/fleet/v1/approvals/${encodeURIComponent(id)}/${decision}`
+  const { status, body } = await fleetPostJson(addr, path, { via: 'tray', ...(reason ? { reason } : {}) }, env)
+  return { ok: status < 400, status, body }
+}

package/src/tray/render.ts

@@ -18,8 +18,15 @@ const COLOR = {
   meta: '#8b949e',
   live: '#3fb950',
   down: '#f85149',
+  warn: '#d29922',
 } as const
 
+// Approval content shown INLINE in the menu is capped (a big diff must not blow up the
+// dropdown); the FULL verbatim content stays available via `iapeer approvals` + GET
+// /fleet/v1/approvals/<id> (criterion #7 holds on the payload, the menu is its truncated view).
+const APPROVAL_CONTENT_MAX_LINES = 20
+const APPROVAL_CONTENT_MAX_CHARS = 8000
+
 // ── docs/15 snapshot shape (only the fields the tray reads) ───────────────────
 
 export interface TrayRuntime {
@@ -40,6 +47,16 @@ export interface TrayPeer {
   queue_depth?: number
 }
 
+export interface TrayApproval {
+  id: string
+  personality: string
+  runtime?: string
+  kind?: string
+  tool: string
+  summary?: string
+  content?: string
+}
+
 export interface TraySnapshot {
   version?: string
   host?: {
@@ -50,6 +67,8 @@ export interface TraySnapshot {
     fda?: boolean | null
   }
   peers: TrayPeer[]
+  /** Pending human-approval requests (docs/15/17). ABSENT ⇒ empty queue (client obligation). */
+  approvals?: TrayApproval[]
 }
 
 export interface RenderOptions {
@@ -135,12 +154,28 @@ export function renderSwiftBar(snapshot: TraySnapshot, opts: RenderOptions): str
     return r !== 0 ? r : a.personality.localeCompare(b.personality)
   })
   const liveCount = snapshot.peers.filter(p => aggregate(p) === 'live').length
+  const pending = snapshot.approvals ?? []
+  const pendingByPeer = new Map<string, number>()
+  for (const a of pending) pendingByPeer.set(a.personality, (pendingByPeer.get(a.personality) ?? 0) + 1)
 
   const lines: string[] = []
-  // ── menu-bar title: antenna icon + live-peer count ──
-  lines.push(line(0, String(liveCount), { sfimage: 'antenna.radiowaves.left.and.right' }))
+  // ── menu-bar title ──
+  // Pending approvals TAKE OVER the menu-bar as a red iOS-style badge so the owner sees an awaiting
+  // request at a glance; an empty queue is the normal antenna + live-peer count.
+  if (pending.length > 0) {
+    lines.push(renderBadge(pending.length))
+  } else {
+    lines.push(line(0, String(liveCount), { sfimage: 'antenna.radiowaves.left.and.right' }))
+  }
   lines.push('---')
 
+  // ── pending approvals (ALWAYS-ON: whenever the queue is non-empty, at the TOP of the dropdown;
+  //    each request expanded with verbatim content + Allow/Deny at depth 0 — no extra clicks) ──
+  if (pending.length > 0) {
+    lines.push(...renderApprovals(pending, bin))
+    lines.push('---')
+  }
+
   // ── host header ──
   const ver = snapshot.host?.version ?? snapshot.version ?? '?'
   const up = snapshot.host?.uptimeSecs !== undefined ? ` · up ${fmtUptime(snapshot.host.uptimeSecs)}` : ''
@@ -154,7 +189,7 @@ export function renderSwiftBar(snapshot: TraySnapshot, opts: RenderOptions): str
     lines.push(line(0, 'no peers registered', { color: COLOR.meta }))
   }
   for (const p of peers) {
-    lines.push(renderPeerRow(p, bin, now))
+    lines.push(renderPeerRow(p, bin, now, pendingByPeer.get(p.personality) ?? 0))
   }
 
   // ── Manage submenu (lifecycle commands per peer; kept off the rows so a row click
@@ -203,7 +238,7 @@ function attachable(p: TrayPeer): boolean {
  * `Cmd-T` System-Events keystroke that silently no-ops without Accessibility permission.
  * Infra (launchd) rows are plain status lines. Lifecycle lives in the Manage submenu.
  */
-function renderPeerRow(p: TrayPeer, bin: string, now: number): string {
+function renderPeerRow(p: TrayPeer, bin: string, now: number, pendingCount = 0): string {
   const agg = aggregate(p)
   const detail = p.runtimes.map(r => `${r.runtime}${GLYPH[r.status]}`).join(' ')
   const badges =
@@ -211,8 +246,13 @@ function renderPeerRow(p: TrayPeer, bin: string, now: number): string {
     (p.launchd_managed ? ' 🔒' : '') +
     (p.wake_policy === 'ephemeral' && (p.queue_depth ?? 0) > 0 ? ` ⏳${p.queue_depth}` : '')
   const ageStr = p.last_active_ms ? `  ${fmtAge(p.last_active_ms, now)}` : ''
-  const label = `${p.personality}  ${detail}${badges}${ageStr}`
-  const rowColor = agg === 'live' ? COLOR.live : COLOR.meta
+  // HIGHLIGHT a peer with a pending approval: a ⚠ prefix + a red count badge + the row painted red
+  // so the owner sees WHICH peer is waiting (owner criterion — the static-menu equivalent of a pulse;
+  // SwiftBar cannot animate). The highlight wins over the live/meta color.
+  const prefix = pendingCount > 0 ? '⚠ ' : ''
+  const pendingBadge = pendingCount > 0 ? ` 🔴${pendingCount}` : ''
+  const label = `${prefix}${p.personality}  ${detail}${badges}${pendingBadge}${ageStr}`
+  const rowColor = pendingCount > 0 ? COLOR.down : agg === 'live' ? COLOR.live : COLOR.meta
   if (!attachable(p)) return line(0, label, { color: rowColor })
   return line(0, label, { color: rowColor, bash: bin, param1: 'tray', param2: 'attach-term', param3: p.personality, terminal: false })
 }
@@ -242,6 +282,67 @@ function renderManage(peers: TrayPeer[], bin: string): string[] {
   return out
 }
 
+// ── approval renderers (docs/17 — the always-on approval channel in the bar) ─────
+
+/** Menu-bar pending badge: a red `N.circle.fill` SF Symbol (the iOS-notification look — a red circle
+ *  with the number inside). SF Symbols carries numbered circles 0…50; past that, a red
+ *  exclamation-circle + the count as text. `sfcolor` tints the symbol red; `color` is set too as a
+ *  fallback for SwiftBar builds that read `color` for the tint. The numbered symbol carries the count,
+ *  so no text is needed for ≤50. */
+function renderBadge(count: number): string {
+  if (count <= 50) return line(0, '', { sfimage: `${count}.circle.fill`, sfcolor: COLOR.down, color: COLOR.down })
+  return line(0, String(count), { sfimage: 'exclamationmark.circle.fill', sfcolor: COLOR.down, color: COLOR.down })
+}
+
+/** Defuse SwiftBar STRUCTURAL injection from verbatim content: ` | ` is the param separator (replace
+ *  with a broken bar) and a leading `--` nests a submenu (defused by the `│ ` prefix in capContent).
+ *  Display-only — the FULL verbatim content stays in `iapeer approvals` (criterion #7 on the payload;
+ *  the menu is its truncated, structurally-safe view). */
+function sanitizeMenuText(s: string): string {
+  return s.replace(/ \| /g, ' ¦ ')
+}
+
+/** Cap the inline content (a big diff must not blow up the dropdown) and prefix each row with `│ ` so
+ *  it reads as quoted content AND never begins with `--`. Full verbatim content stays in `iapeer
+ *  approvals`. */
+function capContent(content: string): string[] {
+  const clipped = content.length > APPROVAL_CONTENT_MAX_CHARS ? content.slice(0, APPROVAL_CONTENT_MAX_CHARS) : content
+  let rows = clipped.split('\n')
+  let truncated = content.length > APPROVAL_CONTENT_MAX_CHARS
+  if (rows.length > APPROVAL_CONTENT_MAX_LINES) {
+    rows = rows.slice(0, APPROVAL_CONTENT_MAX_LINES)
+    truncated = true
+  }
+  const out = rows.map(r => `│ ${sanitizeMenuText(r)}`)
+  if (truncated) out.push('│ …[truncated — full content: iapeer approvals]')
+  return out
+}
+
+/** The pending-approval section (top of the dropdown). Each request is FLAT (depth 0, no submenu): a
+ *  header (peer · tool), the verbatim content (monospace, capped), then Allow / Deny click actions —
+ *  both visible + clickable with NO extra clicks. A click runs `iapeer tray approve|deny <id>` in the
+ *  background (unix-first fleet POST) → the broker resolves → the streaming plugin re-renders off the
+ *  approval-resolved SSE event (no refresh=true — the stream is always fresh). */
+function renderApprovals(approvals: TrayApproval[], bin: string): string[] {
+  const out: string[] = [
+    line(0, `${approvals.length} pending approval${approvals.length === 1 ? '' : 's'}`, {
+      sfimage: 'bell.badge.fill',
+      sfcolor: COLOR.down,
+      color: COLOR.down,
+    }),
+  ]
+  for (let i = 0; i < approvals.length; i++) {
+    if (i > 0) out.push('---') // separate multiple requests
+    const a = approvals[i]!
+    out.push(line(0, `${a.personality} · ${a.tool}`, { sfimage: 'hand.raised.fill', sfcolor: COLOR.warn, color: COLOR.warn }))
+    const content = a.content ?? a.summary ?? ''
+    if (content) for (const cl of capContent(content)) out.push(line(0, cl, { font: 'Menlo', size: 12, color: COLOR.meta }))
+    out.push(line(0, 'Allow', { sfimage: 'checkmark.circle.fill', sfcolor: COLOR.live, color: COLOR.live, bash: bin, param1: 'tray', param2: 'approve', param3: a.id, terminal: false }))
+    out.push(line(0, 'Deny', { sfimage: 'xmark.circle.fill', sfcolor: COLOR.down, color: COLOR.down, bash: bin, param1: 'tray', param2: 'deny', param3: a.id, terminal: false }))
+  }
+  return out
+}
+
 /** The degraded output when no advertised daemon address answers (docs/15: "A
  *  dashboard that cannot reach any advertised address should render the daemon as
  *  down"). Distinct menu-bar icon + a red header; a Refresh item to retry. */