@agfpd/iapeer 0.4.74 → 0.4.76

package/README.md

@@ -107,6 +107,8 @@ What this means for you:
 - You are trusting the model's judgment, and the doctrine you give each peer, the same way you would trust a developer with a shell on your account.
 - iapeer does **not** silently weaken your own interactive `claude` / `codex` setup. The bypass acceptance is recorded per peer, in that agent's own config; the project-MCP pre-approval is written **project-locally**, under the peer's folder — never to your global user settings.
 
+**Want a human in the loop for a given peer?** Set its approval mode to `gated` — `iapeer approval-mode <peer> gated`. That peer launches **without** the bypass flag, and every blocking approval its runtime would raise is routed to you — a Telegram button, a click in the tray, or `iapeer approve` on the CLI — before the tool runs; your `allow`/`deny` (with a reason) flows back and the tool proceeds or is refused. The default stays `yolo` (bypass) for every peer; `gated` is opt-in, per peer. See [docs/17 — Human approval](docs/17-approval.md).
+
 Run iapeer on a host you control, give each peer only the access it needs, and treat a peer's instructions as security-relevant. `iapeer onboard` states this at setup; it's repeated here so the trade-off is explicit before you create your first agent. Details on every first-run dialog: [docs/07 — Install & update](docs/07-install-and-update.md#first-run-dialogs-on-a-clean-machine).
 
 ## Documentation
@@ -121,8 +123,6 @@ Planned, not yet built:
 - **Linux support** — iapeer runs on macOS today; Linux is planned.
 - **More agent runtimes** — `opencode` and `antigravity`, two further CLI runtimes alongside Claude Code and Codex.
 - **Discord runtime** — a human-presence runtime for Discord, alongside Telegram.
-- **Permissions gate** — finer control over what an agent is allowed to do.
-- **Approve permissions over Telegram** — approve an agent's permission requests from the chat; today permissions are auto-allowed by flags.
 
 ## License
 

package/docs/07-install-and-update.md

@@ -35,7 +35,7 @@ The same operation is available as `iapeer install` if the binary is already in
 iapeer onboard
 ```
 
-`onboard` prepares the host for agents. First of all it **brings up the daemon** — loads the plist into launchd, after which launchd holds the daemon itself, bringing it back up on a crash and a reboot. No separate `launchctl` command is needed for this. Then onboard registers the extension marketplace in Claude and Codex, provisions the scheduler (`notifier`), creates a human peer on Telegram, and installs the memory provider. The daemon start always runs; the rest are on by default and turned off with flags (`--no-notifier`, `--no-telegram`, `--no-memory`).
+`onboard` prepares the host for agents. First of all it **brings up the daemon** — loads the plist into launchd, after which launchd holds the daemon itself, bringing it back up on a crash and a reboot. No separate `launchctl` command is needed for this. Then onboard registers the extension marketplace in Claude and Codex, provisions the scheduler (`notifier`), creates a human peer on Telegram, installs the memory provider and the voice backend, and offers the menu-bar tray face (SwiftBar). The daemon start always runs; the memory/voice/notifier/telegram steps are on by default and turned off with flags (`--no-notifier`, `--no-telegram`, `--no-memory`, `--no-voice`). The **tray** is the exception — default **off** (it pulls in a GUI app via Homebrew), opted into with `--tray` on the non-interactive path or a `[y/N]` prompt in the interactive wizard; without Homebrew it degrades to a soft skip (the plugin is left in place, install SwiftBar manually with `iapeer tray install --app`).
 
 Check the daemon is alive and the host is ready:
 

package/docs/16-tray.md

@@ -24,11 +24,16 @@ activation that also installs SwiftBar.app when it is absent.
   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:
+  provider heartbeats, then one row per peer, in **two groups**: the `🔒` **launchd block**
+  (the human channel + service infra — non-clickable status rows) is pulled to the **top as
+  one contiguous block, before the first working agent**, regardless of live/asleep — so the
+  bar separates "service, don't touch" from the working agents at a glance. Working agents
+  follow. Within **each** group the order is live → asleep → stopped, then alphabetical.
   - `<peer>  <runtime><glyph> …  <age>` with the same glyph semantics as the CLI —
     `●` live · `○` asleep · `✕` stopped — green when any runtime is live. Badges: `👤`
-    a human is attached, `🔒` launchd-managed (H4 read-only), `⏳N` an ephemeral peer's
-    queue depth.
+    a human is attached, `🔒` launchd-managed (H4 read-only), `🛡` the peer runs in **gated**
+    human-approval mode (docs/17; `yolo` is the fleet default and carries no badge — a bare
+    row reads as yolo), `⏳N` an ephemeral peer's queue depth.
   - **Click an agent peer → Terminal.app running `iapeer attach <peer>`.** The row itself is
     the attach action (no submenu, so a click attaches rather than merely expanding). The
     handoff goes through `iapeer tray attach-term`, which writes a per-peer `.command`
@@ -37,8 +42,16 @@ activation that also installs SwiftBar.app when it is absent.
     own `terminal=true`, whose Terminal launch drives a `Cmd-T` System-Events keystroke that
     silently no-ops unless SwiftBar holds Accessibility permission. **Launchd-managed infra
     peers (telegram / notifier, `🔒`) are not pty-attachable** — their rows are plain status
-    lines. Lifecycle actions (Wake / Stop / Start / New / Interrupt / Refresh / Compact) live
+    lines. Lifecycle actions (Stop / Start / New / Interrupt / Refresh / Compact) live
     in the **Manage** submenu, each a `POST /fleet/v1/peers/<peer>/<cmd>` via `iapeer tray cmd`.
+    (No Wake item — a peer-row click already wakes a sleeping peer before it attaches, so
+    it was redundant.) For an agentic peer the Manage submenu also carries an
+    **approval-mode toggle** (docs/17): it reads the current mode and flips it via the local
+    `iapeer approval-mode <peer> <mode>` verb, applied on the peer's **next fresh session**
+    (a click never respawns a live session). The friction is asymmetric to the security
+    weight: `yolo → gated` (adds human approval) is one safe tap; `gated → yolo` (REMOVES the
+    approval perimeter) sits behind the submenu as an explicit red ⚠ confirm, so it is never
+    dropped by a stray click.
 - **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

package/docs/ru/16-tray.md

@@ -22,11 +22,16 @@ SwiftBar.app, если его нет.
   покажет сломанный демон — встроенный TUI держит прямой путь чтения для этого случая, см.
   [15](15-fleet-api.md)).
 - **Выпадашка:** шапка хоста (`iapeer <версия> · up <аптайм>`) и хартбиты провайдеров памяти
-  и голоса, затем строка на пира:
+  и голоса, затем строка на пира, **двумя группами**: блок `🔒` **под launchd** (человеческий
+  канал + служебная инфра — некликабельные статус-строки) вынесен **наверх единым непрерывным
+  блоком, перед первым рабочим агентом**, независимо от live/asleep — так бар с одного взгляда
+  отделяет «служебное, не трогать» от рабочих агентов. Рабочие агенты идут следом. Внутри
+  **каждой** группы порядок: живой → спит → остановлен, затем по алфавиту.
   - `<peer>  <рантайм><глиф> …  <возраст>` с той же семантикой глифов, что в CLI —
     `●` живой · `○` спит · `✕` остановлен — зелёный, если хоть один рантайм живой. Бейджи:
-    `👤` подключён человек, `🔒` под launchd (H4 read-only), `⏳N` глубина очереди эфемерного
-    пира.
+    `👤` подключён человек, `🔒` под launchd (H4 read-only), `🛡` пир в режиме **gated**
+    human-approval (docs/17; `yolo` — дефолт флота, без бейджа: голая строка читается как yolo),
+    `⏳N` глубина очереди эфемерного пира.
   - **Клик по агент-пиру → Terminal.app с `iapeer attach <peer>`.** Строка сама и есть действие
     attach (без подменю — клик аттачит, а не раскрывает). Передача идёт через `iapeer tray
     attach-term`: пишет per-peer `.command`-лаунчер и `open`'ит его — `open <файл>.command`
@@ -34,8 +39,15 @@ SwiftBar.app, если его нет.
     родной `terminal=true` SwiftBar, чей запуск Terminal бьёт `Cmd-T` кейстроком через System
     Events и молча не срабатывает без права Accessibility у SwiftBar. **Launchd-инфра-пиры
     (telegram / notifier, `🔒`) не pty-аттачатся** — их строки просто статус. Lifecycle-действия
-    (Wake / Stop / Start / New / Interrupt / Refresh / Compact) — в подменю **Manage**, каждое —
-    `POST /fleet/v1/peers/<peer>/<cmd>` через `iapeer tray cmd`.
+    (Stop / Start / New / Interrupt / Refresh / Compact) — в подменю **Manage**, каждое —
+    `POST /fleet/v1/peers/<peer>/<cmd>` через `iapeer tray cmd`. (Пункта Wake нет — клик по строке
+    пира и так будит спящего перед аттачем, отдельный Wake был избыточен.) Для агентного пира
+    подменю Manage несёт ещё **переключатель approval-режима** (docs/17): читает текущий режим и
+    флипает его локальным verb'ом `iapeer approval-mode <peer> <mode>`, применяется на **следующей
+    свежей сессии** пира (клик никогда не респавнит живую сессию). Трение асимметрично весу
+    безопасности: `yolo → gated` (добавляет human-approval) — один безопасный тап; `gated → yolo`
+    (СНИМАЕТ периметр approval) спрятан в подменю как явный красный ⚠ confirm, чтобы его не сбросить
+    случайным кликом.
 - **Ожидающие подтверждения (docs/17):** когда очередь непуста, **вверху выпадашки** каждый
   ожидающий запрос показан **раскрытым, без доп. кликов** — заголовок (`<peer> · <tool>`),
   **дословное содержимое действия** (команда / диф / план, моноширинно, усечено для меню; ПОЛНОЕ

package/package.json

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

@@ -1168,6 +1168,7 @@ const BOOLEAN_FLAGS: ReadonlySet<string> = new Set([
   'plugin-only',
   'remove-codesign-identity',
   'stream',
+  'tray',
   'yes',
 ])
 
@@ -1219,8 +1220,8 @@ const VERBS: ReadonlyArray<{ sig: string; desc: string }> = [
   { sig: 'help | --help | -h', desc: 'print this usage (works appended to any verb; executes nothing)' },
   { sig: 'daemon [--install-plist]', desc: 'run the host-wide HTTP-MCP router (launchd-held)' },
   {
-    sig: 'onboard [--accept-risk] [--dry-run] [--no-notifier] [--no-telegram] [--telegram-human <p>] [--telegram-user-id <id>] [--no-memory] [--memory <pkg>] [--no-voice] [--voice <pkg>] [--infra <csv>]',
-    desc: 'backbone host-phase: marketplace → notifier → telegram (human peer) → memory → voice (all default YES). --accept-risk (or IAPEER_ACCEPT_RISK=1) accepts the security warning non-interactively',
+    sig: 'onboard [--accept-risk] [--dry-run] [--no-notifier] [--no-telegram] [--telegram-human <p>] [--telegram-user-id <id>] [--no-memory] [--memory <pkg>] [--no-voice] [--voice <pkg>] [--tray] [--infra <csv>]',
+    desc: 'backbone host-phase: marketplace → notifier → telegram (human peer) → memory → voice (default YES) → tray (default NO, --tray opts in). --accept-risk (or IAPEER_ACCEPT_RISK=1) accepts the security warning non-interactively',
   },
   { sig: 'status', desc: 'host snapshot: version, daemon health, memory + voice slots (<provider> | none)' },
   { sig: 'live-runtime <peer>', desc: 'print the peer\'s CURRENT live runtime (freshest pane-log among pid-alive sessions; NOT default_runtime). Exit 1 + no output if none alive' },
@@ -1526,6 +1527,17 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         })
         const voiceLabel = voice.provider ? `${voice.provider.provider} ${voice.provider.version}` : 'none'
         out(`voice: ${voice.state}${voice.detail ? ` — ${voice.detail}` : ''} (slot: ${voiceLabel})\n`)
+        // Tray face (SwiftBar menu-bar fleet dashboard): OPTIONAL and DEFAULT-NO on the
+        // linear path (a GUI dependency — conservatively opt-in). `--tray` opts in;
+        // without it the step is skipped (non-interactive never hangs — the step asks
+        // nothing). The plugin FILE is already dropped by install; this is GUI activation.
+        const { onboardTrayStep } = await import('../onboard/tray.ts')
+        const tray = await onboardTrayStep({
+          skip: flags.tray !== true,
+          dryRun: flags['dry-run'] === true,
+          env,
+        })
+        out(`tray: ${tray.state}${tray.detail ? ` — ${tray.detail}` : ''}\n`)
         // Runtime auth readiness (clean-host prerequisite): a peer runs the runtime's
         // interactive TUI; the launcher auto-clears first-run modals (theme/trust) but
         // CANNOT complete a login OAuth flow. Warn for every INSTALLED runtime (marketplace

package/src/launch/index.ts

@@ -122,6 +122,24 @@ export function exitLogPath(exitLogDir: string): string {
 // launch — bring up ONE session (runtime-agnostic via the adapter)
 // ─────────────────────────────────────────────────────────────────────────────
 
+/**
+ * The intelligence gate — launch step (0), extracted as a PURE predicate so it is
+ * unit-testable in isolation (no bring-up, never touches the pty host). A channel
+ * adapter that declares `allowedIntelligences` (telegram/voicetalk → ['natural',
+ * 'absent']) refuses a peer whose nature is NOT in the set — and refuses too when
+ * the nature is unknown (cannot confirm). Returns the fail-loud reason string, or
+ * `null` when the gate PASSES (the peer may proceed to bring-up).
+ */
+export function intelligenceGateReason(adapter: RuntimeAdapter, spec: LaunchSpec): string | null {
+  if (adapter.allowedIntelligences && (spec.intelligence == null || !adapter.allowedIntelligences.includes(spec.intelligence))) {
+    return (
+      `runtime "${spec.runtime}" requires intelligence ∈ {${adapter.allowedIntelligences.join(', ')}}, ` +
+      `peer "${spec.personality}" is ${spec.intelligence ?? 'unknown'} — refusing to launch`
+    )
+  }
+  return null
+}
+
 export const launch: LaunchFn = async (
   spec: LaunchSpec,
   adapter: RuntimeAdapter,
@@ -137,13 +155,8 @@ export const launch: LaunchFn = async (
   //     A channel runtime carries a human (natural) OR a faceless service bot (absent), never an
   //     LLM agent (artificial). Ports the persistent-peer FATAL human-channel guard, relaxed to
   //     first-class faceless service bots (docs/Рантайм-адаптеры).
-  if (adapter.allowedIntelligences && (spec.intelligence == null || !adapter.allowedIntelligences.includes(spec.intelligence))) {
-    return fail(
-      identity,
-      `runtime "${spec.runtime}" requires intelligence ∈ {${adapter.allowedIntelligences.join(', ')}}, ` +
-        `peer "${spec.personality}" is ${spec.intelligence ?? 'unknown'} — refusing to launch`,
-    )
-  }
+  const gateReason = intelligenceGateReason(adapter, spec)
+  if (gateReason) return fail(identity, gateReason)
 
   // (0.5) Ensure the socket's PARENT dir exists before `tmux new-session -S <sock>` —
   //       tmux does NOT create it and fails SILENTLY (the session "dies immediately")

package/src/onboard/tray.ts

@@ -0,0 +1,101 @@
+// Tray-face onboard step (the SwiftBar menu-bar fleet dashboard).
+//
+// Host-phase, OPTIONAL, DEFAULT-NO (a GUI dependency — conservative: do not pull it
+// onto the host without an explicit yes). This is a thin WRAPPER over the existing
+// activation `installTray` (src/tray/install.ts) — the SAME mechanics as `iapeer tray
+// install --app`: brew cask + dequarantine + launch + refresh — dressed in an
+// onboard-shaped result vocabulary, with a SOFT no-Homebrew path (report + continue,
+// NEVER fail the onboard) per the phase principle "unavailability is a soft skip".
+//
+// IDEMPOTENT: SwiftBar already installed → NOT reinstalled, only the plugin is
+// (re)activated + launched. The plugin FILE itself is dropped by the foundation
+// install step regardless (inert without SwiftBar); this step is the GUI activation.
+//
+// Outcome semantics: this step NEVER fails the onboard exit code — no tray is a fully
+// valid state regardless of why (skipped / no brew / cask failure). Mirrors
+// onboard/voice.ts deliberately (same shape), minus the provider-slot concepts.
+
+import { isExecutable } from './index.ts'
+import { installTray, swiftBarInstalled, type Runner } from '../tray/install.ts'
+
+export interface TrayOnboardOptions {
+  /** --no-tray (wizard) / absence of --tray (linear): skip the step entirely. */
+  skip?: boolean
+  dryRun?: boolean
+  env?: NodeJS.ProcessEnv
+  /** Injectable side-effect runner (tests). Default: installTray's own spawnSync. */
+  run?: Runner
+  /** Injectable SwiftBar.app presence probe (tests). Default swiftBarInstalled(). */
+  probeApp?: () => boolean
+  /** Injectable Homebrew-availability probe (tests). Default: `brew` on PATH. */
+  brewAvailable?: () => boolean
+}
+
+export interface TrayOnboardResult {
+  state:
+    | 'installed' // SwiftBar.app installed (brew cask) + plugin activated + launched
+    | 'activated' // SwiftBar already present → plugin activated + launched (idempotent, no reinstall)
+    | 'skipped-flag' // --no-tray / not opted-in
+    | 'skipped-no-brew' // SwiftBar absent AND no Homebrew — soft skip (plugin dropped inert; guidance given)
+    | 'install-failed' // brew ran and failed (network/cask) — soft (reported; plugin still lands)
+    | 'dry-run'
+  detail?: string
+  /** The resolved plugin file, when known. */
+  pluginFile?: string
+}
+
+const DOCS = 'docs/16-tray.md'
+
+export async function onboardTrayStep(opts: TrayOnboardOptions = {}): Promise<TrayOnboardResult> {
+  const env = opts.env ?? process.env
+  if (opts.skip) return { state: 'skipped-flag' }
+  const probeApp = opts.probeApp ?? swiftBarInstalled
+  const brewAvailable = opts.brewAvailable ?? ((): boolean => isExecutable('brew', env))
+
+  if (opts.dryRun) {
+    const present = probeApp()
+    return {
+      state: 'dry-run',
+      detail: present
+        ? 'SwiftBar present — would activate the fleet plugin + launch'
+        : brewAvailable()
+          ? 'would install SwiftBar.app (brew cask) + activate the fleet plugin + launch'
+          : 'no Homebrew — would drop the plugin inert + advise manual SwiftBar install',
+    }
+  }
+
+  const present = probeApp()
+
+  // SwiftBar absent AND no Homebrew → SOFT skip. The auto-install path is brew-only, so
+  // without it there is nothing to run; drop the plugin inert (it activates the moment
+  // SwiftBar appears), guide the user, and NEVER fail the onboard.
+  if (!present && !brewAvailable()) {
+    const r = installTray({ env, installApp: false, launch: false, run: opts.run, probeApp: opts.probeApp })
+    return {
+      state: 'skipped-no-brew',
+      pluginFile: r.pluginFile,
+      detail:
+        'Homebrew not found — the menu-bar app (SwiftBar) needs it. The fleet plugin is in place; ' +
+        'install SwiftBar manually (`brew install --cask swiftbar`, or https://swiftbar.app), then run ' +
+        `\`iapeer tray install --app\`. Details: ${DOCS}`,
+    }
+  }
+
+  // Present → activate ONLY (installApp:false — never reinstall). Absent + brew → install the cask.
+  const r = installTray({ env, installApp: !present, launch: true, run: opts.run, probeApp: opts.probeApp })
+  if (r.app === 'install-failed') {
+    return {
+      state: 'install-failed',
+      pluginFile: r.pluginFile,
+      detail:
+        `SwiftBar install via brew failed (${r.appReason ?? 'unknown'}) — the fleet plugin is in place; ` +
+        `retry with \`iapeer tray install --app\` or install SwiftBar manually (${DOCS}).`,
+    }
+  }
+  const activatedMsg = r.launched ? 'plugin activated + SwiftBar launched' : 'plugin written (SwiftBar not launched)'
+  return {
+    state: present ? 'activated' : 'installed',
+    pluginFile: r.pluginFile,
+    detail: `${activatedMsg}${r.dir === 'existing-swiftbar' ? ' (your SwiftBar plugin dir)' : ''}`,
+  }
+}

package/src/tray/render.ts

@@ -43,6 +43,8 @@ export interface TrayPeer {
   last_active_ms?: number
   attached?: boolean
   launchd_managed?: boolean
+  /** Human-approval mode (docs/17). ABSENT ⇒ `yolo` (client obligation — a pre-approval daemon omits it). */
+  approval_mode?: 'yolo' | 'gated'
   wake_policy?: 'warm' | 'ephemeral'
   queue_depth?: number
 }
@@ -133,10 +135,18 @@ function aggregate(p: TrayPeer): 'live' | 'asleep' | 'stopped' {
 
 const RANK: Record<'live' | 'asleep' | 'stopped', number> = { live: 0, asleep: 1, stopped: 2 }
 
+// 🔒 launchd-managed peers (the human channel + service infra — arthur/timer/watcher) are
+// NON-clickable status rows. They form ONE contiguous block at the very TOP, before the first
+// working agent, regardless of live/asleep — so the bar separates "service, don't touch" from the
+// working agents at a glance (owner UX). `attachable` (= !launchd_managed) is the same predicate.
+const lockRank = (p: TrayPeer): number => (p.launchd_managed ? 0 : 1)
+
 // ── renderers ─────────────────────────────────────────────────────────────────
 
 const MANAGE_COMMANDS: Array<{ cmd: string; label: string }> = [
-  { cmd: 'wake', label: 'Wake' },
+  // NB: no 'Wake' — a peer-row click (attach) already wakes a sleeping peer before it
+  // connects, so a separate Wake item was redundant (owner decision). `tray cmd wake`
+  // stays available on the CLI / fleet API; only the menu item is dropped.
   { cmd: 'stop', label: 'Stop' },
   { cmd: 'start', label: 'Start' },
   { cmd: 'new', label: 'New session (fresh)' },
@@ -150,6 +160,10 @@ export function renderSwiftBar(snapshot: TraySnapshot, opts: RenderOptions): str
   const now = opts.now ?? Date.now()
   const bin = opts.binPath
   const peers = [...snapshot.peers].sort((a, b) => {
+    // primary: the 🔒 lock block first (service/human infra), working agents below
+    const l = lockRank(a) - lockRank(b)
+    if (l !== 0) return l
+    // secondary (within EACH block): the existing live→asleep→stopped, then alpha
     const r = RANK[aggregate(a)] - RANK[aggregate(b)]
     return r !== 0 ? r : a.personality.localeCompare(b.personality)
   })
@@ -241,9 +255,14 @@ function attachable(p: TrayPeer): boolean {
 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(' ')
+  // approval mode (docs/17): the whole fleet defaults to `yolo`, so showing it on every row is
+  // noise — mark ONLY the exception, `gated` (this peer's blocking approvals go to a human), with a
+  // 🛡 shield. No badge ⇒ yolo (the default; also how a pre-approval snapshot with the field absent
+  // renders). So the row reads the mode: 🛡 = gated, bare = yolo.
   const badges =
     (p.attached ? ' 👤' : '') +
     (p.launchd_managed ? ' 🔒' : '') +
+    (p.approval_mode === 'gated' ? ' 🛡' : '') +
     (p.wake_policy === 'ephemeral' && (p.queue_depth ?? 0) > 0 ? ` ⏳${p.queue_depth}` : '')
   const ageStr = p.last_active_ms ? `  ${fmtAge(p.last_active_ms, now)}` : ''
   // HIGHLIGHT a peer with a pending approval: a ⚠ prefix + a red count badge + the row painted red
@@ -278,10 +297,54 @@ function renderManage(peers: TrayPeer[], bin: string): string[] {
         }),
       )
     }
+    // approval-mode toggle — only for agentic (attachable) peers; meaningless for the
+    // human channel / notifier infra (arthur/timer/watcher), which are always yolo.
+    if (attachable(p)) out.push(...renderApprovalToggle(p, bin))
   }
   return out
 }
 
