Module worktree 

Isolated git worktrees for subagents.

Parallel subagents that share one working copy collide. Per-path write locks (providers::tool::path_lock) stop two children from losing each other’s bytes, but nothing stops child A’s build from compiling child B’s half-finished edit, and nothing stops two children from making changes that are individually fine and jointly incoherent.

An isolated child gets its own checkout under the Mermaid data dir and never sees the user’s working copy. Its result comes back as a patch, applied under a lock once the child is done — so overlapping work fails loudly at merge time instead of interleaving silently mid-run.

Lifecycle

1. AgentWorktree::create adds a detached worktree at the project’s HEAD, replays the project’s uncommitted state into it, and commits that as the base. The child therefore starts from what the user currently has, not from the last commit.
2. The child runs, rooted at AgentWorktree::root.
3. AgentWorktree::merge_into_project diffs the worktree against the base and applies that patch to the project. On success it re-anchors the base, so a continuation of the same child merges only its new work rather than replaying what already landed.
4. AgentWorktree::destroy removes the checkout.

What is deliberately not carried in

Ignored files. target/, node_modules/, and .env stay behind, which is what makes a worktree cheap to create and is also why a child that needs to build pays a cold-cache build. Untracked-but-not-ignored files are carried, since those are usually the new files the user is midway through writing.

Structs

AgentWorktree

A subagent’s private checkout.

Enums

MergeOutcome

What happened when a child’s work was applied to the project.

Functions

gc_orphaned_worktrees

Best-effort removal of worktree directories older than max_age_days.