Sandbox Issues
Sandboxes run prompts in isolated git worktrees. Most of the time they promote or discard cleanly, but here’s how to recover when one doesn’t.
A session freezes
Section titled “A session freezes”Several escape hatches exit a stuck session:
- The titlebar exit button.
- The banner action on the session.
- Ctrl+Shift+X.
- An automatic exit after three failed starts.
A session won’t register or persist
Section titled “A session won’t register or persist”Sandbox sessions are tracked in the queue database. If a session doesn’t appear after a restart, list stored sessions (orbit_list_sandbox_sessions) — the system falls back to a health check on the sandbox port if no healthy session is found in the table. Routing a prompt to an invalid or non-runnable session id fails loudly rather than silently sending the prompt to the live queue, which is the intended, safe behavior.
Orphaned worktrees, branches, or session rows
Section titled “Orphaned worktrees, branches, or session rows”Orbit detects these in the background. Clear them under Settings → Queue & Sessions → Sandbox with per-item Clean Up or Ignore.