@agfpd/iapeer 0.4.80 → 0.4.82

package/docs/16-tray.md

@@ -80,12 +80,12 @@ whole dashboard twice.
 
 | Verb | What it does |
 |---|---|
-| `iapeer tray install [--plugin-only]` | Install SwiftBar.app when absent (owner-sanctioned), point it at the plugin dir, write the plugin, launch + refresh. `--plugin-only` writes just the plugin file (no app, no launch — what the foundation install does). Idempotent. |
-| `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 install [--plugin-only]` | Install SwiftBar.app when absent (owner-sanctioned), point it at the plugin dir, write the plugin, launch + refresh, **and register the login-autostart LaunchAgent**. `--plugin-only` writes just the plugin file (no app, no launch, no autostart — what the foundation install does). Idempotent. |
+| `iapeer tray uninstall` | Remove the plugin file, refresh SwiftBar, **and tear down the login-autostart LaunchAgent**. **Never touches the fleet** — the daemon, TUI and delivery keep running; SwiftBar.app is left installed (it may host other plugins). |
 | `iapeer tray 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. |
+| `iapeer tray status` | Read-only: is the fleet API up (from `router.json`), is SwiftBar installed and where is its plugin dir, is the plugin file present, **is the login autostart registered**. Repairs nothing. |
 
 ## How it is wired
 
@@ -102,6 +102,26 @@ plugin is installed into the user's own dir); otherwise a dedicated
 reads on launch (it is not sandboxed and stores no security-scoped bookmark), so the
 folder picker is skipped.
 
+Login autostart: activating the tray registers a user LaunchAgent
+`~/Library/LaunchAgents/com.agfpd.iapeer.tray.plist` (RunAtLoad, no KeepAlive) whose
+`ProgramArguments` are `open -g -b com.ameba.SwiftBar` — so SwiftBar (and with it the
+fleet dashboard + approval badge) comes back on its own after a reboot, with no manual
+`open -a SwiftBar`. A **LaunchAgent** is used deliberately, not a System Events "Login
+Item" nor SMAppService: a Login Item needs the invoking process to hold Automation TCC
+over System Events (attributed to whatever parent runs the verb — fragile in a headless /
+`iapeer update` context), and SMAppService can only register a helper the *target* app
+ships (we cannot register the third-party SwiftBar with it from a CLI). The LaunchAgent
+needs no TCC and reuses the foundation's idempotent plist lifecycle: the plist is
+byte-stable (write-if-changed), carries the `com.iapeer.managed` ownership sentinel, and
+is bootstrapped/cycled undead-safe — so re-activation never plants a duplicate. It is
+**RunAtLoad-only** (fire once at login) rather than KeepAlive, because the `open` process
+exits immediately once SwiftBar is up (KeepAlive would respawn-storm it) and supervising
+SwiftBar itself would fight the user quitting it. `tray uninstall` boots it out and
+removes the plist (only our own sentinel-marked file — a foreign plist at the label is
+left untouched). The label lives in the foundation's own `com.agfpd.*` namespace, never
+`com.iapeer.<personality>` (the persistent-peer fleet), so the H4 launchd-owned
+sweep-guard can never mistake it for a peer.
+
 Auth follows the Fleet API: on an open-local host no bearer is needed; when the daemon is
 configured with `IAPEER_BEARER_TOKEN`, the plugin's environment must carry it too.
 

package/docs/ru/16-tray.md

@@ -76,12 +76,12 @@ SwiftBar.app, если его нет.
 
 | Verb | Что делает |
 |---|---|
-| `iapeer tray install [--plugin-only]` | Доустановит SwiftBar.app, если его нет (санкция владельца), нацелит его на каталог плагинов, запишет плагин, запустит + обновит. `--plugin-only` пишет только файл плагина (без приложения и запуска — так делает foundation-install). Идемпотентно. |
-| `iapeer tray uninstall` | Удалит файл плагина и обновит SwiftBar. **Флот не трогает** — демон, TUI и доставка живут; SwiftBar.app остаётся (может держать другие плагины). |
+| `iapeer tray install [--plugin-only]` | Доустановит SwiftBar.app, если его нет (санкция владельца), нацелит его на каталог плагинов, запишет плагин, запустит + обновит **и зарегистрирует LaunchAgent автозапуска при логине**. `--plugin-only` пишет только файл плагина (без приложения, запуска и автозапуска — так делает foundation-install). Идемпотентно. |
+| `iapeer tray uninstall` | Удалит файл плагина, обновит SwiftBar **и снесёт LaunchAgent автозапуска**. **Флот не трогает** — демон, TUI и доставка живут; SwiftBar.app остаётся (может держать другие плагины). |
 | `iapeer tray render [--stream]` | Печатает вывод плагина SwiftBar. `--stream` — streamable-цикл, который крутит плагин; одноразовая форма — поллинг-фолбэк и тест-поверхность. |
 | `iapeer tray cmd <command> <peer> [runtime]` | POST fleet-команды (`wake`/`stop`/`start`/`new`/`refresh`/`interrupt`/`compact`) — lifecycle-пункты меню зовут это. |
 | `iapeer tray approve <id>` · `iapeer tray deny <id> [reason]` | Резолв ожидающего human-approval (docs/17) — `POST /fleet/v1/approvals/<id>/(approve\|deny)` через тот же unix-first fleet-клиент. Пункты Allow/Deny меню зовут это; инвариант единой очереди — резолв виден каждому каналу (CLI, telegram). |
-| `iapeer tray status` | Только чтение: жив ли fleet API (из `router.json`), установлен ли SwiftBar и где его каталог плагинов, на месте ли файл плагина. Ничего не чинит. |
+| `iapeer tray status` | Только чтение: жив ли fleet API (из `router.json`), установлен ли SwiftBar и где его каталог плагинов, на месте ли файл плагина, **зарегистрирован ли автозапуск**. Ничего не чинит. |
 
 ## Как устроено
 
@@ -97,6 +97,25 @@ SwiftBar.app, если его нет.
 который SwiftBar читает при запуске (он не sandboxed и не хранит security-scoped bookmark),
 поэтому окно выбора папки пропускается.
 
+Автозапуск при логине: активация трея регистрирует пользовательский LaunchAgent
+`~/Library/LaunchAgents/com.agfpd.iapeer.tray.plist` (RunAtLoad, без KeepAlive), чьи
+`ProgramArguments` — `open -g -b com.ameba.SwiftBar`, так что SwiftBar (а с ним fleet-дашборд
+и бейдж аппрувов) сам поднимается после перезагрузки, без ручного `open -a SwiftBar`.
+**LaunchAgent** выбран намеренно, не «Login Item» через System Events и не SMAppService: Login
+Item требует, чтобы вызывающий процесс держал Automation-TCC на System Events (грант
+атрибутируется тому родителю, что запустил verb — хрупко в headless / `iapeer update`
+контексте), а SMAppService умеет регистрировать только хелпер, который несёт *само* целевое
+приложение (сторонний SwiftBar так из CLI не зарегистрировать). LaunchAgent не требует TCC и
+переиспользует идемпотентный plist-жизненный цикл foundation: plist байт-стабилен (пишется
+только при изменении), несёт sentinel владения `com.iapeer.managed` и bootstrap'ится/
+пересоздаётся undead-safe — повторная активация не плодит дубль. Он **RunAtLoad-only** (сработать
+один раз при логине), а не KeepAlive, потому что процесс `open` завершается сразу, как SwiftBar
+поднят (KeepAlive устроил бы respawn-шторм), а супервизия самого SwiftBar боролась бы с
+пользователем, который его закрыл. `tray uninstall` делает bootout и удаляет plist (только наш
+файл с sentinel — чужой plist на этом лейбле не трогается). Лейбл живёт в собственном namespace
+foundation `com.agfpd.*`, никогда не `com.iapeer.<personality>` (флот persistent-пиров), поэтому
+H4-страж launchd-owned пиров не может принять его за пира.
+
 Авторизация — как у Fleet API: на open-local хосте bearer не нужен; если демон настроен с
 `IAPEER_BEARER_TOKEN`, окружение плагина тоже должно его нести.
 

package/package.json

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

@@ -2581,6 +2581,9 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
                 `  plugin dir: ${r.pluginDir} (${r.dir})\n` +
                 `  SwiftBar: ${r.app}${r.appReason ? ` — ${r.appReason}` : ''}\n` +
                 (r.launched ? '  launched + refreshed SwiftBar\n' : '') +
+                (r.autostart
+                  ? `  login autostart: ${r.autostart.state}${r.autostart.detail ? ` — ${r.autostart.detail}` : ''} (${r.autostart.plistPath})\n`
+                  : '') +
                 (r.app === 'absent' || r.app === 'install-failed'
                   ? '  (SwiftBar not active — run `iapeer tray install` to install it, then it appears in the menu bar)\n'
                   : ''),
@@ -2592,6 +2595,7 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
             out(
               (r.removed.length ? `removed:\n${r.removed.map(f => `  ${f}`).join('\n')}\n` : 'no tray plugin file found\n') +
                 (r.refreshed ? '  refreshed SwiftBar\n' : '') +
+                `  login autostart: ${r.autostart.state}${r.autostart.removed ? ` (${r.autostart.plistPath})` : ''}\n` +
                 '  fleet untouched (daemon / TUI / delivery unaffected)\n',
             )
             return 0
@@ -2603,7 +2607,8 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
                 `  sock: ${s.daemon.sock ?? '—'}\n` +
                 `  tcp:  ${s.daemon.tcp ?? '—'}\n` +
                 `SwiftBar: ${s.swiftbar.installed ? `installed (plugin dir: ${s.swiftbar.pluginDir ?? 'unset'})` : 'not installed'}\n` +
-                `plugin: ${s.plugin.installed ? s.plugin.path : 'not installed'}\n`,
+                `plugin: ${s.plugin.installed ? s.plugin.path : 'not installed'}\n` +
+                `login autostart: ${s.autostart.registered ? s.autostart.path : 'not registered'}\n`,
             )
             return 0
           }

package/src/launch/launchd.ts

@@ -452,6 +452,57 @@ export function cycleLaunchdJob(
   })
 }
 
+/**
+ * Idempotently ensure ANY launchd job is LOADED in the gui domain — bootstrap when
+ * absent, no-op when already loaded. The generic sibling of `bootstrapDaemon` for a
+ * caller-supplied label/plist pair (e.g. the tray SwiftBar-autostart LaunchAgent).
+ * The CALLER owns any ownership/fleet guard; this primitive only loads the concrete
+ * label/plist. Composed on bootstrapJobCore (undead-job-safe wait-for-gone + backoff).
+ * SANDBOX FAIL-SAFE: never calls launchctl under IAPEER_TEST_SANDBOX (`bootstrap
+ * gui/<uid>` is host-global regardless of IAPEER_ROOT) — consulting BOTH the passed and
+ * the process env, the same fail-closed rule as launchctlBootstrap.
+ */
+export function bootstrapLaunchdJob(
+  label: string,
+  plistPath: string,
+  env: NodeJS.ProcessEnv = process.env,
+): BootstrapResult {
+  if (env.IAPEER_TEST_SANDBOX === '1' || process.env.IAPEER_TEST_SANDBOX === '1') {
+    return { state: 'skipped-sandbox', label, detail: 'IAPEER_TEST_SANDBOX=1 — not loading a real launchd job' }
+  }
+  const uid = currentUid()
+  const core = bootstrapJobCore(uid, label, plistPath, {
+    run: args => {
+      const r = spawnSync('launchctl', args, { encoding: 'utf8' })
+      return { status: r.status, stderr: r.stderr ?? '' }
+    },
+    sleepMs: ms => spawnSync('sleep', [String(ms / 1000)]),
+  })
+  return core.state === 'failed' ? { state: 'failed', label, detail: core.detail } : { state: core.state, label }
+}
+
+export interface BootoutResult {
+  state: 'booted-out' | 'not-loaded' | 'skipped-sandbox' | 'failed'
+  detail?: string
+}
+
+/**
+ * Unload a launchd job from the gui domain (`launchctl bootout gui/<uid>/<label>`) —
+ * the teardown primitive (used to remove the tray SwiftBar-autostart LaunchAgent on
+ * `tray uninstall`). Idempotent: an un-loaded label is `not-loaded` (no-op). The CALLER
+ * removes the plist file (this only unloads the running job). Sandbox-safe: never calls
+ * launchctl under IAPEER_TEST_SANDBOX.
+ */
+export function bootoutLaunchdJob(label: string, env: NodeJS.ProcessEnv = process.env): BootoutResult {
+  if (env.IAPEER_TEST_SANDBOX === '1' || process.env.IAPEER_TEST_SANDBOX === '1') {
+    return { state: 'skipped-sandbox' }
+  }
+  const uid = currentUid()
+  if (!isLaunchdLoaded(label, uid)) return { state: 'not-loaded' }
+  const r = spawnSync('launchctl', ['bootout', `gui/${uid}/${label}`], { encoding: 'utf8' })
+  return r.status === 0 ? { state: 'booted-out' } : { state: 'failed', detail: (r.stderr ?? '').trim() || `exit ${r.status}` }
+}
+
 /**
  * AUTO-bootstrap a freshly-provisioned foundation plist into the gui domain
  * (`launchctl bootstrap gui/<uid> <plist>`) — the "load it now, don't write-and-wait

package/src/transport/index.ts

@@ -307,7 +307,7 @@ async function deliverViaHost(
   // a short grace covers it. The receiver's own assistant/tool turn never reproduces the
   // `<iap from-personality=…>` wrapper, so it cannot forge a confirm. No such record within the grace →
   // false-FAIL (the sender retries) — NOT a false-OK (silent loss the contract forbids).
-  const confirm = seam.confirmLanded ?? ((payload: string) => transcriptCarriesEnvelope(baseline, payload))
+  const confirm = seam.confirmLanded ?? ((payload: string) => transcriptCarriesEnvelope(baseline, payload, { env }))
   const sleep = seam.sleep ?? ((ms: number) => new Promise<void>(r => setTimeout(r, ms)))
   const graceMs = confirmGraceMs()
   const graceDeadline = monotonicMs() + graceMs
@@ -579,20 +579,37 @@ function jsonStringValuesContain(value: unknown, needle: string): boolean {
  * the full envelope is UNFORGEABLE by a concurrent turn — no false-OK. Because only bytes PAST the
  * baseline offset are read, a pre-existing copy of an identical earlier message cannot pass either.
  *
- * Iterates the baseline file LIST verbatim — it does NOT re-scan the runtime's session dir each poll
- * (unlike the minutes-long compact-done gate). A delivery's confirm window is seconds, so a brand-new
- * session file appearing mid-delivery (a resume mid-flight) is negligible, and missing it fails in the
- * SAFE direction (false-FAIL → the sender retries, never a silent loss). For codex this also avoids a
- * full recursive `~/.codex/sessions` re-scan on every ~100ms poll (the active session file is already
- * in the baseline), keeping the hot delivery path cheap.
+ * Scans each baseline file from its captured offset AND any session file that APPEARS AFTER the baseline
+ * from offset 0 — the post-baseline pickup is load-bearing. A FRESH session (self-fresh/eager-fresh)
+ * writes its NEW jsonl LAZILY on the first delivered turn, so the confirming record for the FIRST delivery
+ * into that session lands in a file the baseline never captured (the fresh jsonl is born ~a beat AFTER the
+ * pre-deliver baseline snapshot). Iterating baseline-only made EVERY such first-delivery a false-FAIL: the
+ * dead OLD session file gets scanned, the live NEW one is ignored, and the confirm reported "not delivered"
+ * for a message the session had actually accepted + processed (verified live 2026-07-10: telegram-arthur →
+ * mrmechanic ok=false, yet the envelope stood in the fresh jsonl at +0.3s, within the grace). A
+ * post-baseline file is BRAND-NEW for this cwd, so reading it from 0 cannot match a pre-existing copy
+ * (nothing pre-existed), and the full `<iap from-personality=…>` envelope is unforgeable by the receiver's
+ * own assistant/tool turn — the SAME false-OK safety `compactTranscriptHasDone` already relies on. In
+ * production this loop runs ONLY for claude (codex confirms by the socket-ack BEFORE reaching here), so the
+ * per-poll re-list is a single cheap readdirSync of one project dir — never a recursive `~/.codex/sessions`
+ * walk. `env` scopes the re-list under a test HOME (default process.env).
  */
-export function transcriptCarriesEnvelope(baseline: CompactDoneBaseline, envelope: string): boolean {
+export function transcriptCarriesEnvelope(
+  baseline: CompactDoneBaseline,
+  envelope: string,
+  opts: { env?: NodeJS.ProcessEnv } = {},
+): boolean {
   const needle = envelope.replace(/\r/g, '')
   if (!needle) return false
-  for (const { path, size: offset } of baseline.files) {
-    // Read ONLY the tail past the baseline offset — a full readFileSync here re-read the ENTIRE
-    // transcript (hundreds of MB for a long-running peer) on every ~100ms confirm-poll, stalling the
-    // single-threaded router event loop for the whole fleet.
+  // Baseline files at their pre-deliver offset; a file NOT in the baseline (born after it) is read from 0.
+  const offsets = new Map(baseline.files.map(f => [f.path, f.size]))
+  for (const path of compactCandidateFiles(baseline.runtime, baseline.cwd, opts.env)) {
+    if (!offsets.has(path)) offsets.set(path, 0)
+  }
+  for (const [path, offset] of offsets) {
+    // Read ONLY the tail past the offset — a full readFileSync here re-read the ENTIRE transcript
+    // (hundreds of MB for a long-running peer) on every ~100ms confirm-poll, stalling the single-threaded
+    // router event loop for the whole fleet.
     const tail = readFileTailFrom(path, offset)
     if (!tail) continue
     for (const line of tail.split(/\r?\n/)) {

package/src/tray/install.ts

@@ -21,12 +21,20 @@
 // 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 { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, 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 {
+  IAPEER_PLIST_OWNER_KEY,
+  bootoutLaunchdJob,
+  bootstrapLaunchdJob,
+  cycleLaunchdJob,
+  isFoundationOwnedPlist,
+  launchAgentsDir,
+} from '../launch/launchd.ts'
 import { resolveFleetAddress } from './client.ts'
 
 /** Streamable plugin: the `.10s.` token is the RESPAWN cadence SwiftBar uses if the
@@ -34,6 +42,16 @@ import { resolveFleetAddress } from './client.ts'
  *  ignored. The basename is stable — install rewrites the same file (idempotent). */
 export const PLUGIN_BASENAME = 'iapeer.10s.sh'
 const SWIFTBAR_DOMAIN = 'com.ameba.SwiftBar'
+// SwiftBar's `defaults` domain IS its bundle identifier — reuse it for the autostart
+// LaunchAgent's `open -b <bundleid>` (bundle-id launch survives the app moving/renaming
+// between /Applications and ~/Applications, unlike a baked absolute path or `-a <name>`).
+const SWIFTBAR_BUNDLE_ID = SWIFTBAR_DOMAIN
+// The login-autostart LaunchAgent's label. Foundation namespace (`com.agfpd.*` = the
+// foundation's own jobs), DELIBERATELY not `com.iapeer.<personality>` — that namespace
+// is the persistent-peer fleet keyed on personality, and the tray autostart is neither a
+// peer nor daemon-managed. Distinct label ⇒ it can never be mistaken for a peer plist by
+// the H4 launchd-owned sweep-guard.
+const SWIFTBAR_AUTOSTART_LABEL = 'com.agfpd.iapeer.tray'
 const SWIFTBAR_APP_PATHS = ['/Applications/SwiftBar.app', join(homedir(), 'Applications', 'SwiftBar.app')]
 
 export type RunResult = { status: number | null; stdout: string; stderr: string }
@@ -114,6 +132,147 @@ export function buildPluginShim(binPath: string): string {
   ].join('\n')
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Login autostart — a RunAtLoad LaunchAgent that brings SwiftBar up at login, so the
+// fleet dashboard + approval badge survive a reboot without a manual `open -a SwiftBar`.
+//
+// MECHANISM CHOICE (owner-relevant): a user LaunchAgent, not a System Events "Login
+// Item" and not SMAppService.
+//   • System Events Login Item (osascript `make login item`) — the manual stop-gap —
+//     requires the INVOKING process to hold Automation TCC over System Events; that
+//     grant is attributed to whatever parent runs the activation verb (Terminal / the
+//     daemon / an onboard run), so it silently no-ops or prompts in a headless / update
+//     context. A LaunchAgent needs no TCC at all — pure filesystem + launchctl.
+//   • SMAppService (macOS 13+) is the modern path, but it registers a helper the TARGET
+//     app ships — we cannot register a THIRD-PARTY GUI app (SwiftBar) with it from a CLI.
+//   • The LaunchAgent reuses the foundation's proven idempotent plist lifecycle
+//     (write-if-changed + undead-safe bootstrap/cycle, sandbox-guarded) and carries the
+//     ownership sentinel so uninstall can recognize + remove exactly our artifact.
+//
+// RunAtLoad-ONLY, no KeepAlive: the ProgramArguments launch SwiftBar via `open` (which
+// exits immediately once SwiftBar is up), so KeepAlive would respawn-storm `open` every
+// throttle window. A login-autostart only needs to fire once per session; keeping
+// SwiftBar itself supervised (relaunch-on-quit) would fight the user quitting it and
+// duplicate SwiftBar's own launch-at-login — out of scope for "start it at login".
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Absolute path of the tray autostart LaunchAgent plist (IAPEER_LAUNCHAGENTS_DIR
+ *  isolates it under test/sandbox; else ~/Library/LaunchAgents). */
+export function swiftBarAutostartPlistPath(env: NodeJS.ProcessEnv = process.env): string {
+  return join(launchAgentsDir(env), `${SWIFTBAR_AUTOSTART_LABEL}.plist`)
+}
+
+/** Render the RunAtLoad SwiftBar-autostart plist. PURE/deterministic (golden-testable).
+ *  Launch is `open -g -b <bundleid>`: LaunchServices activates the app correctly as a
+ *  menu-bar agent (`-g` = don't steal focus), and bundle-id targeting survives the app
+ *  moving. Carries the foundation ownership sentinel (inert `<key>` launchd ignores). */
+export function renderSwiftBarAutostartPlist(): string {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${SWIFTBAR_AUTOSTART_LABEL}</string>
+    <key>${IAPEER_PLIST_OWNER_KEY}</key>
+    <true/>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/usr/bin/open</string>
+        <string>-g</string>
+        <string>-b</string>
+        <string>${SWIFTBAR_BUNDLE_ID}</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+</dict>
+</plist>
+`
+}
+
+export type AutostartState =
+  | 'loaded' // bootstrapped now (was not loaded)
+  | 'already-loaded' // job already in the gui domain → no-op
+  | 'restarted' // plist changed → cycled (bootout+bootstrap) onto the new content
+  | 'skipped-sandbox' // IAPEER_TEST_SANDBOX=1 → never touch a real plist / launchctl
+  | 'failed' // launchctl bootstrap/cycle failed
+export interface EnsureAutostartResult {
+  plistPath: string
+  /** Whether the plist bytes changed (false = already current). */
+  wrote: boolean
+  state: AutostartState
+  detail?: string
+}
+
+/**
+ * Idempotently register the SwiftBar login-autostart LaunchAgent (write the plist if its
+ * bytes changed, then load/restart it). Safe to repeat — a changed plist is cycled, an
+ * unloaded one is bootstrapped, an unchanged-and-loaded one is a no-op (never a dup).
+ * SANDBOX FAIL-SAFE: under IAPEER_TEST_SANDBOX with no isolated IAPEER_LAUNCHAGENTS_DIR
+ * it writes NOTHING (a leaked real autostart would outlive the test) and touches no
+ * launchctl; with an isolated dir it writes there but still skips launchctl (host-global).
+ */
+export function ensureSwiftBarAutostart(env: NodeJS.ProcessEnv = process.env): EnsureAutostartResult {
+  const plistPath = swiftBarAutostartPlistPath(env)
+  const content = renderSwiftBarAutostartPlist()
+  const sandbox = env.IAPEER_TEST_SANDBOX === '1' || process.env.IAPEER_TEST_SANDBOX === '1'
+  const realAgents = join(homedir(), 'Library', 'LaunchAgents')
+  if (sandbox && plistPath.startsWith(`${realAgents}/`)) {
+    return {
+      plistPath,
+      wrote: false,
+      state: 'skipped-sandbox',
+      detail: 'IAPEER_TEST_SANDBOX=1 without IAPEER_LAUNCHAGENTS_DIR — refusing to write a real LaunchAgents plist',
+    }
+  }
+  mkdirSync(launchAgentsDir(env), { recursive: true })
+  let wrote = false
+  if (!existsSync(plistPath) || readFileSync(plistPath, 'utf8') !== content) {
+    // atomic write (tmp+rename): an interrupted direct write could leave a sentinel-less
+    // stub that the ownership guard then reads as foreign.
+    const tmp = `${plistPath}.tmp-${process.pid}`
+    writeFileSync(tmp, content, { mode: 0o644 })
+    renameSync(tmp, plistPath)
+    wrote = true
+  }
+  if (sandbox) return { plistPath, wrote, state: 'skipped-sandbox' }
+  // Live: load / restart onto the plist now on disk.
+  const bootstrap = (): EnsureAutostartResult => {
+    const bs = bootstrapLaunchdJob(SWIFTBAR_AUTOSTART_LABEL, plistPath, env)
+    const state: AutostartState =
+      bs.state === 'loaded' ? 'loaded' : bs.state === 'already-loaded' ? 'already-loaded' : 'failed'
+    return { plistPath, wrote, state, detail: bs.detail }
+  }
+  if (!wrote) return bootstrap()
+  const cyc = cycleLaunchdJob(SWIFTBAR_AUTOSTART_LABEL, plistPath, env)
+  if (cyc.state === 'restarted') return { plistPath, wrote, state: 'restarted' }
+  if (cyc.state === 'not-loaded') return bootstrap() // first install: nothing to cycle → load it
+  return { plistPath, wrote, state: 'failed', detail: cyc.detail }
+}
+
+export interface RemoveAutostartResult {
+  plistPath: string
+  removed: boolean
+  state: 'removed' | 'not-present' | 'foreign' | 'skipped-sandbox'
+}
+
+/**
+ * Tear down the SwiftBar login-autostart LaunchAgent (bootout the job, remove the plist)
+ * — the symmetric counterpart of ensureSwiftBarAutostart, run on `tray uninstall`. Only
+ * removes OUR plist (ownership sentinel present); a sentinel-less file at the label is
+ * left untouched (`foreign`). Sandbox-safe.
+ */
+export function removeSwiftBarAutostart(env: NodeJS.ProcessEnv = process.env): RemoveAutostartResult {
+  const plistPath = swiftBarAutostartPlistPath(env)
+  const sandbox = env.IAPEER_TEST_SANDBOX === '1' || process.env.IAPEER_TEST_SANDBOX === '1'
+  const realAgents = join(homedir(), 'Library', 'LaunchAgents')
+  if (sandbox && plistPath.startsWith(`${realAgents}/`)) return { plistPath, removed: false, state: 'skipped-sandbox' }
+  if (!existsSync(plistPath)) return { plistPath, removed: false, state: 'not-present' }
+  if (!isFoundationOwnedPlist(plistPath)) return { plistPath, removed: false, state: 'foreign' }
+  bootoutLaunchdJob(SWIFTBAR_AUTOSTART_LABEL, env) // unload the running job (sandbox-safe no-op)
+  rmSync(plistPath, { force: true })
+  return { plistPath, removed: true, state: 'removed' }
+}
+
 /** 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 {
@@ -143,6 +302,8 @@ export interface InstallTrayResult {
   app: 'present' | 'installed' | 'install-failed' | 'absent'
   appReason?: string
   launched: boolean
+  /** Login-autostart registration outcome (only when launched + SwiftBar present). */
+  autostart?: EnsureAutostartResult
 }
 
 /**
@@ -208,22 +369,28 @@ export function installTray(opts: InstallTrayOptions = {}): InstallTrayResult {
     }
   }
 
-  // 4 — launch + refresh
+  // 4 — launch + refresh + register login autostart (so a reboot brings the tray back).
   let launched = false
+  let autostart: EnsureAutostartResult | undefined
   if (opts.launch && present) {
     dequarantineApp(run)
     launchSwiftBar(run)
     refreshSwiftBar(run)
     launched = true
+    // Idempotent: the plist is byte-stable and the bootstrap is a no-op when loaded, so
+    // re-activation never plants a duplicate autostart.
+    autostart = ensureSwiftBarAutostart(env)
   }
 
-  return { pluginFile, pluginDir, wrote, dir, app, appReason, launched }
+  return { pluginFile, pluginDir, wrote, dir, app, appReason, launched, autostart }
 }
 
 export interface UninstallTrayResult {
   removed: string[]
   /** SwiftBar was refreshed to drop the now-missing plugin. */
   refreshed: boolean
