Recovery worktrees are bonsai’s Git isolation boundary: a mutating run executes in a detached managed worktree seeded from an exact snapshot of the source checkout, so the checkout you launched from is never modified mid-run. When the run finishes you review the result and decide — merge it back, keep it as a branch, or discard it.
bonsai -p) — governed by --isolation auto|worktree|off.
auto (the default) isolates mutating runs at balanced, auto-accept,
and yolo autonomy. An automatic mutating run outside Git refuses to
start unless --isolation off explicitly opts out of recovery.bonsai --isolation worktree
(also with -c resume). The TUI reads and edits the managed worktree, but
session history, permissions, plans, peer identity, /clear, and /resume
stay attached to the original project. The recovery id is visible in the
transcript and printed again after the TUI exits. --isolation auto follows
the saved autonomy level; omitting the flag leaves interactive sessions in
the source checkout.The snapshot includes tracked, staged, unstaged, and untracked non-ignored
files, so the run starts from what you actually had, not from HEAD.
Recovery setup requires the workspace to have been trusted during an interactive launch — internal Git snapshot operations must never activate repository filters or hooks before that trust decision. See Security model.
When an isolated run finishes, bonsai prints a recovery id:
bonsai recovery list # every managed result
bonsai recovery inspect <id> # what changed, against what base
bonsai recovery merge <id> # apply to the source working tree
bonsai recovery keep <id> [branch] # preserve as a branch
bonsai recovery discard <id> # drop it
merge applies the reviewed result to the source working tree without
changing its Git index. It refuses if either the source content or the index
changed after the run started — a stale merge never silently overwrites
concurrent work. When merge refuses, use keep to land the result on a
branch and integrate it manually.
Isolation is one of three independent boundaries; it does not replace the other two:
| Boundary | Question it answers |
|---|---|
| Autonomy & permissions | May this action run without asking? |
| Sandbox | What can the spawned command physically touch? |
| Recovery worktree | Can the run’s file effects be reviewed before they land? |
A sandboxed, permission-gated run inside a recovery worktree is the highest
default posture for unattended work — this is exactly what headless auto
isolation at balanced+ gives you.
See also: Headless mode for the flags, Troubleshooting for inspecting a run that went wrong.