fix(exec): fall back to queue and poll when the relay has no run endpoint (2026.8.28.0-6244)

handoff exec went straight to the one-shot run endpoint, so it failed against
any relay that had not been updated yet. It now retries through the queue and
result endpoints, which have been there all along, and reshapes the reply into
the same envelope so callers see one contract either way.

An unknown session token also answers 404, so that case is told apart from a
missing route and reported as-is rather than being retried.

Author: RealWhyKnot

cmd/exec.go

@@ -78,8 +78,7 @@ func Exec(args []string) int {
 		return execExitUsage
 	}
 
-	url := fmt.Sprintf("%s/api/sessions/%s/run?wait_ms=%d", opts.Relay, token, timeout.Milliseconds())
-	body, status, err := postJSON(ctx, url, payload)
+	body, status, err := runCommand(ctx, opts.Relay, token, payload, timeout)
 	if err != nil {
 		fmt.Fprintln(os.Stderr, "request failed:", err)
 		return 1
@@ -237,3 +236,124 @@ func viewTokenFrom(s string) string {
 	}
 	return strings.Trim(s, "/")
 }
+
+// runCommand prefers the relay's one-shot endpoint and falls back to queueing
+// plus a result poll. A relay that predates /run answers 404, and a client that
+// gave up there would be useless against any relay not yet carrying it.
+func runCommand(ctx context.Context, relayBase, token string, payload map[string]interface{}, timeout time.Duration) ([]byte, int, error) {
+	runURL := fmt.Sprintf("%s/api/sessions/%s/run?wait_ms=%d", relayBase, token, timeout.Milliseconds())
+	body, status, err := postJSON(ctx, runURL, payload)
+	if err != nil {
+		return nil, 0, err
+	}
+	if status != http.StatusNotFound {
+		return body, status, nil
+	}
+
+	// A 404 from an unknown session names the token; a 404 from a relay with no
+	// /run route does not, and that is the case worth retrying.
+	var probe map[string]interface{}
+	if json.Unmarshal(body, &probe) == nil {
+		if msg, _ := probe["error"].(string); strings.Contains(msg, "view token") {
+			return body, status, nil
+		}
+	}
+	return queueAndAwait(ctx, relayBase, token, payload, timeout)
+}
+
+func queueAndAwait(ctx context.Context, relayBase, token string, payload map[string]interface{}, timeout time.Duration) ([]byte, int, error) {
+	ackBody, ackStatus, err := postJSON(ctx, fmt.Sprintf("%s/api/sessions/%s/cmd", relayBase, token), payload)
+	if err != nil {
+		return nil, 0, err
+	}
+	if ackStatus != http.StatusOK {
+		return ackBody, ackStatus, nil
+	}
+
+	var ack struct {
+		CommandID string `json:"command_id"`
+	}
+	if err := json.Unmarshal(ackBody, &ack); err != nil || ack.CommandID == "" {
+		return ackBody, ackStatus, nil
+	}
+
+	kind, _ := payload["kind"].(string)
+	deadline := time.Now().Add(timeout)
+	resultURL := fmt.Sprintf("%s/api/sessions/%s/cmd/%s", relayBase, token, ack.CommandID)
+
+	for time.Now().Before(deadline) {
+		wait := time.Until(deadline)
+		if wait > 25*time.Second {
+			wait = 25 * time.Second
+		}
+		req, err := http.NewRequestWithContext(ctx, http.MethodGet,
+			fmt.Sprintf("%s?wait_ms=%d", resultURL, wait.Milliseconds()), nil)
+		if err != nil {
+			return nil, 0, err
+		}
+		resp, err := http.DefaultClient.Do(req)
+		if err != nil {
+			return nil, 0, err
+		}
+		raw, readErr := io.ReadAll(resp.Body)
+		resp.Body.Close()
+		if readErr != nil {
+			return nil, 0, readErr
+		}
+
+		var got map[string]interface{}
+		_ = json.Unmarshal(raw, &got)
+
+		switch resp.StatusCode {
+		case http.StatusOK:
+			// An older relay returns the raw terminal event; reshape it into
+			// the same envelope /run would have produced.
+			if inner, isMap := got["payload"].(map[string]interface{}); isMap {
+				return reshapeResult(inner, kind, ack.CommandID), http.StatusOK, nil
+			}
+			if got["status"] == "pending" {
+				continue
+			}
+			return raw, http.StatusOK, nil
+		case http.StatusGone:
+			return raw, http.StatusGone, nil
+		case http.StatusNotFound:
+			continue
+		default:
+			return raw, resp.StatusCode, nil
+		}
+	}
+
+	pending, _ := json.Marshal(map[string]interface{}{
+		"command_id": ack.CommandID,
+		"kind":       kind,
+		"status":     "pending",
+		"ok":         false,
+		"result_url": fmt.Sprintf("/api/sessions/%s/cmd/%s", token, ack.CommandID),
+	})
+	return pending, http.StatusAccepted, nil
+}
+
+func reshapeResult(inner map[string]interface{}, kind, commandID string) []byte {
+	ok, _ := inner["ok"].(bool)
+	out := map[string]interface{}{
+		"command_id": commandID,
+		"kind":       kind,
+		"ok":         ok,
+		"status":     "error",
+		"result":     inner["result"],
+		"error":      inner["error"],
+		"elapsed_ms": inner["elapsed_ms"],
+	}
+	if ok {
+		out["status"] = "ok"
+	}
+	if detail, present := inner["detail"]; present {
+		out["detail"] = detail
+	}
+	enc, err := json.Marshal(out)
+	if err != nil {
+		return []byte(`{"ok":false,"error":"could not read the relay's result"}`)
+	}
+	return enc
+}

