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.

An active bound session blocks removal with worktree_session_active. Removal never silently stops sessions. End the session through its own controls before retrying.

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.

Remove several Worktrees in the app

In the menubar workspace submenu or Workspaces overview, choose Select worktrees…. Select individual rows, use Shift to select a range, or choose Select all eligible. Select all captures only eligible rows currently represented by that list; later arrivals are not added. Escape clears selection. Selection never navigates into a checkout or adopts a discovered one.

Remove selected freezes the workspace, profile and Worktree IDs. The confirmation separates checkout removal from dismissal of missing records. Missing rows can also be resolved individually through Clean up missing record…, which retains It's back.

Each target receives fresh server checks. Active/busy Worktrees, unknown lifecycle states, unreadable status, hook denials, dirty edits and unpublished work remain refused. The batch never forces removal or stops sessions. Switch to the owning active profile before selecting a foreign row; archived owners and unregistered discovered checkouts are ineligible.

Results report each success and refusal independently. Successful targets stay recorded in the result list; Retry failed reconciles the original IDs and retries only failed or unconfirmed items. A changed lifecycle state requires a new selection and confirmation. This is not an atomic batch: one refusal does not undo successful removals.

Dismissing a missing record preserves files even if something reappeared at that path, plus branches, Git history, sessions and task/Loop history. It does not prune Git's administrative entries; an unregistered stale Git checkout may appear separately as unavailable discovery. Repeating dismissal by the retained ID is safe. Refreshing or restarting does not revive the dismissed registry entry.

Existing HTTP/UDS remove and dismiss clients may omit profile: operator requests infer the owner from the target record. Explicit selectors must match that owner, authenticated agents remain bound to their session profile, and archived owners are refused. The Web bulk flow always sends its frozen profile selector; reading the all-profiles catalog does not grant bulk mutation authority.