HydraIssues

Runbook: body-recovery.md covers a dead agent on Windows only — there is no macOS/Mac mini path
open unclassified Project: hydra Reporter: 11 Jul 2026 09:00

Description

hydracluster/docs/runbooks/body-recovery.md:48-102 ("HydraNode is dead") is the fleet's offline-node triage runbook, and it is entirely Windows: schtasks, C:\Windows\System32\config\systemprofile\.hydranode\, Notepad-as-Administrator, C:\hydranode\body.yaml. Its two documented failure modes (the SYSTEM-profile wipe #146 and the crash #150) are both Windows-specific.

It never mentions macOS, launchd, or Mac minis — despite Mac minis being the entire flatscreen head fleet (cheeky-cactus-86, peppy-dumpling-32, cederikmini, turbo-pancake-76).

The only macOS agent-lifecycle content in any repo is a service-management cheat-sheet at hydranode/docs/runbooks/runbook.md:113-133 (cat /tmp/hydranode.log, pkill -f 'hydranode run', launchctl load/unload). Every one of those commands presupposes you already have a shell on the box — which, when the agent is dead, you do not, because exec/shell are agent-pull.

Its claim at :173 — "The only operator-on-site case left is the catastrophic both-body.yaml-locations-wiped scenario, which is acceptably rare" — is Windows-scoped and false on macOS, where the LaunchAgent can simply never load (see the LaunchAgent issue).

What the macOS section needs

  • How to tell a dead agent from a powered-off Mac (cross-reference hydraneck; see the triage-runbook issue).
  • What launchd is supposed to do (KeepAlive respawns the process — install_darwin.go:121-122) and the specific reasons it fails: LaunchAgent not loaded at loginwindow; plist deleted with no ensureInstall() to recreate it on darwin; stale root-owned binary at /usr/local/bin/hydranode blocking auto-update (runbook.md:133).
  • An honest statement that with no logged-in console user, there is no remote fix — installService() hard-fails without a console user (install_darwin.go:22-24). Operator on site.