xy/docs/superpowers/specs/2026-07-31-xy-start-on-login-design.md

xy — Start on Login (macOS)

Date: 2026-07-31 Status: Approved — ready for implementation planning

Problem

The daemon must be launched by hand (xy daemon) and dies with the terminal that started it. The MVP spec (2026-05-25) listed "auto-start at login via launchd" as an explicit non-goal; this design delivers it.

Goals

• Install a user-level launchd agent that starts xy daemon at login and restarts it if it dies.
• Manage that agent from xy itself — install, uninstall, start, stop, status.
• Survive the environment launchd hands a login agent, which is far poorer than an interactive shell's.
• Give the daemon a log file, so "it didn't come up at login" is diagnosable.

Non-goals (deferred)

• Linux (systemd) and Windows support. The CLI shape is chosen so these are a change inside one module, not a change to the command surface.
• System-level (root) agents. User agents only.
• Managing the agent over IPC. xy service * deliberately bypasses the daemon.

Decisions

launchd owns the daemon's lifecycle

Once installed, the LaunchAgent is the sanctioned way to run the daemon on macOS: RunAtLoad starts it at login and KeepAlive restarts it on crash. xy daemon remains available for foreground and development use; the existing pidfile keeps the two from colliding.

Environment: snapshot PATH at install time

A LaunchAgent inherits PATH=/usr/bin:/bin:/usr/sbin:/sbin and nothing from the user's shell. Supervised MCP servers inherit whatever the daemon has, and servers launched through toolchain shims (pnpx, bunx) will not find their interpreter under that PATH.

xy service install therefore captures the invoking shell's PATH and writes it into the plist's EnvironmentVariables. The snapshot is deterministic and visible in the plist, at the cost of going stale when a new toolchain is added — xy service install --force re-snapshots.

Rejected: wrapping the daemon in /bin/zsh -lc, which makes login-time startup depend on shell rc being fast and non-interactive-safe, and adds a process to the tree for no gain here.

Verified 2026-07-31: XDG_CONFIG_HOME, XDG_STATE_HOME and XDG_RUNTIME_DIR are all unset on this machine, so etcetera's Xdg strategy resolves to ~/.config and ~/.local/state identically for the CLI and for a launchd-spawned daemon. There is no path-mismatch risk to design around.

Third-party crate: service-manager

service-manager = "0.11" (469K downloads, 29 reverse deps, updated 2026-02-18) provides LaunchdServiceManager::user() targeting ~/Library/LaunchAgents, an install context carrying environment, autostart and restart_policy, and a status() returning NotInstalled / Running / Stopped(Option<String>).

Rejected alternatives:

• auto-launch (4.6M downloads) is built for GUI applications at login. It has no notion of KeepAlive, restart policy, or service status — the wrong abstraction for a supervised daemon.
• Hand-rolled plist + launchctl would re-implement the crate and leave us owning modern-vs-legacy launchctl compatibility.

Use the crate's generated plist; log from inside the daemon

LaunchdInstallConfig exposes only keep_alive — there is no way to set StandardOutPath or StandardErrorPath through the typed API. Rather than bypass it with the contents: Option<String> escape hatch and hand-author plist XML, the daemon gains its own log file (see below).

Accepted limitation. Failures occurring before the daemon's logger exists — missing binary, dyld error, malformed plist — appear in neither xy.log nor xy service status beyond a bare Stopped. Documented recourse:

launchctl print gui/$UID/se.aceofba.xy

Program path: current_exe(), with a warning

xy service install resolves and canonicalizes std::env::current_exe(). If the result contains a target/debug or target/release path component, it prints a warning that the agent will break on cargo clean and proceeds.

Architecture

service-manager is added to [workspace.dependencies] and consumed by the xy crate alone. xy-protocol, xy-supervisor and xy-ipc are unchanged except for one addition to logs.rs (below). Nothing crosses the IPC boundary: xy service * manipulates launchd directly, which is what makes it work when the daemon is dead.

Two new modules in crates/xy, Rust-2018 layout (foo.rs + foo/):

• src/service.rs — the OS-facing unit. Owns AgentSpec and thin install / uninstall / start / stop / status functions that translate it into ServiceInstallCtx and back out into an AgentStatus. Knows about launchd; knows nothing about clap or printing. Returns data, never prints, so it is testable without a terminal.
• src/cli/service.rs — the presentation unit. Parses the verbs, calls into service.rs, formats human output, maps outcomes to exit codes. Mirrors the existing cli/mod.rs / cli/format.rs split.

