kew health

Attest that the control plane itself is functioning — a monitoring/CI gate.

kew health                # human table; exit 0 healthy / 1 degraded / 2 can't read db
kew health --json         # machine-readable result for monitors/CI
kew health --window 14    # retrospective window in days (default 7)

Checks

Check	What it verifies
meter_running	Successful runs on non-free models recorded cost/tokens (catches silent-zero metering; includes models with no pricing entry).
spend_within_limits	Daily/weekly spend is within the configured [budget] limits (warn at 80%; fixed daily/7-day window, independent of --window). Attests spend is within bounds, not per-dispatch enforcement.
audit_parses	Every audit_events row in the window parses end-to-end (payload + envelope fields).
runner_reachable	Every configured routing-tier runner's CLI is on PATH (+ credential env var where detectable).
dispatch_state	Dispatch enabled, or warn (visible, non-paging) when halted by kew stop / the circuit breaker.
switchyard	Skipped in direct mode. In Switchyard mode, bounded /health and /v1/models probes must admit the configured route. Managed launch separately verifies the pinned binary version and dry run before dispatch. Refusals expose only a sanitized endpoint origin and reason.

Switchyard diagnostics

When Switchyard mode is configured, kew health also takes one bounded snapshot from the proxy's /metrics endpoint. --json includes it under the switchyard check's detail.proxy_observation field:

{
  "kind": "switchyard_proxy_observation",
  "scope": "process_wide_proxy",
  "accounting_authority": "runner_reported_usage",
  "per_run_attribution": false,
  "samples": []
}

Only documented request, error, latency, routing-overhead, selected model/tier, and token families are included. Metric labels are allowlisted; response bodies, credentials, arbitrary labels, and raw transport errors are never printed. If /metrics is unavailable, the same object has an empty samples list and a sanitized unavailable_reason. Metrics availability is observational and does not override the /health and route-admission verdict.

These counters describe the whole Switchyard process. They cannot be assigned to a Kew run when requests overlap, and they never replace runner-reported token usage or Kew's governed cost calculation.

Exit codes

0 — all checks pass (warnings allowed). 1 — at least one check failed. 2 — the run store could not be read.

kew health --json emits {healthy, exit_code, window_days, checks: [{name, status, summary, detail}]}. Direct mode retains the existing schema and does not contact or render Switchyard diagnostics.