Lifecycle

Ctrl+C and services stop in reverse tier order. Each receives SIGTERM with time to shut down gracefully.

Graceful, reverse-order

When you press q in the TUI or send SIGINT/SIGTERM, fuku performs a graceful shutdown – stopping services in reverse tier order so that dependent services stop before their dependencies.

│ received signal: SIGINT
│
│ stopping tier edge
│   ○ web         stopping  SIGTERM → pid 76780
│   ✓ web         stopped
│
│ stopping tier platform
│   ○ api         stopping  SIGTERM → pid 76758
│   ○ worker      stopping  SIGTERM → pid 76759
│   ✓ worker      stopped
│   ✓ api         stopped
│
│ stopping tier foundation
│   ○ auth        stopping  SIGTERM → pid 76741
│   ✓ auth        stopped
│
│ all services stopped

How shutdown works

1. Services stop in reverse tier order (edge → platform → foundation)
2. Each service receives SIGTERM first
3. If the service doesn't exit within the timeout, SIGKILL is sent
4. Within a tier, services stop concurrently

Orphan process cleanup

Before starting services, fuku automatically checks for orphaned processes from previous runs. This prevents port conflicts and zombie processes – common issues when a previous fuku session crashed or was killed with kill -9.

$ fuku run default
│
│ preflight  scanning service directories...
│ preflight  found stale process api pid 75210
│ preflight  found stale process worker pid 75211
│ preflight  killed 2 orphaned processes
│ preflight  done
│
│ tier foundation
│   ✓ auth        running

Pre-flight checks each service directory for leftover PID files and kills any stale processes before starting fresh. This runs automatically – no configuration needed.

One run per project

A second fuku run of the same project is refused while the first instance holds an exclusive lock on the project's lock file. The second process exits before its pre-flight cleanup can touch the running services. An instance started by an older fuku holds no lock, so it is not detected.

$ fuku run
Error: fuku is already running for this project (socket /tmp/fuku-3f9a1c2b7d4e5f60.sock)
Run 'fuku logs' to follow it or stop that instance before starting another.