dsh-worktree

Readme

# dsh-worktree

Filesystem isolation for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) subagents via git worktrees. Subagents already isolate messages, permission policy, and tool sets — this plugin isolates the **filesystem**: each child runs in its own worktree under `<repoRoot>/.dsh/worktrees/`, sharing the repository object store while keeping the working tree private.

Two entries, one package:

- **`dsh-worktree`** — the `ctx.worktree` service: create/restore/list/remove git worktrees with strict slug validation, change protection, best-effort post-creation setup, and periodic sweeping of stale temporary worktrees.
- **`dsh-worktree/commands`** — the human-facing `/worktree create <slug> | list | remove <slug> [--discard]` slash commands.

## Install

Requires the DeepSeek Harness `next` line (`dsh` ≥ 0.1.0-rc.6). From GitHub:

```sh
dsh plugin --profile default add github:you/dsh-worktree
```

pnpm ≥ 10 asks you to allow the build — add the printed package key to the profile's `pnpm-workspace.yaml`:

```yaml
allowBuilds:
  dsh-worktree: true
```

Then re-run the `add`. From npm (prebuilt):

```sh
dsh plugin --profile default add dsh-worktree
```

## Usage

```
/worktree create feature/demo    → creates .dsh/worktrees/feature+demo, branch worktree-feature+demo
/worktree list                   → name/path/branch rows
/worktree remove feature/demo    → refuses while dirty; --discard forces
```

Service API (for plugin authors):

```ts
const lease = await ctx.worktree.acquire('agent-abc1234', cwd)  // create/restore at HEAD
// ...run an isolated child with its session header.cwd = lease.entry.path...
const { kept, path, branch } = await lease.release()            // clean → removed; dirty → kept + reported
```

- Worktrees live at `<repoRoot>/.dsh/worktrees/<flatSlug>/`; nested slugs flatten `/` to `+` (`team/alice` → `team+alice`), branch `worktree-team+alice`.
- `validateSlug` enforces `[a-zA-Z0-9._-]` per segment, length ≤ 64, rejecting `.`, `..`, `//`, and leading/trailing separators.
- Post-creation setup is best-effort: copies project `.dsh` config, inherits `core.hooksPath`, symlinks `node_modules`/`.venv`/`vendor` (Windows symlink failures degrade to a warning), copies `.worktreeinclude`-listed ignored files.
- Change detection is fail-closed: any git failure counts as "has changes", so a broken worktree is kept rather than deleted.
- Per-repository mutations serialize; concurrent acquires of the same slug are idempotent (fast restore, no git subprocess).

## Configuration

```ts
interface Config {
  sweepIntervalMs?: number  // default 3_600_000 (1h)
  sweepMaxAgeMs?: number    // default 86_400_000 (24h); only agent-* temp worktrees are swept
}
```

## Automatic subagent isolation

The one-line integration — `subagent(..., worktree: true)` creating a worktree per child run with automatic cleanup — needs a small upstream capability in `dsh-subagent`/`dsh-tool-subagent` (an optional `cwd` on `SubagentStartRequest`). See [UPSTREAM-PR.md](./UPSTREAM-PR.md) for the exact changes and their in-tree implementation; until the upstream accepts them, use `ctx.worktree.acquire()` in your own plugins or the `/worktree` commands manually.

## Known limitations

- **In-process isolation only** — child-session cwd overrides are stamped by in-process backends; out-of-process backends (acp, claude-code, codex, dsh-sdk) ignore them.
- **No cross-process sharing** — one DSH instance owns its worktrees.
- **No merge strategy** — merging kept worktrees is the delegating agent's job (`git merge worktree-<flatSlug>`).

## Contributing to the ecosystem

- Tagged with the `dsh-plugin` topic — [browse other plugins](https://github.com/topics/dsh-plugin).
- Tests run with `pnpm install && pnpm test` (real temporary git repositories, no network).
- The behavior ported here comes from [CsyCode](https://github.com/you/csycode) chapter 14's worktree isolation.

## License

MIT