MCP tool envelope: workspaceId is not session-sticky — multi-call sessions default into the "default" workspace

[gcp007-ops]

Summary

The MCP CLI envelope (getTools / useTools) takes workspaceId on every call and falls back to 'default' when it is not explicitly passed. There is no per-session stickiness: a multi-call MCP session working in one territory must re-specify workspaceId on every envelope, or its traces, sessions and states silently pile into the default workspace.

The infrastructure to avoid this already exists (SessionContextManager), but the envelope path doesn't use it. Raising as a design issue with options rather than a cold PR, since the cleanest fix touches a boundary you may have an opinion on.

Evidence

Profiling the workspace event store (.nexus-data/data/workspaces/) on a long-lived vault:

• ws_default = 119 MB / 26 shards; 91% of it is trace_added (9,933 events).
• ws_default trace_added per month: 147 → 2,381 → 3,351 → 4,054 (Feb→May) — steady, growing.
• Territory workspaces (Academico, Advocacia, Desenvolvedor, …) stay small.

Almost all of that is MCP-session activity that belongs to a territory but was filed under default. It then feeds the cold-start fullRebuild cost — see #158 (the bloat is what turns that design deficiency into a hard failure).

Why it happens

1. Schema nudges. The "Known-good example" in getTools.ts and useTools.ts hardcodes "workspaceId":"default"; the param description is 'Workspace ID. Optional. Defaults to "default".'; toolManager/types.ts says 'Use "default" for the global workspace. Do not invent workspace IDs.'. An LLM client mirrors the example.
2. The fallback. ToolCliNormalizer.ts (v5.9.5, ~L556): workspaceId: params.workspaceId || 'default'.
3. Existing infra is not consulted. SessionContextManager already maps sessionId → WorkspaceContext (getWorkspaceContext / setWorkspaceContext / updateFromResult). baseTool.getInheritedWorkspaceContext + a workspaceContext param already give workspace inheritance between internal tools. Neither is wired into the MCP envelope.
4. Secondary — name vs id. workspaceId: "Desenvolvedor" (name) and the workspace UUID resolve to distinct event stores, so even a careful caller can fragment a workspace's history by alternating the two forms.

#159 fixed the handler that ignored the envelope workspaceId; this is the layer above — the envelope having no notion of "the workspace this session is already working in."

Options

Prerequisite for any of the below: stop hardcoding default in the schema examples/descriptions — otherwise any stickiness mechanism just sticks to default on the first example-mimicking call.

• Option A — session-sticky resolution in ToolCliNormalizer. Resolution chain: explicit params.workspaceId → SessionContextManager.getWorkspaceContext(sessionId) → 'default'. An explicit workspaceId also writes the session context. First explicit call (typically getTools) establishes it; the rest inherit. Smallest change; one resolution point.
• Option B — A, plus loadWorkspace binds the session. loadWorkspace calls setWorkspaceContext(sessionId, …), so loading a workspace also means "this session is now in that workspace." Two explicit bind points, inheritance for the rest.
• Option C — surface the existing workspaceContext inheritance to the MCP envelope. Extend the internal workspaceContext mechanism (getInheritedWorkspaceContext / updateFromResult) to the getTools / useTools boundary, so the MCP path uses the same continuation Nexus already uses internally instead of a separate code path.

I lean toward C — it extends a mechanism that already exists rather than bolting session state onto the normalizer — but it touches the most surface and the envelope/result contract, so it's your call. Happy to prototype whichever option you choose, and to share the full trace profile / repro.

Environment

Nexus 5.9.5, Obsidian, macOS; used as MCP server via connector.js. Code references from the 5.9.5 tag.

[gcp007-ops]

Implemented Option C as a reference: fix/mcp-envelope-workspace-stickiness on the gcp007-ops fork (1 commit, +23/-5, typechecks clean against the 5.9.5 tag).

It turned out small. connector.ts already reads the session's WorkspaceContext and inherits workspaceId from it. The only missing piece was the write-back: nothing ever calls setWorkspaceContext on the MCP path, so sessionContextMap stays empty for MCP sessions and the inheritance read can only resolve to the default. The change captures an explicit envelope workspaceId and persists it via setWorkspaceContext after resolution — the first explicit call of a session establishes the workspace, later calls that omit it inherit. Plus the de-nudge (stop hardcoding default in the schema examples/descriptions).

Happy to open a PR if you'd like C, or adapt to A/B.

[gcp007-ops]

Update — built and deployed the Option C reference branch locally against 5.9.5 and tested it: it does not work. Worth recording why, because it blocks A/B/C as framed.

The session handle is workspace-scoped. SessionContextManager keys handles as ${workspaceId}::${handle}, and connector.ts resolves the session (validateSessionId, which takes workspaceId) before the workspace-context lookup. So when a call omits workspaceId, the handle resolves under default to a different internal session than the same handle resolved under a real workspace — getWorkspaceContext then finds nothing and falls back to default.

Empirically: two calls with the same session handle — call 1 with an explicit workspace, call 2 omitting it — produced two distinct session_created events in two different workspace stores, and call 2's trace landed in default.

