PR conflict conversation

What it is

The one conversation your computers hold when a pull request you pushed conflicts.

Before a pull request exists, the master sync's merge agents settle a conflict during the sync. Once a pull request is pushed and conflicts, the owner's rule is different: the computers involved and the main computer agree one version for now, so everyone keeps syncing, and then one side tests and publishes the final version that everyone adopts. This conversation is how they do that.

Where to find it

Between your own computers it rides Agents across your computers. Each computer routes one standing conversation, sync-conflicts, to the session that handles conflicts there, exactly as any other conversation is routed. The computer that publishes to GitHub has the main computer role switched on; every other computer leaves it off.

Another developer takes part through the agent lane you share in Team Chat. The conflict reaches the session their lane is routed to, and they take part as one party, whichever of their computers answers. The main computer opens a conflict with a developer only once the lane is switched on at both ends; if it goes off later, that developer is treated like a computer that is away, and gets what they missed, in order, once it is back on.

A lane is a teammate, not you, so a developer's computer takes a version from the conversation only when it is GitHub master's own copy, or the copy it already has. No one can place code on another computer through a lane. It also means that when your main computer's agent picks the pull request's copy as the interim, other developers' computers stay on master's copy until the final.

How it behaves

It starts on its own

You do not have to ask for it. Every 15 minutes, your main computer checks GitHub for pull requests into master that conflict, and starts the conversation for each one it finds — including every pull request that already conflicted when you first set this up, all at once. A conflict GitHub merely reports is not enough: git itself is asked to try the merge, and only the files it cannot merge open a conversation. A pull request that merges cleanly starts nothing, and is not looked at again until it is pushed to.

A pull request that merges cleanly starts nothing — but that is a verdict about the master it was checked against, not a life sentence. Master moves, and a pull request that merged cleanly a while ago can genuinely conflict later; it is looked at again when that happens, so a conflict cannot go quietly unnoticed.

It runs only on the computer with the main computer role, and only while that role is on. If something it needs is missing — the GitHub CLI not installed or not signed in, the sync-conflicts conversation switched off, or no session routing that conversation — you get one card in your inbox naming exactly what is missing, with a button that takes you to where you fix it. Nothing opens until it is fixed. A temporary GitHub outage is not a card; it just tries again on the next run.

Starting all of them at once can take a while the first time. A run works through as many as it can in about nine minutes, saves each one as it goes, and picks up where it stopped next time — so you never have to wait for it, and nothing is started twice.

Your teammates, once you say so

By default only pull requests you opened start a conversation. To have your teammates' conflicts start too, turn on Start conflicts for teammates' pull requests too in the Dev Pipeline panel's Setup tab, in the Master sync card. It is off until you turn it on.

A teammate is recognised by the GitHub account their own computer recorded — but nothing at all is sent to another developer until you switch this on. No message, no question, nothing. Your computer then asks, over the agent lane you share, which account they publish as; their computer answers with the account its own gh is signed in as, and is the only machine that can ever answer for them. It answers again only if that account changes. You never type it in for them, a claim from anyone else on the lane is ignored, and if two developers somehow answer with the same account it names neither of them. A teammate who has not set that up, or whose lane is not currently connected, is simply left alone; their pull requests are not touched. When one of theirs does start, the conversation names their lane as the side responsible for the final, because the work is theirs.

Nothing reaches GitHub until you say so

The conversation settles a version on its own, but changing anything on GitHub is always your decision. Two of its four jobs do that — the side responsible for the final pushes the branch and updates the pull request, and your main computer merges the pull request into master. Neither one runs until you approve it for that specific conflict, with one button on a card in your inbox. Until then the work is finished locally and simply waits, which costs nothing.

The approval is per conflict and one-shot: approving one conflict never approves another, and no agent can give itself that permission — the button is on your card, in your app, on your computer.

One thread per conflict, opened by the main computer

The main computer opens each conflict as one thread on the standing conversation, naming the files, the computers involved and the one responsible side (the pull request's author by default). No computer has to find the thread, and no second thread about the same conflict can start. A pull request whose conversation is still running is skipped whatever new commits are pushed to it, so a fresh push cannot start a rival thread.

When one conversation cannot carry it

A conflict in more than 25 files, or in a file GitHub master has deleted, is more than one conversation can hold. That pull request gets one card naming it in your inbox, asking a person to settle it, and no conversation is opened.

The interim is GitHub master's copy

Every computer already syncs GitHub master, so its copy of each conflicted file is the interim version: adopting it cannot start another conflict, and nothing has to be sent. Silence by the deadline is agreement. The interim settles within 30 minutes of opening, or sooner once every computer has agreed. The one exception is the computer that authored the pull request: it keeps the pull request's changes in those files until the final lands, so your local build and tests keep working while the final is prepared.

Nobody loses unpublished work

A computer whose master holds lines in a conflicted file that are in neither the pull request nor GitHub master objects automatically and keeps its own copy, visibly, until the final lands. The master sync only ever replaces a copy an agreement already knows, so no agreement can remove that work. An objection wakes the main computer's agent once to decide.

The final rides the pull request

The responsible side is woken to test the merged result and update the pull request. The main computer publishes it; the final record names the published commit and each file's version, and every computer checks those against GitHub before adopting. The thread closes once every computer has confirmed.

It asks you only when the agents cannot agree

A conflict spends at most three agent turns per computer and twenty-four in all, and each computer at most fifty a day. The records themselves cost nothing: they are filed, never counted as turns, and they never use up an agent lane's own allowance. When a limit is spent, the final is overdue, or two computers both claim to be the main computer, you get a card. When a limit is spent or the final is overdue, each other developer involved also gets one Team Chat message on their own machine.

When a conflict has used its turns, its card has a Give the agents another round button. One click starts that conflict's allowance over and wakes the agent whose turn was refused, if that step is still needed. Only you can press it; no agent can. When a computer has used its fifty for the day, its card says so instead: a refill cannot help that, and the limit resets each day.

A closed laptop never holds anyone up

A computer that does not answer by the deadline is skipped and catches up when it returns. An absent main computer delays only objections and the final, never the interim. If the side building the final is away past its 24 hours, you get a card and the main computer's agent hands the final to another computer, which gets a fresh 24 hours.

For agents

The conversation's records are typed data under the 8,000-character message cap: open, ack, object, interim, final-ready, final, reassign, adopted, closed. A record can only choose among versions that exist on GitHub, and no record carries write access or a credential. A developer's party is named lane:<their Team Chat id>, and a lane may speak only for its own developer. The desk session on each computer follows the sync-conflict-desk skill; its routes live under /agent-devices/conflicts, present while either Agents across your computers or agent lanes is on.

Related

• pr-conflict-conversation-contract.md — the promises.
• cross-device-agent-messages.md — the carrier between your computers.
• agent-lanes.md — the carrier to other developers.