Introduction

The @dsh-external/workflow plugin for DeepSeek Harness (DSH) reserves the registerIsolationAdapter() interface, but does not implement concrete logic. According to its README, when a workflow task declares isolation: 'worktree' but no adapter is configured, it fails directly with an error.

The dsh-workflow-worktree plugin fills this gap. It acts as an isolation backend, allowing each agent with write permissions to have an independent code checkout, and these checkouts can be retained after the task ends without polluting the main workspace.

Plugin Positioning

  • Name: dsh-workflow-worktree
  • Core Value: Git worktree isolation backend for DeepSeek Harness workflows
  • Maintainer: lisycotana
  • License: MIT
  • Category: Workflow

Core Features

This plugin implements the registerIsolationAdapter() interface, enabling DSH workflows to use the isolation: 'worktree' mode. Main features include:
* Isolated Checkouts: Provides an independent Git worktree for each workflow agent with write permissions.
* Crash Survivability: Records state through a manifest to ensure lane information can be recovered after a service crash.
* Fingerprint Cleanliness: Adds the worktree directory to .git/info/exclude to ensure git status in the main repository remains clean.

Installation and Activation

Before installation, ensure that @dsh-external/workflow is already installed. Install this plugin using the following commands:

dsh plugin --profile web add @dsh-external/workflow
dsh plugin --profile web add dsh-workflow-worktree

After installation, workflow tasks can request isolation mode.

Typical Usage

In a workflow script, specify isolation: 'worktree' directly in the spawnAgent configuration.

await wf.spawnAgent({
  name: 'refactor-auth',
  prompt: '…',
  isolation: 'worktree',  // 启用隔离
})

Design Constraints and Behavior

This plugin follows these design principles to ensure safety:

  1. Refuse to Degrade: If the directory is not a valid Git worktree, or the worktree cannot be created, prepare() refuses initialization, causing the task to fail directly. This is safer than silently running in the main tree.
  2. Return a New Agent: The returned agent is a completely new instance, and its session must be created inside the worktree instead of inheriting the parent session.
  3. Retain Uncommitted Changes: At task completion, if a lane still has uncommitted changes, it will not be discarded but marked as retained-dirty. Git itself prohibits deleting dirty worktrees, and this plugin follows this behavior.
  4. Keep State Clean: Workspace fingerprint validation depends on a clean git status. This plugin excludes the worktree directory via .git/info/exclude, preventing it from being misidentified as untracked files.
  5. Idempotent Dispose: The dispose() method can be called multiple times without throwing an error.

Storage Structure

The plugin maintains a manifest file and directory structure under the repository root:
* <repo>/.dsh-worktrees/lanes.json: Records lane metadata (runId, taskId, path, branch, base commit, session id, status).
* <repo>/.dsh-worktrees/wf-<runId>-<taskId>: The specific checkout directory.
* <repo>/dsh/wf-<runId>-<taskId>: The corresponding Git branch.

You can use the worktree_lanes tool to view lane status.

Known Limitations

  • No Merge Support: The v1 version only creates and recovers isolated workspaces, and does not handle diff/merge logic.
  • Dirty Lane Accumulation: For safety, the plugin only removes lanes that Git no longer recognizes and does not actively clean up dirty lanes still in use.
  • Single-Repository Limitation: One lane supports only one repository. If a task’s cwd is not at the repository root, the task is rejected.

References

  • Catalog Page: https://www.skillhub.cn/plugins/lisycotana/dsh-workflow-worktree
  • GitHub: https://github.com/lisycotana/dsh-workflow-worktree
  • Verified Environment: @deepseek-ai/dsh@0.1.0-rc.6, @dsh-external/workflow@0.1.2, git 2.47, Node 24, Windows