Chicken-and-egg: resolving the session needs the workspace; inferring the workspace needs the session. Anything hung off getWorkspaceContext(sessionId) — A, B and C — hits this. The real fix is one layer down: handle resolution would need to be workspace-agnostic, or look the handle up across workspaces when workspaceId is omitted.

The de-nudge part of the branch (drop workspaceId from required, stop hardcoding default in the examples) stands on its own. The stickiness mechanism does not — I've reverted the local deploy.

[gcp007-ops]

Implemented and verified the real fix — branch fix/mcp-workspace-handle-resolution on the gcp007-ops fork (off the 5.9.6 tag, 2 commits, typechecks clean).

As the previous comment anticipated, the fix is one layer down, in validateSessionId:

• The signature workspaceId = 'default' becomes workspaceId?: string, so an omitted workspaceId is distinguishable from an explicit 'default'. (All three SessionContextManager.validateSessionId callers already pass string | undefined.)
• When workspaceId is omitted, a new resolveHandleAcrossWorkspaces() scans sessionHandleMap for the handle across every workspace and reuses the session only if it resolves unambiguously — a handle reused across workspaces, or unknown, falls back to default-scoped creation. An explicit workspaceId keeps the existing workspace-scoped lookup, so the deliberate "handles are workspace-scoped" design is untouched for that path.

Verified on the affected vault (built and deployed against 5.9.6): two calls with the same session handle — call 1 with an explicit workspace, call 2 omitting it — now produce a single session_created, and both traces land in the explicit workspace. Previously call 2 forked a second session under default.

The branch carries the de-nudge (workspaceId optional, no hardcoded default in the schema) + the connector write-back + this handle fix — together the complete session-sticky path. Happy to open a PR.

[gcp007-ops]

Correction — a self-review caught that the connector half of the earlier branch was dead code, so I've revised it.

The setWorkspaceContext write-back I had added sat in MCPConnector.callTool, which has no callers anywhere in the repo (only a unit test references it) — the live MCP tool path does not route through it, so that write-back never executed. The fix works regardless: it is carried entirely by the validateSessionId change — cross-workspace handle resolution returns the correct internal session and the live path derives the workspace from there.

The branch fix/mcp-workspace-handle-resolution is now 2 clean commits (force-pushed), +51/-14, connector.ts untouched:

• b6d6587c — drop workspaceId from the schema required array + de-nudge the descriptions.
• 170557be — validateSessionId: workspaceId optional + cross-workspace handle resolution.

Two correctness fixes from the review also went into the SessionContextManager commit: keys are matched exactly (reconstructed via handleKey) instead of endsWith(), avoiding ::-delimiter ambiguity; and an empty/whitespace workspaceId is normalized to "omitted" so it cannot create a session under "".

Re-verified on the affected vault: a call omitting workspaceId after an explicit first call reuses the same session and lands in the right workspace (single session_created, no fork).

[gcp007-ops]

Self-review of the reference branch fix/mcp-workspace-handle-resolution — known limitations and follow-ups, for transparency before evaluation. None block the core fix; recording the edges.

The fix is one-directional. It cleanly handles the common case — an explicit workspaceId on the first call, omitted on later calls (verified on a real vault). Two patterns are not covered:

• Ambiguous handle → silent fork. When the same friendly handle exists in 2+ workspaces, resolveHandleAcrossWorkspaces returns undefined (ambiguous) and validateSessionId forks a new default-scoped session, with no warning. For a handle that existed in default and another workspace this is a regression from the pre-fix behavior, where workspaceId defaulting to 'default' made every omitted call collapse deterministically onto one session. A logger.systemWarn on the ambiguous case would at least make it non-silent.
• Explicit-after-omit still forks. If the first call omits workspaceId (session created under default) and a later call passes an explicit workspace, the workspace-scoped lookup misses and a second session is forked. The fix adds the omit→cross-workspace path but leaves the explicit branch's exact-workspace lookup unchanged.

Both are inherent to keeping the workspace-scoped handle design — flagging them as the known edges rather than claiming full coverage.

Smaller follow-ups:

1. Standard-format sessionId path ignores workspaceId. The friendly-handle branch of validateSessionId honors workspaceId; the standard-format (s-… id) branch never reads it — a session reached via a standard id + explicit workspace falls to default. Pre-existing asymmetry, made visible by the fix.
2. Schema required vs validateContext. workspaceId was dropped from the getTools/useTools schema required array, but ToolBatchExecutionService.validateContext still hard-requires context.workspaceId. Not live — every path backfills via ToolCliNormalizer.normalizeContext — but schema and validator now disagree.
3. resolveHandleAcrossWorkspaces is O(n) over an unbounded sessionHandleMap. Each omitted-workspaceId call scans the whole map; the map only shrinks on explicit session deletion.
4. Type nit. resolveHandleAcrossWorkspaces returns seen.values().next().value guarded by size === 1 — correct at runtime, guarantee not expressed to the compiler.

Already fixed in the branch from this review: resolveHandleAcrossWorkspaces dedups handle matches by the entry object rather than by id, so a second-granular generateSessionId() collision can't mask a genuine cross-workspace ambiguity.