# ADR-0007: The Console v2 server runs as a LaunchAgent from Phase 1 onward

**Status:** Accepted (Phase 1; reaffirmed Phase 2)

## Context

Manually starting `uvicorn` every morning is a per-user-action footgun: JT
forgets, mobile fails to connect, the desktop console silently falls back
to localStorage. The Studio is always on; the bottleneck is process
lifecycle. Other Recoil surfaces (cortex, workspace MCP) already use
LaunchAgents for the same reason.

## Decision

Phase 1 ships `com.recoil.console-v2.plist` to Studio's
`~/Library/LaunchAgents/`. The plist runs `uvicorn recoil.api.main:app
--host 0.0.0.0 --port 8431`, with stdout/stderr to
`~/Library/Logs/recoil-api-stdout.log` / `...-stderr.log`, KeepAlive on, and
RunAtLoad on. Health is verified via `curl 127.0.0.1:8431/api/health` →
`{"ok":true}`. Phase 2 onward assumes the server is up and reachable;
clients render a "disconnected" status pill on failure.

## Consequences

Workspace state is always available to every console surface that can reach
Tailscale. The cost: a misbehaving server (e.g., bad migration) cycles
endlessly under KeepAlive — phase 19 onward needs healthcheck + circuit
break. The plist is checked into the repo at
`scripts/launchagent/com.recoil.console-v2.plist` and re-installed by a
top-level `make install-agent` target.