worktree

Worktree

Create and maintain worktree-per-writer isolation for agent-toolkit swarm so each role works on its own branch without stepping on others. Integrates with swarm-handoff promotion and github-cli-workflow for PRs.

When to use

• Swarm needs isolated writes: implementer, reviewer, integrator each own a worktree/branch.
• worktree_failed trace or find_repo_root error on .git file worktrees.
• Before swarm promote — ensure the handoff's worktree is clean and pushable.
• Cleanup after a run is promoted or abandoned.

Prerequisites

• Repo is Git with git worktree available (git worktree --help).
• Swarm run exists: .agent-toolkit/swarm/runs/<run-id>/state.json; worktrees live under .agent-toolkit/swarm/runs/<run-id>/worktrees/<role>-<short>/.
• find_repo_root uses git rev-parse --git-common-dir to handle worktree .git files (not directories).

Workflow

1. Inspect current worktrees

git worktree list
agent-toolkit swarm status --run-id <run-id> --json | jq '.worktrees'
# Expected: {implementer: {path, branch, commit}, reviewer: {path, branch}, ...}
cat .agent-toolkit/swarm/runs/<run-id>/state.json | jq '.trace | map(select(.event | contains("worktree")))'

2. How swarm creates them (automatic)

On handoff create --from X --to Y for a writer role Y, swarm:

1. Resolves repo root via find_repo_root (git rev-parse --git-common-dir fallback).
2. Creates branch swarm/<run-id>/<role> if missing.
3. Runs git worktree add <run-dir>/worktrees/<role>-<short> <branch>.
4. Exports AGENT_TOOLKIT_SWARM_RUN_ID/RUN_DIR/REPO SWARMFORGE_ROLE and cd <worktree> && exec <runner> "$(cat prompt)" via _user_shell() (/usr/bin/zsh -lc on this host).

Do not create worktrees by hand for swarm roles — let handoff create do it so state.json stays authoritative.

3. Manual recovery

If worktree_failed:

git rev-parse --git-common-dir  # from worktree dir — should succeed
AGENT_TOOLKIT_SWARM_RUN_ID=<run-id> agent-toolkit swarm handoff create --type artifact --from implementer --to reviewer --artifact artifacts/retry.md --run-id <run-id>
# Re-triggers provisioning with fixed repo-root logic