feat(gateway): diagnose set-header assumptions; refresh routing docs

The folder-set constraint rests on two assumptions that can only be checked
against live traffic: that mcp-remote expands ${WORKSPACE_FOLDER_PATHS}, and
that the active folder is always a member of the resulting set (212/212 in the
probe). Both now report failure instead of degrading quietly.

Adds warns for an unexpanded template on either header, a pinned root absent
from the reported set (the invariant the constraint depends on), an ambiguous
multi-folder session, and a refused set_workspace_root call. The candidate
store is now idempotent so these audit once per change rather than per request.

Also drops unexpanded ${...} entries during parsing. Keeping one would have
matched no real folder and turned the membership check into a blanket refusal
of every legitimate root, so this closes a real failure mode rather than only
reporting it.

Docs corrected where they still blamed the Agents window or called
${workspaceFolder}-via-args reliable: it fails 21% overall, and editor windows
(29%) are worse than Agents windows (4%). Records the ruled-out alternatives so
the first-entry heuristic doesn't get proposed again, and flags that the
per-repo installer writes a bearer token into the repo with no gitignore entry.

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

Author: crimsonsunset

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

@@ -262,6 +262,19 @@ pub async fn mcp_oauth_middleware(
         (sid, ws, ws_set)
     };
     match (&session_id_header, &workspace_header) {
+        // Neither the editor nor mcp-remote expanded the template, so the
+        // literal reached us. Distinct from the empty case below: it means
+        // mcp-remote's own `${ENV}` substitution changed behavior, since today
+        // it rewrites an unknown variable to an empty string.
+        (_, Some(ws)) if ws.contains("${") => {
+            warn!(
+                trace_id = %trace_id,
+                session_id = session_id_header.as_deref().unwrap_or("<none>"),
+                workspace_header = %ws,
+                "[SessionRoots] X-Mcpmux-Workspace arrived as an unexpanded template — \
+                 pin skipped rather than pinning a literal",
+            );
+        }
         (_, Some(ws)) if ws.trim().is_empty() => {
             warn!(
                 trace_id = %trace_id,
@@ -303,6 +316,21 @@ pub async fn mcp_oauth_middleware(
     // 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) {
+        // The bridge config assumes Cursor leaves `${WORKSPACE_FOLDER_PATHS}`
+        // alone (it isn't a Cursor variable) so mcp-remote expands it from the
+        // child environment. This warn is how that assumption reports failure:
+        // the set is dropped rather than parsed, so routing degrades to the
+        // pre-set-header behavior instead of misrouting.
+        (_, Some(set)) if set.contains("${") => {
+            warn!(
+                trace_id = %trace_id,
+                session_id = session_id_header.as_deref().unwrap_or("<none>"),
+                workspace_set_header = %set,
+                "[SessionRoots] X-Mcpmux-Workspace-Set arrived unexpanded — no candidate \
+                 set for this session; check that WORKSPACE_FOLDER_PATHS is present in \
+                 the mcp-remote child environment",
+            );
+        }
         (_, Some(set)) if set.trim().is_empty() => {}
         (Some(sid), Some(set)) => {
             services.session_roots.set_candidates(sid, set);

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

@@ -14,6 +14,7 @@ use async_trait::async_trait;
 use mcpmux_core::normalize_workspace_root;
 use rmcp::model::CallToolResult;
 use serde_json::{json, Value};
+use tracing::warn;
 
 use super::meta_tool_common::{emit_tools_list_changed, text_result};
 use super::registry::{MetaTool, MetaToolCall, MetaToolError};
@@ -81,6 +82,16 @@ impl MetaTool for SetWorkspaceRootTool {
                 .session_roots
                 .get_candidates(session_id)
                 .unwrap_or_default();
+            // Expected when an agent guesses; a burst of these against roots
+            // the user believes are open points at the membership invariant
+            // (see the audit warn in `session_roots::store_candidates`).
+            warn!(
+                %session_id,
+                client_id = %call.client_id,
+                requested_root = %normalized,
+                candidates = ?candidates,
+                "[meta_tools] set_workspace_root refused — root not open in this window",
+            );
             return Err(MetaToolError::InvalidArgument(format!(
                 "workspace_root `{normalized}` is not open in this window. \
                  Declare one of: {}",

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

@@ -120,6 +120,7 @@ pub struct SessionRootsRegistry {
 fn parse_candidate_set(raw_set: &str) -> Vec<String> {
     let mut parsed: Vec<String> = raw_set
         .split(',')
+        .filter(|entry| !is_unexpanded_variable(entry))
         .map(normalize_workspace_root)
         .filter(|path| !path.is_empty())
         .collect();
@@ -128,6 +129,16 @@ fn parse_candidate_set(raw_set: &str) -> Vec<String> {
     parsed
 }
 
+/// Whether a header value still carries a `${...}` template, meaning neither
+/// the editor nor `mcp-remote` expanded it.
+///
+/// Such a value must never become a candidate: it can't match any real folder,
+/// so it would turn the membership check into a blanket rejection of every
+/// legitimate root the caller might declare.
+fn is_unexpanded_variable(value: &str) -> bool {
+    value.contains("${")
+}
+
 impl SessionRootsRegistry {
     pub fn new() -> Arc<Self> {
         Arc::new(Self {
@@ -339,6 +350,18 @@ impl SessionRootsRegistry {
         if parsed.is_empty() {
             return;
         }
+        // The set header rides every request, so skip the audit and the write
+        // when nothing changed. Read the comparison into an owned bool so the
+        // DashMap guard drops before the insert below (see `record_resolution`
+        // for the self-deadlock this avoids).
+        let unchanged = self
+            .candidates
+            .get(session_id)
+            .is_some_and(|existing| *existing == parsed);
+        if unchanged {
+            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.
@@ -349,6 +372,41 @@ impl SessionRootsRegistry {
             );
             self.set_pinned(session_id, only);
         }
+
+        match self.get_pinned(session_id) {
+            // Audits the invariant the whole design rests on: the active
+            // folder was a member of the reported set in 212 of 212 sampled
+            // multi-folder spawns. If this ever fires, membership is no longer
+            // safe as a constraint and `is_candidate` will start refusing
+            // legitimate roots — treat it as a design regression, not noise.
+            Some(pinned) if !parsed.iter().any(|c| c == &pinned) => {
+                warn!(
+                    %session_id,
+                    pinned_root = %pinned,
+                    candidates = ?parsed,
+                    "[SessionRoots] pinned root is absent from X-Mcpmux-Workspace-Set — \
+                     membership invariant violated; set_workspace_root may now reject \
+                     valid roots for this session",
+                );
+            }
+            Some(_) => {}
+            // The active-folder header failed and more than one folder is
+            // open, so this session cannot be routed without the caller
+            // declaring which folder it is in. Logged at warn because it is
+            // the case that costs the user an extra round trip.
+            None if parsed.len() > 1 => {
+                warn!(
+                    %session_id,
+                    candidate_count = parsed.len(),
+                    candidates = ?parsed,
+                    "[SessionRoots] no pinned root and multiple folders open — session must \
+                     call mcpmux_set_workspace_root to disambiguate (a per-repo static \
+                     header install avoids this entirely)",
+                );
+            }
+            None => {}
+        }
+
         self.candidates.insert(session_id.to_string(), parsed);
     }
 
@@ -775,6 +833,26 @@ mod tests {
         assert!(parse_candidate_set("  ,  ").is_empty());
     }
 
+    #[test]
+    fn unexpanded_template_never_becomes_a_candidate() {
+        // If mcp-remote stops expanding the variable, the literal must be
+        // dropped. Keeping it would match no real folder and so turn the
+        // membership check into a blanket refusal.
+        assert!(parse_candidate_set("${WORKSPACE_FOLDER_PATHS}").is_empty());
+
+        let reg = SessionRootsRegistry::default();
+        reg.set_candidates("sess-1", "${WORKSPACE_FOLDER_PATHS}");
+        assert!(reg.get_candidates("sess-1").is_none());
+        assert!(
+            reg.is_candidate("sess-1", CANDIDATES[0]),
+            "an unexpanded set must leave the session unconstrained, not deny it"
+        );
+
+        // A partially expanded value keeps the real folders and drops the rest.
+        let mixed = format!("{},${{WORKSPACE_FOLDER_PATHS}}", CANDIDATES[0]);
+        assert_eq!(parse_candidate_set(&mixed), vec![CANDIDATES[0].to_string()]);
+    }
+
     #[test]
     fn pending_candidates_apply_when_session_id_arrives() {
         let reg = SessionRootsRegistry::default();

docs/manual/cursor-workspace-bridge.md

@@ -6,6 +6,11 @@ Regression check for the global `~/.cursor/mcp.json` bridge (see
 This path replaces per-repo `.cursor/mcp.json` header installs for Cursor by
 routing through `npx mcp-remote` with `${workspaceFolder}` in the bridge args.
 
+Cursor resolves that variable unreliably (~21% failure, measured), so the bridge
+also sends `${WORKSPACE_FOLDER_PATHS}` as `X-Mcpmux-Workspace-Set`. That set is a
+constraint on which folder a session may claim, never a way to pick one — see
+[Fallback](#fallback) for why inference is off the table.
+
 ## Prerequisites
 
 - `pnpm dev:admin` (or production McpMux) with gateway on `localhost:45818`.
@@ -48,38 +53,76 @@ Check the McpMux log (macOS:
 - `[FeatureSetResolver] resolved via WorkspaceBinding workspace_root=…` matching
   each window's folder.
 
+Three warns exist to report that the bridge's assumptions broke. None should
+appear in a healthy two-window run:
+
+| Log line                                            | Means                                                                                                                                                            |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `X-Mcpmux-Workspace-Set arrived unexpanded`         | Cursor mangled `${WORKSPACE_FOLDER_PATHS}` instead of passing it to `mcp-remote`. No candidate set, so routing degrades to pre-set-header behavior.              |
+| `pinned root is absent from X-Mcpmux-Workspace-Set` | The active folder isn't a member of the reported set. This violates the invariant the constraint rests on; `set_workspace_root` will start refusing valid roots. |
+| `no pinned root and multiple folders open`          | The 16% case. Expected occasionally; the session needs one `mcpmux_set_workspace_root` call.                                                                     |
+
 ## 4. Bridge flags sanity check
 
 Confirm the generated config includes:
 
 - `--allow-http` (gateway is loopback HTTP, not TLS).
 - `--header` with **no space** after the colon:
   `X-Mcpmux-Workspace:${workspaceFolder}`.
+- `--header X-Mcpmux-Workspace-Set:${WORKSPACE_FOLDER_PATHS}`. Not a Cursor
+  variable, so it passes through untouched and `mcp-remote` expands it from the
+  child environment. Carries every folder open in the calling window.
 - `Authorization:Bearer ${MCPMUX_API_KEY}` with the key in `env.MCPMUX_API_KEY`.
 
 To verify `mcp-remote` accepts these flags outside Cursor:
 
 ```bash
 npx -y mcp-remote http://127.0.0.1:45818/mcp --allow-http \
   --header "X-Mcpmux-Workspace:/path/to/folder" \
+  --header "X-Mcpmux-Workspace-Set:/path/to/folder,/path/to/other" \
   --header "Authorization:Bearer mcpk_…"
 ```
 
 The process should stay up and the gateway should log an incoming MCP session.
 
 ## Fallback
 
-Cursor's Agents window sometimes spawns the `mcp-remote` bridge without
-resolving `${workspaceFolder}`. The gateway then sees
-`X-Mcpmux-Workspace` present but empty, skips the pin, and the session
-stays at `PendingRoots` (or routes via the full multi-folder `roots/list`).
-
-Look for this log line:
+Cursor fails to substitute `${workspaceFolder}` before spawning `mcp-remote` in
+roughly 21% of spawns. `mcp-remote` then expands the leftover literal to an
+empty string, so the gateway sees `X-Mcpmux-Workspace` present but empty and
+skips the pin.
 
 ```
 [SessionRoots] X-Mcpmux-Workspace present but empty — pin skipped
 ```
 
-When that happens, use the per-repo install path in
-[`workspace-header-routing.md`](./workspace-header-routing.md) section B
-(static `X-Mcpmux-Workspace` header in `.cursor/mcp.json`, no variable).
+This is **not** an Agents-window problem, despite what earlier revisions of this
+doc claimed. A 282-spawn probe measured editor windows failing at 29% and Agents
+windows at 4%, across folder counts from zero to five. It's a flaky
+substitution, not a surface-specific one.
+
+There is no fallback signal for the active folder. The probe checked all 22
+Cursor and VS Code environment variables in the child process:
+`CURSOR_WORKSPACE_LABEL` is stale (it names the window that started the
+extension host, often a folder not even in the set), `VSCODE_PID` and
+`VSCODE_IPC_HOOK` are app-level rather than per-window, `cwd` is always the home
+directory, and no `.code-workspace` file exists for ad-hoc multi-root windows.
+
+`WORKSPACE_FOLDER_PATHS` is the one usable signal, and only as a constraint. The
+active folder was a member of it in 212 of 212 resolved multi-folder spawns, but
+its position identified the active folder in only 70% of them. A 30% misroute
+rate would hand one project's credentials to another, so the gateway does not
+infer from position. What it does instead:
+
+- **One folder in the set:** pins outright. Unambiguous by construction.
+- **No folders:** no workspace to route to; falls through to grants.
+- **Two or more:** refuses to guess. The session gets meta tools only until it
+  calls `mcpmux_set_workspace_root`, which is now validated against the set so a
+  caller can't declare a folder its window doesn't have open.
+
+To avoid the whole class of problem, use the per-repo install in
+[`workspace-header-routing.md`](./workspace-header-routing.md) section B. It
+writes a literal path into `.cursor/mcp.json` with no variable to substitute,
+which is why it never flakes. Note that it also writes the bearer token into a
+file inside the repo and does not add a `.gitignore` entry, so exclude it
+yourself before committing.

docs/manual/workspace-header-routing.md

@@ -28,6 +28,16 @@ This avoids maintaining a `.cursor/mcp.json` + `.gitignore` entry in every
 repo. The per-repo install path below (sections A–B) remains a supported
 fallback when you cannot use `npx`/`mcp-remote`.
 
+**Multi-root windows should prefer the per-repo path.** Cursor fails to
+substitute `${workspaceFolder}` in about 21% of bridge spawns, and when the
+window has several folders open there is no sound way to recover which one is
+active (see [`cursor-workspace-bridge.md`](./cursor-workspace-bridge.md)
+Fallback). The per-repo install writes a literal path, so it never flakes.
+
+**Before committing:** the installer writes your gateway bearer token into the
+repo-local config and does **not** add a `.gitignore` entry. Exclude the file
+yourself, or `git add .` will commit an access key.
+
 ## Prerequisites
 
 - `pnpm dev` (desktop app + gateway) running.

docs/planning/aug14-gateway-ops-bugs.md

@@ -27,15 +27,16 @@ These stay on the branch. They are not the dig targets.
 
 Severity is "how much it hurts today," not "how hard to fix."
 
-### B1. Empty `${workspaceFolder}` header (Agents window)
+### B1. Empty `${workspaceFolder}` header
 
 **Severity:** High (wrong or stuck routing)
-**Status:** Telemetry shipped; no client-side fix
-**Symptom:** Cursor Agents window (and some other spawn paths) send `X-Mcpmux-Workspace` present but empty. `set_pinned` no-ops. Session falls through to multi-folder `roots/list` → `PendingRoots` or the wrong space.
-**Evidence:** 477 empty-header warns in ~40 min of new-binary uptime. Session `896e45f3…` fires it on every `tools/list` / `prompts/list` / `resources/list`.
-**Likely cause:** Cursor leaves `${workspaceFolder}` unresolved; `mcp-remote` then treats `${…}` as an env var and substitutes empty.
-**Related:** [`cursor-workspace-routing-bridge.md`](./cursor-workspace-routing-bridge.md) Open question (Aug 14). Fallback is per-repo static header in [`cursor-workspace-bridge.md`](../manual/cursor-workspace-bridge.md).
-**Decision already made:** no auto-disambiguation, no agent-facing UI, no client workaround this pass. Dig is "when/why + is the warn too loud."
+**Status:** Root-caused and bounded (`efabe48`); residual ~16% is inherent
+**Symptom:** Cursor sends `X-Mcpmux-Workspace` present but empty. `set_pinned` no-ops. Session falls through to multi-folder `roots/list` → `PendingRoots` or the wrong space.
+**Evidence:** 477 empty-header warns in ~40 min of new-binary uptime. Session `896e45f3…` fires it on every `tools/list` / `prompts/list` / `resources/list`. A later 282-spawn `env-probe` put the substitution failure at 21% overall.
+**Cause (confirmed):** Cursor leaves `${workspaceFolder}` unresolved; `mcp-remote` treats `${…}` as an env var and substitutes empty.
+**Correction:** this was filed as an Agents-window bug. It isn't. Editor windows fail at 29%, Agents windows at 4%. The `oauth_middleware` warn that blamed the Agents window has been reworded.
+**Related:** [`cursor-workspace-routing-bridge.md`](./cursor-workspace-routing-bridge.md) resolved question (Aug 20) and [`resilience-routing-leftovers.md`](./resilience-routing-leftovers.md) item 1. Fully immune path is the per-repo static header in [`cursor-workspace-bridge.md`](../manual/cursor-workspace-bridge.md).
+**Decision:** still no auto-disambiguation — a first-entry heuristic on `WORKSPACE_FOLDER_PATHS` would misroute 30% of the time. The window's folder set is now carried as a constraint instead, which bounds `set_workspace_root` rather than guessing.
 
 ### B2. Empty-header warn is per-request, not per-session
 

docs/planning/backend-connection-resilience-test.md

@@ -22,7 +22,7 @@ Follow-on (`dcc2977`) playbook: [`pool-invalidation-and-session-survival-test.md
 
 **Inbound 404 after gateway rebuild:** process death drops `LocalSessionManager`. `POST /mcp` with a stale `Mcp-Session-Id` is a spec-correct 404. [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) and the [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk/issues/1708) do **not** re-`initialize` on that 404. Do not persist sessions. Recovery is Reload MCP once. `/health` staying 200 means the gateway is up.
 
-**Header pin after reload:** a non-empty `X-Mcpmux-Workspace` is held across initialize and applied when `mcp-session-id` appears. Empty `${workspaceFolder}` is still the Agents-window hole.
+**Header pin after reload:** a non-empty `X-Mcpmux-Workspace` is held across initialize and applied when `mcp-session-id` appears. An empty `${workspaceFolder}` is a ~21% flake in Cursor's substitution, not an Agents-window-specific hole (editor windows are the worse offender at 29%); the window's folder set now arrives separately as `X-Mcpmux-Workspace-Set` and collapses the single-folder case. See [`cursor-workspace-routing-bridge.md`](./cursor-workspace-routing-bridge.md).
 
 ---