Monitoring
Zephr health surfaces are deliberately small and honest: each surface uses its own
vocabulary, and none of them invents numbers. Producers report ready / degraded /
absent, pulse metrics report measured / not_evaluated / unavailable, and a component
with no measurement plane is not_evaluated — never a silent zero. This page is the
operator's routine.
The health ladder
Run these in order — each is safe and needs nothing beyond your own installation:
zephr health # daemon status + MCP handshake
zephr doctor # per-check on-box diagnostics
zephr status # auth state and resolved role (--pulse: local pulse)zephr healthprints azephrd runningline (yes/no) and anMCP handshakeline reporting the handshake state.zephr doctorreports per-check diagnostics. Each check carries an id (binary.identity,binary.attestation,daemon.socket— best-effort,daemon.peer— pass-with-note in standalone installs,client.handshake.<name>,install.cold_runner_risk,schema— best-effort, skipped locally, andhost.pack.<platform>when host packs are installed), a status (pass|warn|fail), a message, and arecoveryhint. The overall report isok,degraded, orunhealthy; the exit code is 0 when all checks pass, 1 when any fail, and 2 when the command itself is used unsatisfiably.zephr doctor --jsonemits a machine-readable report.zephr statusreports your authentication state and the resolved active role;zephr status --pulseprints a local pulse snapshot (component coverage, measured counts) instead.
In-client health: zephr_status
The MCP zephr_status tool reports system health to the agent: schema version,
embedding capability, retrieval modes (lexical and semantic flags), and storage
stats. With action "changes" it returns a worktree-scoped Change Radar report since a
session or timestamp anchor.
Useful signals — read the fields, not the prose:
retrieval.lexical/retrieval.semantic— which tiers are actually usable.embedding— present as{ model, available, sandboxed, alpha }only when the semantic tier is available; the block's absence is the honest unavailable signal (withretrieval.semantic: false). Default recall then degrades to lexical results with the fallback disclosed (modelexical_fallback); only requests that require the semantic tier abstain withsemantic_unavailable. Nothing is fabricated, and nothing degrades silently.storage— present only when the dispatch has an admitted worktree scope, and counts are limited to the current worktree. Installation-wide totals come from the capability-gatedzephr_adminstatsaction.storage.locationreportsfileormemory— amemorylocation means everything is discarded at exit.producers— the producer-readiness matrix (ready|degraded|absent). Adegradedproducer carries a named compensatingstrategy; anabsentone may report none. Present only when a readiness surface is bound; its absence is honest, never a fabricatedok.daemon—zephrdtelemetry (store_kind,ipc_schema_version,uptime_secs), present only when the daemon is reachable; its absence is the honest "daemon unavailable" signal.
Account-connected health
When you are connected to your Zephr account, the public Cloud API exposes getSystemHealth
and getRuntimeStatus (see the generated Cloud API reference).
zephr notifications lists the notification feed (newest first), and zephr usage shows
account and review spend — see the Quota and billing
entry in the troubleshooting catalog for how to read it.
Reading exit codes
The CLI's shipped exit-code vocabulary: 0 success, 1 catch-all, 2 usage error, 3 data
integrity error, 4 I/O error, 5 drift (a sync run completed with partial success), 69
unavailable (required daemon or binary not reachable), 130 interrupted (SIGINT).
On-box evidence commands add two epistemic codes: 64 usage and 77 abstention (an
honest empty result — e.g. recall with --why — not a failure).
Two deserve an operator's attention:
- 69 — a required dependency is unreachable; the caller must not fabricate data as a substitute. Start with the Daemon entry in the troubleshooting catalog.
- 5 — reconciliation is not fully in sync. Start with the Sync entry in the troubleshooting catalog.
A minimal monitoring routine
- Daily or on suspicion:
zephr health— daemon and handshake up? - On any anomaly:
zephr doctor— which check failed, and what is itsrecoveryhint? - In-agent: ask for
zephr_statusand checkretrieval.semantic(and theembeddingblock when present) before diagnosing recall behaviour. - On repeated failures: run the incident recovery loop.
What monitoring is not
Pulse is the product observability surface for health, usage, trust, drift, storage, and
diagnostics, and the Runtime workspace that hosts it is evolving, not complete. A
pulse metric is measured, not_evaluated, or unavailable; where a metric's measurement
plane has not produced a value, the surface renders not_evaluated — an honest gap, never a
silent zero. Pulse is not a substitute for the health ladder above: it reports what is
measured, and it does not fabricate readings for planes that are not instrumented.