ADR-005: Foreground Process (Not Daemon)

Status

Accepted

Context

The orchestrator could run as a background daemon or a foreground process attached to a terminal.

Decision

Run as a foreground process. The user starts swarm start in a terminal and the TUI takes over. The process exits when the user quits or sends SIGINT/SIGTERM.

Rationale

  • Simpler lifecycle management — no PID files, no orphan daemons.
  • TUI requires a terminal anyway.
  • Users can use tmux/screen for persistence.
  • --no-tui mode still runs in foreground, just without the UI.

Alternatives Considered

AlternativeWhy rejected
Daemon with swarm attachComplex (double-fork, PID management, socket for TUI attach)
systemd serviceOver-engineered, not portable

Consequences

  • Session lockfile contains the orchestrator PID for staleness detection.
  • swarm stop from another terminal sends SIGTERM to the orchestrator PID.
  • Signal handler catches SIGINT/SIGTERM and triggers graceful shutdown.
  • swarm status checks if the PID is alive to determine session liveness.