dsh-worktree

Filesystem isolation for 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:

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:

allowBuilds:
  dsh-worktree: true

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

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):

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

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.
• Tests run with pnpm install && pnpm test (real temporary git repositories, no network).
• The behavior ported here comes from CsyCode chapter 14's worktree isolation.

License

MIT