Skip to main content

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};