[RFC] Workspace-scoped configuration and runtime state for MCP, environment overlays, and project services

[TTTPOB]

Summary

DeepSeek Harness currently has a process/profile-wide Cordis composition and per-agent scoped registrations, but it does not have a workspace-scoped configuration and runtime plane.

This becomes visible with MCP:

• an @deepseek-ai/dsh-mcp-client row added through a profile patch creates one long-lived MCP client/server instance;
• its cwd and env are fixed when the plugin instance is loaded;
• its tools are normally registered in the root ctx.tools layer;
• every session in the same DSH Host can therefore see and call those tools, regardless of session.header.cwd.

As a result, a project cannot safely declare an MCP server that is automatically available only to sessions in that project.

The same missing scope also affects other project-bound services such as environment overlays, language servers, code indexes, persistent terminals, and local development services.

A concrete motivating case is a potential dsh-envrc plugin. Safely applying .envrc in DSH Web requires an environment owned by a workspace rather than mutation of the Host's process.env. The resulting environment should be reusable by Bash, persistent terminals, workspace MCP servers, LSP processes, and other subprocess consumers without leaking into unrelated sessions.

Expected behavior

A project-local configuration should be able to express something like:

{
  "mcp": {
    "project_database": {
      "transport": "stdio",
      "command": "project-database-mcp",
      "cwd": "."
    }
  }
}

with the following semantics:

Session in /work/project-a
  -> sees global tools + project-a tools
  -> uses an MCP process rooted at /work/project-a

Session in /work/project-b
  -> sees global tools + project-b tools
  -> cannot see or call project-a's MCP tools

Two sessions in /work/project-a
  -> may share the same project-a MCP process

A subagent inherited from a project-a agent
  -> remains attached to project-a unless explicitly moved

Project-local configuration should merge over Host-global defaults, and a project should be able to override or disable an inherited global MCP entry.

Current behavior

DSH profiles are composed at Host startup from:

1. bundle patches;
2. the profile's cordis.patch.yml;
3. $DSH_HOME/cordis.patch.yml;
4. command-line --patch overlays.

These layers configure the Host Cordis tree, not a tree selected from each session's workspace.

@deepseek-ai/dsh-mcp-client reflects that model:

• one plugin instance connects to one MCP server;
• stdio cwd and env are static plugin configuration;
• the connection lives until the plugin fiber is disposed or reloaded;
• discovered tools are registered through the plugin context;
• serverName reservations are currently unique across the application root.

A root/profile MCP row therefore represents a Host-level MCP server.

DSH does have scoped tool registrations and Agent Presets. Those are useful foundations, but they do not provide workspace-local configuration:

• a preset is selected as an agent capability composition, not discovered from session.header.cwd;
• selecting a workspace does not automatically select or compose a corresponding preset;
• a preset is not a canonical workspace runtime shared by all sessions in that workspace;
• MCP cwd and env remain static configuration rather than values derived from the owning workspace;
• project instruction discovery (AGENTS.md, AGENTS.local.md, CLAUDE.md, and CLAUDE.local.md) affects model instructions only, not Cordis services or MCP configuration.

In other words, DSH has an authoritative session cwd and scoped registries, but it lacks the layer that turns a workspace identity into scoped service instances and configuration.

Why this is more than an MCP convenience issue

1. Tool visibility

If project A adds an MCP row through the profile, sessions in project B receive the same root tool registrations.

Tool naming or prompting cannot provide strong isolation. The project-B agent should not receive project-A tool schemas in the first place.

2. Process working directory

A stdio MCP server receives the plugin's configured cwd, not the cwd of the session making the tool call.

A project-sensitive server may therefore read or modify the wrong repository when used from another session.

3. Environment and secrets

A project MCP may need a virtual environment, Nix/direnv environment, database URL, or project-specific credential.

Injecting that environment into a root MCP instance makes it shared by every session that can call the instance. Mutating the Host's process.env would be worse: DSH Web can host concurrent sessions from unrelated workspaces.

4. Stateful servers

