#1987 Native background/daemon mode for swamp serve

Problem

swamp serve runs as a foreground process. When the parent shell exits (e.g. terminal closed, SSH disconnect, CI session ends), serve dies immediately. There is no built-in way to run it as a persistent background service.

Current workarounds require platform-specific solutions outside of swamp:

• nohup swamp serve ... & + disown
• macOS launchd plist
• systemd unit on Linux

Proposed solution

A native mechanism to start serve in the background and manage its lifecycle. Some options:

1. swamp serve --daemon / swamp serve --background flag that forks to background, writes a PID file, and logs to a file
2. swamp serve stop / swamp serve status for lifecycle management
3. A swamp serve install command that generates the platform-appropriate service definition (launchd plist on macOS, systemd unit on Linux)

Alternatives considered

• Documenting the nohup/launchd/systemd patterns — works but is boilerplate every user has to figure out
• Docker — overkill for local dev

Context

Found during e2e testing of puddle-ui → puddle-serve integration. Serve kept "crashing" — actually just dying with its parent shell between Claude Code sessions. The token vault persists across restarts, but requiring manual restart each session is friction.