dsh-workflow-worktree

Git worktree isolation for DeepSeek Harness workflows — every write-capable
workflow agent gets its own checkout that cannot touch your working tree, and
survives a crash.

The gap this fills

@dsh-external/workflow reserves a
seam for worktree isolation and deliberately ships no implementation. Its README
is explicit: "worktree 通过 registerIsolationAdapter() 接入，未注册时明确失败."

So a workflow task declaring isolation: 'worktree' fails today:

workflow worktree isolation requested but no isolation adapter is configured

This plugin is that adapter.

Not another worktree manager

Several plugins manage git worktrees. This one is not for you to use — it is for
the workflow engine to use.

If you want to fork a workspace and keep working in it, use a manual plugin such
as dsh-worktree. If you want
spawnAgent({ isolation: 'worktree' }) to work, use this one. They coexist.

Install

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

Then a workflow task can ask for isolation:

await wf.spawnAgent({
  name: 'refactor-auth',
  prompt: '…',
  isolation: 'worktree',      // ← previously a hard failure
})

What a lane is

<repo>/.dsh-worktrees/wf-<runId>-<taskId>     the checkout
dsh/wf-<runId>-<taskId>                       its branch
<repo>/.dsh-worktrees/lanes.json              the manifest

The manifest records runId, taskId, worktree path, branch, base commit,
session id, and status. Git already knows which worktrees exist; it does not
know which workflow task owned one. That binding is what survives a crash.

Inspect lanes with the worktree_lanes tool:

run-7/task-3  dirty
  worktree: /repo/.dsh-worktrees/wf-run-7-task-3
  branch:   dsh/wf-run-7-task-3
  base:     d1015c2e…
  changed:  ?? agent-work.txt

Design commitments

Never degrade to the shared checkout. If the directory is not a git working
tree, or the worktree cannot be created, prepare() rejects. The engine then
fails the task loudly. An isolation backend that quietly runs the agent in your
tree is worse than one that refuses, because the failure is invisible until the
damage is done.

The returned agent is a new agent. The engine does
parent = isolation.parent and reads cwdOf(parent) afterwards, so the
returned agent's session must be created in the worktree. Returning the
caller's parent unchanged type-checks and silently defeats the whole plugin —
verify-contract.mjs asserts this binding directly.

Uncommitted work is never discarded. A lane that still has changes when the
task ends is retained and marked retained-dirty, with its path and branch
logged. Git refuses to remove a dirty worktree; so does this.

Your git status stays clean. The lane directory is added to
.git/info/exclude, not to a tracked .gitignore — an isolation backend must
not author changes in the tree it protects. Without this the directory reads as
?? .dsh-worktrees/ and perturbs the workspace fingerprints workflow
verification takes around each task.

dispose() is idempotent. The engine calls it on task settle, run failure,
and explicit stop.

Verified against

@deepseek-ai/[email protected], @dsh-external/[email protected], git 2.47, Node 24,
Windows.

verify-contract.mjs runs the adapter against a real repository and asserts the
load-bearing invariants:

CONTRACT cwd bound to worktree : true
CONTRACT not the main checkout : true
main tree after agent write    : []
dirty lane retained on dispose : retained-dirty
clean lane removed             : true
double dispose survived        : true

Known limitations

• No merge. This creates and recovers isolated workspaces; deciding what to
  do with the result is the operator's. Diff/merge-preflight are deliberately
  out of scope for v1.
• Dirty lanes accumulate. Retention is the safe default; recoverLanes()
  prunes only lanes git no longer knows about, never live ones.
• One repository per lane. A task whose cwd is outside the repository root
  is refused rather than isolated somewhere surprising.

License

MIT