Omniscio documentation
Browse all documentation
  1. Getting Started13
  2. Sessions & Agents115
  3. Inbox & Notifications64
  4. Projects & Tasks95
  5. Automation & Scheduling81
  6. Knowledge & Memory26
  7. AI Features61
  8. Integrations100
  9. Plugins & Marketplace33
  10. Cloud & Teams56
  11. Settings & Customization59
  12. Account & Billing28
  13. Troubleshooting85
  14. CLI & API Reference22
  15. Legal & Policies4
  16. Uncategorised22

Worktree lifecycle management

Worktree lifecycle management is the create-and-reap machinery behind one worktree per session: a paced create gate, a retire-then-sweep teardown that never destroys uncommitted work, a stranded-worktree reaper, and the Worktree Cleanup dashboard.

What it is

Worktree lifecycle management is the reliability half of session isolation. Creating a worktree is paced through a single gate (a FIFO queue, never a refusal), and removing one is a two-step retire-then-sweep so a folder is never deleted while something still holds it. A background reaper then finds worktrees whose work has already landed and reclaims them, recording a recovery ledger and a patch first.

Where to find it

Settings -> Performance -> "Run automatic worktree cleanup" (worktreeCleanupEnabled) — Windows only, off by default. The dashboard itself lives inside the Dev Pipeline panel, and its control-server twin is the /worktree-cleanup/* family. POST /worktree-cleanup/run-now asks for a pass now.

How it behaves

  • Create paces, never declines. Every spawn goes through one gated chokepoint that queues rather than rejecting, so a burst of sessions slows down instead of failing.
  • Teardown never destroys uncommitted work and never reaps a worktree with a live dev-pipeline run. remove and reclaim answer 200 with removed: false plus a skipped / heldFor reason when a floor held.
  • The reaper classifies a tree as landed by ancestry, squash-identical content, or patch-already-in-master, and writes a recovery ledger plus a patch before it deletes anything.
  • run-now is load-gated: while the box is busy it answers 200 { started: false, deferred } and starts nothing. { force: true } is a human-only override (403 to any provenance-declaring caller), and 409 comes back if a pass is already running.
  • Off Windows, run-now and recover are no-ops. Two dropdowns pick which engine and model run the paid stranded-worktree triage session.

For agents

  • Create gate: src/main/services/worktree/worktree-create-gate.ts.
  • Sweeper and dashboard backend: src/main/services/worktree-cleanup/worktree-cleanup-supervisor.ts.
  • Route family: src/main/services/cli/cli-server-worktree-cleanup-routes.ts.

Related

Last verified 2026-10-06