Many MCP servers keep indexes, caches, database handles, or in-memory state. One process cannot simultaneously have two different project roots and OS environments unless the server protocol explicitly models them.

5. Other workspace services

The same scope mismatch appears when implementing:

• per-project environment overlays;
• project-specific LSP processes;
• local code indexes;
• project terminals or persistent shells;
• file watchers and development servers.

Adding independent ad hoc fixes for each consumer would duplicate workspace identity, lifetime, reload, and disposal logic.

6. A concrete blocked consumer: safe .envrc integration

This issue became clear while investigating a possible dsh-envrc plugin.

A simple implementation could run:

direnv export json

and assign the result to the Host's process.env. Some OpenCode plugins take this approach, but it is unsafe for DSH Web:

Session A in /repo/a
  -> loads PATH, VIRTUAL_ENV, and secrets from /repo/a/.envrc

Session B in /repo/b
  -> shares the same Host process

The last session to mutate process.env would affect unrelated sessions and any subsequently spawned Host service. Removed variables would also require explicit unset semantics, and project secrets would be exposed to more subprocesses than intended.

Injecting the environment only into one-shot Bash is safer, but incomplete. Persistent Bash/PTY, workspace MCP servers, LSP processes, and other subprocess consumers use separate creation paths. Each consumer could grow an independent direnv adapter, but that would duplicate:

• workspace-root resolution;
• .envrc trust state;
• environment loading and caching;
• set/unset semantics;
• change detection;
• failure policy;
• reload and disposal behavior;
• session and workspace isolation.

A workspace runtime would provide a natural owner for this behavior:

Workspace A runtime
├── trusted direnv snapshot A
├── Bash processes using A
├── persistent terminal processes using A
├── MCP processes using A
└── LSP processes using A

Workspace B runtime
├── trusted direnv snapshot B
└── unrelated processes using B

The environment would be copied into each workspace-owned child process at spawn time. The DSH Host itself would remain environment-neutral, and global services would not accidentally inherit project variables.

This does not imply automatically trusting .envrc. An .envrc is executable project code. A safe implementation should never run direnv allow automatically, should bind trust to a canonical file/path and content revision, should avoid logging exported values, and should make fail-open versus fail-closed behavior explicit.

The important architectural requirement is therefore not built-in direnv support. It is a reusable workspace-owned environment capability that a dsh-envrc plugin can provide and Bash, PTY, MCP, LSP, and other workspace process providers can consume.

Prior art: OpenCode server mode

OpenCode solves this even when one app server serves multiple GUI workspaces.

The GUI creates a directory-bound SDK client and sends the directory with each request. The server resolves the request to an InstanceContext and caches instance state by normalized directory:

request(directory=/repo/a)
  -> Instance A
  -> merged Config A
  -> MCP State A
  -> tools A

request(directory=/repo/b)
  -> Instance B
  -> merged Config B
  -> MCP State B
  -> tools B

Global and project opencode.json/opencode.jsonc files are merged per instance. MCP clients, LSP state, plugins, and tool assembly read the current instance state.

This does not require one server process per GUI project. One server multiplexes multiple directory instances while keeping their service state separate.

The important idea is not OpenCode's exact config format. It is the existence of a directory/workspace runtime between the global server and individual sessions.

Suggested design direction

This section is intentionally brief; the primary request is for a supported workspace scope, not a specific implementation.

1. Introduce a canonical workspace runtime

A Host service could resolve and retain a runtime by canonical workspace identity:

interface WorkspaceRuntimeRegistry {
  acquire(input: {
    cwd: string
    session: Session
  }): Promise<WorkspaceRuntimeLease>
}

interface WorkspaceRuntime {
  root: string
  config: WorkspaceConfig
  context: Context
}

The runtime could be keyed by a canonical project/worktree root rather than by raw path spelling.

Sessions in the same workspace could share it. The final lease release would dispose workspace-owned plugin fibers and processes.

2. Allow workspace runtimes to contribute environment overlays

A workspace runtime should be able to expose an environment snapshot independently of Host process.env:

interface WorkspaceEnvironmentSnapshot {
  readonly set: Readonly<Record<string, string>>
  readonly unset: ReadonlySet<string>
  readonly revision: string
}

