Treehouse workspace lifecycle

Use this skill when a task needs an isolated workspace. Read Workspace Isolation for the policy around it. The CLI wraps only the leased lifecycle of Treehouse: read status, write acquire, and write return. It never installs Treehouse, and it does not expose enter, init, update, prune, destroy, or --force.

Run the CLI

Bazel builds the CLI from a pinned source, so the first call in a session takes longer. The output is JSON. Run from the repository root, ./community/tools/treehouse.cmd in an Ultimate checkout and ./tools/treehouse.cmd in a Community checkout. Every example below uses the Ultimate spelling. Keep a read call and a write call separate, so an approval stays narrow and reusable. For Codex, read the last section first.

Inspect the pool

./community/tools/treehouse.cmd read status

The result lists every workspace with its lease and its process list. status is inspection only, and an available workspace can show an old detached HEAD. Never enter, edit, reset, rebase, or synchronize a path taken from status. Only write acquire reserves and prepares a workspace.

Acquire a workspace

./community/tools/treehouse.cmd write acquire --holder <session-id>

Pass the current development or agent session ID as --holder when one is available. Without the option, the CLI uses TREEHOUSE_LEASE_HOLDER, then it generates an agent-<UUID> label. The result holds the workspace path, the lease ID, the holder, and the receipt path.

The acquire takes a clean lease with --no-fetch and detaches it at the exact HEAD of the caller. It transfers no index, working-tree, or untracked change, and it performs no fetch, rebase, stash, cherry-pick, or file copy. It refuses only when the current checkout itself holds a lease, so one checkout can hold several leases.

The receipt is out/treehouse/lease.json inside the acquired workspace. It has schema version 2 and records the captured source_head. Both repository layouts ignore out/. Do not edit, move, or copy the receipt.

Return a workspace

First verify that every intended change is committed or preserved elsewhere, and that no intended uncommitted or untracked work remains. Next, stop every process that read status reports for the workspace, because the wrapper refuses a return while Treehouse reports one. Then run from the original checkout, or from another directory outside the leased workspace. A run from outside keeps the wrapper and its parent shell out of that process list.

./community/tools/treehouse.cmd write return --workspace <leased-path>

The wrapper checks the receipt against the live Treehouse status, passes both identity guards, and removes the receipt only after Treehouse reports success. It verifies the result against the live lease state, not against the exit code.

A dirty workspace needs an attestation that the work is preserved:

./community/tools/treehouse.cmd write return --workspace <leased-path> --confirm-preserved

The flag answers the Clean and return? [Y/n] prompt of Treehouse, so no TTY is necessary. Pass it only after the checks above pass, because the return cleans the workspace. The wrapper refuses a dirty return without the flag, and it never substitutes --force.

When a command fails

The CLI writes a JSON failure document to stderr with the message, the exit code, and the details. Exit code 2 marks a usage or a precondition failure. Exit code 127 means that the pinned CLI binary did not resolve. That is a Bazel build failure or a runfiles failure. It is not a missing host install.

Never install Treehouse. Never fall back to a Git worktree, a clone, or another workspace manager on your own initiative. Continue in the current checkout when that is safe, or ask the user for an isolated workspace. Use a Git worktree only when the user asked for one for this task.

When a lease survives the failure, retain it and report the path, the lease ID, and the holder from the error.

Codex sandbox

1. Before an acquire, check that the built-in request_permissions tool is available. If it is not, do not acquire a lease, and report that Treehouse cannot be used in this session. Do not ask the user to change permission settings, to restart with --add-dir, or to grant access to the Treehouse pool.
2. Run from this skill directory, and request two approval prefixes. They are ../../../community/tools/treehouse.cmd read and ../../../community/tools/treehouse.cmd write. In a Community checkout, drop community/ from both. The write approval only lets the wrapper reach the Treehouse pool. It does not authorize an acquire or a return.
3. A change of the working directory of a tool does not add the leased workspace to the writable roots of the session. Keep running from the original checkout, and use request_permissions for session-scoped write access to exactly the returned path. Do this before any edit inside the workspace. Do not request the Treehouse pool, the source checkout, the shared Git directory, or full access. Do not replace the single grant with per-command escalations. After the grant, use the workspace path as the working directory for every later tool.
4. If the grant is denied, do not enter, edit, or run a command in the leased workspace. Return the untouched lease at once from the original checkout. Do not ask the user to reconfigure permissions.