dsh-workflow-worktree

Readme

# 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`](https://github.com/icetomoyo/dsh_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.

| | manual worktree plugins | dsh-workflow-worktree |
|---|---|---|
| who creates it | you, or the model, on request | the workflow engine, per task |
| bound to | a name you pick | `runId` + `taskId` + session |
| lifetime | permanent until you delete it | the task's, with dirty-lane retention |
| entry point | agent tools / chat commands | `registerIsolationAdapter()` |

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

## Install

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

Then a workflow task can ask for isolation:

```js
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/dsh@0.1.0-rc.6`, `@dsh-external/workflow@0.1.2`, 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