🐛 fix(crux): /v1/health 503 body names the missing tmux through api.Client

api.Client.checkStatus decodes a non-2xx body as api.Error; the tmux 503
body was a plain api.Health with no error key, so StatusError.Error()
fell back to "crux server returned HTTP 503" and the supervisor polled
to ReadyTimeout, then killed and restarted crux serve without ever
logging that tmux was the cause.

- api.Health gains error/code (omitempty) sharing api.Error's wire keys,
  so the 503 body decodes as both.
- handleHealth sets error="tmux not found on PATH: ..." and
  code=unavailable (new api.CodeUnavailable) on the 503 path; the 200
  body is unchanged.
- Tests: serve asserts the 503 body's error/code; api asserts
  Client.Health surfaces the message in the StatusError and that
  WaitReady keeps polling a 503 until ctx ends.

Hive-Fix-Attempt: 1/6
Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>

Author: hivecommons-hive[bot]

changelog.d/fixed-crux-health-tmux.md

@@ -1 +1 @@
-- Crux `GET /v1/health` now reports a `tmux` field (where tmux resolves on PATH) and answers 503, with the full health body, when tmux is missing: every agent runs in tmux, so a server without it cannot serve traffic and was reporting healthy ([hivecommons/crux#137](https://github.com/hivecommons/crux/issues/137)). Existing fields are unchanged; probes that treated any 200 as healthy now see the failure.
+- Crux `GET /v1/health` now reports a `tmux` field (where tmux resolves on PATH) and answers 503, with the full health body, when tmux is missing (the body also carries `error`/`code`, so `api.Client` callers and the supervisor see "tmux not found on PATH" rather than a bare 503): every agent runs in tmux, so a server without it cannot serve traffic and was reporting healthy ([hivecommons/crux#137](https://github.com/hivecommons/crux/issues/137)). Existing fields are unchanged; probes that treated any 200 as healthy now see the failure.

src/crux/api/api.go

@@ -108,6 +108,12 @@ type Health struct {
 	// Tmux is where tmux resolves on PATH, "" when it does not. Every agent
 	// runs inside tmux, so the route answers 503 (with this body) when empty.
 	Tmux string `json:"tmux"`
+	// Error and Code are set only on a non-2xx answer and share their wire
+	// keys with api.Error, so the 503 body also decodes as the Error that
+	// Client surfaces in a *StatusError: a caller polling health (the
+	// supervisor's WaitReady) sees "tmux not found on PATH", not a bare 503.
+	Error string `json:"error,omitempty"`
+	Code  string `json:"code,omitempty"`
 }
 
 // HiveCallback is the wire form of the callback client's status.
@@ -257,4 +263,7 @@ const (
 	// holds; the runtime does not replace definitions.
 	CodeConflict = "conflict"
 	CodeRuntime  = "runtime_error"
+	// CodeUnavailable is a server that is up but cannot serve: GET /v1/health
+	// answers 503 with it when tmux is missing from PATH.
+	CodeUnavailable = "unavailable"
 )

src/crux/api/client_test.go

@@ -512,3 +512,36 @@ func TestClientStatusTracksReachability(t *testing.T) {
 		t.Fatalf("status after success = %+v", st)
 	}
 }
+
+// A 503 health body carries error/code alongside the health fields, so the
+// client names the cause (the supervisor's WaitReady logs this error).
+func TestClientHealthUnavailableNamesCause(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", ContentTypeJSON)
+		w.WriteHeader(http.StatusServiceUnavailable)
+		_ = json.NewEncoder(w).Encode(Health{
+			Version: Version,
+			Error:   "tmux not found on PATH: exec: \"tmux\": executable file not found in $PATH",
+			Code:    CodeUnavailable,
+		})
+	}))
+	t.Cleanup(srv.Close)
+	c, err := NewClient(srv.URL, "tok")
+	if err != nil {
+		t.Fatal(err)
+	}
+	_, err = c.Health(context.Background())
+	var se *StatusError
+	if !errors.As(err, &se) || se.Status != http.StatusServiceUnavailable || se.Body.Code != CodeUnavailable {
+		t.Fatalf("status error: %+v (%v)", se, err)
+	}
+	if !strings.Contains(err.Error(), "tmux not found on PATH") {
+		t.Fatalf("error does not name tmux: %v", err)
+	}
+	// WaitReady keeps polling a 503 (it is not 401) and ends with ctx.
+	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
+	defer cancel()
+	if err := c.WaitReady(ctx, time.Millisecond); !errors.Is(err, context.DeadlineExceeded) {
+		t.Fatalf("wait ready: %v", err)
+	}
+}

src/crux/serve/health_test.go

@@ -5,6 +5,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"strings"
 	"testing"
 
 	"github.com/hivecommons/hive/crux/api"
@@ -28,6 +29,10 @@ func TestHealthTmuxMissingIs503(t *testing.T) {
 	if h.Tmux != "" || h.Version != api.Version {
 		t.Fatalf("health: %+v", h)
 	}
+	// The body is also an api.Error, so api.Client callers see the cause.
+	if h.Code != api.CodeUnavailable || !strings.Contains(h.Error, "tmux not found on PATH") {
+		t.Fatalf("health error: %+v", h)
+	}
 }
 
 func TestHealthTmuxPresentIs200(t *testing.T) {

src/crux/serve/serve.go

@@ -391,7 +391,10 @@ func (s *Server) handleHealth(w http.ResponseWriter, _ *http.Request) {
 	}
 	status := http.StatusOK
 	if path, err := tmux.LookPath(); err != nil {
+		// The body doubles as an api.Error so api.Client reports the cause.
 		status = http.StatusServiceUnavailable
+		h.Error = fmt.Sprintf("tmux not found on PATH: %v", err)
+		h.Code = api.CodeUnavailable
 	} else {
 		h.Tmux = path
 	}