+/**
+ * The per-peer approval-mode control in the Manage submenu (docs/17): READS the current
+ * mode and FLIPS it via the local `approval-mode` verb.
+ *
+ * APPLY = next session, NOT now. The flip persists the mode + brings the runtime
+ * surfaces to it; it does NOT pass --now, so it takes effect on the peer's NEXT fresh
+ * session. A menu tap must never kill a live session mid-work (a respawn is a heavy,
+ * surprising side effect of a click). The item says "(next session)" so the wait is
+ * explicit.
+ *
+ * refresh=true is the ONE deliberate exception to the "no refresh in the streamable
+ * menu" rule: the flip runs the local verb (no daemon round-trip → NO SSE event), so
+ * the plugin must re-render to reflect the new mode.
+ *
+ * SECURITY-ASYMMETRIC friction (a mode-flip changes the security PERIMETER — unlike a
+ * one-off Deny): yolo→gated STRENGTHENS (adds human approval) → a single safe tap;
+ * gated→yolo WEAKENS (REMOVES human approval) → the current mode sits on a submenu and
+ * the flip is an explicit red ⚠ confirm CHILD, so the perimeter is never dropped by one
+ * stray click. SwiftBar has no native confirm dialog — the nested explicit item IS the
+ * confirm.
+ */
+function renderApprovalToggle(p: TrayPeer, bin: string): string[] {
+  const flip = (target: 'gated' | 'yolo'): Record<string, string | boolean> => ({
+    bash: bin,
+    param1: 'approval-mode',
+    param2: p.personality,
+    param3: target,
+    terminal: false,
+    refresh: true, // local verb → no SSE event → re-render to show the new mode
+  })
+  if (p.approval_mode === 'gated') {
+    // WEAKEN — current on the parent (no action); the flip is an explicit red confirm child.
+    return [
+      line(2, 'Approval: gated 🛡', { color: COLOR.warn }),
+      line(3, '⚠ Switch to yolo — removes human approval (next session)', { color: COLOR.down, ...flip('yolo') }),
+    ]
+  }
+  // STRENGTHEN (yolo → gated) — safe, one tap.
+  return [line(2, 'Approval: yolo → gated 🛡 (next session)', flip('gated'))]
+}
+
 // ── 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

