@agfpd/iapeer 0.4.75 → 0.4.77

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

@@ -42,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

@@ -39,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.75",
+  "version": "0.4.77",
   "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/hook.ts

@@ -112,10 +112,20 @@ function throwEvent(v: unknown): never {
   throw new Error(`hook stdin has an unexpected hook_event_name "${String(v)}"`)
 }
 
-/** The decision JSON in the shape the given event accepts. A deny carries the reason to the
- *  model. PermissionRequest uses `decision.behavior` (+ `message`); PreToolUse uses
- *  `permissionDecision` (+ `permissionDecisionReason`) — both verified live 2.1.201 / codex 0.142.5. */
-export function formatHookDecision(d: ApprovalDecision, event: HookEvent): string {
+/**
+ * The decision JSON in the shape the given event (and runtime) accepts. A deny carries the
+ * reason to the model. PermissionRequest uses `decision.behavior` (+ `message`); PreToolUse
+ * uses `permissionDecision` (+ `permissionDecisionReason`).
+ *
+ * codex vs claude on the PreToolUse **allow** path (VERIFIED LIVE, codex-cli 0.142.5): codex
+ * honors ONLY `permissionDecision:"deny"` — emitting `permissionDecision:"allow"` marks the
+ * hook **Failed** (fail-open, the "PreToolUse Failed"/"unsupported permissionDecision:allow"
+ * the operator saw). The clean allow on codex is to **abstain**: emit NOTHING (exit 0) → codex
+ * marks the hook **Completed** and the tool proceeds under the gated bypass base (approval is a
+ * DENY-or-abstain gate on codex, not a two-sided allow/deny one). claude's PreToolUse DOES honor
+ * `permissionDecision:"allow"`, so it keeps the affirmative form. Deny is identical on both.
+ */
+export function formatHookDecision(d: ApprovalDecision, event: HookEvent, runtime = 'claude'): string {
   if (event === 'PermissionRequest') {
     return JSON.stringify({
       hookSpecificOutput: {
@@ -124,11 +134,19 @@ export function formatHookDecision(d: ApprovalDecision, event: HookEvent): strin
       },
     })
   }
+  // PreToolUse
+  if (d.decision === 'allow') {
+    // codex: abstain (empty output) — an affirmative "allow" fails the hook (verified live 0.142.5).
+    if (runtime === 'codex') return ''
+    // claude: affirmative allow is honored.
+    return JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow' } })
+  }
+  // deny (+ reason) — honored identically on claude and codex.
   return JSON.stringify({
     hookSpecificOutput: {
       hookEventName: 'PreToolUse',
-      permissionDecision: d.decision,
-      ...(d.decision === 'deny' && d.reason ? { permissionDecisionReason: d.reason } : {}),
+      permissionDecision: 'deny',
+      ...(d.reason ? { permissionDecisionReason: d.reason } : {}),
     },
   })
 }
@@ -162,6 +180,9 @@ export async function runApprovalHook(stdin: string, deps: RunHookDeps = {}): Pr
   const env = deps.env ?? process.env
   const doFetch = deps.fetch ?? fetch
   const timeoutMs = deps.timeoutMs
+  // Runtime resolved up front so BOTH the success and the fail-safe-deny paths format for the
+  // right runtime (codex's allow-shape differs from claude's — see formatHookDecision).
+  const runtime = env.PEER_RUNTIME?.trim() || 'claude'
   let event: HookEvent
   let toolName: string
   let toolInput: Record<string, unknown> | undefined
@@ -174,18 +195,17 @@ export async function runApprovalHook(stdin: string, deps: RunHookDeps = {}): Pr
   try {
     const personality = env.PEER_PERSONALITY?.trim()
     if (!personality) throw new Error('no PEER_PERSONALITY in the hook environment')
-    const runtime = env.PEER_RUNTIME?.trim() || 'claude'
     const { kind, content, summary } = actionContent(toolName, toolInput)
     const decision = await requestApproval(
       resolveFleetBase(env),
       { personality, runtime, kind, tool: toolName, content, summary },
       { env, fetch: doFetch, timeoutMs },
     )
-    return { stdout: formatHookDecision(decision, event), stderr: '', exitCode: 0 }
+    return { stdout: formatHookDecision(decision, event, runtime), stderr: '', exitCode: 0 }
   } catch (e) {
     // Event known → event-appropriate DENY JSON (never allow-by-accident, never hang).
     return {
-      stdout: formatHookDecision({ decision: 'deny', reason: `iapeer approval unavailable (${e instanceof Error ? e.message : String(e)}) — denied fail-safe` }, event),
+      stdout: formatHookDecision({ decision: 'deny', reason: `iapeer approval unavailable (${e instanceof Error ? e.message : String(e)}) — denied fail-safe` }, event, runtime),
       stderr: '',
       exitCode: 0,
     }

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/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

@@ -144,7 +144,9 @@ 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)' },
@@ -295,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)