kew doctor¶
Run local environment diagnostics and surface known issues that cause silent failures or wasted dispatch spend.
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. |
Each check reports one of three outcomes:
- pass — the check ran and found no problem.
- stale / issue — a problem was found;
kew doctorexits1and prints the fix (foragent-image, thedocker 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.