Treehouse agent worktrees

The ai set installs the native worktree manager from its pinned, checksum-verified release. New agent allocations live at <primary-repository>/.worktrees/<agent>-<8-hex>/; no task name is required. Full task and owner identities remain in manager records. See standalone worktree management for installation and lifecycle commands.

Shell functions route codex and claude through launchers. command codex and command claude invoke native executables directly. Fresh interactive codex --worktree and codex exec --worktree requests use the manager; --cd selects the repository and preserves the requested subdirectory. Ordinary launches, resumes, forks, desktop commands and remote connections retain native behavior. Existing assigned checkouts are reused without claiming ownership.

Claude receives paired WorktreeCreate and WorktreeRemove factory hooks plus session lifecycle hooks through transient settings. The launcher preserves the last effective caller settings, arguments and existing hooks. In-session and subagent worktree requests use the manager. Custom factory conflicts and uninspectable plugin/policy sources fail before allocation. Explicit modes that disable custom hooks, such as --bare and --safe-mode, keep native behavior and are outside launcher placement enforcement.

Missing or failing manager allocation aborts a managed request instead of falling back to temporary native placement or Treehouse. Nonzero creation responses may still describe a protected surviving task; the integration records confirmed task identity before reporting failure, and uncertain tasks remain available through worktree status --json for reconciliation. Lost responses and explicit uncertain results retain a durable pending intent with the full owner ID and block another allocation in that session until reconciled.

bin/agent-worktree keeps private ownership records under ${XDG_STATE_HOME:-~/.local/state}/agent-treehouse and the existing AGENT_TREEHOUSE_SESSION environment identity for compatibility with running sessions. New records contain manager task IDs and owner identities; outstanding Treehouse records retain their lease IDs and guarded legacy return handler. bin/agent-treehouse remains a compatibility entrypoint and does not allocate new leases.

The native client replaces the launcher process, preserving streams, signals and exit status. A detached watcher observes exit. The worker waits for observed session completion, verifies exact task ownership, Git state, branch preservation, process references and native client inventories, then repeats inspections before worktree finish. Dirty work, valuable ignored artifacts, active processes, unavailable inspections and uncertain task ownership retain protection with a concrete reason. Only the task’s own native Git lock is exempted from the Git-operation check; other locks remain protected.

Finishing protection preserves checkout files and branches. Removal requires explicit safe pruning; there is no startup deletion sweep. Legacy Treehouse return remains guarded by its original lease ID and holder and preserves pool directories. Its native mutation has the pre-existing race after final inspection and may terminate lingering processes; finishing manager task protection does not reset or remove files.

Deferred results are recorded in returns.jsonl and worker.log under the private state directory. Results distinguish finished, legacy returned, retained and unconfirmed. After resolving a retention reason, retry one ended session with uv run --script ~/.files/bin/agent-worktree reap SESSION_TOKEN. Use watch first if the exit watcher failed and its record still says ended: false.

make test-agent-worktree runs Codex and Claude workflows against the native manager, real Git and process inspection, plus an outstanding-Treehouse-record compatibility check. Native client factory/settings smoke checks remain separate from the simulated agent workflows. The compatibility target make test-agent-treehouse runs the same detector.