fix(admin): forward session cookie on KeyViz fan-out so peers do not 401 (#692)

## Summary

**Hotfix for the screenshot a user shared after enabling fan-out** — the
heatmap collapsed to "1 of 6 nodes responded" with every peer returning
`401 missing session cookie`.

**Root cause**: PR #686 shipped fan-out with the design assumption (#685
§3) that peers would accept anonymous calls on a private network. But
the receiving side runs the same `SessionAuth` middleware as the browser
path, so anonymous fan-out calls are rejected with 401. The "anonymous
on a private network" framing was wrong: the implementation didn't put a
bypass on the peer side, so anonymous calls never went through
end-to-end.

**Fix**: forward the inbound user's cookies on every peer call. Cluster
nodes already share `--adminSessionSigningKey` for HA, so a cookie
minted on node A is verifiable on node B — no new infrastructure needed.

## What changed

- `KeyVizFanout.Run` gains a `cookies []*http.Cookie` parameter; nil
preserves the legacy behaviour for tests / future non-browser callers.
- `KeyVizHandler` passes `r.Cookies()` so a SPA poll forwards
`admin_session` (and `admin_csrf`, harmless on a GET) transparently.
- `TestKeyVizFanoutRunForwardsCookies` pins that both cookies reach the
peer verbatim.
- Design doc §3 rewritten: documents the cookie-forwarding scheme + the
operator-trust assumption that `--keyvizFanoutNodes` points at trusted
hosts only. Phase 2-C+ will replace cookie forwarding with a dedicated
inter-node token to decouple browser-session expiry from inter-node call
validity.

## Five-lens self-review

1. **Data loss** — n/a; auth path change.
2. **Concurrency / distributed** — Cookies are passed by reference into
per-peer goroutines but the slice is read-only inside `fetchPeer` (each
goroutine `req.AddCookie`s independently). No shared mutation.
3. **Performance** — Adds N `req.AddCookie` calls per fan-out request.
Trivial.
4. **Data consistency** — Auth-only change; merge semantics unchanged.
5. **Test coverage** — New `TestKeyVizFanoutRunForwardsCookies` asserts
both cookies reach the peer with the original values. Existing fan-out
tests pass `nil` and continue to exercise the unauthenticated path the
existing code handled (peer 401s, request reports `ok=false`).

## Test plan

- [x] `go test -race -count=1 ./internal/admin/...` — clean
- [x] `golangci-lint run ./internal/admin/...` — clean
- [ ] Manual: 6-node cluster with shared
`ELASTICKV_ADMIN_SESSION_SIGNING_KEY`, `--keyvizFanoutNodes` set on
every node. Heatmap should now show "6 of 6 nodes" instead of "1 of 6".

## Trust / threat model note

Cookie forwarding is safe when (a) every peer is operator-configured and
trusted, and (b) the network is private. **Do NOT point
`--keyvizFanoutNodes` at an untrusted host** — the user's admin session
would be replayed there. The design doc §3 update is explicit about
this. Phase 2-C+ removes this footgun by switching to a dedicated
inter-node token.

Closes the production-impacting symptom from screenshot review.

Author: bootjp

docs/design/2026_04_27_proposed_keyviz_cluster_fanout.md

@@ -132,22 +132,45 @@ elastickv \
   network); the HTTP client uses `http://`. A follow-up will
   introduce `--keyvizFanoutTLS` once the rest of the admin path
   has TLS too.
