# Daemon Wire Protocol and Metrics
`daemon.rs` implements the long-lived `kkernel mcp --daemon` process that keeps ANN/embedder
state warm across MCP sessions (ADR-049): its framed request/response protocol, boot-time
locking, and the metrics snapshot served to callers. This document covers the versioned wire
protocol, the two lock-acquisition strategies the daemon uses, and where each metrics gauge is
sourced from.
## protocol_version
Version history for `PROTOCOL_VERSION`:
- 1 — initial versioned framing (added `protocol_version` + `version_mismatch`); added
`probe_only` request field + probe-ack sentinel shape in response
- 2 — gate subhandler verbs by wire origin (`from_wire` request field)
- 3 — added per-request identity context to the request frame (`actor_id`,
`visible_namespaces`); the daemon now serves a request under the frame's identity instead of
rejecting on `namespace_mismatch` (the `config_id` equality reject stays hard)
- 4 — added request-origin `process_ref` attribution. Although optional, it can affect durable
comm message properties, so v3/v4 peers reject each other before dispatch instead of allowing a
v3 daemon to execute a write while silently ignoring the new field.
`process_ref` carries the originating client's opaque `KHIVE_PROCESS_REF`; it is request
attribution, not identity, and prevents a shared daemon from substituting its own process
environment. Its `serde(default)` preserves the meaning of an omitted value within protocol v4;
it does not make a v3 daemon safe to use. `request_id` is the independent additive numeric
audit-correlation field and does not alter dispatch or persisted verb output.
## try_acquire_flock_until
Unlike `acquire_recovery_lock`/`acquire_daemon_boot_guard` (unbounded blocking `flock`, correct
for the daemon's own boot sequence where waiting until quiescence IS the desired behavior), a
caller only trying to _detect_ whether a lock is currently free — without committing to wait
forever for a possibly-wedged holder — needs a deadline instead.
## build_metrics_snapshot
`tx_registry` (ADR-091 Plank 0) is a process-global singleton reachable directly, with no plumbing
through `dispatcher`. TRUNCATE counters remain module-scoped atomics. The logical WAL fields
(`wal_log_frames`, `wal_checkpointed_frames`, and `wal_pending_frames`) and
`wal_physical_bytes` come from the dispatcher's exact pool's last routine PASSIVE tick; building a
metrics frame does not issue an on-demand checkpoint or stat the sidecar. `wal_pages` remains the
compatibility projection of `wal_log_frames`. The backend key is load-bearing in a multi-backend
daemon: a secondary task's later tick cannot relabel its state as the main pool's sample.
`write_queue_depth`/`_capacity` (ADR-067 Component A) come from the same pool and are `None`
unless a writer task exists. The `write_last_*_micros` fields expose that task's latest completed
queue-wait, transaction-acquisition, body, commit, and total stages, plus the observation time.
All new fields are additive `serde(default)` metrics-only fields; older peers can omit them without
changing request dispatch or the canonical verb result.