Introduction

In DSH (DeepSeek Harness) single-process model, managing configuration isolation and dynamic updates for multiple workspaces usually requires restarting the host or using complex scripts. The dsh-workspace-overlay plugin introduces workspace-level Scope, Composition hot reloading, and a workspace-aware MCP manager to solve the issues of multi-environment configuration sharing and dynamic changes.

Plugin Overview

This is an out-of-tree DSH bundle maintained by TTTPOB under the MIT license. It aims to provide a shared Cordis scope service (workspaceCordis) for each canonical workspace path, supports mounting and hot reloading workspace composition, and provides Agent integration and workspace-based MCP management features.

Core Features

This plugin mainly includes the following capabilities:

  1. Shared Workspace Scope: Provides a shared Cordis scope (workspaceCordis service) for each canonical workspace path. All consumers of the same workspace (sessions, agents) lease the same scope; the scope is disposed when the last lease is released.
  2. Composition Hot Reloading: Supports mounting and hot reloading workspace-scoped Cordis composition. The first lease mounts <workspace>/.dsh/cordis.yml as the composition for that workspace, and when watching is enabled by default, editing and saving triggers a full-tree hot reload.
  3. Agent Integration: Provides Agent integration that takes over the official agentPresets mount/composeFrom/recompose flow to generate workspace-local presets.
  4. Workspace-aware MCP: Provides a workspace-aware MCP manager that supports process control at the global/serverName/workspace level and same-name namespace shadowing. It also ports the official rc.6 MCP core (transport/tool sync/connection supervisor).
  5. Dependencies: Runtime dependencies include DSH service package 0.1.5-rc.2, Cordis 4.0.2, Include 1.0.7, and Loader 1.0.3.

Installation and Enablement

To install this plugin, use the dsh plugin command with a profile. After installation, you can view the injected configuration entries with dsh --dump-config.

dsh plugin --profile web add https://github.com/TTTPOB/dsh-workspace-overlay/releases/download/v0.1.1/dsh-workspace-overlay-0.1.1.tgz
dsh --profile web --dump-config

After installation, the plugin inserts three configuration entries into dsh.bundle.patch: workspace-registry, workspace-mcp-manager, and workspace-agent-integration.

Typical Usage

  1. Configure Trust and Watching: After installing and enabling the plugin, it sets trustWorkspaceConfig and watchWorkspaceConfig to true by default. This means <workspace>/.dsh/cordis.yml will be trusted and mounted.
  2. Configure Workspace MCP: Add MCP line configuration in the workspace’s .dsh/cordis.yml.
  3. Hot Reload Control: To adjust the hot reload behavior, explicitly configure reloadDebounceMs (default 150 ms). If you do not want to watch file changes, set watchWorkspaceConfig to false.

Notes and Limitations

When using this plugin, be aware of the following limitations and dependencies:

  1. Certain Files Are Not Watched: The plugin does not watch the preset agent.cordis.yml, nor does it watch JS/package modules imported by the composition. Changes to these files require manually touching them or re-saving the top-level cordis.yml to trigger a reload.
  2. Tool Calls Are Not Interrupted: The plugin does not drain in-flight third-party tool calls. Pending lifecycles for third-party tools are retained until they end naturally.
  3. Failure Policy: The plugin does not perform blue-green deployment and does not retain the last known-good tree after a failure. This is consistent with the runtime model of DSH global patch HMR.
  4. Provider HMR Is Not Supported: The plugin’s own structural providers (such as workspace-agent-integration) do not support live HMR. During development, you must first dispose all live Agents or restart the Host.
  5. RC Compatibility: The RC compatibility scope is declared in package.json and does not automatically guarantee cross-RC baseline compatibility.
  6. Permissions and Source: The plugin runs with the current DSH process permissions. It is recommended to inspect the source code and license before installation.

Summary

dsh-workspace-overlay provides a complete workspace isolation and dynamic configuration solution for DSH. Through the workspaceCordis scope and hot reload mechanism, developers can manage Agent and MCP configurations across multiple workspaces without restarting the host, making it suitable for technical teams that need fine-grained control over workflow environments.