Lesson 10 — Worktrees and Execution Environments

Outcome

Create, verify, persist, and safely refuse destructive cleanup of a Task worktree; wrap it as the first Execution Environment.

Why this comes now

Isolation is central to parallel delegated work, but mature tools show that worktree lifecycle has many sharp edges. We introduce the abstraction and safety rules before agents depend on it.

Understand

Worktree creation is a pipeline, not one command: inspect → resolve base → choose stable path/branch → add → verify → optional trusted setup. Paths use immutable Project/Task IDs so renaming a Task cannot invalidate provider state tied to cwd.

ExecutionEnvironment is separate from AgentAdapter. Today it means LocalWorktree; tomorrow it can mean Docker/SSH without rewriting Claude/Codex adapters.

Build the real project

1. Add Worktree record/lifecycle and migration.
2. Define stable XDG worktree path from IDs.
3. Implement CREATE_WORKTREE Operation handler.
4. Verify branch/path/base revision after creation.
5. Add LocalWorktreeEnvironment exposing prepared cwd/environment.
6. Add cleanup eligibility checks and a removal Operation.
7. Test renaming Task does not change path.
8. Create dirty file and prove automatic removal is refused.
9. Add a minimal Project Trust flag; do not run project-defined setup scripts yet.

Completion gate

All worktree tests use real temp repos. Dirty work is never deleted. Re-running creation reconciles expected existing state. Worktree path is stable across title changes.

Pitfalls to avoid

Do not use age as deletion permission. Do not create hidden user-visible “autosave” commits just to make cleanup easier. Be aware a target branch can be checked out in another worktree.

References

Required: git-worktree, Emdash worktree pipeline: https://github.com/generalaction/emdash/blob/main/agents/workflows/worktrees.md . Pitfalls: https://github.com/BloopAI/vibe-kanban/issues/1897 and https://github.com/BloopAI/vibe-kanban/issues/2993

Checkpoint

M3 is complete when you would trust Forge to create and refuse unsafe deletion of a worktree containing your own uncommitted code.