Treehouse

treehouse keeps a pool of pre-warmed git worktrees, with dependencies already installed. Lease worktrees autonomously for an authorized task. Return an empty worktree to the pool rather than destroying it, so the next effort finds one ready; destroy only one the pool shouldn't keep. Settlement keeps the calling session's occupied worktree leased and leaves its session host's topology open.

1. Check the installed version and help for the operation. For a new effort, use get --lease --json --lease-holder <effort> -b <branch> and save the returned path, lease_id and lease_holder. Resolve the path physically and verify its repository and branch before using it. Use the returned identity for later release; a holder label alone can be reused.
2. Before releasing a worktree, verify its exact canonical path, repository, branch and current lease against that recorded acquisition. Confirm the worktree is clean, preserve any needed ignored files, and prove the branch merged using the invoking workflow's merge proofs. If the original acquisition has no recorded identity, verify ownership before recording the current lease; a current pool listing alone does not authorize adopting someone else's lease.
3. Check occupants immediately before release:
   • Sources: treehouse status --json, together with live caller, pane and OS process inspection.
   • Scope: verify the actual current directories of agents, idle sessions, shells, services and their children, including descendants of the worktree path. Resolve symlinks and compare path components, so a similarly prefixed sibling does not match.
   • Not proof: workspace checkout metadata, titles and conversation context do not prove process location.
   • Caller: check the caller and its ancestors independently, since Treehouse filters them from its reported process list.
   • Known users: a service or session known to use the worktree counts as an occupant even if its current directory is elsewhere.
   • When occupied or uncertain: Preserve the lease and branch, and report the occupants or missing evidence. This includes the calling session, a missing lease ID, unreadable relevant process locations, recovered or damaged entries, and changed identities. status silently omits processes whose directories it cannot read; an empty process list alone is not proof that the worktree is empty. Keep topology open and do not schedule delayed cleanup or terminate occupants to make settlement possible.
4. From outside the target worktree, return only the verified empty target with treehouse return <exact-path> --if-lease-id <recorded-id> --if-lease-holder <recorded-holder>. Recheck identity and occupancy after any intervening work. The flags atomically guard the lease before detach, process termination and reset; they do not guard occupancy or terminal topology. Use a single explicit target, since return --all can reclaim occupied slots.
5. After the return:
   • Result: check the command's exit status and inspect the resulting pool and Git state.
   • Branch deletion: delete the branch only after a confirmed successful release, the invoking workflow's merge proofs bound to the verified branch tip, and verifying that no worktree still checks out that branch. Recheck the tip before deletion, and repeat the merge proofs if it changed.
   • Failed, interrupted or uncertain return: it can have changed state, so preserve the branch, inspect live state before any retry, and use the original lease identity again only if it still matches. An already available or reassigned slot is not a reason to retry the return.