Agent / Orchestrator: Handle merge conflicts in pr_iteration workflow - NEED DISCUSSION

[leandrodamascena]

Component

None

Describe the feature

When the agent creates a PR and the base branch evolves (someone pushes changes to main that touch the same files), the PR ends up with merge conflicts. Right now neither the agent nor the platform does anything about it - the PR just sits there as unmergeable and nobody notices until a human checks.

I hit this in practice: the agent opened a PR that created a pyproject.toml for a new project scaffold. Meanwhile I pushed a different pyproject.toml to main (production lib config, different name, version, dependencies). The PR is now in conflict and a pr_iteration to address review feedback would work on top of a stale branch without realizing the base has diverged. The agent would be editing a pyproject.toml that doesn't reflect what's actually on main.

Use case

The agent created PR #5 with a pyproject.toml for project "xyz" v0.0.1. I then pushed to main a pyproject.toml for project "LEO" v1.0.1 with completely different config (production lib, different deps, different build system). The PR is now unmergeable but there's no mechanism to detect or resolve this. If I send a pr_iteration now, the agent will work on top of its own version of pyproject.toml without knowing main has a completely different one.

How to reproduce

1. Submit a new_task that creates or modifies a file (e.g. "create a pyproject.toml for project xyz v0.0.1")
2. Wait for the agent to open the PR
3. While the PR is open, push a change to main that touches the same file (e.g. a different pyproject.toml with different project name, version, dependencies)
4. The PR is now unmergeable - GitHub shows "This branch has conflicts that must be resolved"
5. Submit a pr_iteration on that PR (e.g. to address review feedback)
6. The agent works on top of its own branch without realizing main has diverged - it edits a pyproject.toml that doesn't reflect what's actually on main

Proposed solution

The pr_iteration workflow should check for conflicts before starting work:

1. Detect - at the start of pr_iteration, after checking out the PR branch, run git merge origin/main --no-commit --no-ff (or git rebase origin/main --no-autostash) to see if there are conflicts
2. Resolve if possible - if there are conflicts, the agent already has full context (it knows what the PR is doing and can read the incoming changes from main). Include in the pr_iteration prompt something like: "Before addressing review feedback, check if your branch has conflicts with the base branch. If it does, resolve them first - the base branch version takes priority unless the PR explicitly changes that file"
3. Surface if not - if the conflict is too complex (e.g. large structural changes), fail with a clear message: "PR has merge conflicts with main that need manual resolution" instead of silently working on a stale branch

This could also work as an automatic trigger: a webhook on the pull_request event with action: "auto_merge_failed" or a periodic check for unmergeable PRs that creates pr_iteration tasks to resolve them. But the simpler first step is just making pr_iteration conflict-aware.

Other information

No response

Acknowledgements

• I may be able to implement this feature
• This might be a breaking change