interface WorkspaceRuntime {
  readonly root: string
  readonly config: WorkspaceConfig
  readonly context: Context
  readonly environment?: WorkspaceEnvironmentSnapshot
}

The exact API is only illustrative. The important properties are:

• values are owned by one canonical workspace;
• deletion is representable rather than approximated by omission;
• consumers receive an immutable snapshot;
• environment values are not added to logs, model context, or Host-global state;
• a revision change can invalidate or restart workspace-owned processes;
• global processes do not receive the overlay unless explicitly configured.

A dsh-envrc plugin could implement this capability by evaluating an already trusted .envrc through direnv export json, caching the result per workspace, and publishing a new snapshot when direnv's watched inputs change.

Process providers could consume the same snapshot at their actual spawn boundaries:

one-shot Bash       -> ShellExecRequest.env
persistent Bash/PTY -> terminal spawn environment
workspace MCP       -> stdio transport environment
workspace LSP       -> language-server spawn environment

This keeps environment policy separate from each consumer while preserving consumer-specific lifecycle behavior. Long-lived MCP, LSP, and terminal processes would normally need restart or explicit refresh after an environment revision changes; changing a cached map cannot modify an already running process's OS environment.

3. Add workspace scope to the existing scope chain

A useful lookup order could be:

Host/global
  -> workspace
  -> preset
  -> agent/session

Registrations made through the workspace context would be visible only to agents attached to that workspace.

This would let the existing layered ctx.tools design provide correct visibility without checking cwd inside every tool execution.

The exact order of workspace and preset scopes should be decided explicitly, especially for shadowing and restrictions.

4. Start with a declarative project configuration

Automatically loading arbitrary Cordis modules from a repository is equivalent to executing project code and needs a trust decision.

A safer first version could support a restricted declarative file, for example:

<workspace>/.dsh/config.jsonc

with a narrow initial schema such as:

{
  "mcp": {
    "project_database": {
      "transport": "stdio",
      "command": "project-database-mcp",
      "args": [],
      "cwd": ".",
      "enabled": true
    }
  }
}

Possible precedence:

Host defaults
  -> workspace-root config
  -> nearer directory config, if nested overrides are supported
  -> explicit session override

A workspace should be able to disable an inherited global entry with enabled: false.

Full workspace Cordis composition could be considered separately, with explicit trust and approval semantics.

5. Make MCP instances workspace-owned

For a local MCP entry:

• resolve relative cwd against the canonical workspace root;
• construct its environment without mutating Host process.env;
• register its tools in the workspace scope;
• allow the same serverName in unrelated workspace scopes;
• share one instance among sessions in the same workspace when configured to do so;
• close the client and process when the workspace runtime is disposed;
• reload only that workspace when its configuration changes.

A global MCP entry should remain possible and retain its existing Host-wide semantics.

6. Bind sessions and subagents explicitly

A session should record or deterministically derive the workspace runtime it joined.

Resume should reattach to the same workspace identity. Subagents should inherit the parent's workspace by default, while an explicit cross-workspace delegation would require a separate operation and permission decision.

7. Treat workspace config as a trust boundary

Project configuration can start executable programs and supply environment references. It should not become trusted merely because a user opened a directory.

At minimum, the design should define:

• whether first use requires approval;
• whether trust is tied to canonical path and content hash;
• what changes invalidate trust;
• which environment variables or credential references may be supplied;
• whether untrusted config is ignored, reported, or blocks workspace activation;
• how symlinks and worktrees affect workspace identity.

Acceptance examples

Project-only MCP

Global config: no "database" MCP
Project A config: defines "database"
Project B config: no "database"

Expected:

• an Agent in A sees the database tools;
• an Agent in B does not receive their schemas;
• a direct attempt to execute the A-only tool from B fails lookup before transport;
• B does not inherit A's MCP environment.

Same MCP name in two projects

Project A: "project" -> command A, cwd A
Project B: "project" -> command B, cwd B

Expected:

