zero_headless/lib.rs
1//! Operator-local supervisor daemon (ADR-006, M2 §6).
2//!
3//! `zero-headless` ships two artifacts:
4//!
5//! 1. **`zero-headlessd` binary** — the supervisor daemon. Runs
6//! under launchd (macOS) or systemd (Linux); listens on a
7//! Unix socket at
8//! `<zero_dir>/operators/<operator-slug>/sock` for typed line-delimited JSON
9//! requests from the `zero` CLI (and, in M3, the Telegram
10//! bot). Persists its "operator intended me to be running"
11//! state under
12//! `<zero_dir>/operators/<operator-slug>/state/headless.json` so a
13//! crash-and-restart recovers the operator's posture rather
14//! than silently defaulting to "off".
15//!
16//! 2. **Library surface** — the [`protocol`] envelopes, the
17//! [`client::Client`] dialer, and the [`state::State`]
18//! persistence type. The `zero-commands` crate's real
19//! `SupervisorSource` adapter (shipped in §6, not in this
20//! module) is built on top of [`client::Client`] so the
21//! shipped binary and the CLI-side dialer speak the same
22//! wire format by construction.
23//!
24//! # Invariants
25//!
26//! - **Line-delimited JSON framing.** One request per line,
27//! one response per line. Chosen over length-prefixed framing
28//! so an operator debugging a stuck daemon can
29//! `nc -U <zero_dir>/operators/<operator-slug>/sock` and read
30//! what the daemon is saying without tooling. Every envelope has
31//! a `kind` tag so the
32//! protocol is forward-extensible.
33//!
34//! - **Kill-switch paths are never gated.** A `/kill` from the
35//! CLI, a `SIGTERM`, or a Telegram-originated kill all reach
36//! the same `graceful_drain` path. Silence on a kill request
37//! is the 2 AM failure mode the architecture exists to
38//! prevent — the daemon logs a single-line breadcrumb for
39//! every kill attempt and honours it within a hard deadline.
40//!
41//! - **Three honest questions in one `status`.** The protocol's
42//! [`protocol::StatusReply`] answers (a) is the daemon
43//! running, (b) is the engine reachable from the daemon, (c)
44//! what was the daemon's most recent action. Silence on any
45//! of the three is a lie; the protocol type forces all three
46//! to be populated on every reply.
47//!
48//! The daemon itself does *not* make trading decisions — those
49//! live in the engine. `zero-headlessd` is a watchdog + kill-
50//! switch surface + structured keepalive; it exists so an
51//! operator who closes their laptop still has a path to halt
52//! the engine from a phone (via the M3 Telegram bot) or a
53//! second terminal (via `zero kill`, §8).
54
55#![allow(clippy::module_name_repetitions)]
56
57pub mod client;
58pub mod daemon;
59pub mod paths;
60pub mod protocol;
61pub mod state;
62
63pub use client::{Client, ClientError};
64pub use paths::{default_socket_path, default_state_path};
65pub use protocol::{
66 ActionKind, ActionRecord, EngineHealth, PROTOCOL_VERSION, Request, Response, StatusReply,
67 SupervisorState,
68};
69pub use state::{PersistError, State};