feat(gateway): log workspace pin/session signals for Agents Window spike

Surface session_id, X-Mcpmux-Workspace, pin/clobber, and resolved root so we can prove whether Agents Window shares MCP sessions across workspaces.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>

Author: crimsonsunset

crates/mcpmux-gateway/src/mcp/handler.rs

@@ -109,9 +109,14 @@ impl McpMuxGatewayHandler {
             .await
         {
             Ok(resolved) => {
+                let workspace_root = session_id
+                    .and_then(|sid| services.session_roots.get(sid))
+                    .and_then(|roots| roots.into_iter().next())
+                    .unwrap_or_else(|| "<none>".into());
                 info!(
                     %client_id,
                     session_id = session_id.unwrap_or("<none>"),
+                    workspace_root = %workspace_root,
                     feature_set_ids = ?resolved.feature_set_ids,
                     space_id = resolved.space_id.map(|u| u.to_string()).unwrap_or_else(|| "<none>".into()),
                     source = ?resolved.source,

crates/mcpmux-gateway/src/mcp/oauth_middleware.rs

@@ -245,7 +245,7 @@ pub async fn mcp_oauth_middleware(
     // client can claim any binding (see FeatureSetResolver trust model). Keyed
     // by the `mcp-session-id` the client echoes on every post-initialize
     // request (the same key the handler stores reported roots under).
-    let pin = {
+    let (session_id_header, workspace_header) = {
         let headers = request.headers();
         let sid = headers
             .get("mcp-session-id")
@@ -255,10 +255,20 @@ pub async fn mcp_oauth_middleware(
             .get("x-mcpmux-workspace")
             .and_then(|v| v.to_str().ok())
             .map(str::to_owned);
-        sid.zip(ws)
+        (sid, ws)
     };
-    if let Some((sid, ws)) = pin {
-        services.session_roots.set_pinned(&sid, &ws);
+    match (&session_id_header, &workspace_header) {
+        (Some(sid), Some(ws)) => {
+            services.session_roots.set_pinned(sid, ws);
+        }
+        (None, Some(ws)) => {
+            warn!(
+                trace_id = %trace_id,
+                workspace_header = %ws,
+                "[SessionRoots] X-Mcpmux-Workspace present without mcp-session-id — pin skipped",
+            );
+        }
+        _ => {}
     }
 
     // Extract MCP method from body if POST
@@ -276,6 +286,8 @@ pub async fn mcp_oauth_middleware(
                     trace_id = %trace_id,
                     client = %&client_id[..client_id.len().min(12)],
                     space = %&space_id.to_string()[..8],
+                    session_id = session_id_header.as_deref().unwrap_or("<none>"),
+                    workspace_header = workspace_header.as_deref().unwrap_or("<absent>"),
                     method = method.as_deref().unwrap_or("-"),
                     "→ MCP"
                 );

crates/mcpmux-gateway/src/server/logging_middleware.rs

@@ -46,6 +46,8 @@ fn redact_headers_compact(headers: &axum::http::HeaderMap) -> String {
                     | "mcp-session-id"
                     | "mcp-protocol-version"
                     | "last-event-id"
+                    | "x-mcpmux-workspace"
+                    | "x-mcpmux-machine-id"
             )
         })
         .map(|(name, value)| {

crates/mcpmux-gateway/src/services/session_roots.rs

@@ -14,7 +14,7 @@ use std::time::{Duration, Instant};
 
 use dashmap::DashMap;
 use mcpmux_core::normalize_workspace_root;
-use tracing::debug;
+use tracing::{info, warn};
 
 use super::tool_discovery::ToolIndex;
 
@@ -216,23 +216,31 @@ impl SessionRootsRegistry {
     /// header falls back to the client's reported roots rather than denying.
     /// Cheap to call on the request hot path: redundant writes (same
     /// normalized value already pinned) are skipped to avoid shard churn.
+    ///
+    /// Logs at info on first pin, warn when the same session is re-pinned to a
+    /// different root (Agents Window / shared-session cross-workspace clobber).
     pub fn set_pinned(&self, session_id: &str, raw_root: &str) {
         let normalized = normalize_workspace_root(raw_root);
         if normalized.is_empty() {
             return;
         }
-        if self
-            .pinned
-            .get(session_id)
-            .is_some_and(|v| *v == normalized)
-        {
-            return;
+        if let Some(previous) = self.pinned.get(session_id) {
+            if *previous == normalized {
+                return;
+            }
+            warn!(
+                %session_id,
+                previous = %previous.as_str(),
+                new = %normalized,
+                "[SessionRoots] X-Mcpmux-Workspace pin clobber — same session, different root",
+            );
+        } else {
+            info!(
+                %session_id,
+                workspace_root = %normalized,
+                "[SessionRoots] pinned explicit workspace root from X-Mcpmux-Workspace header",
+            );
         }
-        debug!(
-            %session_id,
-            workspace_root = %normalized,
-            "[SessionRoots] pinned explicit workspace root from X-Mcpmux-Workspace header",
-        );
         self.pinned.insert(session_id.to_string(), normalized);
     }
 

docs/planning/cursor-workspace-routing-bridge.md

@@ -1,7 +1,7 @@
 # Cursor Workspace Routing via Global `mcp-remote` Bridge
 
-**Last Updated:** Jul 20, 2026
-**Status:** Complete (Phases 1–3 on `dev-rebased`)
+**Last Updated:** Jul 24, 2026
+**Status:** Complete (Phases 1–3) — Agents Window multi-workspace spike **pending** (observability logs shipped)
 **Branch:** `dev-rebased`
 
 ### Phase 1 spike results (Jul 20, 2026)
@@ -10,9 +10,39 @@
 - **Gateway:** `localhost:45818` up (`0.5.0`).
 - **Auth + connect:** `phase1-spike-bridge` client reached gateway; machine-naming dialog appeared and was approved.
 - **Remaining manual QA:** two-window `${workspaceFolder}` routing not yet verified in real Cursor; transport/auth path is confirmed.
+
 **Depends on:** `docs/manual/workspace-header-routing.md` (existing per-repo header fix this supersedes as the recommended path), `upstream-client-mapping-reconciliation.md` Phase 1 (`mcpk_` API-key auth — this feature's auth mechanism)
 **Unblocks:** Zero-maintenance Cursor workspace routing — no per-repo files, no agent cooperation required
 
+### Agents Window multi-workspace spike (Jul 24, 2026)
+
+**Hypothesis:** Cursor Agents Window groups agents by workspace in the UI, but may share one MCP session / mis-resolve `${workspaceFolder}` across workspaces, so mux cannot pin the correct root→FeatureSet binding. Gondor-local + global bridge config is already the intended Editor path; this spike proves what Agents Window actually sends.
+
+**Observability (shipped):** gateway logs now include:
+
+| Signal | Where | Level |
+| ------ | ----- | ----- |
+| `session_id` + `workspace_header` on every MCP POST | `oauth_middleware` `→ MCP` | info |
+| Workspace header without `mcp-session-id` (pin skipped) | `oauth_middleware` | warn |
+| First pin / same-session root clobber | `session_roots.set_pinned` | info / warn |
+| `workspace_root` on resolve | `handler` `[FeatureSetResolver] resolved` | info |
+| `x-mcpmux-workspace` / `x-mcpmux-machine-id` in DEBUG request headers | `logging_middleware` | debug |
+
+**Repro (Gondor):**
+
+1. Rebuild/restart the desktop gateway so the new logs are live.
+2. In Agents Window, start one agent under workspace A and one under workspace B (both already machine-bound on Gondor, e.g. `mcp-mux` vs `sync2hire-platform`).
+3. From each agent, call any `mcpmux_*` tool (e.g. `mcpmux_list_servers` or `mcpmux_search_tools`).
+4. Grep gateway logs: `SessionRoots`, `workspace_header`, `pin clobber`, `→ MCP`, `[FeatureSetResolver] resolved`.
+
+**Pass:** distinct `session_id` values; each `workspace_header` / resolved `workspace_root` matches that agent's workspace; no `pin clobber` warn.
+
+**Fail:** shared `session_id` with `pin clobber` (previous ≠ new), or `workspace_header=<absent>`, or header present without session id.
+
+**Next if fail:** prefer per-repo static `.cursor/mcp.json` header for Agents Window, and/or treat as Cursor Agents Window MCP binding gap (not a new per-agent identity axis).
+
+**Spike results:** _pending manual run_
+
 ---
 
 ## Problem
@@ -161,7 +191,9 @@ Removes the "hand-assemble JSON" friction so the bridge is actually usable by so
 | File | Note |
 | ---- | ---- |
 | [`apps/desktop/src-tauri/src/commands/workspace_install.rs`](../../apps/desktop/src-tauri/src/commands/workspace_install.rs) | The existing per-repo header install this feature supplements, not replaces |
-| [`crates/mcpmux-gateway/src/services/session_roots.rs`](../../crates/mcpmux-gateway/src/services/session_roots.rs) | `X-Mcpmux-Workspace` is already authoritative here — no gateway changes needed |
+| [`crates/mcpmux-gateway/src/services/session_roots.rs`](../../crates/mcpmux-gateway/src/services/session_roots.rs) | `X-Mcpmux-Workspace` pin is authoritative; Agents Window spike adds pin/clobber info+warn logs |
+| [`crates/mcpmux-gateway/src/mcp/oauth_middleware.rs`](../../crates/mcpmux-gateway/src/mcp/oauth_middleware.rs) | `→ MCP` logs `session_id` + `workspace_header`; warns when pin skipped |
+| [`crates/mcpmux-gateway/src/mcp/handler.rs`](../../crates/mcpmux-gateway/src/mcp/handler.rs) | Resolver resolved log includes `workspace_root` |
 | [`docs/manual/workspace-header-routing.md`](../manual/workspace-header-routing.md) | Documents the underlying Cursor `roots`-reporting bug this bridge works around |
 | [`docs/planning/upstream-client-mapping-reconciliation.md`](./upstream-client-mapping-reconciliation.md) | Phase 1 — `mcpk_` API-key auth, reused here as the bridge's auth mechanism |
 | [`apps/desktop/src/features/clients/RegisterApiKeyClientModal.tsx`](../../apps/desktop/src/features/clients/RegisterApiKeyClientModal.tsx) | Existing API-key minting UI this feature's Phase 2 panel is modeled on |