• both workspace runtimes can use the local name project;
• each Agent sees only its workspace's definition;
• the two stdio processes have different cwd/environment values;
• disposing A does not disconnect B.

Global default overridden by a project

Global: "search" enabled
Project A: "search" disabled
Project B: no override

Expected:

• A does not see the search tools;
• B continues to use the global server;
• the override does not mutate the Host-global configuration.

Concurrent Web sessions

Run sessions in A and B concurrently and call their MCP tools.

Expected:

• no tool-schema leakage;
• no cwd/environment crossover;
• no shared mutable client state unless the two sessions intentionally share one workspace runtime.

Workspace environment isolation

Project A:
  .envrc exports VIRTUAL_ENV=/repo/a/.venv
  .envrc prepends /repo/a/bin to PATH

Project B:
  .envrc exports VIRTUAL_ENV=/repo/b/.venv
  .envrc prepends /repo/b/bin to PATH

Expected:

• Bash, PTY, workspace MCP, and LSP processes created for A receive only environment A;
• corresponding processes for B receive only environment B;
• the DSH Host's process.env is not mutated;
• a global MCP server receives neither project environment by default;
• environment values never appear in logs, tool schemas, or model-visible status output;
• removing a variable from A is represented as an unset for future A processes;
• changing A's environment does not restart or invalidate B's services;
• blocked or untrusted .envrc files are not automatically allowed.

Questions for maintainers

1. Is a workspace/runtime scope already planned between Host and Agent Preset scopes?
2. Should workspace-local configuration initially be restricted to declarative capabilities such as MCP, rather than arbitrary Cordis rows?
3. Should the canonical lifetime be per directory, Git worktree, DSH workspace record, or another identity?
4. Should global MCP entries be inherited into every workspace by default, with project-level override/disable support?
5. Could @deepseek-ai/dsh-mcp-client be adapted to a workspace context, or should a manager/provider own workspace MCP instances above it?
6. How should workspace scope compose with Agent Presets and subagent inheritance?
7. Should a workspace runtime expose a generic environment-overlay capability so external plugins such as dsh-envrc can supply one snapshot to Bash, PTY, MCP, LSP, and other workspace process providers?

[TTTPOB]

Update: community precedent found — re-scoping this RFC

Since posting, two community plugins were shared in #1320 (by @Momojie-S):

• @momojie-s/dsh-workspace-mcp — reads <session-cwd>/.dsh/mcp.servers.yml, connects the declared MCP servers and registers their tools into the agent scope on agent/created, with chokidar-based hot reload and teardown/disconnect on agent/disposed.
• @momojie-s/dsh-workspace-env — injects <workdir>/.env into pwsh invocations (currently Windows/pwsh only).

The plugin's ADR-0002 makes the architectural call this RFC was circling around: agent-scoped registration already delivers per-workspace isolation without a new scope layer — tools die with the agent, so "switch workspace = switch agent = switch toolset", and nothing leaks across projects. The documented trade-off is that sessions in the same workspace do not share one MCP process, and agent rebuilds reconnect.

So the RFC should be re-scoped: per-workspace isolation is largely solved at the agent layer. What is still missing is the workspace-level shared runtime:

1. Canonical workspace identity derived from session.header.cwd (normalization, worktrees), reused across sessions and reattached on resume.
2. Sharing: one MCP process per workspace (not per agent), reference-counted, disposed when the last lease releases.
3. Environment overlays owned by the workspace (.envrc / .env), injected at subprocess spawn boundaries (Bash, PTY, MCP, LSP) without mutating Host process.env.
4. A declarative workspace config format — the community plugins already use <workspace>/.dsh/mcp.servers.yml; a more general form could be .dsh/cordis.yml speaking the same plugin-row dialect as profiles, so plugins like dsh-workspace-mcp could fold into one mechanism later.

Revised questions for maintainers:

1. Is a workspace scope between preset and agent planned, or is agent-scoped registration the intended isolation boundary for now?
2. If a workspace runtime is added, should it be a plugin-level service (composition) rather than core machinery?
3. Should the .dsh/ config format be standardized (e.g., reusing the Cordis YAML dialect) so existing workspace plugins can be folded into one mechanism?
4. Is a workspace-owned environment snapshot a reasonable capability for the runtime to expose to process providers?

