Troubleshooting

Start with zap explain <path> for any worktree that surprises you. It shows every check zap ran.

I merged it, but zap says active

Your local copy of the target branch probably doesn't have the merge yet. Pull, or run zap scan --fetch. If the pull request was merged on GitHub, --gh asks GitHub directly. See How zap decides.

If your repository merges into something other than main or master, set target in the .zap file or pass --target.

zap says merged but won't remove it

A safety check failed. zap clean --dry-run prints the reason after keep:, and e in the picker shows every check. The usual ones:

Reason	Fix
holds ignored .env	Move the file out, or remove its pattern from keep_ignored
active within min_age	Wait, or lower min_age in .zap
a process is working in it	Exit the shell, terminal editor or agent running in it
uncommitted changes	Commit, stash or discard them
locked	Unlock it with git worktree unlock <path>, or, if the lock is stale, zap clean --unlock-stale

zap clean says it changes nothing

The repository isn't opted in. Run zap init there. See Opt a repository in.

zap scan --all doesn't find my repository

It isn't under a scan root. Add its parent folder with zap roots add <folder>. See Scan roots.

gone worktrees aren't removed

gone means the branch was deleted on the remote, which doesn't prove its work was merged. Add "gone" to rules in .zap if you want them removed. A gone worktree with unmerged commits keeps its branch.

The AGENT column says -

zap didn't recognise the folder. This only affects the label. See the folder list in How zap decides.

zap clean exits with code 4 in a script

Either you haven't accepted the disclaimer yet (run zap clean once in a terminal), or the script didn't pass --yes.

macOS won't open the binary

You downloaded it with a browser, so macOS quarantined it. Run xattr -d com.apple.quarantine <path-to-zap>, or install with Homebrew.

I removed something by mistake

Run zap undo. See Undo.

If none of these fit, open an issue.