Expand description
Operator-local supervisor daemon (ADR-006, M2 §6).
zero-headless ships two artifacts:
-
zero-headlessdbinary — the supervisor daemon. Runs under launchd (macOS) or systemd (Linux); listens on a Unix socket at<zero_dir>/operators/<operator-slug>/sockfor typed line-delimited JSON requests from thezeroCLI (and, in M3, the Telegram bot). Persists its “operator intended me to be running” state under<zero_dir>/operators/<operator-slug>/state/headless.jsonso a crash-and-restart recovers the operator’s posture rather than silently defaulting to “off”. -
Library surface — the
protocolenvelopes, theclient::Clientdialer, and thestate::Statepersistence type. Thezero-commandscrate’s realSupervisorSourceadapter (shipped in §6, not in this module) is built on top ofclient::Clientso the shipped binary and the CLI-side dialer speak the same wire format by construction.
§Invariants
-
Line-delimited JSON framing. One request per line, one response per line. Chosen over length-prefixed framing so an operator debugging a stuck daemon can
nc -U <zero_dir>/operators/<operator-slug>/sockand read what the daemon is saying without tooling. Every envelope has akindtag so the protocol is forward-extensible. -
Kill-switch paths are never gated. A
/killfrom the CLI, aSIGTERM, or a Telegram-originated kill all reach the samegraceful_drainpath. Silence on a kill request is the 2 AM failure mode the architecture exists to prevent — the daemon logs a single-line breadcrumb for every kill attempt and honours it within a hard deadline. -
Three honest questions in one
status. The protocol’sprotocol::StatusReplyanswers (a) is the daemon running, (b) is the engine reachable from the daemon, (c) what was the daemon’s most recent action. Silence on any of the three is a lie; the protocol type forces all three to be populated on every reply.
The daemon itself does not make trading decisions — those
live in the engine. zero-headlessd is a watchdog + kill-
switch surface + structured keepalive; it exists so an
operator who closes their laptop still has a path to halt
the engine from a phone (via the M3 Telegram bot) or a
second terminal (via zero kill, §8).
Re-exports§
pub use client::Client;pub use client::ClientError;pub use paths::default_socket_path;pub use paths::default_state_path;pub use protocol::ActionKind;pub use protocol::ActionRecord;pub use protocol::EngineHealth;pub use protocol::PROTOCOL_VERSION;pub use protocol::Request;pub use protocol::Response;pub use protocol::StatusReply;pub use protocol::SupervisorState;pub use state::PersistError;pub use state::State;
Modules§
- client
- Client-side dialer for the daemon.
- daemon
- Daemon core — Unix-socket listener + request handler.
- paths
- Filesystem path helpers for the daemon and its clients.
- protocol
- Line-delimited JSON IPC protocol between the
zeroCLI and thezero-headlessddaemon. - state
- Persistent supervisor state under the operator-local
state/headless.json.