The trust question from the original post can stay out of scope for a first version.

[nearyou]

This RFC identifies a significant architectural gap in the current model: workspace identity is currently implicit through session context, but runtime-owned resources such as MCP servers, LSP processes, terminals, and environment overlays require an explicit lifecycle boundary.

The proposed workspace runtime abstraction appears to be a strong direction because it provides a single ownership model for configuration, process isolation, resource sharing, and cleanup. This avoids duplicating workspace-awareness logic across individual plugins.

One area worth defining further is workspace identity and lifecycle management. In real-world environments, a workspace may represent a directory, Git worktree, monorepo package, or another logical project boundary. Establishing a canonical identity model early would help prevent resource collisions and unexpected sharing.

It may also be worth considering lazy runtime initialization and reference-counted disposal so workspace services are only created when required and safely released when no sessions remain attached.

Overall, this seems like a foundational improvement that could provide a consistent platform for future workspace-aware capabilities beyond MCP.

[TTTPOB]

Another process-level config source: the new hooks subsystem

The harness recently gained a packages/hooks subsystem (in master): @deepseek-ai/dsh-hooks-claude-code and @deepseek-ai/dsh-hooks-codex bridge existing Claude Code / Codex shell-hook configs (hooks.json or a settings hooks key) onto the harness's typed interception points (tools/pre-execute, tools/post-execute, agent/pre-step, agent/turn-stopping, agent/session-start, subagent/start|end).

Its config scope matches the exact pattern this RFC describes:

• Config is process-level: configPath is parsed once at load and resolved against the process launch cwd; the README explicitly carries TODO(per-session-hook-config) — there is no session/new.cwd-based config discovery yet. One config applies to the whole process, exactly like a global MCP row.
• Execution is already session-scoped: hooks run with the session's cwd as the hook process working directory, and payloads carry session_id — so only the config discovery / instance ownership half is missing.

Hook config is therefore a third process-level configuration source next to MCP rows and environment overlays (.envrc / .env). The same workspace layer — a .dsh/cordis.yml row mounting the bridge with configPath: ./.claude/hooks.json — would give every project its own hooks, with the identical ownership story: config discovered per workspace, bridge instance per workspace, hook processes already per-session.

Suggested acceptance scenario to add: per-project hooks — project A defines its own hooks.json entries, project B has none (inherits global), and a hook declared only in A never fires for B sessions; plus a project-level configPath override of an inherited global bridge row.

[TTTPOB]

Implementation update: I built a pure out-of-tree prototype for this RFC and published it here:

https://github.com/TTTPOB/dsh-workspace-overlay

It targets DSH 0.1.0-rc.6 and implements canonical workspace scopes, trusted <workspace>/.dsh/cordis.yml composition mounting, workspace-local preset generations for the public async ctx.agents.create/resume paths, and per-workspace MCP routing with whole-namespace masking. The repository includes Chinese and English READMEs, the implementation plan, focused lifecycle tests, and isolated-profile verification notes.

The documented v1 limits remain explicit: synchronous AgentLoop.create() / direct-factory paths are unsupported, and live HMR of the structural decorators/manager is not promised.

[TTTPOB]

Follow-up from implementing the out-of-tree prototype: the low-level scope graph is flexible enough, but the current high-level preset mount API owns a fixed placement and the only re-link authority. That is the seam the prototype had to reconstruct.

Evidence from current master

Pinned source revision: 47f943859bef60e4160492346772ded9b24f765a.

The limitation is not in dsh-scope:

• bindScopeParent() already permits an arbitrary parent and returns the sole re-link authority.
• createScope(ctx, key, { parent }) already supports custom placement.

The fixed topology comes from the high-level AgentPresets provider:

