feat(gateway): constrain workspace pins to the caller's open folder set

Cursor fails to substitute ${workspaceFolder} in ~21% of mcp-remote spawns
(282 sampled), and mcp-remote then expands the unresolved literal to an empty
X-Mcpmux-Workspace header. Probing the child environment found no reliable
active-folder signal to fall back on: CURSOR_WORKSPACE_LABEL is stale,
VSCODE_PID and VSCODE_IPC_HOOK are app-level rather than per-window, and
position within WORKSPACE_FOLDER_PATHS identifies the active folder only 70%
of the time. A 30% misroute rate would leak the wrong space's credentials into
the wrong repo, so nothing here infers a folder.

What WORKSPACE_FOLDER_PATHS does guarantee is membership: the active folder was
in the set in 212 of 212 resolved multi-folder spawns. Carry it as a new
X-Mcpmux-Workspace-Set header and use it strictly as a constraint. A one-member
set pins (unambiguous by construction); larger sets only record candidates.

mcpmux_set_workspace_root now refuses a root the calling window doesn't have
open, closing a self-service grant where any approved client could name any
path and receive that workspace's FeatureSet and credentials. Clients that send
no set header stay permissive. bind_current_workspace names the open folders in
its no-roots refusal instead of leaving the agent to guess.

Also corrects the empty-header warning, which blamed the Agents window; the
probe shows editor windows fail at 29% versus 4% for Agents windows.

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

Author: crimsonsunset

apps/desktop/src/features/clients/cursor-bridge-config.helpers.ts

@@ -5,7 +5,13 @@ export const CURSOR_BRIDGE_CLIENT_NAME = 'cursor-global-bridge';
  * Build the `~/.cursor/mcp.json` snippet for the global mcp-remote bridge.
  *
  * Cursor resolves `${workspaceFolder}` in `args` at spawn time, so one global
