Expand description
Persistent supervisor state under the operator-local
state/headless.json.
§Why persist
Without persistence, a daemon crash-and-respawn would default
to “off” — silently reverting the operator’s stated intent.
The M2 spec rejects that: if the operator asked for the
supervisor to be armed, a restart must reinstate that posture
and the operator’s next /headless status must show
“started”, not “stopped”.
§Atomic writes
Every state mutation is written via the classic
write-to-tempfile + fsync + rename dance. Partial writes
on power loss would otherwise leave the daemon with
unparseable state, and the honest response to unparseable
state is to refuse to start — not a great experience when
the alternative is “safely lose the last change”.
§Wire format
The on-disk format is deliberately the same JSON shape as the IPC protocol’s state envelope. An operator who wants to see why the daemon started the way it did can just inspect the operator-local state file instead of learning a second schema.
Structs§
- State
- Persistent state shape. Kept intentionally small so the
file is human-grippable under
cat. Additions that don’t alter the supervisor’s recovery behaviour should stay out of this struct and into a sibling file.
Enums§
Constants§
- MAX_
RECENT_ ACTIONS - How many recent actions to keep on disk. Spec wants
/headless statusto be able to show the last 3 underheadless_recent_actions; we keep one extra slot as cheap context for debugging without turning the state file into an append-only log.