• mount() always resolves the provider's global standing mount, calls bindScopeParent(agentKey, standing.key), and stores the binding privately.
• composeFrom() likewise performs a fresh direct bind to the parent's exact standing key.
• recompose() can move the agent only through the provider-private binding.
• ensureStanding() is private, caches only by preset id, and creates the mount with createScope(this.selfCtx, key)—there is no caller-provided parent placement.
• Readers also encode the direct-parent topology: standingMountFor() reads only scopeParentOf(agentKey) and matches that exact key.

There is already a useful lower-level primitive: mountPreset(scopedCtx, preset) mounts and audits a preset under any supplied scoped context. However, it returns no mount handle and does not expose the provider's standing-generation cache or binding lifecycle. A third-party placement layer therefore has to reproduce generation caching, stamp/single-flight behavior, joined membership, and rebind bookkeeping even though the actual preset composition is still mounted by the official helper.

This is why inserting a workspace scope with the native primitives is not enough by itself. The desired chain is:

global -> workspace -> preset generation -> agent

but the current high-level call attempts a second independent bind:

agent -> workspace       (created by the workspace setup)
agent -> standing preset (attempted by AgentPresets.mount)

A scope key has one parent, and only the original ScopeParentBinding can re-link it, so the two integrations cannot compose through the public API.

Proposed minimal, generic modification

I do not think dsh-scope needs workspace-specific concepts. The missing API belongs to AgentPresets and can be placement-generic.

One possible split is:

export interface PresetMountPlacement {
  /** Context that owns the mounted subtree. */
  ctx: Context
  /** Enclosing scope in the dsh-scope parent chain. */
  parent: ScopeKey
}

export interface PresetMountRef {
  readonly presetId: string
  readonly key: ScopeKey
}

export interface PresetJoinOptions {
  /** Existing ancestry authority, when another setup layer performed the first bind. */
  binding?: ScopeParentBinding
}

interface AgentPresets {
  ensureMount(id?: string, placement?: PresetMountPlacement): Promise<PresetMountRef>
  join(agentCtx: Context, mount: PresetMountRef, options?: PresetJoinOptions): void
  joinFrom(agentCtx: Context, parentCtx: Context, options?: PresetJoinOptions): string | undefined
}

Semantics:

1. Omitting placement preserves today's global standing behavior and compatibility.
2. A supplied placement is validated (scopeOf(placement.ctx) === placement.parent) and cached by (placement.parent, presetId), not only presetId.
3. The provider creates that generation with createScope(placement.ctx, mountKey, { parent: placement.parent }), then uses the existing mountPreset() audit path.
4. join() either creates the first binding or uses the supplied authority to rebind(mount.key); the provider retains that authority for later recompose().
5. joinFrom() still inherits the parent's exact generation synchronously, but can use an existing child binding instead of attempting a second bind.
6. Existing mount() / composeFrom() / recompose() become compatibility conveniences over these primitives.

The exact naming is open; the important separation is:

resolve/ensure a mounted generation at a caller-selected parent
                         +
join/re-link an agent using either a new or caller-owned binding

This is not workspace-specific. It would also allow any future deployment layer between global and preset (tenant, project, policy domain, test runtime) without copying the provider.

Companion seam for Agent setup

The prototype still has to wrap the public AgentRegistry.create() / resume() forwarding methods to prepend the awaited workspace acquire/bind transaction while preserving the caller's setup.

A small effect-owned setup decorator registry would remove that second patch point, for example:

ctx.agents.decorateSetup((next) => async (agentCtx) => {
  // awaited placement setup, effect-owned rollback
  return await next?.(agentCtx)
}) // -> disposer

create() and resume() would apply the registered decorators before forwarding to the factory. This keeps the existing awaited publication boundary and remains generic to other setup layers.

Prototype evidence

The out-of-tree implementation and tests are here:

https://github.com/TTTPOB/dsh-workspace-overlay

It proves the target topology with the existing native scope primitives and official mountPreset()/reader APIs, but currently needs reversible wrappers for AgentRegistry.create/resume and AgentPresets.mount/composeFrom/recompose, plus a parallel workspace-local generation registry. A parent-aware ensure/join seam and an Agent setup decorator seam would let those wrappers and most duplicated generation/binding state disappear without adding a workspace concept to the core scope package.