fix(gateway): reject multi-root bind with recoverable root list

mcpmux_bind_current_workspace was still first-root-wins on unpinned
multi-root sessions, so a gait agent could offer to mutate sync2hire.
Refuse until one root is pinned, list candidates in the error and in
mcpmux_list_servers PendingRoots notes, and log pre-approval binds.

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

Author: crimsonsunset

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

@@ -133,14 +133,43 @@ impl MetaTool for BindCurrentWorkspaceTool {
             .session_id
             .and_then(|sid| call.ctx.session_roots.get(sid))
             .unwrap_or_default();
-        let root = roots.into_iter().next().ok_or_else(|| {
-            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(),
-            )
-        })?;
+        // Same gate as FeatureSetResolver PendingRoots: never first-root-wins
+        // 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(),
+                ));
+            }
+            [single] => single.clone(),
+            many => {
+                info!(
+                    session_id = ?call.session_id,
+                    client_id = %call.client_id,
+                    root_count = many.len(),
+                    reported_roots = ?many,
+                    feature_set_id = %fs_id,
+                    "[meta_tools] bind_current_workspace refused — multiple unpinned roots"
+                );
+                let listed = many
+                    .iter()
+                    .map(|r| format!("  - {r}"))
+                    .collect::<Vec<_>>()
+                    .join("\n");
+                return Err(MetaToolError::InvalidArgument(format!(
+                    "cannot bind: {} workspace roots reported and none is pinned, so which \
+                     folder to mutate is ambiguous. Reported roots:\n{listed}\n\
+                     Call mcpmux_set_workspace_root with exactly one of those paths (the \
+                     workspace this agent is actually working in), then retry \
+                     mcpmux_bind_current_workspace with the same feature_set_id. A correct \
+                     X-Mcpmux-Workspace header pin also collapses this.",
+                    many.len(),
+                )));
+            }
+        };
         let normalized = normalize_workspace_root(&root);
 
         let fs_name = call
@@ -198,6 +227,18 @@ impl MetaTool for BindCurrentWorkspaceTool {
         let session_id_owned = call.session_id.map(str::to_owned);
         let caller_client_id_for_response = caller_client_id.clone();
         let request_machine_id = call.request_machine_id;
+        info!(
+            session_id = ?call.session_id,
+            client_id = %call.client_id,
+            chosen_root = %normalized,
+            root_count = 1,
+            feature_set_id = %fs_id,
+            feature_set_name = %fs_name,
+            request_machine_id = ?call.request_machine_id,
+            effective_machine_id = ?machine_id,
+            space_id = %space_id,
+            "[meta_tools] bind_current_workspace approval requested"
+        );
         with_approval(
             &call,
             "mcpmux_bind_current_workspace",

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

@@ -12,6 +12,43 @@ use super::diagnose_server::{
 use super::meta_tool_common::{caller_resolution, derive_server_readiness, text_result};
 use super::registry::{MetaTool, MetaToolCall, MetaToolError};
 use crate::pool::ConnectionStatus;
+use crate::services::ResolutionSource;
+
+/// Everything shows `readiness: "bindable"` when the resolver is at
+/// `PendingRoots` — indistinguishable from a genuinely unbound workspace on
+/// the server list alone. Give the agent a direct diagnosis instead of
+/// making it infer the cause from "every server is bindable".
+fn pending_roots_note(call: &MetaToolCall<'_>, source: ResolutionSource) -> Option<String> {
+    if source != ResolutionSource::PendingRoots {
+        return None;
+    }
+    let roots = call
+        .session_id
+        .and_then(|sid| call.ctx.resolver.session_roots().get(sid))
+        .unwrap_or_default();
+    if roots.len() > 1 {
+        let listed = roots
+            .iter()
+            .map(|r| format!("  - {r}"))
+            .collect::<Vec<_>>()
+            .join("\n");
+        Some(format!(
+            "{} workspace roots reported and none is pinned, so no binding can be resolved \
+             unambiguously — every server below shows as bindable regardless of any existing \
+             binding. Reported roots:\n{listed}\n\
+             Call mcpmux_set_workspace_root with exactly one of those paths (the workspace this \
+             agent is actually working in) to disambiguate.",
+            roots.len(),
+        ))
+    } else {
+        Some(
+            "No workspace root has arrived for this session yet, so no binding can be resolved \
+             — every server below shows as bindable regardless of any existing binding. If this \
+             persists, call mcpmux_set_workspace_root with this session's workspace path."
+                .to_string(),
+        )
+    }
+}
 
 pub struct ListServersTool;
 
@@ -168,6 +205,10 @@ impl MetaTool for ListServersTool {
                 .cmp(b.get("id").and_then(|v| v.as_str()).unwrap_or(""))
         });
 
-        Ok(text_result(json!({ "servers": servers })))
+        let mut result = json!({ "servers": servers });
+        if let Some(note) = pending_roots_note(&call, resolved.source) {
+            result["note"] = json!(note);
+        }
+        Ok(text_result(result))
     }
 }

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

@@ -1,7 +1,7 @@
 # Cursor Workspace Routing via Global `mcp-remote` Bridge
 
-**Last Updated:** Jul 27, 2026
-**Status:** Complete (Phases 1–3) — Agents Window spike **done**; multi-root ambiguity gate shipped as server-side safety net
+**Last Updated:** Jul 28, 2026
+**Status:** Complete (Phases 1–3) — Agents Window spike **done**; multi-root ambiguity gate covers resolver + bind + list_servers note
 **Branch:** `dev-rebased`
 
 ### Phase 1 spike results (Jul 20, 2026)
@@ -43,6 +43,8 @@
 
 **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.
 
+**Follow-up (Jul 27–28, 2026):** An unpinned dual-root session still let `mcpmux_bind_current_workspace` first-root-wins and offered to append `bundle:gait` onto `sync2hire-platform` (approval dialog). **Bind now shares the multi-root gate:** refuses with an `isError` listing the reported roots and instructing `mcpmux_set_workspace_root` with exactly one path before retry. `mcpmux_list_servers` adds a `note` with the same candidate list when resolution is `PendingRoots`. Pre-approval bind logs include `session_id` / `chosen_root` / `feature_set_id`.
+
 ---
 
 ## Problem
@@ -133,7 +135,7 @@ Cursor resolves `${workspaceFolder}` to the active window's project root *before
 
 ### Interaction with existing resolver tiers
 
-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.
+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` holds at `PendingRoots`, and `mcpmux_bind_current_workspace` refuses with a recoverable error listing candidates (multi-root ambiguity gate, Jul 27–28) — the server-side safety net for the empty-header path the Agents Window spike found.
 
 ---
 
@@ -195,6 +197,8 @@ Removes the "hand-assemble JSON" friction so the bridge is actually usable by so
 | [`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) |
+| [`crates/mcpmux-gateway/src/services/meta_tools/bind_workspace.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/bind_workspace.rs) | Same multi-root gate on bind; fat recoverable error + pre-approval info log |
+| [`crates/mcpmux-gateway/src/services/meta_tools/list_servers.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/list_servers.rs) | `PendingRoots` `note` lists candidate roots for agent self-heal |
 | [`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 |