fix(#6044): make grafel stop actually stop grafel — service-aware, persistent, honestly confirmed

[cajasmota]

grafel stop did not stop grafel. It sent the Stop RPC, the daemon obeyed, and launchd immediately respawned it — the LaunchAgent declares an unconditional KeepAlive. The command printed stop requested and returned 0 either way, so the user saw the service still running and reasonably concluded the command was broken.

Reported by a user, reproduced four times on macOS. The asymmetry is the root cause: grafel start is service-aware (OS service detected for this daemon; restarting via the OS service manager); stop was not. start went through launchd, stop went around it.

03:30:11  serve=72746 (up since 03:05:47)
03:30:20  $ grafel stop  →  "stop requested"  (rc=0)
03:30:21  serve=82993   ← respawned ~1s later

Three stop calls inside the same second returned stop requested / daemon not running / stop requested — launchd resurrecting the daemon between consecutive calls. That flapping is what a user experiences as "sometimes it stops it, and it never stays down".

stop is now persistent, and that decision is deliberate

The issue asked for this to be chosen rather than defaulted into. bootout stops the job now but the plist still loads at login, so macOS pairs it with launchctl disable; Load() unconditionally enables before bootstrap so the ordinary install/start/restart cycle is unaffected. systemd's Unload() was already disable --now and schtasks's already deletes the registration, so all three platforms now agree: stop means stay down; grafel start is the way back. grafel stop --help says so explicitly.

Confirmation is on the socket, not the job registry

The first implementation confirmed via Status(), which on darwin derives Running purely from launchctl list <label>'s exit code — is the job loaded in the domain, not is the process alive. After bootout the job is gone by definition, making the check very nearly a tautology, and blind to a manually-started daemon outside the domain entirely.

Concretely: a plist on disk plus a hand-started daemon routes to the service path (serviceInstalledForThisRoot only stats the plist). Unload() gives up after 3s with errors ignored, bootout no-ops on an unloaded job with its exit status discarded, and stop printed "daemon stopped" over a live daemon.

stopConverge now polls Probe() — the real socket — via waitStopped, mirroring the existing waitReady. Pinned by TestStopConverge_TrustsProbeNotStatus, whose fixture composes probeAlwaysUp with loaded:false so it genuinely models "Status says down, socket says up", and which asserts its own fixture precondition before the real assertion.

The persistence decision is now falsifiable

launchctlBootout/Bootstrap/Disable/Enable are package vars. Before that seam existed, deleting both the disable and enable calls outright left the entire suite green — the diff's most consequential decision was unpinned. Unload records the outcome on lastDisableErr and stopService reads it, so the CLI no longer prints "even across reboot" over a disable whose error it discarded.

Two callers of the new persistence that the first pass missed: uninstall now re-enables the label after teardown rather than leaving a launchd override with no plist to explain it, and install.sh's restart_daemon detects "plist present but not loaded" and calls enable before bootstrap instead of silently giving up on any machine where stop had been used.

The orphaned-engine window

A hard exit of serve orphaned its engine child — ppid flips to 1 — while launchd spawned a replacement alongside it: two process trees against one state directory, the shape that produces torn writes and doubled memory. Drain signals are now group-directed.

groupOrSingleSignal checks Getpgid(pid) == pid before negating. The #5999 precedent (sched/nice_unix.go) was verified rather than cited: it is safe there because Cancel runs strictly before Wait frees the pid. This supervisor's drain races a separate reaping goroutine and has no such ordering, so without the leadership check a lost race would signal whatever group inherited the reused pid. A microsecond TOCTOU window remains and is documented as such — a reuse race is not constructible in a test, and the comment says so rather than implying coverage.

defaultEngineChildCommand's cmd.Env = os.Environ() and its load-bearing comment are byte-identical; git diff -- internal/daemon/supervise.go is empty.

Verification

go build ./... && go vet ./... && gofmt -l . clean. 30 packages green at raw exit 0 across internal/cli, internal/daemon, cmd/grafel, internal/install. -race clean on the service and supervisor packages.

Mutation battery rebuilt against the final tree; every behavioural change dies individually. Two mutations that survived the first round now die, each naming its hole: reverting stopConverge to Status()-only, and deleting the disable/enable calls.

A false-pass fixture was found, disclosed by the author, and independently reproduced. The original SIGKILL test used a plain sleep grandchild, which died to the group SIGTERM before the drain timeout ever elapsed — so it passed regardless of whether signalKill was group-directed. The grandchild now does trap '' TERM; exec sleep 300 (SIG_IGN survives exec), and the escalation branch is genuinely reached: 0.59s blind versus 6.63s biting. Reverting the trap alone, with signalKill still broken, restores the false pass — which is how the fixture's load-bearing element was confirmed rather than assumed. signalTerminate and signalKill now have independent pins; mutating either fails only its own tests.

Known and disclosed

• Probe() proves socket-death, not process-death. listener.Close() precedes the remaining graceful tail, so waitStopped can return before the process is gone — the issue's own worst case, a stalled RPC mid-index. Bounded by defaultShutdownWatchdog = 5s, which force-exits the whole tail, so the window is ≤~5s. The definitive axis (ReadPIDFile + pidStillAlive, already used by runDaemonRestart) is in-tree and unused here. Follow-up, not a blocker.
• The Linux half of the installer asymmetry is unaddressed. A disabled systemd unit still appears in list-unit-files and still restarts, so an upgrade brings the daemon back running-but-still-disabled-at-boot, while macOS now fully reverts the stop. Neither tells the user their deliberate stop was undone. Follow-up.
• waitStopped's budget is 60s against the RPC path's 5s. Success is fast (the first probe short-circuits); a stubborn daemon now blocks for a minute before reporting. Correct-over-fast, but the asymmetry is unexplained.
• The watchdog force-exit can still orphan the engine — the pre-existing hard-exit case the issue itself calls out, orthogonal to the group-signal fix, which only applies when the drain actually runs.

Independently adversarially reviewed across two rounds; five of six findings verified closed by execution.

Closes #6044