package/src/tui/onboard/app.tsx

@@ -19,6 +19,8 @@ export interface WizardResult {
   code: number
   memoryConsent: boolean
   voiceConsent: boolean
+  /** Install the SwiftBar menu-bar tray face (default-NO — a GUI dependency). */
+  trayConsent: boolean
   advisories: string[]
   summary: string[]
   telegramConsent: boolean
@@ -28,7 +30,7 @@ export interface WizardResult {
   hostRuntime?: OnboardRuntime
 }
 
-type Phase = 'gate' | 'running' | 'telegram' | 'memory' | 'voice' | 'declined' | 'finishing'
+type Phase = 'gate' | 'running' | 'telegram' | 'memory' | 'voice' | 'tray' | 'declined' | 'finishing'
 type StepStatus = 'pending' | 'running' | 'ok' | 'warn' | 'fail'
 interface Step {
   key: string
@@ -98,16 +100,20 @@ export function OnboardApp({
   const [hostRuntime, setHostRuntime] = useState<OnboardRuntime | undefined>(undefined)
   const [telegramConsent, setTelegramConsent] = useState(false)
   const [memoryConsent, setMemoryConsent] = useState(false)
+  const [voiceConsent, setVoiceConsent] = useState(false)
   const spin = useSpinnerFrame(phase === 'running')
 
-  const finish = (voiceConsent: boolean): void => {
+  const finish = (trayConsent: boolean): void => {
     const failed = steps.some(s => s.status === 'fail')
     const summary = steps.map(s => {
       const mark = s.status === 'ok' ? '✓' : s.status === 'warn' ? '!' : s.status === 'fail' ? '✗' : '·'
       return `  ${mark} ${s.label}${s.detail ? ` — ${s.detail}` : ''}`
     })
     summary.unshift(failed ? 'Onboard finished with errors:' : 'Onboard complete:')
-    onResult({ code: failed ? 1 : 0, memoryConsent, voiceConsent, telegramConsent, advisories, summary, hostRuntime })
+    // voiceConsent is committed state by now (its phase completed a render cycle before
+    // tray); trayConsent is the last decision, passed directly (its setState wouldn't
+    // have flushed within this same input handler).
+    onResult({ code: failed ? 1 : 0, memoryConsent, voiceConsent, trayConsent, telegramConsent, advisories, summary, hostRuntime })
     setPhase('finishing')
     setTimeout(() => exit(), 30)
   }
@@ -152,19 +158,34 @@ export function OnboardApp({
     { isActive: phase === 'memory' },
   )
 
-  // Voice consent — DEFAULT-YES ([Y/n]: Enter or y → install). The LAST consent → finish.
+  // Voice consent — DEFAULT-YES ([Y/n]: Enter or y → install). Then → tray.
   useInput(
     (input, key) => {
-      if (input === 'n' || input === 'N') finish(false)
-      else if (input === 'y' || input === 'Y' || key.return) finish(true)
+      if (input === 'n' || input === 'N') {
+        setVoiceConsent(false)
+        setPhase('tray')
+      } else if (input === 'y' || input === 'Y' || key.return) {
+        setVoiceConsent(true)
+        setPhase('tray')
+      }
     },
     { isActive: phase === 'voice' },
   )
 
+  // Tray consent — DEFAULT-NO ([y/N]: Enter or n → skip; y → install). A GUI
+  // dependency (SwiftBar), so conservatively opt-IN. The LAST consent → finish.
+  useInput(
+    (input, key) => {
+      if (input === 'y' || input === 'Y') finish(true)
+      else if (input === 'n' || input === 'N' || key.return || key.escape) finish(false)
+    },
+    { isActive: phase === 'tray' },
+  )
+
   // Declined → exit 1 (no host mutation).
   useEffect(() => {
     if (phase !== 'declined') return
-    onResult({ code: 1, memoryConsent: false, voiceConsent: false, telegramConsent: false, advisories: [], summary: ['onboard aborted — risk not accepted.'] })
+    onResult({ code: 1, memoryConsent: false, voiceConsent: false, trayConsent: false, telegramConsent: false, advisories: [], summary: ['onboard aborted — risk not accepted.'] })
     const t = setTimeout(() => exit(), 30)
     return () => clearTimeout(t)
   }, [phase, onResult, exit])
@@ -377,6 +398,14 @@ export function OnboardApp({
           <Text dimColor> A local text-to-speech / speech-to-text HTTP service. Per-agent voice tools are a separate `iapeer enable`. [Y/n]</Text>
         </Box>
       ) : null}
+      {phase === 'tray' ? (
+        <Box marginTop={1} flexDirection="column">
+          <Text bold color="cyan">
+            ? Install the menu-bar tray face (SwiftBar)?
+          </Text>
+          <Text dimColor> A live fleet dashboard in your macOS menu bar (installs SwiftBar via Homebrew). [y/N]</Text>
+        </Box>
+      ) : null}
     </Box>
   )
 }

package/src/tui/onboard/run.tsx

@@ -71,7 +71,7 @@ export async function runOnboardWizard(opts: OnboardWizardOptions = {}): Promise
   // wizard only runs on one), off under NO_COLOR.
   const a = makeAnsi(colorEnabled(env, process.stdout))
 
-  let result: WizardResult = { code: 0, memoryConsent: false, voiceConsent: false, telegramConsent: false, advisories: [], summary: [] }
+  let result: WizardResult = { code: 0, memoryConsent: false, voiceConsent: false, trayConsent: false, telegramConsent: false, advisories: [], summary: [] }
   try {
     const app = render(<OnboardApp env={env} onResult={r => (result = r)} />)
     await app.waitUntilExit()
@@ -164,6 +164,31 @@ export async function runOnboardWizard(opts: OnboardWizardOptions = {}): Promise
         '\n' + paintResult('voice', 'skipped', ' — set it up later with `npx @agfpd/voice-connect init`', a) + '\n',
       )
     }
+
+    if (result.trayConsent) {
+      const { onboardTrayStep } = await import('../../onboard/tray.ts')
+      process.stdout.write(
+        '\n' +
+          a.bold('Installing the menu-bar tray face (SwiftBar)…') +
+          '\n' +
+          a.dim(
+            'A live fleet dashboard in the macOS menu bar. Needs Homebrew to auto-install SwiftBar;\n' +
+              'without brew the plugin is dropped inert and you install SwiftBar manually (`iapeer tray install --app`).',
+          ) +
+          '\n\n',
+      )
+      try {
+        const t = await onboardTrayStep({ env })
+        process.stdout.write('\n' + paintResult('tray', t.state, t.detail ? ` — ${t.detail}` : '', a) + '\n')
+      } catch (e) {
+        const rest = ` — ${e instanceof Error ? e.message : String(e)} ${a.dim('(activate later: `iapeer tray install --app`)')}`
+        process.stdout.write('\n' + paintResult('tray', 'step skipped', rest, a) + '\n')
+      }
+    } else {
+      process.stdout.write(
+        '\n' + paintResult('tray', 'skipped', ' — add it later with `iapeer tray install --app`', a) + '\n',
+      )
+    }
   } finally {
     process.removeListener('SIGINT', ignore)
     for (const h of prevInt) process.on('SIGINT', h as NodeJS.SignalsListener)