@agfpd/iapeer 0.4.63 → 0.4.65

package/src/tray/client.ts

@@ -0,0 +1,233 @@
+// tray/client — the fleet-API HTTP client. Ф1 of iapeer-tray is the FIRST EXTERNAL
+// client of the daemon's fleet API, and it is written ONLY against the normative
+// contract docs/15-fleet-api.md — NOT against daemon source. This module therefore
+// imports NOTHING from src/daemon: it discovers the daemon via router.json, speaks
+// plain HTTP+JSON (+SSE) over the two advertised listeners, and models the snapshot
+// with its OWN local interfaces (client obligation 2: unknown fields ignored). If the
+// doc and the daemon ever diverge, this client feels it — that is the whole point of
+// dogfooding the contract through a real second client.
+//
+// Transport: prefer the 0600 unix socket (same-uid, same trust class as the CLI),
+// fall back to the TCP loopback. Bun's fetch carries the `unix` option; the compiled
+// `iapeer` binary bundles the Bun runtime, so this works when SwiftBar execs it.
+
+import { readFileSync } from 'fs'
+import { join } from 'path'
+import { pluginStateDir, type StorageOptions } from '../storage/index.ts'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Discovery — router.json (docs/15 §Surface and transport)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface FleetAddress {
+  /** Unix-socket path (preferred). */
+  sock?: string
+  /** TCP origin, e.g. `http://127.0.0.1:8765` (derived from router.json `tcp`). */
+  tcp?: string
+  /** The daemon's advertised version, when present. */
+  version?: string
+  /** The fleet capability marker: `1` when the daemon serves /fleet/v1. Absent ⇒
+   *  a pre-fleet daemon ⇒ the client must degrade (docs/15 §Discovery). */
+  fleet?: number
+}
+
+/** Read `~/.iapeer/state/iapeer/router.json`. Absent/unreadable ⇒ empty address
+ *  (daemon down) — the caller renders the down state. Never throws. */
+export function resolveFleetAddress(opts: StorageOptions = {}): FleetAddress {
+  const routerJson = join(pluginStateDir('iapeer', opts), 'router.json')
+  try {
+    const parsed = JSON.parse(readFileSync(routerJson, 'utf8')) as {
+      sock?: unknown
+      tcp?: unknown
+      version?: unknown
+      fleet?: unknown
+    }
+    const addr: FleetAddress = {}
+    if (typeof parsed.sock === 'string' && parsed.sock) addr.sock = parsed.sock
+    // router.json advertises the MCP url (…/mcp); the fleet surface lives on the SAME
+    // origin under /fleet/v1 — keep only the origin.
+    if (typeof parsed.tcp === 'string' && parsed.tcp) {
+      try {
+        addr.tcp = new URL(parsed.tcp).origin
+      } catch {
+        /* malformed tcp url → no tcp fallback */
+      }
+    }
+    if (typeof parsed.version === 'string') addr.version = parsed.version
+    if (typeof parsed.fleet === 'number') addr.fleet = parsed.fleet
+    return addr
+  } catch {
+    return {}
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Requests — unix-first, TCP-fallback, optional bearer
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** The bearer, when the host configured H8 auth (docs/15 §Auth). Read from the
+ *  env the client runs under; open-local hosts have none. */
+function bearerHeader(env: NodeJS.ProcessEnv): Record<string, string> {
+  const t = env.IAPEER_BEARER_TOKEN?.trim()
+  return t ? { authorization: `Bearer ${t}` } : {}
+}
+
+export class FleetUnreachableError extends Error {
+  constructor(readonly detail: string) {
+    super(`fleet daemon unreachable: ${detail}`)
+    this.name = 'FleetUnreachableError'
+  }
+}
+
+interface FetchAttempt {
+  url: string
+  init: RequestInit & { unix?: string }
+}
+
+/** Build the ordered transport attempts for a fleet path: unix socket first, TCP
+ *  second. `unix` is Bun's fetch option (routes the HTTP request over the socket). */
+function attempts(addr: FleetAddress, path: string, base: RequestInit, env: NodeJS.ProcessEnv): FetchAttempt[] {
+  const headers = { ...(base.headers as Record<string, string> | undefined), ...bearerHeader(env) }
+  const list: FetchAttempt[] = []
+  if (addr.sock) list.push({ url: `http://iapeer${path}`, init: { ...base, headers, unix: addr.sock } })
+  if (addr.tcp) list.push({ url: `${addr.tcp}${path}`, init: { ...base, headers } })
+  return list
+}
+
+async function fetchFleet(
+  addr: FleetAddress,
+  path: string,
+  init: RequestInit,
+  env: NodeJS.ProcessEnv,
+): Promise<Response> {
+  const tries = attempts(addr, path, init, env)
+  if (tries.length === 0) throw new FleetUnreachableError('no advertised address (router.json missing sock/tcp)')
+  let lastErr = ''
+  for (const a of tries) {
+    try {
+      const res = await fetch(a.url, a.init as RequestInit)
+      return res
+    } catch (e) {
+      lastErr = e instanceof Error ? e.message : String(e)
+      // try the next transport
+    }
+  }
+  throw new FleetUnreachableError(lastErr || 'all transports failed')
+}
+
+export async function fleetGetJson<T = unknown>(addr: FleetAddress, path: string, env: NodeJS.ProcessEnv): Promise<T> {
+  const res = await fetchFleet(addr, path, { method: 'GET' }, env)
+  const text = await res.text()
+  if (!res.ok) throw new Error(`GET ${path} → ${res.status}: ${text.slice(0, 300)}`)
+  return JSON.parse(text) as T
+}
+
+export async function fleetPostJson<T = unknown>(
+  addr: FleetAddress,
+  path: string,
+  body: Record<string, unknown>,
+  env: NodeJS.ProcessEnv,
+): Promise<{ status: number; body: T }> {
+  const res = await fetchFleet(
+    addr,
+    path,
+    { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) },
+    env,
+  )
+  const text = await res.text()
+  let parsed: T
+  try {
+    parsed = JSON.parse(text) as T
+  } catch {
+    parsed = text as unknown as T
+  }
+  return { status: res.status, body: parsed }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SSE — GET /fleet/v1/events (docs/15 §GET /fleet/v1/events)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface SseEvent {
+  /** The event name (`event:` line) — the `ev` vocabulary. Unknown kinds MUST be
+   *  tolerated by the caller (client obligation 1). */
+  event: string
+  /** Epoch-ms of the event (`id:` line) — for at-least-once dedup. */
+  id?: number
+  /** The parsed `data:` JSON payload. */
+  data: Record<string, unknown>
+}
+
+/**
+ * Open the SSE stream and invoke `onEvent` per frame until the signal aborts or the
+ * connection drops (then this resolves — the caller decides whether to reconnect).
+ * Parses the `event:` / `id:` / `data:` triplet; comments (`: connected`, `: hb`) are
+ * skipped. Deliberately minimal — no reconnect here (the render loop owns that).
+ */
+export async function streamFleetEvents(
+  addr: FleetAddress,
+  onEvent: (e: SseEvent) => void,
+  opts: { replay?: number; signal?: AbortSignal; env: NodeJS.ProcessEnv },
+): Promise<void> {
+  const replay = Math.max(0, Math.min(500, opts.replay ?? 0))
+  const res = await fetchFleet(
+    addr,
+    `/fleet/v1/events?replay=${replay}`,
+    { method: 'GET', headers: { accept: 'text/event-stream' }, signal: opts.signal },
+    opts.env,
+  )
+  if (!res.ok || !res.body) throw new Error(`events stream → ${res.status}`)
+  const reader = res.body.getReader()
+  const decoder = new TextDecoder()
+  let buf = ''
+  try {
+    for (;;) {
+      const { value, done } = await reader.read()
+      if (done) break
+      buf += decoder.decode(value, { stream: true })
+      // Frames are separated by a blank line.
+      let sep: number
+      while ((sep = buf.indexOf('\n\n')) !== -1) {
+        const frame = buf.slice(0, sep)
+        buf = buf.slice(sep + 2)
+        const parsed = parseSseFrame(frame)
+        if (parsed) onEvent(parsed)
+      }
+    }
+  } finally {
+    try {
+      reader.releaseLock()
+    } catch {
+      /* already released */
+    }
+  }
+}
+
+/** Parse one SSE frame (the text between blank-line separators). Returns null for
+ *  comment-only frames (`: connected`, `: hb`) or frames without a data payload. */
+export function parseSseFrame(frame: string): SseEvent | null {
+  let event = 'message'
+  let id: number | undefined
+  const dataLines: string[] = []
+  for (const raw of frame.split('\n')) {
+    const line = raw.replace(/\r$/, '')
+    if (!line || line.startsWith(':')) continue // comment or blank
+    const colon = line.indexOf(':')
+    const field = colon === -1 ? line : line.slice(0, colon)
+    const val = colon === -1 ? '' : line.slice(colon + 1).replace(/^ /, '')
+    if (field === 'event') event = val
+    else if (field === 'id') {
+      const n = parseInt(val, 10)
+      if (Number.isFinite(n)) id = n
+    } else if (field === 'data') dataLines.push(val)
+  }
+  if (dataLines.length === 0) return null
+  let data: Record<string, unknown> = {}
+  try {
+    const parsed = JSON.parse(dataLines.join('\n'))
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) data = parsed as Record<string, unknown>
+  } catch {
+    return null
+  }
+  return { event, ...(id !== undefined ? { id } : {}), data }
+}

package/src/tray/index.ts

@@ -0,0 +1,146 @@
+// tray/index — the fleet dashboard's runtime entry points, called by the `tray` CLI
+// verb. Ф1 of iapeer-tray: the FIRST external client of the daemon fleet API, written
+// strictly against docs/15-fleet-api.md.
+//
+//   • render (one-shot) — fetch /snapshot once, print one SwiftBar block. Used by the
+//     poll-fallback plugin and by tests.
+//   • render --stream — the SwiftBar streamable loop: print a block, subscribe to
+//     /events, and re-fetch the snapshot on each change (the canonical docs/15 loop
+//     "snapshot is state, events are hints"). Coalesces event bursts, heartbeats a
+//     refresh every 15 s (ages stay fresh + a missed event self-heals), and reconnects
+//     across daemon restarts / down windows. Degrades to the daemon-down block.
+//   • cmd — POST a fleet command (wake/stop/…): dogfoods the command endpoints.
+
+import { resolveFleetAddress, fleetGetJson, fleetPostJson, streamFleetEvents } from './client.ts'
+import { renderSwiftBar, renderDaemonDown, type TraySnapshot } from './render.ts'
+import { iapeerBinPath } from '../install/index.ts'
+
+export * from './install.ts'
+export { resolveFleetAddress } from './client.ts'
+
+const SNAPSHOT_PATH = '/fleet/v1/snapshot'
+const DEFAULT_HEARTBEAT_MS = 15_000
+const COALESCE_MS = 200
+const RECONNECT_BACKOFF_MS = 1_000
+const DOWN_RETRY_MS = 3_000
+
+/** Heartbeat cadence: re-render even without an event so ages stay fresh and a missed
+ *  event self-heals. Tunable via IAPEER_TRAY_HEARTBEAT_MS (clamped 1s…10m). */
+function heartbeatMs(env: NodeJS.ProcessEnv): number {
+  const raw = parseInt(env.IAPEER_TRAY_HEARTBEAT_MS ?? '', 10)
+  if (!Number.isFinite(raw)) return DEFAULT_HEARTBEAT_MS
+  return Math.max(1_000, Math.min(600_000, raw))
+}
+
+export const TRAY_COMMANDS = ['wake', 'stop', 'start', 'new', 'refresh', 'interrupt', 'compact'] as const
+export type TrayCommand = (typeof TRAY_COMMANDS)[number]
+
+/** Fetch the snapshot and render one SwiftBar block, or the degraded down-block when
+ *  no advertised address answers / the daemon predates the fleet API. Never throws. */
+export async function renderTrayOnce(env: NodeJS.ProcessEnv): Promise<string> {
+  const binPath = iapeerBinPath(env)
+  const addr = resolveFleetAddress({ env })
+  if (addr.fleet !== 1 || (!addr.sock && !addr.tcp)) {
+    const reason = addr.sock || addr.tcp ? 'daemon predates the fleet API (no fleet:1 in router.json)' : 'no daemon address (router.json missing)'
+    return renderDaemonDown(reason, { binPath })
+  }
+  try {
+    const snap = await fleetGetJson<TraySnapshot>(addr, SNAPSHOT_PATH, env)
+    return renderSwiftBar(snap, { binPath })
+  } catch (e) {
+    return renderDaemonDown(e instanceof Error ? e.message : String(e), { binPath })
+  }
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise(resolve => {
+    if (signal?.aborted) return resolve()
+    const t = setTimeout(resolve, ms)
+    ;(t as { unref?: () => void }).unref?.()
+    signal?.addEventListener('abort', () => { clearTimeout(t); resolve() }, { once: true })
+  })
+}
+
+/**
+ * The SwiftBar streamable loop (docs/16 §streaming). Emits a full menu block, then a
+ * `~~~` separator before every subsequent block. Drives updates off the SSE stream
+ * with burst-coalescing + a heartbeat; reconnects forever. `out` defaults to stdout;
+ * `signal` (tests) stops the loop.
+ */
+export async function streamTray(
+  env: NodeJS.ProcessEnv,
+  out: (s: string) => void = s => process.stdout.write(s),
+  signal?: AbortSignal,
+): Promise<void> {
+  let first = true
+  // Serialize all emits through a promise chain so a `~~~`+block is never interleaved.
+  let chain: Promise<void> = Promise.resolve()
+  const emit = (): Promise<void> => {
+    chain = chain.then(async () => {
+      const block = await renderTrayOnce(env)
+      out(first ? block : `~~~\n${block}`)
+      first = false
+    })
+    return chain
+  }
+  // Coalesce event bursts into a single re-render.
+  let coalesceTimer: ReturnType<typeof setTimeout> | undefined
+  const requestEmit = (): void => {
+    if (coalesceTimer) return
+    coalesceTimer = setTimeout(() => {
+      coalesceTimer = undefined
+      void emit()
+    }, COALESCE_MS)
+    ;(coalesceTimer as { unref?: () => void }).unref?.()
+  }
+
+  await emit() // initial block
+
+  while (!signal?.aborted) {
+    const addr = resolveFleetAddress({ env })
+    if (addr.fleet !== 1 || (!addr.sock && !addr.tcp)) {
+      await sleep(DOWN_RETRY_MS, signal)
+      await emit() // keep the down-block current until the daemon returns
+      continue
+    }
+    const heartbeat = setInterval(requestEmit, heartbeatMs(env))
+    ;(heartbeat as { unref?: () => void }).unref?.()
+    try {
+      // Blocks until the stream ends (daemon restart / network drop). Each event just
+      // marks the menu dirty — the snapshot re-fetch is the source of truth.
+      await streamFleetEvents(addr, () => requestEmit(), { replay: 0, signal, env })
+    } catch {
+      /* connection failed → fall through to a refresh + backoff + reconnect */
+    } finally {
+      clearInterval(heartbeat)
+    }
+    if (signal?.aborted) break
+    await emit() // reflect whatever changed across the drop
+    await sleep(RECONNECT_BACKOFF_MS, signal)
+  }
+}
+
+export interface TrayCmdResult {
+  ok: boolean
+  status: number
+  body: unknown
+}
+
+/** POST a fleet command for a peer (dogfoods POST /fleet/v1/peers/<peer>/<cmd>). */
+export async function trayCmd(
+  env: NodeJS.ProcessEnv,
+  command: string,
+  personality: string,
+  runtime?: string,
+): Promise<TrayCmdResult> {
+  if (!(TRAY_COMMANDS as readonly string[]).includes(command)) {
+    throw new Error(`unknown tray command "${command}" — one of: ${TRAY_COMMANDS.join(', ')}`)
+  }
+  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/peers/${encodeURIComponent(personality)}/${command}`
+  const { status, body } = await fleetPostJson(addr, path, runtime ? { runtime } : {}, env)
+  return { ok: status < 400, status, body }
+}

package/src/tray/install.ts

@@ -0,0 +1,266 @@
+// tray/install — idempotent lifecycle of the SwiftBar plugin that hosts the fleet
+// dashboard. The plugin FILE is a thin shim: it execs the installed `iapeer` binary
+// (`iapeer tray render --stream`), so ALL rendering/streaming logic lives in the
+// binary (TypeScript, tested) rather than in brittle shell — the .sh is stable and
+// carries only SwiftBar metadata.
+//
+// SwiftBar facts (verified against SwiftBar/PreferencesStore.swift):
+//   • PluginDirectory is a PLAIN String default (read via expandingTildeInPath), NOT
+//     a security-scoped bookmark — `defaults write com.ameba.SwiftBar PluginDirectory
+//     -string <dir>` set BEFORE first launch is honored and skips the folder picker.
+//   • SwiftBar is not sandboxed (it runs arbitrary scripts), so a hidden ~/.iapeer
+//     path is readable without a TCC prompt.
+//
+// Packaging (owner decision 05.07.2026): the tray ships WITH the foundation (same
+// class as the `iapeer list` TUI — another face of the daemon). `iapeer install`
+// drops the plugin file (inert without SwiftBar); `iapeer tray install [--app]` is
+// the activation verb that also installs SwiftBar.app when absent (owner-sanctioned)
+// and launches it. Tearing down the GUI layer NEVER touches the fleet.
+//
+// Paths route through cfg/env (the dedicated plugin dir is under resolveGlobalRoot,
+// so IAPEER_ROOT isolates it in tests); every external side-effect (defaults / brew /
+// open) goes through an injectable Runner so tests stay hermetic.
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { spawnSync } from 'child_process'
+import { homedir } from 'os'
+import { join } from 'path'
+import { resolveGlobalRoot } from '../storage/index.ts'
+import { iapeerBinPath } from '../install/index.ts'
+import { resolveFleetAddress } from './client.ts'
+
+/** Streamable plugin: the `.10s.` token is the RESPAWN cadence SwiftBar uses if the
+ *  streaming process exits (daemon-down backoff); while the stream is alive it is
+ *  ignored. The basename is stable — install rewrites the same file (idempotent). */
+export const PLUGIN_BASENAME = 'iapeer.10s.sh'
+const SWIFTBAR_DOMAIN = 'com.ameba.SwiftBar'
+const SWIFTBAR_APP_PATHS = ['/Applications/SwiftBar.app', join(homedir(), 'Applications', 'SwiftBar.app')]
+
+export type RunResult = { status: number | null; stdout: string; stderr: string }
+export type Runner = (cmd: string, args: string[]) => RunResult
+
+const defaultRun: Runner = (cmd, args) => {
+  const r = spawnSync(cmd, args, { encoding: 'utf8' })
+  return { status: r.status, stdout: r.stdout ?? '', stderr: r.stderr ?? '' }
+}
+
+/** The dedicated iapeer-owned plugin dir under ~/.iapeer (IAPEER_ROOT-isolated). */
+export function dedicatedPluginDir(env: NodeJS.ProcessEnv = process.env): string {
+  return join(resolveGlobalRoot(env), 'tray', 'plugins')
+}
+
+/** Is SwiftBar.app installed? (either /Applications or ~/Applications). */
+export function swiftBarInstalled(): boolean {
+  return SWIFTBAR_APP_PATHS.some(p => existsSync(p))
+}
+
+/** The plugin-dir SwiftBar is currently configured with (plain-string default,
+ *  ~-expanded), or undefined when unset/unreadable. */
+export function readSwiftBarPluginDir(run: Runner = defaultRun): string | undefined {
+  const r = run('defaults', ['read', SWIFTBAR_DOMAIN, 'PluginDirectory'])
+  if (r.status !== 0) return undefined
+  const raw = r.stdout.trim()
+  if (!raw) return undefined
+  return raw.startsWith('~') ? join(homedir(), raw.slice(1)) : raw
+}
+
+function setSwiftBarPluginDir(dir: string, run: Runner): RunResult {
+  return run('defaults', ['write', SWIFTBAR_DOMAIN, 'PluginDirectory', '-string', dir])
+}
+
+function installSwiftBarApp(run: Runner): RunResult {
+  return run('brew', ['install', '--cask', 'swiftbar'])
+}
+
+function launchSwiftBar(run: Runner): void {
+  run('open', ['-g', '-a', 'SwiftBar'])
+}
+
+function refreshSwiftBar(run: Runner): void {
+  run('open', ['-g', 'swiftbar://refreshallplugins'])
+}
+
+/** The plugin shim: SwiftBar metadata + exec of the streaming renderer. binPath is
+ *  embedded absolute (SwiftBar's PATH is minimal, like launchd). */
+export function buildPluginShim(binPath: string): string {
+  return [
+    '#!/bin/bash',
+    '# <xbar.title>iapeer fleet</xbar.title>',
+    '# <xbar.version>v1</xbar.version>',
+    '# <xbar.author>iapeer</xbar.author>',
+    '# <xbar.desc>iapeer multi-agent fleet — live peer dashboard over the daemon fleet API.</xbar.desc>',
+    '# <swiftbar.type>streamable</swiftbar.type>',
+    '# <swiftbar.hideRunInTerminal>true</swiftbar.hideRunInTerminal>',
+    '# <swiftbar.hideLastUpdated>true</swiftbar.hideLastUpdated>',
+    '# <swiftbar.hideDisablePlugin>true</swiftbar.hideDisablePlugin>',
+    `exec "${binPath}" tray render --stream`,
+    '',
+  ].join('\n')
+}
+
+/** Fail-closed sandbox guard (in spirit with install/scaffoldHostDocs): never write
+ *  into the REAL ~/.iapeer under a sandboxed test that forgot to set IAPEER_ROOT. */
+function assertTraySandboxIsolated(env: NodeJS.ProcessEnv): void {
+  if (env.IAPEER_TEST_SANDBOX === '1' && resolveGlobalRoot(env) === join(homedir(), '.iapeer')) {
+    throw new Error('refusing to install the tray plugin into the REAL ~/.iapeer under IAPEER_TEST_SANDBOX=1 — set IAPEER_ROOT')
+  }
+}
+
+export interface InstallTrayOptions {
+  env?: NodeJS.ProcessEnv
+  /** Install SwiftBar.app via brew when absent (owner-sanctioned). Default false. */
+  installApp?: boolean
+  /** Launch + refresh SwiftBar after writing the plugin. Default false. */
+  launch?: boolean
+  run?: Runner
+  /** Injectable app-presence probe (tests). Default: swiftBarInstalled(). */
+  probeApp?: () => boolean
+}
+
+export interface InstallTrayResult {
+  pluginFile: string
+  pluginDir: string
+  /** Whether the plugin file bytes changed (false = already current). */
+  wrote: boolean
+  /** How the plugin dir was chosen. */
+  dir: 'existing-swiftbar' | 'dedicated-configured' | 'dedicated-only'
+  app: 'present' | 'installed' | 'install-failed' | 'absent'
+  appReason?: string
+  launched: boolean
+}
+
+/**
+ * Idempotently install the tray plugin. Steps (each safe to repeat):
+ *   1. install SwiftBar.app if absent && installApp (best-effort — a brew failure is
+ *      reported, not thrown; the plugin file still lands so it activates later).
+ *   2. resolve the target dir: an already-configured SwiftBar PluginDirectory is
+ *      RESPECTED (install into the user's dir); otherwise the dedicated ~/.iapeer dir,
+ *      and — only when SwiftBar is present — point SwiftBar at it via defaults.
+ *   3. write the plugin shim (skip if byte-identical; always ensure +x).
+ *   4. launch + refresh SwiftBar when launch && SwiftBar present.
+ */
+export function installTray(opts: InstallTrayOptions = {}): InstallTrayResult {
+  const env = opts.env ?? process.env
+  const run = opts.run ?? defaultRun
+  const probeApp = opts.probeApp ?? swiftBarInstalled
+  assertTraySandboxIsolated(env)
+  const binPath = iapeerBinPath(env)
+
+  // 1 — app
+  let app: InstallTrayResult['app'] = probeApp() ? 'present' : 'absent'
+  let appReason: string | undefined
+  if (app === 'absent' && opts.installApp) {
+    const r = installSwiftBarApp(run)
+    if (r.status === 0 || probeApp()) app = 'installed'
+    else {
+      app = 'install-failed'
+      appReason = (r.stderr || r.stdout || `brew exit ${r.status}`).trim().slice(0, 300)
+    }
+  }
+  const present = app === 'present' || app === 'installed'
+
+  // 2 — target dir
+  const existing = present ? readSwiftBarPluginDir(run) : undefined
+  let pluginDir: string
+  let dir: InstallTrayResult['dir']
+  if (existing && existsSync(existing)) {
+    pluginDir = existing
+    dir = 'existing-swiftbar'
+  } else {
+    pluginDir = dedicatedPluginDir(env)
+    if (present) {
+      setSwiftBarPluginDir(pluginDir, run)
+      dir = 'dedicated-configured'
+    } else {
+      dir = 'dedicated-only'
+    }
+  }
+  mkdirSync(pluginDir, { recursive: true })
+
+  // 3 — plugin file (idempotent write; always +x)
+  const pluginFile = join(pluginDir, PLUGIN_BASENAME)
+  const content = buildPluginShim(binPath)
+  let wrote = false
+  if (!existsSync(pluginFile) || readFileSync(pluginFile, 'utf8') !== content) {
+    writeFileSync(pluginFile, content, { mode: 0o755 })
+    wrote = true
+  } else {
+    try {
+      chmodSync(pluginFile, 0o755)
+    } catch {
+      /* best-effort */
+    }
+  }
+
+  // 4 — launch + refresh
+  let launched = false
+  if (opts.launch && present) {
+    launchSwiftBar(run)
+    refreshSwiftBar(run)
+    launched = true
+  }
+
+  return { pluginFile, pluginDir, wrote, dir, app, appReason, launched }
+}
+
+export interface UninstallTrayResult {
+  removed: string[]
+  /** SwiftBar was refreshed to drop the now-missing plugin. */
+  refreshed: boolean
+}
+
+/**
+ * Remove the tray plugin file from EVERY dir it could live in (the dedicated dir and
+ * a configured SwiftBar dir) and refresh SwiftBar. DELIBERATELY leaves SwiftBar.app
+ * installed (the user may run other plugins) and NEVER touches the fleet — the daemon,
+ * TUI and delivery keep running (acceptance criterion: GUI teardown ≠ fleet teardown).
+ */
+export function uninstallTray(
+  opts: { env?: NodeJS.ProcessEnv; launch?: boolean; run?: Runner; probeApp?: () => boolean } = {},
+): UninstallTrayResult {
+  const env = opts.env ?? process.env
+  const run = opts.run ?? defaultRun
+  assertTraySandboxIsolated(env)
+  const present = (opts.probeApp ?? swiftBarInstalled)()
+  const dirs = new Set<string>([dedicatedPluginDir(env)])
+  if (present) {
+    const existing = readSwiftBarPluginDir(run)
+    if (existing) dirs.add(existing)
+  }
+  const removed: string[] = []
+  for (const d of dirs) {
+    const f = join(d, PLUGIN_BASENAME)
+    if (existsSync(f)) {
+      rmSync(f, { force: true })
+      removed.push(f)
+    }
+  }
+  let refreshed = false
+  if (opts.launch && present) {
+    refreshSwiftBar(run)
+    refreshed = true
+  }
+  return { removed, refreshed }
+}
+
+export interface TrayStatus {
+  daemon: { fleet: boolean; version?: string; sock?: string; tcp?: string }
+  swiftbar: { installed: boolean; pluginDir?: string }
+  plugin: { installed: boolean; path?: string }
+}
+
+/** Read-only diagnostics — never repairs anything. */
+export function trayStatus(opts: { env?: NodeJS.ProcessEnv; run?: Runner; probeApp?: () => boolean } = {}): TrayStatus {
+  const env = opts.env ?? process.env
+  const run = opts.run ?? defaultRun
+  const addr = resolveFleetAddress({ env })
+  const installed = (opts.probeApp ?? swiftBarInstalled)()
+  const cfgDir = installed ? readSwiftBarPluginDir(run) : undefined
+  const searchDirs = [cfgDir, dedicatedPluginDir(env)].filter(Boolean) as string[]
+  const found = searchDirs.map(d => join(d, PLUGIN_BASENAME)).find(f => existsSync(f))
+  return {
+    daemon: { fleet: addr.fleet === 1, version: addr.version, sock: addr.sock, tcp: addr.tcp },
+    swiftbar: { installed, pluginDir: cfgDir },
+    plugin: { installed: Boolean(found), path: found },
+  }
+}