+  /** Login-autostart teardown outcome (the GUI-face activation is being removed). */
+  autostart: RemoveAutostartResult
 }
 
 /**
@@ -257,7 +424,11 @@ export function uninstallTray(
     refreshSwiftBar(run)
     refreshed = true
   }
-  return { removed, refreshed }
+  // Tear down the login-autostart LaunchAgent too — removing the GUI face should not
+  // leave a reboot re-launching SwiftBar. Never touches the fleet (bootout of our own
+  // com.agfpd.* label only).
+  const autostart = removeSwiftBarAutostart(env)
+  return { removed, refreshed, autostart }
 }
 
 /**
@@ -294,6 +465,8 @@ export interface TrayStatus {
   daemon: { fleet: boolean; version?: string; sock?: string; tcp?: string }
   swiftbar: { installed: boolean; pluginDir?: string }
   plugin: { installed: boolean; path?: string }
+  /** Login-autostart LaunchAgent: registered (our plist present) + its path. */
+  autostart: { registered: boolean; path?: string }
 }
 
 /** Read-only diagnostics — never repairs anything. */
@@ -305,9 +478,12 @@ export function trayStatus(opts: { env?: NodeJS.ProcessEnv; run?: Runner; probeA
   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))
+  const autostartPath = swiftBarAutostartPlistPath(env)
+  const autostartOurs = existsSync(autostartPath) && isFoundationOwnedPlist(autostartPath)
   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 },
+    autostart: { registered: autostartOurs, path: autostartOurs ? autostartPath : undefined },
   }
 }