Removal and Recovery

Removal deletes the linked checkout, not operator-owned branches or Git history. CompozyOS checks bound sessions, dirty files, unpushed commits, repository identity, and fresh cleanup evidence before it changes Git.

Remove a clean Worktree

1. Read cleanup evidence

compozy worktree exit feature-auth --workspace . -o json

Continue only when cleanup.safe is true and the evidence matches the intended branch or merged pull request.

2. Remove the linked checkout

compozy worktree remove feature-auth --workspace . -o json

Expected result:

{
  "action": "removed",
  "worktree": {
    "id": "wt_01...",
    "name": "feature-auth",
    "state": "removed"
  }
}

Mutation receipts always report the canonical Worktree ID, even when the command is addressed by name.

A bound idle session is stopped before removal. A session that is mid-turn blocks removal with worktree_session_active.

Review a refusal before force

Dirty or unpushed work returns a structured conflict instead of deleting it:

{
  "code": "worktree_dirty_requires_force",
  "risk": {
    "changed_files": 2,
    "insertions": 4,
    "deletions": 1,
    "unpushed_commits": 3,
    "exists_on_remote": false
  },
  "downgrade": false
}

Return to Assisted exit first. If the operator still intends to discard the checkout after reviewing those exact quantities, confirm explicitly:

compozy worktree remove feature-auth --workspace . --force -o json

--force does not delete an operator-owned branch. A remote branch may downgrade unpushed evidence, but it never hides dirty files or an unreadable safety check. The narrow exception is an unchanged runtime-owned per-run branch: CompozyOS compare-deletes it only while it still points at the recorded creation commit and emits worktree.branch_reclaimed.

Recover a missing path

Run a fresh discovery after a checkout is removed or moved outside CompozyOS:

compozy worktree list --workspace . --refresh -o json

The record becomes missing, retains history, and cannot host new sessions or runs.

If the same linked checkout is back at its recorded path, restore it by adopting that path:

compozy worktree adopt /src/acme-feature-auth --workspace . -o json

Expected result is the original Worktree ID with state: "ready". A different repository at that path is refused.

If the path cannot return, clear only the retained record:

compozy worktree dismiss feature-auth --workspace . -o json

Expected result reports action: "dismissed". Dismiss does not delete a filesystem path, a branch, session history, task history, or workspace memory. The retained record remains readable by its ID, but its name becomes available for a new Worktree. Every non-dismissed record, including removed, continues to reserve its name.

When removal preserved the branch, reuse the released Worktree name by attaching that branch:

compozy worktree create feature-auth --workspace . --existing-branch <retained-branch> -o json

Use feature-auth for <retained-branch> when the original Worktree used its default branch. This creates a new Worktree ID while the dismissed record and its history remain readable by the old ID. Use --branch <new-branch> instead when the replacement should start from a different branch.