-- **Auth (Phase 2-C MVP)**: the fan-out path is anonymous — the
-  aggregator issues unauthenticated GETs to peers. This is only
-  acceptable on a fully-private intra-cluster network, which is
-  the contract `--keyvizFanoutNodes` documents. **Do NOT enable
-  fan-out across an untrusted network until Phase 2-C+ ships
-  proper auth.** Per-call timeout: 2 s default, override via
-  `--keyvizFanoutTimeout`.
-- **Auth (Phase 2-C+)**: a follow-up extends the fan-out path with
-  a short-lived signed token derived from the existing admin
-  session-signing key (`ELASTICKV_ADMIN_SESSION_SIGNING_KEY`).
-  Pre-shared inter-node token, NOT a replay of the browser's
-  session cookie — re-using the cookie would couple browser session
-  TTL to inter-node call validity, and a compromised browser
-  session would gain peer-call authority. The two paths are
-  intentionally distinct. The earlier draft of this section
-  conflated them; this paragraph supersedes it.
+- **Auth (Phase 2-C MVP)**: the aggregator forwards a whitelist of
+  the inbound user's cookies (`admin_session` + `admin_csrf` only)
+  on every peer call. The peer's `SessionAuth` middleware verifies
+  `admin_session` against its own `--adminSessionSigningKey`;
+  cluster nodes already share that key for HA, so a cookie minted
+  on node A is verifiable on node B without any new infrastructure.
+  Unrelated cookies the browser may carry (analytics, feature
+  flags, other-app sessions on the same domain) are dropped at the
+  fan-out boundary so they are not leaked across the internal
+  network (Gemini security-medium on PR #692).
+- **Recursion guard**: peer requests carry an `X-Admin-Fanout-Peer`
+  header. The receiving handler short-circuits its own fan-out
+  when this header is set; without the guard, a symmetric
+  configuration (every node lists every other node) would generate
+  O(N²) HTTP calls per browser poll as each peer recursively
+  fanned out. (Claude bot P1 on PR #692.)
+  - The earlier draft of this paragraph said "anonymous on a
+    private network" — that was wrong: the receiving side enforces
+    session auth, so anonymous calls are rejected with 401 and the
+    cluster heatmap collapses to "1 of N nodes responded". The
+    cookie-forwarding scheme above is what actually works.
+  - **Trust model**: forwarding a session cookie to peers is safe
+    when (a) every peer is operator-configured and trusted, and
+    (b) the network is private (cookies are HttpOnly but ride
+    plaintext HTTP for now). `--keyvizFanoutNodes` is the
+    operator's explicit trust list. **Do NOT point
+    `--keyvizFanoutNodes` at an untrusted host** — the user's
+    admin session would be replayed there.
+  - Per-call timeout: 2 s default, override via
+    `--keyvizFanoutTimeout`.
+- **Auth (Phase 2-C+)**: a follow-up replaces cookie forwarding
+  with a short-lived **inter-node** token derived from
+  `ELASTICKV_ADMIN_SESSION_SIGNING_KEY`. Pre-shared, NOT a replay
+  of the browser cookie — re-using the cookie couples browser
+  session TTL to inter-node call validity, and a compromised
+  browser session gains peer-call authority. The follow-up
+  decouples the two paths so the inter-node call survives a
+  browser-session expiry and a compromised cookie doesn't extend
+  laterally.
 
 ## 4. Merge rules
 

internal/admin/keyviz_fanout.go

@@ -34,6 +34,14 @@ const keyVizFanoutDefaultTimeout = 2 * time.Second
 // misbehaving peer flood operator logs.
 const keyVizPeerErrorBodyLimit = 512
 
+// keyVizFanoutPeerHeader marks a request as originating from another
+// node's fan-out aggregator. The receiving handler skips its own
+// fan-out step when this header is set, breaking the
+// every-node-fans-to-every-node recursion that would otherwise turn
+// a single browser poll into O(N²) peer HTTP calls in a symmetric
+// cluster (Claude bot P1 on PR #692).
+const keyVizFanoutPeerHeader = "X-Admin-Fanout-Peer"
+
 // keyVizPeerResponseBodyLimit caps the JSON body we are willing to
 // decode from a peer. A misbehaving or compromised peer that streams
 // gigabytes back at us would otherwise pin a goroutine on
@@ -190,6 +198,25 @@ func (f *KeyVizFanout) WithTimeout(d time.Duration) *KeyVizFanout {
 	return f
 }
 
+// attachAdminCookies forwards only the admin session and CSRF
+// cookies to a peer request. We whitelist rather than passing every
+// inbound cookie through: a logged-in operator may have unrelated
+// cookies for other services on the same domain (analytics, feature
+// flags, dev-tooling sessions), and the fan-out should not blast
+// those across the cluster's internal network. The peer's
+// SessionAuth middleware only inspects admin_session, and the CSRF
+// double-submit cookie pairs with the X-Admin-CSRF header (which
+// fan-out doesn't send because all peer calls are GETs); the cookie
+// is forwarded for parity with browser-issued requests but not
+// load-bearing. (Gemini security-medium on PR #692.)
+func attachAdminCookies(req *http.Request, cookies []*http.Cookie) {
+	for _, c := range cookies {
+		if c.Name == sessionCookieName || c.Name == csrfCookieName {
+			req.AddCookie(c)
+		}
+	}
+}
+
 // peerResult is the per-peer outcome the goroutine pool collects
 // before the synchronous merge phase. Either matrix is non-nil or
 // err is non-nil; never both.
@@ -205,9 +232,17 @@ type peerResult struct {
 // cluster (peers empty) Run returns local with a Fanout block that
 // reports Expected=1, Responded=1.
 //
+// cookies are attached to every peer request so the receiving node's
+// SessionAuth middleware sees a valid admin session. Production
+// passes the inbound request's cookies; nil disables cookie
+// forwarding (peers will 401 unless they have their own bypass).
+// All cluster nodes must share the same --adminSessionSigningKey for
+// the cookie minted by node A to be verifiable on node B; the
+// existing HA setup already requires this.
+//
 // Run never returns an error: peer-level failures surface in the
 // FanoutResult; aggregation is best-effort.
-func (f *KeyVizFanout) Run(ctx context.Context, params keyVizParams, local KeyVizMatrix) KeyVizMatrix {
+func (f *KeyVizFanout) Run(ctx context.Context, params keyVizParams, local KeyVizMatrix, cookies []*http.Cookie) KeyVizMatrix {
 	if f == nil || len(f.peers) == 0 {
 		merged := local
 		merged.Fanout = &FanoutResult{
@@ -218,7 +253,7 @@ func (f *KeyVizFanout) Run(ctx context.Context, params keyVizParams, local KeyVi
 		return merged
 	}
 
-	results := f.fetchPeersParallel(ctx, params)
+	results := f.fetchPeersParallel(ctx, params, cookies)
 
 	matrices := []KeyVizMatrix{local}
 	statuses := []FanoutNodeStatus{{Node: f.selfName(), OK: true}}
@@ -260,7 +295,7 @@ func countOK(statuses []FanoutNodeStatus) int {
 	return n
 }
 
-func (f *KeyVizFanout) fetchPeersParallel(ctx context.Context, params keyVizParams) []peerResult {
+func (f *KeyVizFanout) fetchPeersParallel(ctx context.Context, params keyVizParams, cookies []*http.Cookie) []peerResult {
 	// Cap per-peer wall time so a single slow node cannot hold the
 	// SPA poll open beyond the configured timeout. The parent
 	// context is preserved as the cancellation root so an early
@@ -274,15 +309,15 @@ func (f *KeyVizFanout) fetchPeersParallel(ctx context.Context, params keyVizPara
 		wg.Add(1)
 		go func(i int, peer string) {
 			defer wg.Done()
-			matrix, err := f.fetchPeer(callCtx, peer, params)
+			matrix, err := f.fetchPeer(callCtx, peer, params, cookies)
 			results[i] = peerResult{node: peer, matrix: matrix, err: err}
 		}(i, peer)
 	}
 	wg.Wait()
 	return results
 }
 
-func (f *KeyVizFanout) fetchPeer(ctx context.Context, peer string, params keyVizParams) (*KeyVizMatrix, error) {
+func (f *KeyVizFanout) fetchPeer(ctx context.Context, peer string, params keyVizParams, cookies []*http.Cookie) (*KeyVizMatrix, error) {
 	target, err := buildKeyVizPeerURL(peer, params)
 	if err != nil {
 		return nil, pkgerrors.Wrap(err, "build peer url")
@@ -292,6 +327,14 @@ func (f *KeyVizFanout) fetchPeer(ctx context.Context, peer string, params keyViz
 		return nil, pkgerrors.Wrap(err, "new request")
 	}
 	req.Header.Set("Accept", "application/json")
+	// Mark this request as a peer fan-out call so the receiving
+	// handler does not recursively fan out to every other peer —
+	// without this header, a symmetric cluster (every node lists
+	// every other node) generates O(N²) peer HTTP calls per
+	// browser poll. The check on the receiving side is in
+	// KeyVizHandler.ServeHTTP. (Claude bot P1 on PR #692.)
+	req.Header.Set(keyVizFanoutPeerHeader, "1")
+	attachAdminCookies(req, cookies)
 	resp, err := f.client.Do(req)
 	if err != nil {
 		return nil, pkgerrors.Wrap(err, "peer request")

internal/admin/keyviz_fanout_test.go

@@ -6,6 +6,7 @@ import (
 	"net/http"
 	"net/http/httptest"
 	"strings"
+	"sync"
 	"testing"
 	"time"
 
@@ -152,6 +153,71 @@ func TestMergeKeyVizMatricesDistinctRowsPreserveOrder(t *testing.T) {
 	require.Equal(t, "route:9", merged.Rows[2].BucketID)
 }
 
+// TestKeyVizFanoutRunForwardsCookies pins the auth bug fix that
+// brought all peers up from 401 to 200: the inbound user's session
+// cookies are forwarded on every peer request so the receiving
+// node's SessionAuth middleware sees a valid principal. Without
+// this, peers reject every fan-out call with 401 missing-session-
+// cookie and the cluster heatmap collapses to "1 of N nodes
+// responded".
+//
+// Pins both halves of the cookie contract:
+//   - admin_session and admin_csrf are forwarded with their values
+//     verbatim.
+//   - Unrelated cookies present on the inbound request are
+//     **dropped** rather than leaked to peer nodes (Gemini
+//     security-medium on PR #692).
+//   - The peer call carries the X-Admin-Fanout-Peer header so the
+//     receiving handler can short-circuit its own fan-out (Claude
+//     bot P1 on PR #692; the receiving check is in
+//     KeyVizHandler.ServeHTTP and is exercised by
+//     TestKeyVizHandlerSkipsFanoutForPeerCall in
+//     keyviz_handler_test.go).
+func TestKeyVizFanoutRunForwardsCookies(t *testing.T) {
+	t.Parallel()
+	var seenRequests []*http.Request
+	var seenMu sync.Mutex
+	peer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if !strings.HasSuffix(r.URL.Path, "/admin/api/v1/keyviz/matrix") {
+			http.NotFound(w, r)
+			return
+		}
+		seenMu.Lock()
+		seenRequests = append(seenRequests, r.Clone(context.Background()))
+		seenMu.Unlock()
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		_ = json.NewEncoder(w).Encode(KeyVizMatrix{Series: keyVizSeriesReads})
+	}))
+	defer peer.Close()
+
+	f := NewKeyVizFanout("self:8080", []string{peer.URL}).WithHTTPClient(peer.Client())
+	cookies := []*http.Cookie{
+		{Name: "admin_session", Value: "session-token-abc"},
+		{Name: "admin_csrf", Value: "csrf-token-def"},
+		{Name: "unrelated_app_session", Value: "should-not-leak"},
+	}
+	merged := f.Run(context.Background(), keyVizParams{series: keyVizSeriesReads, rows: 1024}, KeyVizMatrix{Series: keyVizSeriesReads}, cookies)
+	require.NotNil(t, merged.Fanout, "fan-out result must be present")
+	require.Len(t, merged.Fanout.Nodes, 2, "self + 1 peer = 2 nodes (Claude bot P2 on PR #692)")
+	require.True(t, merged.Fanout.Nodes[1].OK)
+
+	seenMu.Lock()
+	defer seenMu.Unlock()
+	require.Len(t, seenRequests, 1)
+	got := seenRequests[0].Cookies()
+	names := make(map[string]string, len(got))
+	for _, c := range got {
+		names[c.Name] = c.Value
+	}
+	require.Equal(t, "session-token-abc", names["admin_session"], "session cookie must be forwarded verbatim")
+	require.Equal(t, "csrf-token-def", names["admin_csrf"], "csrf cookie forwarded; harmless on a GET but kept for parity")
+	require.NotContains(t, names, "unrelated_app_session",
+		"unrelated cookies must be dropped; only admin_session/admin_csrf are whitelisted")
+	require.Equal(t, "1", seenRequests[0].Header.Get(keyVizFanoutPeerHeader),
+		"peer marker header must be set so the receiver short-circuits its own fan-out")
+}
+
 // TestKeyVizFanoutRunSinglePeerOK exercises the end-to-end happy
 // path: one peer responds with a parseable matrix; the aggregator
 // merges it with the local view and reports both nodes ok.
@@ -176,7 +242,7 @@ func TestKeyVizFanoutRunSinglePeerOK(t *testing.T) {
 		},
 	}
 
-	merged := f.Run(context.Background(), keyVizParams{series: keyVizSeriesReads, rows: 1024}, local)
+	merged := f.Run(context.Background(), keyVizParams{series: keyVizSeriesReads, rows: 1024}, local, nil)
 	require.Equal(t, []uint64{10}, merged.Rows[0].Values, "reads must sum across local + peer")
 	require.NotNil(t, merged.Fanout)
 	require.Equal(t, 2, merged.Fanout.Expected)
@@ -209,7 +275,7 @@ func TestKeyVizFanoutRunPeerHTTPError(t *testing.T) {
 		},
 	}
 
-	merged := f.Run(context.Background(), keyVizParams{series: keyVizSeriesReads, rows: 1024}, local)
+	merged := f.Run(context.Background(), keyVizParams{series: keyVizSeriesReads, rows: 1024}, local, nil)
 	require.Equal(t, []uint64{3}, merged.Rows[0].Values, "5xx peer must not perturb local counts")
 	require.NotNil(t, merged.Fanout)
 	require.Equal(t, 2, merged.Fanout.Expected)
@@ -238,7 +304,7 @@ func TestKeyVizFanoutRunPeerTimeout(t *testing.T) {
 		WithTimeout(50 * time.Millisecond)
 
 	start := time.Now()
-	merged := f.Run(context.Background(), keyVizParams{series: keyVizSeriesReads, rows: 1024}, KeyVizMatrix{Series: keyVizSeriesReads})
+	merged := f.Run(context.Background(), keyVizParams{series: keyVizSeriesReads, rows: 1024}, KeyVizMatrix{Series: keyVizSeriesReads}, nil)
 	require.Less(t, time.Since(start), 1*time.Second, "fan-out must not wait beyond its per-peer timeout")
 	require.NotNil(t, merged.Fanout)
 	require.Equal(t, 1, merged.Fanout.Responded)
@@ -258,7 +324,7 @@ func TestKeyVizFanoutRunNoPeers(t *testing.T) {
 			{BucketID: "route:1", Values: []uint64{99}},
 		},
 	}
-	merged := f.Run(context.Background(), keyVizParams{series: keyVizSeriesWrites, rows: 1024}, local)
+	merged := f.Run(context.Background(), keyVizParams{series: keyVizSeriesWrites, rows: 1024}, local, nil)
 	require.Equal(t, []uint64{99}, merged.Rows[0].Values)
 	require.Equal(t, 1, merged.Fanout.Expected)
 	require.Equal(t, 1, merged.Fanout.Responded)
@@ -322,7 +388,7 @@ func TestKeyVizFanoutRunPeerOrder(t *testing.T) {
 	defer second.Close()
 
 	f := NewKeyVizFanout("self:8080", []string{first.URL, second.URL}).WithHTTPClient(first.Client())
-	merged := f.Run(context.Background(), keyVizParams{series: keyVizSeriesReads, rows: 1024}, matrix)
+	merged := f.Run(context.Background(), keyVizParams{series: keyVizSeriesReads, rows: 1024}, matrix, nil)
 	require.Equal(t, []FanoutNodeStatus{
 		{Node: "self:8080", OK: true},
 		{Node: first.URL, OK: true},
@@ -369,7 +435,7 @@ func TestKeyVizFanoutRunPeerExceedsBodyLimit(t *testing.T) {
 		WithResponseBodyLimit(testCap)
 
 	start := time.Now()
-	merged := f.Run(context.Background(), keyVizParams{series: keyVizSeriesReads, rows: 1024}, KeyVizMatrix{Series: keyVizSeriesReads})
+	merged := f.Run(context.Background(), keyVizParams{series: keyVizSeriesReads, rows: 1024}, KeyVizMatrix{Series: keyVizSeriesReads}, nil)
 	require.Less(t, time.Since(start), 5*time.Second, "decode must respect the size cap and complete promptly")
 	require.NotNil(t, merged.Fanout)
 	require.Equal(t, 2, merged.Fanout.Expected)
@@ -416,7 +482,7 @@ func TestKeyVizFanoutRunPeerNearCapSucceedsWithWarning(t *testing.T) {
 		WithHTTPClient(peer.Client()).
 		WithResponseBodyLimit(testCap)
 
-	merged := f.Run(context.Background(), keyVizParams{series: keyVizSeriesReads, rows: 1024}, KeyVizMatrix{Series: keyVizSeriesReads})
+	merged := f.Run(context.Background(), keyVizParams{series: keyVizSeriesReads, rows: 1024}, KeyVizMatrix{Series: keyVizSeriesReads}, nil)
 	require.NotNil(t, merged.Fanout)
 	require.Len(t, merged.Fanout.Nodes, 2)
 	require.True(t, merged.Fanout.Nodes[0].OK, "self always reports ok")
@@ -458,7 +524,7 @@ func TestKeyVizFanoutRunPeerOverlargeBody(t *testing.T) {
 	f := NewKeyVizFanout("self:8080", []string{peer.URL}).WithHTTPClient(peer.Client())
 
 	start := time.Now()
-	merged := f.Run(context.Background(), keyVizParams{series: keyVizSeriesReads, rows: 1024}, KeyVizMatrix{Series: keyVizSeriesReads})
+	merged := f.Run(context.Background(), keyVizParams{series: keyVizSeriesReads, rows: 1024}, KeyVizMatrix{Series: keyVizSeriesReads}, nil)
 	require.Less(t, time.Since(start), 5*time.Second, "decode must respect the size cap and complete promptly")
 	require.NotNil(t, merged.Fanout)
 	require.True(t, merged.Fanout.Nodes[1].OK, "in-cap response must succeed; cap is 64 MiB and the synthetic body is well under that")

internal/admin/keyviz_handler.go

@@ -177,8 +177,18 @@ func (h *KeyVizHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	cols := h.source.Snapshot(params.from, params.to)
 	matrix := pivotKeyVizColumns(cols, params.series, params.rows)
 	matrix.GeneratedAt = h.now()
-	if h.fanout != nil {
-		matrix = h.fanout.Run(r.Context(), params, matrix)
+	if h.fanout != nil && r.Header.Get(keyVizFanoutPeerHeader) == "" {
+		// Forward the inbound user's cookies so the peer's SessionAuth
+		// middleware sees a valid principal. Cluster nodes share
+		// --adminSessionSigningKey for HA, so a cookie minted on this
+		// node verifies on any peer. nil cookies make peers 401,
+		// which surfaces as ok=false in the per-node status.
+		//
+		// Skip the fan-out when keyVizFanoutPeerHeader is present:
+		// the request is itself a peer call and recursing would
+		// generate O(N²) HTTP calls per browser poll on a symmetric
+		// cluster (Claude bot P1 on PR #692).
+		matrix = h.fanout.Run(r.Context(), params, matrix, r.Cookies())
 	}
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 	w.Header().Set("Cache-Control", "no-store")

internal/admin/keyviz_handler_test.go

@@ -450,3 +450,51 @@ func TestKeyVizHandlerAggregateFallbackWhenTotalZero(t *testing.T) {
 	require.True(t, matrix.Rows[0].Aggregate)
 	require.Equal(t, uint64(2), matrix.Rows[0].RouteCount, "fallback to len(MemberRoutes)")
 }
+
+// TestKeyVizHandlerSkipsFanoutForPeerCall pins the recursion guard
+// added on PR #692 (Claude bot P1): when the inbound request carries
+// the X-Admin-Fanout-Peer header, the handler must serve the local
+// view without invoking its own KeyVizFanout — otherwise a
+// symmetric cluster (every node lists every peer) would generate
+// O(N²) HTTP calls per browser poll. The test uses a recording
+// fanout that fails the test if Run is ever called.
+func TestKeyVizHandlerSkipsFanoutForPeerCall(t *testing.T) {
+	t.Parallel()
+	src := &fakeKeyVizSource{cols: []keyviz.MatrixColumn{
+		{At: time.Unix(1_700_000_000, 0), Rows: []keyviz.MatrixRow{
+			{RouteID: 1, Start: []byte("a"), End: []byte("b"), Writes: 5},
+		}},
+	}}
+	// A real *KeyVizFanout pointed at a peer URL that, if dialled,
+	// would record the call. We assert the call-count stays at zero
+	// because the handler's recursion guard short-circuits before
+	// Run runs the parallel-fetch step.
+	var peerHits int
+	peer := httptest.NewServer(http.HandlerFunc(func(_ http.ResponseWriter, _ *http.Request) {
+		peerHits++
+	}))
+	defer peer.Close()
+
+	fanout := NewKeyVizFanout("self", []string{peer.URL}).WithHTTPClient(peer.Client())
+	h := NewKeyVizHandler(src).
+		WithClock(func() time.Time { return time.Unix(1_700_000_000, 0).UTC() }).
+		WithFanout(fanout)
+	srv := httptest.NewServer(h)
+	defer srv.Close()
+
+	req, err := http.NewRequestWithContext(context.Background(), http.MethodGet, srv.URL, nil)
+	require.NoError(t, err)
+	req.Header.Set(keyVizFanoutPeerHeader, "1")
+	resp, err := http.DefaultClient.Do(req)
+	require.NoError(t, err)
+	defer resp.Body.Close()
+
+	require.Equal(t, http.StatusOK, resp.StatusCode)
+	var matrix KeyVizMatrix
+	require.NoError(t, json.NewDecoder(resp.Body).Decode(&matrix))
+	require.Len(t, matrix.Rows, 1, "local matrix served directly")
+	require.Nil(t, matrix.Fanout,
+		"peer-marked request must not produce a Fanout block — fan-out was skipped, no aggregator metadata to surface")
+	require.Equal(t, 0, peerHits,
+		"recursion guard violated: handler dialled a peer despite X-Admin-Fanout-Peer being set")
+}