microsoft / microsoft/amplifier
git-ops agent has no recovery protocol for non-fast-forward push or merge-overwrite errors
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 3.1k
- Forks
- 261
- Avg merge
- 3h 28m
- Merged PRs (30d)
- 13
Description
Problem
The foundation:git-ops agent has no recovery protocol for two common
recoverable git states: non-fast-forward push rejection (! [rejected] ... (non-fast-forward) / (fetch first)) and merge-overwrite errors when the
working tree is dirty. When git-ops hits either, it surfaces the error to the
caller instead of running the standard fetch → pull --rebase → retry (or
stash → pull --rebase → pop → retry) recovery that any human operator
would do reflexively.
I confirmed this by grepping the current agent file for
reject|non-fast-forward|fetch first|stash|recover — zero matches. The
"Git Safety Protocol" section is purely DON'Ts; "Remote Operations" only
shows the happy-path commands.
Evidence (3 distinct failures in 7 days)
From a learning-digest review on my fleet (multi-machine setup with
concurrent dev, which makes this hit more often than a solo workflow):
foundation:git-ops sub-agent / bash:
! [rejected] docs/notesheet-system-spec -> docs/notesheet-system-spec (non-fast-forward)
error: failed to push some refs
foundation:git-ops sub-agent / bash:
! [rejected] main -> main (fetch first)
error: failed to push some refs
foundation:git-ops sub-agent / bash:
From https://github.com/.../...
* branch main -> FETCH_HEAD
769cb69..8cdd995 main -> origin/main
error: Your local changes to the following files would be overwritten by merge:
scripts/send-message.py
src/channels/cli.ts
Aborting
The third example shows the agent did do a git fetch then attempted
merge, but had uncommitted local changes — also recoverable (stash → pull
→ pop). All three failures had the same end state: the caller got an error
and had to retry manually.
Affects
Anyone who delegates git push (or any pull-side merge) to foundation:git-ops
in a setup with concurrent push activity:
- multi-machine personal setups (sync via Syncthing, simultaneous sessions push to same remotes)
- team setups (collaborator pushed between fetch and push)
- CI side-effects (a bot or workflow advanced the branch)
Solo single-machine users hit it less often, but foundation:git-ops is the
canonical agent every Amplifier user is told to delegate to, so the blast
radius is wide.
Proposed fix
Add a "Push/Pull Recovery Protocol" section to agents/git-ops.md (in
amplifier-foundation), positioned between "Git Safety Protocol" and
"Common Git Commands":
-
On push rejection (
non-fast-forward/fetch first):git fetch origin <branch>- If working tree clean:
git pull --rebase origin <branch>→ retry push - If working tree dirty:
git stash push -u -m "git-ops auto-stash"→
git pull --rebase origin <branch>→ retry push →git stash pop - If rebase conflicts: STOP and report — do NOT auto-resolve
-
On merge-overwrite error ("Your local changes ... would be overwritten by merge"):
git stash push -u→git pull --rebase→ retry →git stash pop
-
Caveats — narrow the auto-recovery surface:
- Auto-recover only for
feature/*,fix/*,chore/*,docs/*branches - For
main/masterpushes, prefer--ff-onlyand just report failure;
do NOT auto-rebase shared default branches - On any rebase conflict, halt and report — never attempt auto-resolution
- Auto-recover only for
The change is pure-additive content in an agent's instruction file. No code,
no behavioral change for paths that already work.
Acceptance
agents/git-ops.md(or wherever the canonical git-ops agent definition
lives in the foundation repo) gains the recovery protocol section- Manual repro: create a local commit, push from another window or another
machine to advance the remote, then ask git-ops to push the same branch —
it recovers automatically and reports the rebase + retry - Subsequent
[rejected] (non-fast-forward)errors from git-ops sub-agents
drop to ~zero in fleet-wide review
Discovery context
Diagnosed on a personal multi-machine fleet during a P2 triage run on
2026-05-09. (Filed in the umbrella repo because amplifier-foundation has
issues disabled — please route to wherever makes sense.)
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with agents/git-ops.md in the amplifier-foundation repository, reading the existing Git Safety Protocol and Common Git Commands sections. Add the requested recovery protocol between them, preserving the stated branch and conflict safeguards. Verify the documented behavior with the manual non-fast-forward and dirty-working-tree reproductions described in the issue.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- git
- Domain
- devops, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100