Firstmate's Treehouse Worktree Isolation: How It Prevents Git Conflicts

Firstmate eliminates concurrent execution conflicts by running every task inside a disposable Git worktree created via treehouse get, enforced by tangle guards that abort operations if workers attempt to access the primary repository checkout.

The kunchenguid/firstmate repository implements a strict isolation model that binds each ship or scout task to a uniquely-named Git worktree rather than the main working directory (referred to as FM_ROOT). This design guarantees that parallel workers cannot modify shared files or corrupt the main branch, creating a hard safety contract for concurrent operations.

The Treehouse Allocation Protocol

When a task spawns, the system immediately allocates an isolated execution environment through the treehouse subsystem.

In bin/fm-spawn.sh at line 2215, the spawn script invokes the allocation command:

spawn_send_text_line "$WT_TARGET" 'treehouse get'

This command performs two critical functions:

1. Creates a fresh Git worktree bound to the task’s unique identifier
2. Migrates the pane’s working directory into that worktree before the worker harness initializes

The worker then executes entirely within this disposable directory, leaving the primary checkout untouched.

The Isolation Guard Mechanism

Before any worktree is utilized, bin/fm-guard.sh validates that the primary repository remains in a pristine state. At lines 30‑40, the guard script checks whether FM_ROOT is checked out to its default branch.

If the primary checkout has been "tangled" onto a feature branch, the script emits a worktree-tangle alarm and aborts the spawn. This prevents accidental commits or modifications to the main repository when the system expects it to remain clean.

Spawn Refusal on Non-Isolated Paths

The spawn script enforces strict boundary validation at lines 135‑137 of bin/fm-spawn.sh. Before launching a worker, it verifies that:

• The resolved task path resolves to a real Git worktree
• The path is distinct from the primary checkout (FM_ROOT)

If the worktree is missing or resolves back to the primary repository location, the spawn aborts with an explicit error, preventing execution in an unisolated environment.

Treehouse Lease for Secondmate Homes

Second-mate workers utilize a leasing protocol to guarantee exclusive resource ownership. As implemented in tests/secondmate-helpers.sh at line 15, the system writes a lease marker via the treehouse lease command:

treehouse lease --holder my-secondmate

This records which second-mate currently owns the worktree, ensuring that concurrent tasks cannot claim the same isolated environment. The lease protocol acts as a mutex for worktree resources.

How Isolation Prevents Conflicts

The treehouse architecture prevents conflicts through three enforcement layers:

• Physical separation: Each task receives a unique filesystem path via treehouse get, eliminating file-level race conditions
• Branch protection: The tangle guard in fm-guard.sh blocks any operation if FM_ROOT is not on the default branch
• Exclusive access: The lease mechanism in secondmate-helpers.sh rejects attempts to reuse worktrees currently held by active workers

Because workers physically cannot write to the primary checkout (enforced by the spawn refusal logic) and cannot share worktrees (enforced by leases), the system eliminates the possibility of concurrent modification conflicts.

Code Examples

Spawning a ship task with automatic isolation:

# This command automatically creates an isolated worktree via treehouse get

fm-spawn.sh mytask projects/my-repo --mode no-mistakes --yolo on

# Internal execution flow:

# 1. treehouse get          # Creates unique worktree

# 2. cd <worktree>          # Switches to isolated directory  

# 3. <harness> run          # Executes worker in isolation

Checking worktree lease status:

# Verify exclusive ownership of a secondmate home

treehouse lease --holder my-secondmate

# Writes lease record at line 15 of secondmate-helpers.sh

Triggering the tangle guard:

# If FM_ROOT is on a feature branch (e.g., feature/test):

fm-spawn.sh task1 projects/foo

# fm-guard.sh detects non-default branch (lines 30-40) and aborts

Summary

• Treehouse worktree isolation creates a disposable Git worktree for every task via treehouse get in bin/fm-spawn.sh (line 2215)
• Tangle detection in bin/fm-guard.sh (lines 30‑40) verifies FM_ROOT remains on the default branch before allowing spawns
• Path validation at bin/fm-spawn.sh lines 135‑137 ensures workers never execute in the primary checkout
• Lease protocols in tests/secondmate-helpers.sh (line 15) enforce exclusive worktree access for second-mates
• Conflict elimination is achieved by combining physical directory isolation with runtime guards that abort unsafe operations

Frequently Asked Questions

What happens if the primary checkout is on a feature branch when spawning a task?

The bin/fm-guard.sh script detects the condition (referred to as a "worktree-tangle") at lines 30‑40 and aborts the spawn with an alarm banner. This prevents workers from accidentally operating against a non-default branch in the primary repository, ensuring FM_ROOT remains pristine.

How does the treehouse lease ensure exclusive access to worktrees?

The lease protocol, demonstrated in tests/secondmate-helpers.sh at line 15, writes a holder identifier to the worktree metadata via treehouse lease --holder. Subsequent attempts to acquire the same worktree check for existing lease markers and reject the request if another worker holds the lease, functioning as a mutex for the isolated environment.

Can two tasks share the same worktree simultaneously?

No. The spawn script at bin/fm-spawn.sh lines 135‑137 validates that each task resolves to a unique worktree path distinct from FM_ROOT. Combined with the lease mechanism, the system guarantees that concurrent tasks cannot access the same filesystem location, eliminating race conditions.

Where is the isolation boundary enforced in the codebase?

The primary enforcement occurs in three locations: the allocation boundary in bin/fm-spawn.sh (line 2215) where treehouse get creates the隔离, the validation boundary in bin/fm-guard.sh (lines 30‑40) checking FM_ROOT branch status, and the access boundary in tests/secondmate-helpers.sh (line 15) managing worktree leases for second-mates.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}