From a6461cb0ce97e262efdc48dbe79215465d7e72ca Mon Sep 17 00:00:00 2001 From: operations <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Thu, 12 Nov 2026 14:09:18 -0500 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=93=96=20runbooks:=20document=20shipp?= =?UTF-8?q?ed=20tmux=20check=20in=20/v1/health?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: operations <280983584+hivecommons-hive[bot]@users.noreply.github.com> --- runbooks/agent-not-working.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/runbooks/agent-not-working.md b/runbooks/agent-not-working.md index 862596b..abfcf04 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 `error: tmux not found on PATH` and no `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? From f676623ef73dfaa6cb6b93c5dc097dd0154b308c Mon Sep 17 00:00:00 2001 From: operations <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Thu, 12 Nov 2026 14:22:27 -0500 Subject: [PATCH 2/2] docs(runbooks): fix tmux health row for 503 case Hive-Fix-Attempt: 1/6 Signed-off-by: operations <280983584+hivecommons-hive[bot]@users.noreply.github.com> --- runbooks/agent-not-working.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/runbooks/agent-not-working.md b/runbooks/agent-not-working.md index abfcf04..db236b4 100644 --- a/runbooks/agent-not-working.md +++ b/runbooks/agent-not-working.md @@ -27,7 +27,7 @@ health check can mean agents cannot start. | `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 | -| `/v1/health` returns 503 with `error: tmux not found on PATH` and no `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 | +| `/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?