Zephr Docs

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 health prints a zephrd running line (yes/no) and an MCP handshake line reporting the handshake state.
  • zephr doctor reports 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, and host.pack.<platform> when host packs are installed), a status (pass | warn | fail), a message, and a recovery hint. The overall report is ok, degraded, or unhealthy; the exit code is 0 when all checks pass, 1 when any fail, and 2 when the command itself is used unsatisfiably. zephr doctor --json emits a machine-readable report.
  • zephr status reports your authentication state and the resolved active role; zephr status --pulse prints 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 (with retrieval.semantic: false). Default recall then degrades to lexical results with the fallback disclosed (mode lexical_fallback); only requests that require the semantic tier abstain with semantic_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-gated zephr_admin stats action. storage.location reports file or memory — a memory location means everything is discarded at exit.
  • producers — the producer-readiness matrix (ready | degraded | absent). A degraded producer carries a named compensating strategy; an absent one may report none. Present only when a readiness surface is bound; its absence is honest, never a fabricated ok.
  • daemon — zephrd telemetry (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

  1. Daily or on suspicion: zephr health — daemon and handshake up?
  2. On any anomaly: zephr doctor — which check failed, and what is its recovery hint?
  3. In-agent: ask for zephr_status and check retrieval.semantic (and the embedding block when present) before diagnosing recall behaviour.
  4. 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.