Git Worktree

Git Worktree — Isolation Mode for /rune:strive

Overview

Git worktree mode gives each swarm worker its own isolated working copy via isolation: "worktree" on the Agent tool. Workers commit directly in their worktrees instead of generating patches. After each wave of workers completes, the orchestrator merges worktree branches back into the feature branch.

Two execution modes coexist in /rune:strive:

Talisman override: work.worktree.enabled: true makes worktree mode the default.

Worktree Lifecycle

Each worker's worktree follows a 6-phase lifecycle: CREATE (SDK creates worktree + branch), WORK (isolated implementation), COMMIT (direct commit, one per task), SEAL (report completion), MERGE (orchestrator merges after wave), CLEANUP (remove worktree + branch). Includes crash recovery protocol.

See worktree-lifecycle.md for the full 6-phase protocol and crash handling.

Merge Strategy

Worktree mode uses sequential merge with --no-ff for clear, revertable history.

Why Sequential (not Octopus)

Decision: Sequential --no-ff (ADR 4) because:

• Know exactly which two branches conflict
• 3 of 5 can merge cleanly even if 2 conflict
• Each merge is individually revertable via git revert -m1
• Deterministic history (sorted by task ID)

Merge Broker Algorithm

See worktree-merge.md for the complete merge broker algorithm, including:

• Branch validation against BRANCH_RE
• Deduplication guard (mergedBranches Set)
• Empty branch detection (skip no-change workers)
• Pre-wave checkpoint tags
• Conflict escalation flow
• Cleanup procedures

Conflict Resolution

Critical rule (C1): No auto-resolution. On ANY merge conflict, escalate to user.

Conflict detected in {file}
  |
  v
AskUserQuestion: How to resolve?
  |
  +-- "Accept theirs" -> git checkout --theirs {file} && git add {file}
  +-- "Accept ours"   -> git checkout --ours {file} && git add {file}
  +-- "Manual resolve" -> pause pipeline, user edits, git add, continue
  +-- "Abort merge"   -> git merge --abort, mark NEEDS_MANUAL_MERGE

Why no auto-resolve: git checkout --theirs replaces the ENTIRE file with the incoming version, discarding all "ours" changes. This is too destructive for automated use. User must make an informed choice for each conflict.

Wave-Based Execution

Tasks are grouped into waves by dependency depth. Wave 0 has no dependencies, Wave N depends only on Wave 0..N-1. Each wave runs workers in parallel, then merges all branches before proceeding. Includes DFS cycle detection and pre-wave checkpoint tags.

See wave-execution.md for the full wave grouping, dependency depth calculation, and execution flow.

Talisman Configuration

work:
  worktree:
    enabled: false                    # Default: patch mode
    max_workers_per_wave: 3           # Max parallel workers per wave
    merge_strategy: "sequential"      # Only "sequential" supported
    auto_cleanup: true                # Remove worktrees after merge
    conflict_resolution: "escalate"   # "escalate" (ask user) | "abort"
    sparse_paths: []                  # empty = disabled; specify paths for cone-mode checkout

Relationship to existing keys:

• work.max_workers caps total workers across the session
• work.worktree.max_workers_per_wave caps per-wave concurrency
• Effective per-wave cap: min(max_workers, max_workers_per_wave)

State File Extensions

When worktree mode is active, the state file (tmp/.rune-work-{timestamp}.json) includes additional fields:

{
  // ... existing fields ...
  worktree_mode: true,           // Absent in patch mode (falsy)
  waves: [[taskIds], [taskIds]], // Task IDs grouped by wave
  current_wave: 0,               // Currently executing wave index
  merged_branches: []             // Branches successfully merged
}

Safety Notes

• Blast radius reduction: A rogue worker only damages its own worktree (primary benefit)
• Disk usage: Each worktree creates a full working copy (shared .git objects)
• Dependency blindness: Workers cannot see other workers' uncommitted changes
• SDK canary: Phase 0 validates isolation: "worktree" support before proceeding
• Experimental: Worktree mode is marked experimental in initial release

Safety Net (Worktree Lifecycle Guard)

When Phase 6 cleanup is not reached (crash, session end, agent idle), three safety nets ensure worktrees are eventually cleaned:

1. Stop hook (on-session-stop.sh Phase 4): Auto-cleans orphaned rune-work-* worktrees on session exit (capped at 3 for timeout budget)
2. SessionStart (session-team-hygiene.sh): Detects orphaned worktrees, reports to user
3. /rune:rest: Manual cleanup via standard mode or --heal

All three use the shared scripts/lib/worktree-gc.sh library with:

• PID liveness checks (never cleans live sessions' worktrees)
• config_dir isolation (cross-installation safety)
• jq dependency guard (fail-open if missing)
• Path traversal + symlink guards
• Salvage patches for uncommitted work (rest mode only)

Known Limitations (Upstream)

References

• worktree-merge.md — Merge broker algorithm, conflict handling, cleanup
• worker-prompts.md — Worker prompt templates (patch + worktree modes)
• parse-plan.md — Task extraction and dependency parsing