main.rs gains a Service { #[command(subcommand)] verb: ServiceCmd } arm.

service.rs wires LaunchdServiceManager::user() under cfg(target_os = "macos"). On other targets the verbs return start-on-login is macOS-only for now and exit 1.

The agent

AgentSpec field	Value	Plist key
label	se.aceofba.xy	Label
program	canonicalized current_exe()	ProgramArguments[0]
args	["daemon"]	ProgramArguments[1..]
environment	[("PATH", <snapshot>)]	EnvironmentVariables
working_directory	$HOME	WorkingDirectory
autostart	true	RunAtLoad
restart_policy	Always { delay_secs: Some(10) }	KeepAlive
username	None — runs as the invoking user	—

launchd collapses RestartPolicy to a KeepAlive boolean: Never maps to false, Always and OnFailure both map to true, and delay_secs is ignored. Always is chosen for the explicit KeepAlive: true it produces; the delay is carried only so the value stays meaningful if this spec is extended to systemd.

The label is the reverse-DNS form of the git.aceofba.se remote. It lives on AgentSpec rather than being a constant so tests can install under a distinct label.

working_directory is $HOME rather than launchd's default /, so that a server config using a relative working_dir resolves somewhere predictable.

Daemon logging

main.rs is reordered so Paths::resolve() and ensure_dirs() run before tracing is initialised. Today ensure_dirs() is called inside daemon::run, which is too late to open a log file for the logger itself.

For the Cmd::Daemon arm only, the subscriber writes to stderr.and(file) via MakeWriterExt, where the file half is log_dir/xy.log backed by the existing xy_supervisor::logs::RotatingLogWriter (10 MB × 5, the same rotation used for per-server logs). A small MakeWriter newtype wrapping Arc<Mutex<RotatingLogWriter>> bridges the two.

Every other subcommand keeps stderr-only logging; CLI output does not belong in the daemon's log.

This requires one targeted addition to existing code: impl std::io::Write for RotatingLogWriter in xy-supervisor/src/logs.rs. The type already tracks written and rotates, but today exposes only write_line(tag, line), which prefixes a tag the daemon's own log does not want.

Result: ~/.local/state/xy/logs/ becomes uniform — xy.log for the daemon, <server>.log per supervised server, all rotated by the same code.

CLI

xy service install [--force]
xy service uninstall
xy service start
xy service stop
xy service status

• install — exits 1 if the plist already exists at ~/Library/LaunchAgents/se.aceofba.xy.plist, directing the user to --force. Presence of that file is the definition of "installed" throughout; the crate's ServiceStatus::NotInstalled is treated as corroborating, not authoritative, because it cannot distinguish a missing plist from an unloadable one. With --force, uninstalls first, which re-snapshots PATH and re-resolves current_exe(); this is also the upgrade path after installing a new binary or adding a toolchain. Warns and proceeds on a build-tree program path. On success it writes the plist and bootstraps, leaving a running daemon.
• uninstall — stops, then removes the plist. Not-installed is not an error: prints not installed, exits 0, matching how xy stop already reports not running.
• start / stop — bootstrap and bootout, leaving the plist in place. Both exit 1 if the agent is not installed. stop on an already-stopped agent exits 0.
• status — reports label, plist path, state, program path, snapshotted PATH, and log path. Never fails on state, only on an inability to query. State is running / stopped / not installed, taken directly from ServiceStatus; the reason string from Stopped is surfaced verbatim, being the main window into launch failures. There is deliberately no separate "loaded" line, because the crate's API cannot distinguish a loaded-but-stopped agent from an unloaded one. The pid is read from the existing paths.pidfile; the crate does not expose one. The snapshot date is the plist's mtime, not a value stored inside it.

Sample output:

$ xy service status
  agent:   se.aceofba.xy (user)
  plist:   ~/Library/LaunchAgents/se.aceofba.xy.plist
  state:   running (pid 4821)
  program: /Users/olsson/.cargo/bin/xy
  path:    /opt/homebrew/bin:… (snapshotted 2026-07-31)
  log:     ~/.local/state/xy/logs/xy.log

Exit codes

Reuses the established scheme, minus the codes that cannot apply. 0 success, 1 operational error (launchctl failed, agent missing, permission denied). Code 2 (daemon unreachable) is structurally impossible because these commands never open the socket; 3 (config invalid) does not arise.

Testing

TDD throughout — failing test first, then minimal implementation.

• Unit tests in service.rs for the AgentSpec → ServiceInstallCtx mapping: label parses, args are ["daemon"], the PATH snapshot is captured, $HOME becomes the working directory. No launchd involved.
• Unit tests for the dev-build path predicate against a table of sample paths.
• Formatting tests in cli/service.rs rendering an AgentStatus to expected text, mirroring the existing cli/format.rs tests.
• A test for impl io::Write for RotatingLogWriter covering byte accounting and the rotation threshold. The rotation logic is currently exercised only through write_line.
• tests/service.rs — a real install → status → stop → start → uninstall cycle, marked #[ignore] and using the label se.aceofba.xy-test so that a stray cargo nextest run can never install a live agent. Run manually with --ignored.

Documentation

README.md gains the five xy service verbs, a note that the agent snapshots PATH at install time and that --force re-snapshots, and the launchctl print recourse for pre-logger failures.