fix(gateway): gate ambiguous multi-root sessions to PendingRoots

A roots-capable session reporting multiple folders (no pinned
X-Mcpmux-Workspace header) was silently resolving to the first
matching binding instead of holding until unambiguous. Reuses the
existing PendingRoots pattern; mcpmux_set_workspace_root or a header
pin remains the escape hatch.

Reconciles the Agents Window spike doc with its actual finding
(session isolation works; this gate is the fix for the real bug it
surfaced) and flips the stale status on the rootless declare-root
gate doc, which already shipped Jul 23.

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

Author: crimsonsunset

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

@@ -7,8 +7,11 @@
 //! ```text
 //! resolve(session_id, client_id):
 //!     // Signal 1 — reported root (deprecated MCP primitive, SEP-2577)
-//!     if session reported roots AND a binding matches:
-//!         return (binding.space_id, [binding.feature_set_id], WorkspaceBinding)
+//!     if session reported roots:
+//!         if roots.len() > 1 (no pinned X-Mcpmux-Workspace header):
+//!             return ([], default_space, PendingRoots)   // ambiguous — never guess
+//!         if a binding matches the (single) root:
+//!             return (binding.space_id, [binding.feature_set_id], WorkspaceBinding)
 //!
 //!     // Tier 1b — roots reported, no binding matched
 //!     if session reported roots AND no binding matched:
@@ -67,6 +70,14 @@
 //! through to another client's grants — after the grace it goes straight to
 //! `Unbound`, preserving per-session isolation.
 //!
+//! Multi-root ambiguity is a separate, non-timed hold: when
+//! [`SessionRootsRegistry::get`](crate::services::session_roots::SessionRootsRegistry::get)
+//! returns more than one root (no pinned `X-Mcpmux-Workspace` header), the
+//! resolver stays at `PendingRoots` indefinitely until the client pins a
+//! single root (header or `mcpmux_set_workspace_root`). Unlike the in-flight
+//! grace window, time alone cannot resolve which open folder the request
+//! belongs to — guessing would silently route to the wrong FeatureSet.
+//!
 //! The caller's client identity is used **only** for the rootless Tier-2 grant
 //! lookup — every roots-capable session routes via its own reported roots,
 //! regardless of which OAuth client opened it. This is what makes "two VS Code
