feat: default telemetry to VM routing allowlist + fallback hardening

Address adversarial review notes on the control-plane fallback:

- Add "telemetry" to the default direct-VM routing subresource allowlist
  (was ["curl"] only) so the telemetry SSE stream is routed to the VM and
  can fall back to the control plane when the VM is gone.
- isBrowserGoneResponse: on a mid-stream body read error, leave the body
  in place (via MultiReader) instead of truncating it, and treat it as a
  non-marker so the live VM response is surfaced unchanged.
- Comment the body-less GET/HEAD assumption at the fallback re-issue site.
- Add regression tests: 503/504 fallback, HEAD fallback, gone header with
  wrong code (no fallback, body preserved), browser_gone body without the
  X-Kernel-Upstream header (no fallback, body preserved), and final
  control-plane body readability after a 502 fallback.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: rgarcia

browser_routing.go

@@ -47,7 +47,9 @@ func withBrowserRouteCache(cache *browserrouting.RouteCache) option.RequestOptio
 
 func browserRouteCacheFromOptions(opts []option.RequestOption) *browserrouting.RouteCache {
 	for _, opt := range opts {
-		if carrier, ok := opt.(interface{ browserRouteCache() *browserrouting.RouteCache }); ok {
+		if carrier, ok := opt.(interface {
+			browserRouteCache() *browserrouting.RouteCache
+		}); ok {
 			if cache := carrier.browserRouteCache(); cache != nil {
 				return cache
 			}
@@ -81,7 +83,7 @@ func browserRouteFromRef(ref browserrouting.Ref) (browserrouting.Route, bool) {
 func browserRoutingSubresourcesFromEnv() []string {
 	raw, ok := os.LookupEnv(browserRoutingSubresourcesEnv)
 	if !ok {
-		return []string{"curl"}
+		return []string{"curl", "telemetry"}
 	}
 	if strings.TrimSpace(raw) == "" {
 		return []string{}

browser_routing_test.go

@@ -127,8 +127,8 @@ func TestBrowserRoutingSubresourcesFromEnvDefaultsToCurl(t *testing.T) {
 		}
 		_ = os.Setenv(browserRoutingSubresourcesEnv, original)
 	})
-	if got := browserRoutingSubresourcesFromEnv(); len(got) != 1 || got[0] != "curl" {
-		t.Fatalf("expected default subresources [curl], got %#v", got)
+	if got := browserRoutingSubresourcesFromEnv(); len(got) != 2 || got[0] != "curl" || got[1] != "telemetry" {
+		t.Fatalf("expected default subresources [curl telemetry], got %#v", got)
 	}
 
 	t.Setenv(browserRoutingSubresourcesEnv, "")

lib/browserrouting/route_cache.go

@@ -142,8 +142,9 @@ func DirectVMRoutingMiddleware(cache *RouteCache, subresources []string) option.
 			}
 
 			// Restore the original control-plane target: URL/Host/Authorization
-			// and drop the VM jwt query param. A body-less GET/HEAD is safe to
-			// resend.
+			// and drop the VM jwt query param. The GET/HEAD gate in
+			// shouldFallBackToControlPlane guarantees this request is body-less, so
+			// re-issuing it without re-buffering a request body is safe.
 			snapshot.restore(req)
 
 			res, err = next(req)
@@ -260,13 +261,17 @@ func isBrowserGoneResponse(res *http.Response) bool {
 	}
 
 	body, err := io.ReadAll(res.Body)
+	if err != nil {
+		// On a mid-stream read error, leave the original body in place (it has
+		// already been partly consumed but we avoid truncating ContentLength) and
+		// treat this as "not the gone marker" so we surface the live VM response.
+		res.Body = io.NopCloser(io.MultiReader(bytes.NewReader(body), res.Body))
+		return false
+	}
 	_ = res.Body.Close()
 	// Restore the body so the response remains readable regardless of outcome.
 	res.Body = io.NopCloser(bytes.NewReader(body))
 	res.ContentLength = int64(len(body))
-	if err != nil {
-		return false
-	}
 
 	var payload struct {
 		Code string `json:"code"`

lib/browserrouting/route_cache_test.go

@@ -299,6 +299,190 @@ func TestFallbackNonRoutedRequestUntouched(t *testing.T) {
 	}
 }
 
+// TestFallback503And504ToControlPlane: 503 and 504 from a dead VM also trigger a
+// single control-plane fallback (same as 502).
+func TestFallback503And504ToControlPlane(t *testing.T) {
+	for _, status := range []int{http.StatusServiceUnavailable, http.StatusGatewayTimeout} {
+		cache := NewRouteCache()
+		cache.Store(Route{SessionID: "sess-1", BaseURL: "https://browser.example/browser/kernel", JWT: "jwt-123"})
+		middleware := DirectVMRoutingMiddleware(cache, []string{"curl"})
+
+		var calls int
+		var lastReq *http.Request
+		res, err := middleware(routedGetRequest(t), func(req *http.Request) (*http.Response, error) {
+			calls++
+			lastReq = req
+			if calls == 1 {
+				return &http.Response{
+					StatusCode: status,
+					Header:     http.Header{},
+					Body:       io.NopCloser(strings.NewReader("upstream down")),
+				}, nil
+			}
+			return &http.Response{
+				StatusCode: http.StatusOK,
+				Header:     http.Header{},
+				Body:       io.NopCloser(strings.NewReader("cp-ok")),
+			}, nil
+		})
+		if err != nil {
+			t.Fatal(err)
+		}
+		if calls != 2 {
+			t.Fatalf("status %d: expected VM attempt + CP fallback, got %d attempts", status, calls)
+		}
+		if lastReq.URL.Host != "api.example" {
+			t.Fatalf("status %d: expected fallback to control plane, got host %q", status, lastReq.URL.Host)
+		}
+		if res.StatusCode != http.StatusOK {
+			t.Fatalf("status %d: expected control-plane 200, got %d", status, res.StatusCode)
+		}
+	}
+}
+
+// TestFallbackHeadToControlPlane: HEAD is idempotent and must fall back like GET.
+func TestFallbackHeadToControlPlane(t *testing.T) {
+	cache := NewRouteCache()
+	cache.Store(Route{SessionID: "sess-1", BaseURL: "https://browser.example/browser/kernel", JWT: "jwt-123"})
+	middleware := DirectVMRoutingMiddleware(cache, []string{"curl"})
+
+	req := routedGetRequest(t)
+	req.Method = http.MethodHead
+
+	var calls int
+	var lastReq *http.Request
+	res, err := middleware(req, func(req *http.Request) (*http.Response, error) {
+		calls++
+		lastReq = req
+		if calls == 1 {
+			return &http.Response{
+				StatusCode: http.StatusBadGateway,
+				Header:     http.Header{},
+				Body:       io.NopCloser(strings.NewReader("Upstream not available")),
+			}, nil
+		}
+		return &http.Response{
+			StatusCode: http.StatusOK,
+			Header:     http.Header{},
+			Body:       io.NopCloser(strings.NewReader("")),
+		}, nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if calls != 2 {
+		t.Fatalf("expected HEAD to fall back (VM + CP), got %d attempts", calls)
+	}
+	if lastReq.URL.Host != "api.example" {
+		t.Fatalf("expected HEAD fallback to control plane, got host %q", lastReq.URL.Host)
+	}
+	if lastReq.Header.Get("Authorization") != "Bearer sk_test" {
+		t.Fatalf("expected Authorization restored on HEAD fallback, got %q", lastReq.Header.Get("Authorization"))
+	}
+	if res.StatusCode != http.StatusOK {
+		t.Fatalf("expected control-plane 200 for HEAD, got %d", res.StatusCode)
+	}
+}
+
+// TestFallbackGoneHeaderWrongCodeNoFallback: a 404 with the X-Kernel-Upstream:
+// gone header but a JSON code that is NOT "browser_gone" must NOT fall back, and
+// its body must remain readable on the returned response.
+func TestFallbackGoneHeaderWrongCodeNoFallback(t *testing.T) {
+	cache := NewRouteCache()
+	cache.Store(Route{SessionID: "sess-1", BaseURL: "https://browser.example/browser/kernel", JWT: "jwt-123"})
+	middleware := DirectVMRoutingMiddleware(cache, []string{"curl"})
+
+	const bodyText = `{"code":"not_found","message":"nope"}`
+	var calls int
+	res, err := middleware(routedGetRequest(t), func(req *http.Request) (*http.Response, error) {
+		calls++
+		return &http.Response{
+			StatusCode: http.StatusNotFound,
+			Header: http.Header{
+				"Content-Type":      []string{"application/json"},
+				"X-Kernel-Upstream": []string{"gone"},
+			},
+			Body: io.NopCloser(strings.NewReader(bodyText)),
+		}, nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if calls != 1 {
+		t.Fatalf("expected no fallback when code != browser_gone, got %d attempts", calls)
+	}
+	body, _ := io.ReadAll(res.Body)
+	if string(body) != bodyText {
+		t.Fatalf("expected body preserved after non-triggering gone sniff, got %q", string(body))
+	}
+}
+
+// TestFallbackGoneBodyWithoutHeaderNoFallback: a browser_gone JSON body WITHOUT
+// the X-Kernel-Upstream: gone header must NOT fall back (header is checked before
+// the body, so the body is never even sniffed).
+func TestFallbackGoneBodyWithoutHeaderNoFallback(t *testing.T) {
+	cache := NewRouteCache()
+	cache.Store(Route{SessionID: "sess-1", BaseURL: "https://browser.example/browser/kernel", JWT: "jwt-123"})
+	middleware := DirectVMRoutingMiddleware(cache, []string{"curl"})
+
+	const bodyText = `{"code":"browser_gone","message":"browser not found"}`
+	var calls int
+	res, err := middleware(routedGetRequest(t), func(req *http.Request) (*http.Response, error) {
+		calls++
+		return &http.Response{
+			StatusCode: http.StatusNotFound,
+			Header:     http.Header{"Content-Type": []string{"application/json"}},
+			Body:       io.NopCloser(strings.NewReader(bodyText)),
+		}, nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if calls != 1 {
+		t.Fatalf("expected no fallback without X-Kernel-Upstream header, got %d attempts", calls)
+	}
+	body, _ := io.ReadAll(res.Body)
+	if string(body) != bodyText {
+		t.Fatalf("expected body untouched (header gate hit first), got %q", string(body))
+	}
+}
+
+// TestFallbackFinalCPBodyReadable: after a 502 fallback, the control-plane
+// response body must be fully readable by downstream consumers.
+func TestFallbackFinalCPBodyReadable(t *testing.T) {
+	cache := NewRouteCache()
+	cache.Store(Route{SessionID: "sess-1", BaseURL: "https://browser.example/browser/kernel", JWT: "jwt-123"})
+	middleware := DirectVMRoutingMiddleware(cache, []string{"curl"})
+
+	const cpBody = `{"code":"browser_not_found"}`
+	var calls int
+	res, err := middleware(routedGetRequest(t), func(req *http.Request) (*http.Response, error) {
+		calls++
+		if calls == 1 {
+			return &http.Response{
+				StatusCode: http.StatusBadGateway,
+				Header:     http.Header{},
+				Body:       io.NopCloser(strings.NewReader("Upstream not available")),
+			}, nil
+		}
+		return &http.Response{
+			StatusCode: http.StatusNotFound,
+			Header:     http.Header{"Content-Type": []string{"application/json"}},
+			Body:       io.NopCloser(strings.NewReader(cpBody)),
+		}, nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	body, readErr := io.ReadAll(res.Body)
+	if readErr != nil {
+		t.Fatalf("expected readable CP body, got error %v", readErr)
+	}
+	if string(body) != cpBody {
+		t.Fatalf("expected CP body %q, got %q", cpBody, string(body))
+	}
+}
+
 func TestDirectVMRoutingMiddlewareClearsStaleRawPath(t *testing.T) {
 	cache := NewRouteCache()
 	cache.Store(Route{