Module daemon 

khived daemon server — persistent warm runtime over a Unix socket.

The daemon binds ~/.khive/khived.sock, accepts length-prefixed request frames, dispatches them through a DaemonDispatch implementor, and serves results back. It is transport-agnostic: the MCP crate provides the dispatch impl, but any future client (CLI, HTTP gateway) can reuse this server.

The client side (forwarding, auto-spawn) lives in the transport crate (e.g. khive-mcp), not here.

Structs

DaemonRequestFrame

Request frame sent from a client to the daemon.

DaemonResponseFrame

Response frame sent from the daemon back to a client.

MetricsSnapshot

Point-in-time snapshot of the daemon’s server-side gauges — the load/perf harness read-surface (measurement substrate, not a product feature).

PhaseGuard

RAII guard for one occurrence of a named background phase. Increments the phase’s count on creation (see register_active_phase); decrements on Drop, so the count comes back down whether the guarded work returns normally, panics, or is cancelled — the same rationale as BackgroundTaskGuard above.

Constants

MAX_FRAME_BYTES

Maximum frame size accepted in either direction.

PROTOCOL_VERSION

Wire protocol version for the daemon IPC framing.

Traits

DaemonDispatch

Transport-agnostic dispatch interface for the daemon server.

Functions

acquire_daemon_boot_guard

Acquire the recovery/boot lock, treating failure as fatal.

acquire_recovery_lock

Acquire an exclusive advisory flock on the recovery/startup lock file.

active_phase_names

Currently active background-phase names, sorted for deterministic output. Empty when no tracked phase is in flight.

background_task_count

Current count of in-flight tasks started via track_background_task. Exposed for tests; drain() reads the shared counter directly.

env_truthy

Returns true for non-empty env values that are not "0" or "false".

lock_path

Advisory lock file used to serialize stale-daemon recovery across concurrent clients (flock on the file; released when the lock file handle is dropped).

pid_path

PID file path written by the daemon.

read_frame

Read one length-prefixed frame (4-byte BE u32 length + JSON bytes).

recoverer_lock_path

Advisory lock file used to serialize RECOVERY (kill+respawn) attempts across concurrent clients only — the daemon’s own boot sequence never acquires this file (lock_path / acquire_daemon_boot_guard is the boot-side lock). A recoverer holding this lock across dead-confirmation → kill → spawn (khive-mcp’s kill_and_respawn) therefore can never deadlock against a peer daemon’s boot, unlike holding the shared boot lock for that whole span would.

register_active_phase

Register one occurrence of a named background phase as currently active. Returns a guard: drop it (or let it fall out of scope) when the phase ends. Best-effort process-wide gauge only, read by comm.health — never load-bearing for correctness.

run_daemon

Run the daemon: bind the socket, warm in the background, serve request frames until SIGTERM/SIGINT.

run_daemon_with_boot_guard

Run the daemon using a startup lock acquired by the caller before building dispatcher, so a second process racing to boot (e.g. two kkernel mcp --daemon spawns before either has bound its socket) cannot run migrations/FTS DDL concurrently against the same database file. boot_guard is only None on non-unix targets, where there is no advisory boot lock to hold in the first place; every unix daemon-mode caller passes Some.

socket_path

Unix socket path the daemon binds and clients connect to.

track_background_task

Spawn a fire-and-forget background task that daemon shutdown’s drain() waits for, instead of a bare tokio::spawn that a SIGTERM can abort mid-flight with no trace. Only the enqueue (an atomic increment) is synchronous on the caller’s path — the future itself still runs fully off-path, unawaited. The decrement happens via BackgroundTaskGuard’s Drop, so a panic inside fut still restores the count.

try_acquire_daemon_boot_guard_until

Bounded, deadline-aware variant of acquire_daemon_boot_guard: attempts the SAME boot/recovery lock (lock_path) but gives up at deadline instead of blocking forever. For callers that need to detect “is a boot in progress right now” without risking an unbounded wait behind a wedged holder: e.g. khive-mcp’s confirm_genuinely_dead re-probing rounds, where DEAD_CONFIRM_ROUNDS must bound elapsed time, not just probe count.

try_acquire_recoverer_lock_until

Bounded, deadline-aware acquisition of the recoverer-only lock (recoverer_lock_path). See try_acquire_daemon_boot_guard_until for the shared rationale — a second recoverer waiting for a peer’s dead confirmation/kill/spawn critical section must give up and report “uncertain” rather than block forever if that peer is itself wedged.

write_frame

Write one length-prefixed frame.

Type Aliases

DaemonBootGuard

Guard returned by acquire_daemon_boot_guard, held across cold-boot schema initialization (migrations + pack schema plans / FTS DDL) through daemon bind + pid-write.