Skip to content

kew doctor

Run local environment diagnostics and surface known issues that cause silent failures or wasted dispatch spend.

kew doctor                # human-readable checks; exit 0 clean / 1 issue found

Checks

Check What it verifies
agent-image The local sandbox agent image is at least as new as its build inputs (docker/agent.Dockerfile and the copied docker/agent-entrypoint.sh). A stale image can fail-close an entire fleet, so this warns with the exact rebuild command before you dispatch.
delegation-reservations No delegation reservation is pinned — a reservation whose run has ended (or whose dispatch never started) still holds a fleet slot. A slot leaks when kew delegate watch dies after dispatching but before releasing; the leaked slot counts against the fleet cap forever. This warns (exit 1) only once the reservation has sat unreleased past a grace, so the healthy window between a run finishing and the watcher's next sweep is not flagged. The hint points at kew epic run <epic> (any driver tick sweeps them) or restarting the watcher. Skipped when there's no dispatch database yet; the database is opened read-only so the check never migrates it, and is skipped (not crashed) when the database is a newer schema, an older schema that predates delegation reservations, or otherwise unreadable.
model-eol Checks every resolved route and pinned reviewer model against the committed model-eol snapshot. scheduled, watch, retiring, and retired models warn with lifecycle details; missing entries are reported as feed-gap. This is advisory and never blocks dispatch.
runner-liveness When the repository has a RUNNER_TARGET Actions variable, checks the registered self-hosted runners through GitHub and warns about any that are offline. This is skipped when the variable is absent or GitHub cannot be queried.
degraded-review Reads the hash-chained adversarial-review verdicts and warns when a reviewer runner/model route has produced three or more consecutive crash verdicts — DEGRADED (advisory review) or UNPARSEABLE (blocking review, where the node is also held). The route and count point operators toward launch, credential, or sandbox diagnostics.

Each check reports one of three outcomes:

  • pass — the check ran and found no problem.
  • stale / issue — a problem was found; kew doctor exits 1 and prints the fix (for agent-image, the docker build … rebuild command).
  • skipped — the check could not run (e.g. the sandbox runtime isn't installed, the image isn't built locally, or you're not in a kew source checkout). Skipped checks are not counted as passing.

Exit codes

0 — all checks passed or were skipped. 1 — at least one issue was found.

The same agent-image staleness check also runs (as a non-blocking warning) during sandboxed dispatch, so a stale image is surfaced even if you never run kew doctor directly.