@@ -135,8 +146,9 @@ pub enum ResolutionSource {
     /// A [`WorkspaceBinding`](mcpmux_core::WorkspaceBinding) matched one of
     /// the session's reported MCP roots.
     WorkspaceBinding,
-    /// No binding matched, but the client is roots-capable so its `roots`
-    /// list is in flight; return empty and re-resolve when they arrive.
+    /// Held empty pending an unambiguous root: roots still in flight (grace
+    /// window), a rootless client awaiting `mcpmux_set_workspace_root`, or a
+    /// multi-root session with no pinned `X-Mcpmux-Workspace` header.
     PendingRoots,
     /// Rootless-by-design client. The space-default's per-client
     /// `client_grants` were applied.
@@ -504,6 +516,27 @@ impl FeatureSetResolverService {
             // (no ancestor inheritance).
             if has_roots {
                 let reported_roots = roots.expect("has_roots implies Some");
+
+                // Ambiguous multi-root session: SessionRootsRegistry::get() only
+                // returns more than one entry when there's no pinned
+                // X-Mcpmux-Workspace header collapsing it to a single root (see
+                // SessionRootsRegistry::get). Never guess which open folder this
+                // request belongs to — hold at PendingRoots (meta tools, incl.
+                // mcpmux_set_workspace_root, remain reachable) until the client
+                // pins one explicitly.
+                if reported_roots.len() > 1 {
+                    debug!(
+                        session_id = %sid,
+                        root_count = reported_roots.len(),
+                        "[FeatureSetResolver] multiple roots reported, no pinned header — PendingRoots",
+                    );
+                    return Ok(ResolvedFeatureSet {
+                        feature_set_ids: vec![],
+                        space_id: Some(deny_space_id),
+                        source: ResolutionSource::PendingRoots,
+                    });
+                }
+
                 if let Some(binding) = self
                     .find_binding_for_roots(&reported_roots, client_id, request_machine_id)
                     .await?

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

@@ -1,7 +1,7 @@
 # Cursor Workspace Routing via Global `mcp-remote` Bridge
 
-**Last Updated:** Jul 24, 2026
-**Status:** Complete (Phases 1–3) — Agents Window multi-workspace spike **pending** (observability logs shipped)
+**Last Updated:** Jul 27, 2026
+**Status:** Complete (Phases 1–3) — Agents Window spike **done**; multi-root ambiguity gate shipped as server-side safety net
 **Branch:** `dev-rebased`
 
 ### Phase 1 spike results (Jul 20, 2026)
@@ -41,7 +41,7 @@
 
 **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_
+**Spike results (Jul 24–27, 2026):** Session isolation works — Agents Window agents in separate workspaces get distinct `session_id`s and (when present) distinct `X-Mcpmux-Workspace` headers; no pin-clobber. Identical tool answers in the repro were overlapping FeatureSets, not shared-session clobber. Real bug found: some sessions arrive with an empty/absent workspace header, so `SessionRootsRegistry::get()` returns the full multi-folder `roots/list` and the resolver used to first-match-wins across that list. **Fix shipped:** resolver returns `PendingRoots` whenever `reported_roots.len() > 1` (no pinned header); escape hatch is `mcpmux_set_workspace_root` / a correct header pin. Complements the bridge's header injection as a server-side safety net.
 
 ---
 
@@ -133,7 +133,7 @@ Cursor resolves `${workspaceFolder}` to the active window's project root *before
 
 ### Interaction with existing resolver tiers
 
-No resolver changes. The bridge is purely a transport-layer trick to get `X-Mcpmux-Workspace` populated correctly — the gateway already treats that header as authoritative and pins it ahead of probed `roots` (`session_roots.rs`, `SessionRootsRegistry`). This feature doesn't touch `feature_set_resolver.rs`, `workspace_binding_repository.rs`, or any migration.
+The bridge is a transport-layer trick to get `X-Mcpmux-Workspace` populated correctly — the gateway already treats that header as authoritative and pins it ahead of probed `roots` (`session_roots.rs`, `SessionRootsRegistry`). When the header is absent and `roots/list` returns multiple folders, `feature_set_resolver.rs` now holds at `PendingRoots` instead of first-match-wins (multi-root ambiguity gate, Jul 27) — the server-side safety net for the empty-header path the Agents Window spike found.
 
 ---
 
@@ -194,6 +194,7 @@ Removes the "hand-assemble JSON" friction so the bridge is actually usable by so
 | [`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` |
+| [`crates/mcpmux-gateway/src/services/feature_set_resolver.rs`](../../crates/mcpmux-gateway/src/services/feature_set_resolver.rs) | Multi-root ambiguity → `PendingRoots` when `get()` returns >1 root (no pin) |
 | [`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 |

docs/planning/rootless-declare-root-gate.md

@@ -1,7 +1,7 @@
 # Rootless Declare-Before-Grant Gate
 
-**Last Updated:** Jul 23, 2026
-**Status:** Planning — ready to implement
+**Last Updated:** Jul 27, 2026
+**Status:** Complete — Phase 1+2 shipped Jul 23 (`dff476f`, `38f1df1` on `dev-rebased`)
 **Branch:** `dev-rebased` (fork-only for now; no upstream port planned)
 **Depends on:** [`deny-by-default-bindable-callers.md`](./deny-by-default-bindable-callers.md) (Tier 4 `Unbound`, `ClientGrant` Tier 3), [`per-device-machine-header.md`](./per-device-machine-header.md), [`workspace-machine-binding.md`](./workspace-machine-binding.md)
 **Unblocks:** Cloud Agent / rootless clients get scoped-by-repo tools instead of a permanent blanket grant

tests/rust/tests/integration/feature_set_resolver.rs

@@ -714,6 +714,70 @@ async fn roots_capable_unmapped_root_stays_unbound_not_grant() {
     assert_ne!(r.feature_set_ids, vec![f.fs_a_id]);
 }
 
+#[tokio::test]
+async fn roots_capable_multi_root_session_is_pending_not_first_match() {
+    // Ambiguity gate: a roots-capable session reporting multiple folders
+    // (no pinned X-Mcpmux-Workspace header) must NOT silently bind to the
+    // first matching root — hold at PendingRoots until the client pins one.
+    let f = Fixture::new().await;
+    let (root_a, root_b) = if cfg!(windows) {
+        ("d:\\work\\a", "d:\\work\\b")
+    } else {
+        ("/work/a", "/work/b")
+    };
+    f.binding_repo
+        .create(&WorkspaceBinding::new(
+            normalize_workspace_root(root_a),
+            f.space_id,
+            f.fs_a_id.clone(),
+        ))
+        .await
+        .unwrap();
+
+    f.session_roots.set("s", [root_a, root_b]);
+    f.session_roots.set_roots_capable("s", true);
+    let r = f.resolver.resolve(Some("s"), None, None).await.unwrap();
+    assert_eq!(r.source, ResolutionSource::PendingRoots);
+    assert!(r.feature_set_ids.is_empty());
+    assert_ne!(r.feature_set_ids, vec![f.fs_a_id]);
+}
+
+#[tokio::test]
+async fn roots_capable_multi_root_session_unblocked_by_pinned_header() {
+    // Same multi-root setup as above, but a pinned header collapses get() to
+    // a single root and resolution resumes via WorkspaceBinding.
+    let f = Fixture::new().await;
+    let (root_a, root_b) = if cfg!(windows) {
+        ("d:\\work\\a", "d:\\work\\b")
+    } else {
+        ("/work/a", "/work/b")
+    };
+    f.binding_repo
+        .create(&WorkspaceBinding::new(
+            normalize_workspace_root(root_a),
+            f.space_id,
+            f.fs_a_id.clone(),
+        ))
+        .await
+        .unwrap();
+    f.binding_repo
+        .create(&WorkspaceBinding::new(
+            normalize_workspace_root(root_b),
+            f.space_id,
+            f.fs_b_id.clone(),
+        ))
+        .await
+        .unwrap();
+
+    f.session_roots.set("s", [root_a, root_b]);
+    f.session_roots.set_roots_capable("s", true);
+    f.session_roots.set_pinned("s", root_b);
+
+    let r = f.resolver.resolve(Some("s"), None, None).await.unwrap();
+    assert_eq!(r.source, ResolutionSource::WorkspaceBinding);
+    assert_eq!(r.feature_set_ids, vec![f.fs_b_id]);
+}
+
 #[tokio::test]
 async fn rootless_client_without_grants_falls_back_to_default() {
     let f = Fixture::new().await;