# Boot-persistence: agent-queue as a macOS LaunchAgent

Auto-start the `agent-queue` run loop on login and keep it alive across
**reboot / crash / logout** — the one failure mode that `tmux` + `caffeinate`
alone can't cover.

| Layer | Survives terminal close | Survives sleep | Survives reboot |
| ----- | :---------------------: | :------------: | :-------------: |
| plain shell | no | no | no |
| `tmux` | yes | no | no |
| `caffeinate` | n/a | yes | no |
| **LaunchAgent (this)** | yes | yes (via caffeinate) | **yes** |

## Install

```bash
bash launchd/install.sh             # render plist, load, start now (RunAtLoad + KeepAlive)
tail -f ~/Library/Logs/agent-queue/agent-queue.out.log
```

It renders `~/Library/LaunchAgents/com.bytelyst.agent-queue.plist` from the
resolved repo path (works on any clone) and bootstraps it into your GUI session.

## Use

The LaunchAgent runs `agent-queue-boot.sh`, which wraps `agent-queue run` in
`caffeinate`. Just drop prompt `.md` files into `queue/inbox/` — they get picked
up automatically, now or after the next reboot.

```bash
aq add ~/jobs/phase3-overnight.md --engine codex   # or drop the file in queue/inbox/
aqs                                                 # status
```

## Configure (no need to edit the plist)

Put overrides in `~/.agent-queue.env` (untracked — also the place for tokens):

```bash
AGENT_QUEUE_ENGINE=codex   # codex (recommended: local repo) | devin | claude
AGENT_QUEUE_MAX=1          # concurrent jobs on this host (default 3)
# AGENT_QUEUE_NO_CAFFEINATE=1   # allow the Mac to idle-sleep (NOT for overnight runs)
# DEVIN_BIN=/custom/path/devin  # if a CLI isn't on the default PATH
```

## Stop / uninstall

```bash
bash launchd/install.sh --uninstall   # bootout + remove plist (queued jobs stay put)
```

## Notes & gotchas

- **codex vs devin:** for a local monorepo overnight runner, **codex** is the
  default — it runs in-repo so `@bytelyst/*` workspace links resolve locally and
  logs/token-usage parsing already work. Use **devin** when you want a cloud
  sandbox doing the heavy lifting (and ACUs/network aren't a concern).
- **Power:** caffeinate wraps the long-lived loop, so the Mac stays awake the
  whole time the LaunchAgent runs. That's intended for a dedicated runner. Set
  `AGENT_QUEUE_NO_CAFFEINATE=1` if you'd rather let it idle-sleep when no job is
  active. Keep it plugged in with the lid open for true overnight runs.
- **PATH:** launchd starts processes with a minimal `PATH`. Both the plist
  (`EnvironmentVariables`) and the wrapper repair it, but if a CLI lives
  somewhere unusual, point at it explicitly via `~/.agent-queue.env`.
- **Dangerous mode:** jobs run `--yolo` (auto-approve) by default. The safety net
  is the agent-queue lifecycle itself — jobs land in `review/` → `testing/` and
  **shipping is always a manual human gate**. Never let an unattended run touch
  `main`; push to a branch and open one PR.
- **Auth:** cache `gh auth login` / git credentials and the agent CLI's auth
  before relying on it overnight, or the first `push` will block forever.