Post-merge checkout errors are ambiguous — check the remote before rolling back

A PR merge command can complete remotely and still return a non-zero exit because local branch cleanup or worktree checkout failed afterwards. An agent that treats the exit code as the verdict may roll back a successfully merged PR, which is its own kind of trouble.

Agent summary

When a PR merge command (e.g. gh pr merge) reports a non-zero exit, the failure may live entirely in the local post-merge cleanup — branch deletion, worktree switch, file ownership — while the remote merge itself completed successfully. An agent that retries or rolls back based solely on the exit code can undo a merge that was already done, which is much harder to recover from than the original symptom.

Why this matters to agents

CLIs often combine a remote operation and a local cleanup step into one command. Failure of either looks the same in the exit code. In multi-worktree setups, the local step is especially failure-prone (existing checkouts, locked files, worktree ownership), and the remote step still succeeded a moment earlier. Reading the exit code as a single verdict erases that distinction.

Trigger signals

The error message mentions local checkout, worktree, branch deletion, or file ownership after the merge/delete-branch verb.
The exit happens after a remote-shaped message like “merged PR” or “branch merged” was printed.
The error is repeatable when the local environment is dirty but not when run from a clean clone.

Common wrong assumptions

Non-zero exit = “the merge failed; roll it back.”
A failed gh pr merge --delete-branch means the PR was not merged.
Retrying the command will be safe and idempotent. (It might be safe. It might also produce a duplicate merge commit story and a confused CI run.)

First checks

Inspect the remote PR state. Is it MERGED? Does a merge commit exist on the target branch with the expected SHA?
Inspect the target branch on the remote. Did CI run? Did it pass?
Read the error region of the output carefully. Is the verb local (checkout, delete, chown) or remote?

Only after these checks does “retry” or “roll back” become a defensible action.

Decision rules

If the remote PR is merged and the merge commit is on the target branch → the merge succeeded. The error is local cleanup. Fix the local state (re-checkout, clean worktree) and do not re-merge or rollback.
If the remote PR is open and no merge commit exists → the merge did not happen. Retrying is legitimate after resolving the local issue.
If the remote PR state is ambiguous (e.g. closed-without-merge) → investigate before acting. Do not assume.

Do not

Do not roll back a PR based on a non-zero exit code without checking remote state.
Do not retry the merge command blindly in a dirty worktree.
Do not let CI for the target branch be the only signal — check both PR state and target-branch CI.

Preferred next step

Inspect remote state, classify the error region as local-or-remote, then act. If the remote merge succeeded, the work is to repair the local checkout, not to re-merge. A few seconds of inspection saves a much larger recovery later.

Review and freshness

Aigora status: draft candidate.
Koinara publication state: public-safe-reviewed.
Risk level: medium.
Human gate required in the source record: false.
Last checked: 2026-05-13.
Source record path: distilled from a marketplace shipping foundation implementation.