- * entry routes each window to the correct workspace header.
+ * entry routes each window to the correct workspace header. That substitution
+ * is unreliable (measured at ~21% failure across 282 spawns), and when it
+ * fails `mcp-remote` expands the leftover literal to an empty header value.
+ * `${WORKSPACE_FOLDER_PATHS}` is not a Cursor variable, so it survives to
+ * `mcp-remote`, which expands it from the child environment — giving the
+ * gateway the window's full folder set even when the active folder is missing.
+ * The set constrains which root the session may claim; it does not pick one.
  */
 export function buildCursorBridgeMcpJson(apiKey: string, gatewayUrl: string): string {
   const mcpUrl = `${gatewayUrl.replace(/\/$/, '')}/mcp`;
@@ -21,6 +27,8 @@ export function buildCursorBridgeMcpJson(apiKey: string, gatewayUrl: string): st
           '--header',
           'X-Mcpmux-Workspace:${workspaceFolder}',
           '--header',
+          'X-Mcpmux-Workspace-Set:${WORKSPACE_FOLDER_PATHS}',
+          '--header',
           'Authorization:Bearer ${MCPMUX_API_KEY}',
         ],
         env: { MCPMUX_API_KEY: apiKey },

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 (session_id_header, workspace_header) = {
+    let (session_id_header, workspace_header, workspace_set_header) = {
         let headers = request.headers();
         let sid = headers
             .get("mcp-session-id")
@@ -255,16 +255,24 @@ pub async fn mcp_oauth_middleware(
             .get("x-mcpmux-workspace")
             .and_then(|v| v.to_str().ok())
             .map(str::to_owned);
-        (sid, ws)
+        let ws_set = headers
+            .get("x-mcpmux-workspace-set")
+            .and_then(|v| v.to_str().ok())
+            .map(str::to_owned);
+        (sid, ws, ws_set)
     };
     match (&session_id_header, &workspace_header) {
         (_, Some(ws)) if ws.trim().is_empty() => {
             warn!(
                 trace_id = %trace_id,
                 session_id = session_id_header.as_deref().unwrap_or("<none>"),
                 "[SessionRoots] X-Mcpmux-Workspace present but empty — pin skipped \
-                 (Cursor Agents window often spawns mcp-remote without resolving \
-                 ${{workspaceFolder}}; see docs/manual/cursor-workspace-bridge.md Fallback)",
+                 (Cursor did not substitute ${{workspaceFolder}} before spawning \
+                 mcp-remote, which then expanded the unresolved literal to empty). \
+                 Affects editor and Agents windows alike; recover with \
+                 mcpmux_set_workspace_root, or install a per-repo static header to \
+                 avoid substitution entirely — \
+                 see docs/manual/cursor-workspace-bridge.md Fallback",
             );
         }
         (Some(sid), Some(ws)) => {
@@ -288,6 +296,30 @@ pub async fn mcp_oauth_middleware(
         _ => {}
     }
 
+    // The calling window's full folder set (`X-Mcpmux-Workspace-Set`, carrying
+    // Cursor's `WORKSPACE_FOLDER_PATHS`). Recorded as a constraint on which
+    // roots this session may claim, and as the candidate list shown when the
+    // workspace header above failed to resolve. A set of one also pins,
+    // because one candidate cannot be ambiguous. Held across initialize like
+    // the workspace header, since both arrive before `mcp-session-id`.
+    match (&session_id_header, &workspace_set_header) {
+        (_, Some(set)) if set.trim().is_empty() => {}
+        (Some(sid), Some(set)) => {
+            services.session_roots.set_candidates(sid, set);
+        }
+        (None, Some(set)) => {
+            services
+                .session_roots
+                .remember_pending_candidates(&client_id, set);
+        }
+        (Some(sid), None) => {
+            services
+                .session_roots
+                .apply_pending_candidates(&client_id, sid);
+        }
+        _ => {}
+    }
+
     // Captured before `request` is consumed below — needed to recognize the
     // spec-correct GET shapes (pre-init SSE, post-timeout reconnect) when
     // deciding whether to warn on the response status.

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

@@ -47,6 +47,7 @@ fn redact_headers_compact(headers: &axum::http::HeaderMap) -> String {
                     | "mcp-protocol-version"
                     | "last-event-id"
                     | "x-mcpmux-workspace"
+                    | "x-mcpmux-workspace-set"
                     | "x-mcpmux-machine-id"
             )
         })

crates/mcpmux-gateway/src/services/meta_tools/bind_workspace.rs

@@ -137,12 +137,31 @@ impl MetaTool for BindCurrentWorkspaceTool {
         // when multiple unpinned roots are present (header pin collapses get() to 1).
         let root = match roots.as_slice() {
             [] => {
-                return Err(MetaToolError::InvalidArgument(
-                    "caller did not report any MCP roots; cannot bind — \
-                     call mcpmux_set_workspace_root first to declare your workspace path, \
-                     then retry mcpmux_bind_current_workspace"
-                        .into(),
-                ));
+                // The window's folder set (X-Mcpmux-Workspace-Set) usually
+                // survives even when the active-folder header came through
+                // empty, so name those folders rather than making the caller
+                // guess what to declare.
+                let candidates = call
+                    .session_id
+                    .and_then(|sid| call.ctx.session_roots.get_candidates(sid))
+                    .unwrap_or_default();
+                let known = if candidates.is_empty() {
+                    String::new()
+                } else {
+                    format!(
+                        " This window has these folders open:\n{}\n",
+                        candidates
+                            .iter()
+                            .map(|c| format!("  - {c}"))
+                            .collect::<Vec<_>>()
+                            .join("\n")
+                    )
+                };
+                return Err(MetaToolError::InvalidArgument(format!(
+                    "caller did not report any MCP roots; cannot bind.{known} \
+                     Call mcpmux_set_workspace_root to declare the workspace this agent is \
+                     actually working in, then retry mcpmux_bind_current_workspace."
+                )));
             }
             [single] => single.clone(),
             many => {

crates/mcpmux-gateway/src/services/meta_tools/set_workspace_root.rs

@@ -70,6 +70,24 @@ impl MetaTool for SetWorkspaceRootTool {
             )));
         }
 
+        // A caller may only declare a folder its own window actually has open.
+        // Without this the tool is a self-service grant: any approved client
+        // could name any path and receive that workspace's FeatureSet and
+        // credentials. The candidate set comes from the spawning host's
+        // environment rather than the caller, so it's the stronger claim.
+        if !call.ctx.session_roots.is_candidate(session_id, &normalized) {
+            let candidates = call
+                .ctx
+                .session_roots
+                .get_candidates(session_id)
+                .unwrap_or_default();
+            return Err(MetaToolError::InvalidArgument(format!(
+                "workspace_root `{normalized}` is not open in this window. \
+                 Declare one of: {}",
+                candidates.join(", ")
+            )));
+        }
+
         call.ctx
             .session_roots
             .set(session_id, std::iter::once(normalized.as_str()));

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

@@ -85,12 +85,49 @@ pub struct SessionRootsRegistry {
     /// before `mcp-session-id` (initialize). Applied on the first request
     /// that has a session id, or when initialize's response issues one.
     pending_by_client: DashMap<String, String>,
+    /// `session_id -> the full set of folders open in the calling window`,
+    /// sourced from the `X-Mcpmux-Workspace-Set` header (Cursor's
+    /// `WORKSPACE_FOLDER_PATHS`, expanded by `mcp-remote`).
+    ///
+    /// This is a **constraint, never a resolver**. Measurement across 212
+    /// multi-folder spawns found the active folder is always a member of this
+    /// set, but its position within the set identifies the active folder only
+    /// 70% of the time — so no ordering heuristic is safe for a routing
+    /// decision that gates credentials. Two things it is good for:
+    /// collapsing a one-member set to a pin (unambiguous), and rejecting a
+    /// [`set_workspace_root`](super::meta_tools) pin that names a folder the
+    /// calling window doesn't even have open.
+    candidates: DashMap<String, Vec<String>>,
+    /// `client_id -> candidate set` held when `X-Mcpmux-Workspace-Set` arrived
+    /// before `mcp-session-id`, mirroring [`Self::pending_by_client`].
+    pending_candidates_by_client: DashMap<String, Vec<String>>,
     /// Per-session active search index keyed by `(feature_set_ids fingerprint, index)`.
     /// Shared with [`MetaToolContext`](crate::services::meta_tools::MetaToolContext)
     /// so `mcpmux_search_tools` can reuse a session's resolved tool index.
     search_cache: Arc<DashMap<String, (u64, Arc<ToolIndex>)>>,
 }
 
+/// Split an `X-Mcpmux-Workspace-Set` header into normalized folder paths,
+/// sorted and deduped.
+///
+/// ponytail: splits on `,` because that is the delimiter Cursor uses for
+/// `WORKSPACE_FOLDER_PATHS`, so a folder whose own name contains a comma will
+/// shatter into bogus entries. The ceiling is acceptable because the set is
+/// only ever a constraint: a shattered entry can't match a real root, so the
+/// worst case is a pin rejection that falls back to today's behavior rather
+/// than a misroute. Upgrade path is a length-prefixed or JSON-array header if
+/// Cursor ever offers one.
+fn parse_candidate_set(raw_set: &str) -> Vec<String> {
+    let mut parsed: Vec<String> = raw_set
+        .split(',')
+        .map(normalize_workspace_root)
+        .filter(|path| !path.is_empty())
+        .collect();
+    parsed.sort();
+    parsed.dedup();
+    parsed
+}
+
 impl SessionRootsRegistry {
     pub fn new() -> Arc<Self> {
         Arc::new(Self {
@@ -102,6 +139,8 @@ impl SessionRootsRegistry {
             first_seen: DashMap::new(),
             pinned: DashMap::new(),
             pending_by_client: DashMap::new(),
+            candidates: DashMap::new(),
+            pending_candidates_by_client: DashMap::new(),
             search_cache: Arc::new(DashMap::new()),
         })
     }
@@ -285,6 +324,77 @@ impl SessionRootsRegistry {
         self.pinned.get(session_id).map(|v| v.clone())
     }
 
+    /// Record the calling window's full folder set from the
+    /// `X-Mcpmux-Workspace-Set` header.
+    ///
+    /// A one-member set is unambiguous, so it pins directly — that is the only
+    /// case where this header decides a route. Larger sets are stored as a
+    /// constraint for [`Self::is_candidate`] and for naming candidates in
+    /// refusals; they never select a folder on their own.
+    pub fn set_candidates(&self, session_id: &str, raw_set: &str) {
+        self.store_candidates(session_id, parse_candidate_set(raw_set));
+    }
+
+    fn store_candidates(&self, session_id: &str, parsed: Vec<String>) {
+        if parsed.is_empty() {
+            return;
+        }
+        if let [only] = parsed.as_slice() {
+            // The active folder is always a member of the set, so a set of one
+            // names it outright — no guessing involved.
+            info!(
+                %session_id,
+                workspace_root = %only,
+                "[SessionRoots] single-folder X-Mcpmux-Workspace-Set — pinned without ambiguity",
+            );
+            self.set_pinned(session_id, only);
+        }
+        self.candidates.insert(session_id.to_string(), parsed);
+    }
+
+    /// The calling window's folder set, if the header supplied one.
+    pub fn get_candidates(&self, session_id: &str) -> Option<Vec<String>> {
+        self.candidates.get(session_id).map(|v| v.clone())
+    }
+
+    /// Whether `root` is one of the folders the calling window has open.
+    ///
+    /// `true` when no set was reported — an absent constraint must not block
+    /// clients that don't send the header (every non-Cursor client, and Cursor
+    /// before the bridge config is reinstalled).
+    pub fn is_candidate(&self, session_id: &str, root: &str) -> bool {
+        let Some(candidates) = self.candidates.get(session_id) else {
+            return true;
+        };
+        let normalized = normalize_workspace_root(root);
+        candidates.iter().any(|c| c == &normalized)
+    }
+
+    /// Hold a candidate set for `client_id` until a session id exists,
+    /// mirroring [`Self::remember_pending_workspace`].
+    pub fn remember_pending_candidates(&self, client_id: &str, raw_set: &str) {
+        let parsed = parse_candidate_set(raw_set);
+        if parsed.is_empty() {
+            return;
+        }
+        self.pending_candidates_by_client
+            .insert(client_id.to_string(), parsed);
+    }
+
+    /// Apply a previously remembered candidate set to a session. Returns
+    /// `true` when one was applied.
+    pub fn apply_pending_candidates(&self, client_id: &str, session_id: &str) -> bool {
+        let Some(candidates) = self
+            .pending_candidates_by_client
+            .get(client_id)
+            .map(|value| value.clone())
+        else {
+            return false;
+        };
+        self.store_candidates(session_id, candidates);
+        true
+    }
+
     /// Drop a session's roots — call on client disconnect.
     pub fn remove(&self, session_id: &str) {
         self.map.remove(session_id);
@@ -294,6 +404,7 @@ impl SessionRootsRegistry {
         self.probe_lock.remove(session_id);
         self.first_seen.remove(session_id);
         self.pinned.remove(session_id);
+        self.candidates.remove(session_id);
         self.search_cache.remove(session_id);
     }
 
@@ -611,6 +722,69 @@ mod tests {
         assert_eq!(reg.get("sess-mixed"), Some(vec![keep]));
     }
 
+    /// Paths that survive `normalize_workspace_root` unchanged on this
+    /// platform, so the candidate assertions below don't fight normalization.
+    #[cfg(windows)]
+    const CANDIDATES: [&str; 3] = ["d:\\alpha", "d:\\beta", "d:\\gamma"];
+    #[cfg(not(windows))]
+    const CANDIDATES: [&str; 3] = ["/repos/alpha", "/repos/beta", "/repos/gamma"];
+
+    #[test]
+    fn single_candidate_pins_but_multiple_only_constrain() {
+        let reg = SessionRootsRegistry::default();
+
+        // One folder open is unambiguous — the set is allowed to decide.
+        reg.set_candidates("sess-one", CANDIDATES[0]);
+        assert_eq!(reg.get_pinned("sess-one"), Some(CANDIDATES[0].to_string()));
+
+        // Several folders open must never auto-select, however tempting the
+        // ordering looks: position predicts the active folder only ~70% of
+        // the time, which is a misroute, not a fallback.
+        let many = CANDIDATES.join(",");
+        reg.set_candidates("sess-many", &many);
+        assert!(
+            reg.get_pinned("sess-many").is_none(),
+            "a multi-folder set must not pin any of its members"
+        );
+        assert_eq!(reg.get_candidates("sess-many").unwrap().len(), 3);
+    }
+
+    #[test]
+    fn candidate_set_constrains_declarable_roots() {
+        let reg = SessionRootsRegistry::default();
+        reg.set_candidates("sess-1", &CANDIDATES.join(","));
+
+        assert!(reg.is_candidate("sess-1", CANDIDATES[1]));
+        assert!(
+            !reg.is_candidate("sess-1", "/repos/not-open"),
+            "a folder the window doesn't have open must be refusable"
+        );
+
+        // No set reported (every client that doesn't send the header) stays
+        // permissive — the constraint must not become a new denial path.
+        assert!(reg.is_candidate("sess-unknown", "/repos/anything"));
+    }
+
+    #[test]
+    fn parse_candidate_set_dedupes_and_drops_blanks() {
+        let raw = format!("{a},,{a},  ,{b}", a = CANDIDATES[0], b = CANDIDATES[1]);
+        assert_eq!(
+            parse_candidate_set(&raw),
+            vec![CANDIDATES[0].to_string(), CANDIDATES[1].to_string()]
+        );
+        assert!(parse_candidate_set("  ,  ").is_empty());
+    }
+
+    #[test]
+    fn pending_candidates_apply_when_session_id_arrives() {
+        let reg = SessionRootsRegistry::default();
+        reg.remember_pending_candidates("client-1", CANDIDATES[0]);
+        assert!(reg.get_candidates("sess-new").is_none());
+        assert!(reg.apply_pending_candidates("client-1", "sess-new"));
+        // A held single-folder set still pins once the session id lands.
+        assert_eq!(reg.get_pinned("sess-new"), Some(CANDIDATES[0].to_string()));
+    }
+
     #[test]
     fn test_remove_clears_resolution_too() {
         let reg = SessionRootsRegistry::default();