treehouse

name	treehouse
description	Use when a task needs a Git worktree or mentions Treehouse; follow Treehouse's pooled acquisition, lease, status, and return workflow.

Treehouse

Treehouse 是 Git worktree 的管理入口：需要使用 Git worktree 时，从 Treehouse 获取、使用和回收，不直接手工管理池中的目录。

心智模型

• 池：Treehouse 为每个仓库维护一组可复用的 worktree。get 优先复用安全的空闲槽位，不满足条件时再创建槽位。
• 安全复用：可复用槽位必须空闲、无租约、内容干净且能证明已合并到重置目标；否则保留在池中。
• 占用：进程正在目录中运行、短生命周期操作保留、以及持久租约是三种不同状态。一个进程消失，不代表租约已经释放。
• 租约：get --lease 把槽位持久标记为当前调用方持有；即使目录里没有进程，后续 get 和清理也会避开它，直到 return。
• 回收：return 会检查残留进程和脏状态，确认后将槽位重置并放回池中。状态无法证明安全时，目录会留在原处。
• 起点：新建或复用的槽位按默认分支目标准备，不承接当前目录的未提交改动；复用意味着重置到该目标，而不是保留现场。

当前 Agent 的用法

Agent 使用非交互路径：

worktree="$(treehouse get --lease)"

后续工具调用把 $worktree 作为工作目录。完成后先把需要保留的改动提交、生成补丁或移出该目录，再执行：

treehouse return "$worktree"

交互式终端才使用不带 --lease 的 treehouse get；它会打开 subshell。

状态不符时

把 treehouse status 作为池状态的事实来源：

• 当前目录在默认 ~/.treehouse/（或配置的池根目录）下时，先确认它确实是本次 Agent 持有的槽位；已持有就继续使用，不重复获取。
• 显示为 leased 或 in-use 且归属不明时，保留该槽位并换用明确可获取的槽位；路径和进程存在不等于你拥有它。
• 显示为 dirty，或归还提示有未提交改动时，先保存交付物，再完成归还。
• return 因残留进程或无法验证而失败时，保留 worktree，处理自己启动的进程后重试；状态未确认前不强制清理。

排查

遇到无法解释的行为或命令失败时，查阅 Treehouse 源码；原作者是 Kun Chen。