diff --git a/runbooks/agent-not-working.md b/runbooks/agent-not-working.md index 862596b..db236b4 100644 --- a/runbooks/agent-not-working.md +++ b/runbooks/agent-not-working.md @@ -17,9 +17,9 @@ curl --unix-socket "$CRUX_SOCKET" http://localhost/v1/health `/v1/health` returns `version`, `agents`, `started_at` and `uptime_seconds`, plus `background` (the in-process loops the server runs) and `hive_callback` -when configured. A `tmux` field (where tmux resolves on PATH) is proposed in -hive#17382 but has not shipped; no current server reports it, so its absence -is expected and not a problem. +when configured, and `tmux` (where tmux resolves on PATH). When tmux cannot be +found the endpoint answers 503 with `error` and `code` set, so a failing +health check can mean agents cannot start. | Observation | Meaning | Action | | --- | --- | --- | @@ -27,7 +27,7 @@ is expected and not a problem. | `uptime_seconds` keeps resetting | The supervisor is restart-looping the server | Read the server's stderr; fix the config it reports; do not just keep restarting | | `agents` lower than expected | The `--config` file defines fewer agents than you think | Check the file and `CRUX_SOCKET`: you may be talking to a different server | | `background` missing or empty on a server meant to run it | The credential and session refresh loops (`StartAgentTokenRefresh`, `StartCredentialWatchdog`, `StartCopilotSessionRefresh`, `StartTranscriptActivityRefresh`) are not running, so agent credentials will not be refreshed | The host embedding the server must set `Server.Background`; do not treat a 200 from `/v1/health` as proof they are running | -| `tmux` present but empty in `/v1/health` (only once hive#17382 ships) | tmux is missing from the server's PATH, so no agent can start | Install tmux or fix the PATH the server runs with, then restart it. Until then, check `which tmux` by hand | +| `/v1/health` returns 503 with an `error` starting with `tmux not found on PATH:` and an empty `tmux` field | tmux is missing from the server's PATH, so no agent can start | Install tmux or fix the PATH the server runs with, then restart it | | 401 / 403 | Missing or wrong bearer token | Pass the token the server was started with | ## 2. Is the hive callback reachable?