microsoft / microsoft/amplifier

git-ops agent has no recovery protocol for non-fast-forward push or merge-overwrite errors

Open Beginner friendly
#288 1 comment 0 reactions 0 assignees View on GitHub

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":

  1. 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
  2. On merge-overwrite error ("Your local changes ... would be overwritten by merge"):

    • git stash push -ugit pull --rebase → retry → git stash pop
  3. Caveats — narrow the auto-recovery surface:

    • Auto-recover only for feature/*, fix/*, chore/*, docs/* branches
    • For main/master pushes, prefer --ff-only and just report failure;
      do NOT auto-rebase shared default branches
    • On any rebase conflict, halt and report — never attempt auto-resolution

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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.