cmd/exec_test.go

@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"net/http"
 	"net/http/httptest"
+	"strings"
 	"testing"
 )
 
@@ -139,3 +140,78 @@ func TestExecRequiresAKind(t *testing.T) {
 		t.Fatalf("exit = %d, want a usage error", code)
 	}
 }
+
+func TestExecFallsBackWhenRelayHasNoRunEndpoint(t *testing.T) {
+	// A relay that predates /run answers 404. Giving up there would make a new
+	// client useless against a relay that has not been deployed yet.
+	var sawCmd, sawResult bool
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		switch {
+		case strings.HasSuffix(r.URL.Path, "/run"):
+			w.WriteHeader(http.StatusNotFound)
+			_, _ = w.Write([]byte(`{"error":"Not Found"}`))
+		case strings.HasSuffix(r.URL.Path, "/cmd"):
+			sawCmd = true
+			_, _ = w.Write([]byte(`{"command_id":"c_fallback"}`))
+		case strings.Contains(r.URL.Path, "/cmd/c_fallback"):
+			sawResult = true
+			_, _ = w.Write([]byte(`{"id":"c_fallback","payload":{"id":"c_fallback","ok":true,"result":{"up":1},"elapsed_ms":7}}`))
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	}))
+	defer srv.Close()
+
+	t.Setenv("HANDOFF_CONFIG", "")
+	if code := Exec([]string{"--relay", srv.URL, "--json", "n1_token", "sys.uptime"}); code != 0 {
+		t.Fatalf("Exec exit = %d, want 0 via the fallback", code)
+	}
+	if !sawCmd || !sawResult {
+		t.Fatalf("fallback path not used: cmd=%v result=%v", sawCmd, sawResult)
+	}
+}
+
+func TestExecDoesNotFallBackForAnUnknownSession(t *testing.T) {
+	// An unknown token also 404s. Retrying that against /cmd would turn a clear
+	// error into a second confusing one.
+	var cmdCalls int
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if strings.HasSuffix(r.URL.Path, "/cmd") {
+			cmdCalls++
+		}
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusNotFound)
+		_, _ = w.Write([]byte(`{"error":"unknown view token"}`))
+	}))
+	defer srv.Close()
+
+	t.Setenv("HANDOFF_CONFIG", "")
+	if code := Exec([]string{"--relay", srv.URL, "--json", "n1_token", "sys.uptime"}); code != 1 {
+		t.Fatalf("Exec exit = %d, want 1", code)
+	}
+	if cmdCalls != 0 {
+		t.Fatalf("fell back %d times for an unknown session", cmdCalls)
+	}
+}
+
+func TestExecFallbackReportsHostFailure(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		switch {
+		case strings.HasSuffix(r.URL.Path, "/run"):
+			w.WriteHeader(http.StatusNotFound)
+			_, _ = w.Write([]byte(`{"error":"Not Found"}`))
+		case strings.HasSuffix(r.URL.Path, "/cmd"):
+			_, _ = w.Write([]byte(`{"command_id":"c_bad"}`))
+		default:
+			_, _ = w.Write([]byte(`{"id":"c_bad","payload":{"id":"c_bad","ok":false,"error":"boom"}}`))
+		}
+	}))
+	defer srv.Close()
+
+	t.Setenv("HANDOFF_CONFIG", "")
+	if code := Exec([]string{"--relay", srv.URL, "--json", "n1_token", "ps.exec"}); code != execExitFailed {
+		t.Fatalf("Exec exit = %d, want %d", code, execExitFailed)
+	}
+}