## TL;DR

The agent keyed its review state to the branch name, so a mid-review rebase (new SHAs, same branch) orphaned it. Key all state to the head SHA, detect SHA changes, and resume or restart cleanly.

## Error

```text
Agent log: resume failed  -  no state found for branch feature/x (state was keyed to the pre-rebase SHA).
```

## Steps

1. Confirm the cause: the PR timeline shows a rebase (force-push, new SHAs) during the agent's run. Expected: the head SHA changed mid-run.
2. Key state by head SHA, not branch name: store `(repo, pr, head_sha) -> state`. Expected: a rebase creates a fresh state bucket instead of a failed lookup.
3. Detect the SHA change at each step: if the PR's head SHA moved, pause and ask whether to resume (map old positions) or restart. Expected: no silent continuation on stale state.
4. Implement position remapping for the resume path, or simply restart the review on the new SHA. Expected: reviews complete even when authors rebase.

## When to use

- The agent's review breaks when the PR is rebased while it runs.
- The agent keeps multi-step state.

## When not to use

- The agent is stateless per run  -  rebases just mean it reviews the new SHA next time.
- The failure is a force-push without rebase (same SHAs dropped); handle deleted refs instead.

## Tool compatibility

- Any stateful review agent.
- GitHub / GitLab.

## Variant phrasings

### Rebase during inline comment drafting

Draft comments anchor to old positions  -  remap or drop them on SHA change.

### Mid-review merge of the base branch

Same handling: the head SHA may not change, but positions can shift  -  revalidate.

## Why it happens

Rebasing rewrites every commit SHA on the branch. State keyed to the branch name (or old SHAs) no longer matches anything, so the agent either crashes or  -  worse  -  posts comments anchored to dead positions.

## Edge cases

- Restarting the review on every rebase can loop if the author rebases repeatedly; cap restarts and notify.
- Position remapping is only reliable for clean rebases; conflict resolutions need a fresh review.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_eKaWJlg7QehE4UGC8Kg4xA