ci: resolve PR merge conflicts with a sandboxed Pi agent

[cv]

Problem Statement

An open PR can conflict with main after either branch changes.
Maintainers must then update the PR branch and resolve the conflicts.
This work delays review and prevents CI from testing the merged files.

NemoClaw has no automation that resolves these conflicts.
The automation must treat all PR files and commands as untrusted.
It must not expose a model credential or GitHub credential to PR code.

Desired Behavior

A workflow must process an open PR when all these conditions are true:

• The PR has the opt-in conflict-fixer label.
• The head repository is NVIDIA/NemoClaw.
• The base branch is main.
• The exact PR SHA conflicts with the exact base SHA.
• All conflicted files are supported text files.

The workflow must complete these actions:

1. Run one Pi coding-agent task in an OpenShell sandbox.
2. Let Pi read and edit the repository and run available local commands.
3. Restrict Pi changes to the original conflicted files.
4. Validate the result outside the sandbox.
5. Create a verified merge commit with the PR SHA and base SHA as its parents.
6. Update the PR branch without a force push.
7. Let the branch update start the normal PR CI workflows.

For example, assume PR #123 conflicts with main in src/example.ts.
The workflow resolves only src/example.ts.
The workflow then pushes one merge commit if the PR SHA and base SHA are unchanged.

Constraints and Non-goals

• Version 1 supports same-repository PRs only.
• Version 1 requires an opt-in label.
• Version 1 supports regular text files below a fixed size limit.
• Version 1 does not support binary files, symlinks, or submodules.
• Version 1 does not resolve conflicts in .github/**, .agents/**, CODEOWNERS, or security-policy files.
• Pi must not fix review findings, refactor code, or update dependencies.
• The sandbox must not contain a GitHub token.
• The sandbox must use OpenShell inference routing instead of a model credential.
• The publisher must not force-push or update a changed PR branch.
• Fork PR support is not part of this work.
• A custom sandbox image is not part of this work.
• A separate comment bot, result schema, review ledger, and test-selection system are not part of this work.

Before implementation, maintainers must approve this product surface.
The decision must identify the owner, lifecycle, GitHub App, model, cost limit, and supported conflict types.

Implementation Idea

Add one workflow with three jobs and two privilege domains:

1. discover finds eligible conflicts with read-only GitHub access.
2. resolve runs Pi in OpenShell with read-only GitHub access.
3. publish validates the result and updates the branch with a dedicated GitHub App.

The workflow should run after a PR head update and after a push to main.
The main trigger should inspect only open PRs with the opt-in label.

Pin the OpenShell version and the official Pi image digest.
Disable PR-provided Pi skills, extensions, prompt templates, and context files.
Allow write access only to the sandbox work directory.
Deny external network access except OpenShell inference routing.
Delete the sandbox after every result.

The resolver should return one bounded binary patch.
The publisher should recreate the same merge from the PR SHA and base SHA.
It should reject changes outside the original conflicted files.
It should also reject unresolved entries, malformed paths, and oversized output.

The publisher should create the two-parent commit through the GitHub API.
It must verify the bot signature before it updates the branch reference.
The reference update must be a fast-forward update.

Keep the implementation in one focused directory:

.github/workflows/pr-merge-conflict-fixer.yaml
tools/pr-merge-conflict-fixer/
  discover.mts
  resolve.mts
  publish.mts
  policy.yaml
test/
  pr-merge-conflict-fixer.test.ts
  pr-merge-conflict-fixer-workflow-boundary.test.ts

Acceptance Criteria

• An eligible textual conflict produces one verified merge commit on the unchanged PR branch.
• The merge commit has the expected PR SHA and base SHA as its parents.
• The result changes only the original conflicted files.
• A clean, unlabeled, fork, draft, or unsupported PR causes no branch change.
• A changed PR SHA or base SHA causes no branch change.
• A failed sandbox, failed validation, or denied GitHub update causes no branch change.
• PR code cannot read the GitHub App credential or model credential.
• PR code cannot access an external network endpoint.
• The branch update starts the normal PR CI workflows.
• Unit tests cover content conflicts, stale revisions, unsupported files, extra file changes, and malformed output.
• Workflow-boundary tests cover permissions, trusted source code, pinned dependencies, artifact provenance, and sandbox cleanup.
• A staging-repository test proves the GitHub App creates a verified commit and starts CI.
• CONTRIBUTING.md explains the opt-in label, supported files, and failure behavior.
• A documentation writer reviews the implementation and the contributor guidance.

Category

Feature

Checklist

• I searched existing issues and this is not a duplicate.
• I described the problem and desired behavior.

[cv]

Proposed simplification: use native GitHub Actions and one bot PAT

The conflict fixer does not need a custom GitHub App. Native GitHub Actions can run the complete workflow.

The workflow uses two GitHub credentials:

• GITHUB_TOKEN creates the verified merge commit.
• A bot personal access token (PAT) updates the PR head ref.

The PAT update starts the normal pull_request: synchronize workflows. A GITHUB_TOKEN update cannot provide the same unattended trigger behavior. GitHub documents the GITHUB_TOKEN trigger limits.

Required bot account

Create a dedicated bot user for the final ref update. Do not use a maintainer's personal account.

The bot user must have write access to NVIDIA/NemoClaw. The bot user should have no unrelated repository access.

Store one classic PAT with public_repo scope as an Actions secret. Expose the PAT only to the publish job.

A classic PAT has broader access than GITHUB_TOKEN. The dedicated bot account limits the affected repositories.

The OpenShell sandbox must not receive either GitHub credential.

Trigger and selection

A push to main starts the workflow. The workflow does not use a label or a manual trigger.

The scan job evaluates every open PR that targets main. The scan job evaluates same-repository PRs and fork PRs.

The scan job selects each PR that conflicts with the pushed base SHA. The scan job does not compare mergeability with the previous base SHA.

This selection rule has two useful results:

• A successful resolution removes the PR from the next scan.
• A failed resolution can run again after the next push to main.

The scan job skips a PR when Git cannot represent every conflict as a supported text-content conflict.

Fork authorization

The workflow can analyze every public fork PR without a write credential. GitHub authorization controls the final ref update.

For a fork PR, the publisher must require these conditions:

• The PR sets maintainer_can_modify to true.
• The fork head repository and head ref still exist.
• GitHub grants the bot user write permission to the head ref.
• The head ref still points to the recorded PR SHA.

GitHub documents maintainer edits for user-owned forks.

The publisher must leave the PR unchanged when GitHub denies the update. The workflow does not create a replacement PR.

A staging test must confirm the PAT behavior for a user-owned fork. The test must also cover an organization-owned fork.

Job 1: scan

The scan job uses default-branch workflow code. The job has read-only repository and PR permissions.

The job performs these actions:

1. Read all open PRs that target main.
2. Record the pushed base SHA.
3. Record each PR SHA and head ref.
4. Reproduce each merge with Git.
5. Select the PRs that have supported conflicts.
6. Produce one matrix entry for each selected PR.

The scan job must use Git results as the mergeability source. GitHub can report an unknown mergeability state.

Job 2: resolve

Each matrix entry starts one resolve job. The resolve job has read-only GitHub permissions.

The resolve job performs these actions:

1. Fetch the exact PR SHA and base SHA.
2. Reproduce the merge conflict.
3. Upload the repository copy to OpenShell.
4. Run one Pi task in the sandbox.
5. Download one bounded patch.
6. Delete the sandbox.

The sandbox receives no GitHub token. OpenShell provides model access through inference.local.

Pi can change the disposable repository copy. The trusted publisher accepts changes only for the original conflict files.

Job 3: publish

The publish job receives GITHUB_TOKEN and the bot PAT. The publish job does not run PR commands.

The publish job performs these actions:

1. Read the PR again.
2. Require the recorded PR SHA.
3. Require the recorded base SHA.
4. Reproduce the merge outside the sandbox.
5. Validate every patch path and file type.
6. Apply the patch to the original conflict files.
7. Require no unresolved conflict entries.
8. Require no changes outside the original conflict files.

The publisher then creates a commit through the Git Database REST API. The commit has these parents, in this order:

1. The recorded PR SHA.
2. The recorded base SHA.

The request must omit custom author, committer, and signature data. GitHub can then apply its bot signature. GitHub documents the bot signature requirements.

The publisher must require verification.verified before the ref update.

The publisher uses the bot PAT only for the ref update. The GraphQL updateRefs mutation must use these values:

• beforeOid: the recorded PR SHA.
• afterOid: the verified merge commit SHA.
• force: false.

The update fails when the contributor changes the PR branch. The update also fails when a repository rule denies the bot.

A PAT-authenticated ref update starts the normal PR workflows. GitHub documents PAT-triggered workflow behavior.

Operational limits

The workflow does not need a custom cost-control service. Use normal Actions controls:

• One Pi task for each selected PR.
• One workflow timeout.
• One combined conflict-content limit.
• One patch-size limit.
• One matrix max-parallel value.
• One concurrency group for each PR.

A newer push to main should cancel an older run for the same PR. The new run uses the new base SHA.

Failure behavior

A failure must not change the PR branch. The workflow summary must identify the failed phase and reason.

The workflow skips unsupported conflicts. The workflow does not add a comment or label.

The workflow must delete each sandbox after success, failure, or cancellation.

Acceptance tests

The implementation must include these tests:

• A push to main selects each eligible conflicted PR.
• A successful resolution changes only the original conflict files.
• The merge commit is verified and has the required parents.
• A changed PR SHA causes the ref update to fail.
• A changed base SHA causes the ref update to fail.
• A PAT update starts the normal PR checks.
• A writable fork branch receives the verified commit.
• An unwritable fork branch remains unchanged.
• The sandbox cannot read GitHub or model credentials.
• The sandbox cannot use an external network endpoint.
• Every completion path deletes the sandbox.

Product decision

Before implementation, maintainers must name these items:

• The bot account owner.
• The PAT rotation owner.
• The approved model and provider.
• The supported text-conflict class.
• The conflict-content and runtime limits.

This design removes the custom GitHub App, PR labels, manual actions, and a separate result service. The trusted publisher remains the only GitHub write boundary.

[cv]

Product decision for V1: use GITHUB_TOKEN only

This decision replaces the PAT and fork-publication sections in the previous proposal.

Authentication

V1 must use the repository GITHUB_TOKEN. V1 must not use these credentials:

• A custom GitHub App.
• A personal access token.
• A machine-user credential.
• A deploy key.

Only the trusted publisher can receive contents: write. The OpenShell sandbox must not receive a GitHub credential.

PR scope

V1 supports same-repository PRs only. An eligible PR must meet these conditions:

• The PR is open.
• The PR targets main.
• The head repository is NVIDIA/NemoClaw.
• The head ref still points to the recorded PR SHA.
• The pushed main ref still points to the recorded base SHA.

The scan job must skip each fork PR before conflict analysis. A fork PR must not start a sandbox or model request.

V1 does not create a replacement PR or resolution artifact for a fork PR. Fork support is a non-goal.

Trigger

Each push to main starts the conflict-fixer workflow. The workflow does not use a label or a manual trigger.

The scan job evaluates all eligible same-repository PRs. The scan job selects each PR that conflicts with the pushed base SHA.

The scan job does not compare the previous base SHA. A failed resolution can run again after the next push to main.

Resolution and publication

The resolve job runs one Pi task for each selected PR. Pi runs in an OpenShell sandbox without GitHub or model credentials.

The trusted workflow must validate the proposed merge outside the sandbox. The trusted workflow must reject these results:

• A change outside the original conflict files.
• An unresolved conflict entry.
• An unsupported file type.
• A malformed or oversized patch.
• A PR SHA or base SHA change.

The publisher creates a GitHub-verified commit with these parents, in this order:

1. The recorded PR SHA.
2. The recorded base SHA.

The publisher must require verification.verified before the ref update.

The publisher updates the PR head ref with GraphQL updateRefs. The mutation must use these values:

• beforeOid: the recorded PR SHA.
• afterOid: the verified merge commit SHA.
• force: false.

A rejected mutation must leave the PR branch unchanged.

Validation checks

A GITHUB_TOKEN ref update does not provide an unattended normal PR workflow run. V1 must not require a second pull_request workflow run.

The trusted conflict-fixer workflow owns validation for the proposed merge commit. The workflow must publish an explicit check for the verified commit SHA.

The validation job must not receive write permission. A separate reporting job can publish the check result.

Repository policy must name the required check before implementation. The check must cover the approved commands for this workflow.

Operational controls

V1 uses normal GitHub Actions controls:

• One Pi task for each selected PR.
• One workflow timeout.
• One combined conflict-content limit.
• One patch-size limit.
• One concurrency group for each PR.

V1 does not require a custom cost service, result service, label, comment bot, or review ledger.

Acceptance changes

V1 must meet these acceptance conditions:

• A push to main selects every eligible conflicted same-repository PR.
• A fork PR does not start conflict analysis or model inference.
• The sandbox cannot read a GitHub or model credential.
• The result changes only the original conflict files.
• The merge commit is verified and has the required parents.
• A changed PR SHA prevents the ref update.
• A changed base SHA prevents the ref update.
• The workflow publishes the named validation check for the verified commit SHA.
• The implementation contains no PAT or custom GitHub App dependency.

This scope keeps one short-lived GitHub credential and one repository write boundary. V1 automatically resolves eligible conflicts without maintainer action.

[cv]

Product decision: Minimal V1

This decision supersedes the earlier design comments in this thread.

Product contract

After each push to main, V1 resolves every conflicting same-repository PR with one credential-free Pi task.

A trusted publisher may update the PR branch only when all structural validation passes. Otherwise, the publisher must not update the branch.

Scope

V1 supports an open PR when these conditions apply:

• The PR targets main.
• The head repository is NVIDIA/NemoClaw.
• Git reports a merge conflict against the pushed base SHA.

The scan job must skip a fork PR before merge analysis. A fork PR must not start a sandbox or model request.

V1 does not use these components:

• A label or manual trigger.
• A personal access token.
• A custom GitHub App.
• A machine-user credential.
• A comment bot or result service.
• A custom validation check.
• A cost-control service.
• A file-mode taxonomy.
• A protected-path list.
• A retry service.

V1 uses the repository GITHUB_TOKEN as its only GitHub credential.

Workflow

V1 has three trust stages.

Scan

The scan job runs after a push to main. The scan job uses read-only GitHub permissions.

The scan job performs these actions:

1. List open same-repository PRs that target main.
2. Record the pushed base SHA and each PR SHA.
3. Reproduce each merge with Git.
4. Select each PR that has a merge conflict.

Git is the only mergeability source. The scan job must not query GitHub mergeability.

Resolve

Each selected PR starts one resolve job. The resolve job uses read-only GitHub permissions.

The resolve job performs these actions:

1. Fetch the exact PR SHA and base SHA.
2. Reproduce the merge conflict.
3. Run one Pi task in OpenShell.
4. Export one Git patch with the recorded identifiers.

The OpenShell sandbox must not receive a GitHub or model credential. OpenShell supplies model access through inference.local.

Pi may change the disposable repository copy. The publisher controls which changes enter the PR branch.

The resolve job must use automatic sandbox deletion. V1 does not require a separate cleanup service.

Publish

The publish job is the only job with contents: write. The publish job must not run PR commands.

The publisher performs these actions:

1. Read the PR and main state once at the write boundary.
2. Require the recorded PR scope and base SHA.
3. Reconstruct the merge from the recorded SHAs.
4. Apply the patch with Git.
5. Require no unresolved Git index entries.
6. Require that the resulting tree changes only original conflict paths.
7. Create a two-parent commit through the Git Database REST API.
8. Require GitHub signature verification.
9. Atomically update the PR head ref.

The commit must have these parents, in this order:

1. The recorded PR SHA.
2. The recorded base SHA.

The REST request must omit custom author, committer, and signature data. The publisher must require verification.verified.

The GraphQL updateRefs mutation must use these values:

• beforeOid: the recorded PR SHA.
• afterOid: the verified merge commit SHA.
• force: false.

beforeOid is the only PR-head race check. V1 does not require a separate live PR SHA comparison.

Git applies the patch and rejects an unsafe path. The final tree comparison is the only accepted-path check.

CI and validation

V1 validates conflict resolution only. V1 does not duplicate the repository CI system.

V1 does not require a new pull_request workflow run. V1 does not publish a custom check or commit status.

Normal CI behavior and required checks remain outside the V1 contract.

Operational behavior

V1 uses one workflow timeout. V1 does not define model-cost, conflict-size, patch-size, or matrix-parallel limits.

An input that exceeds a platform or model limit can fail. A failed run must not update the PR branch.

The next push to main starts a new scan. V1 does not store retry state.

Acceptance criteria

V1 must meet these acceptance criteria:

• A push to main selects every conflicting same-repository PR.
• A fork PR does not start merge analysis or model inference.
• The sandbox cannot read a GitHub or model credential.
• A successful result changes only original conflict paths.
• The merge commit is verified and has the required parents.
• A changed base SHA prevents publication.
• A changed PR head causes the atomic ref update to fail.
• Any structural validation failure leaves the PR branch unchanged.
• The implementation has no PAT or custom GitHub App dependency.
• The implementation does not create a validation check or commit status.

Remaining product approval

Before implementation, maintainers must name these items:

• The workflow owner.
• The V1 lifecycle.
• The approved model and provider.

The approved input is a conflict that Git exposes as editable files. V1 does not define additional conflict categories.

[cv]

Product approval for Minimal V1

Maintainers approve the Minimal V1 specification in the preceding product-decision comment. It supersedes the original issue body and earlier design comments.

• Workflow owner: @NVIDIA/nemoclaw-maintainer.
• Lifecycle: experimental maintainer automation.
• Model and provider: azure/openai/gpt-5.6-terra through OpenShell inference.

The sandbox receives no GitHub credential or upstream model credential. The repository GITHUB_TOKEN remains the only GitHub credential.

This approval completes the remaining product decisions. Implementation can proceed against the Minimal V1 specification.

[cv]

Minimal V1 amendment after the first production run

The first production run showed one GitHub platform limit: the repository GITHUB_TOKEN cannot update a PR branch when the resulting commit changes .github/workflows/**. GitHub returned Resource not accessible by integration.

Maintainers accept this narrow V1 amendment:

• Keep GITHUB_TOKEN as the only GitHub credential. Do not add a PAT or GitHub App.
• Skip a PR before model inference when any original conflict path is under .github/workflows/**.
• Do not add a fallback, label, comment bot, artifact, or retry path for that PR.
• Continue resolving every other conflicting same-repository PR.

This amendment supersedes the Minimal V1 requirements to select every conflicting same-repository PR and to have no protected-path exception. It does not create a general protected-path system; it records the one path GitHub prevents this credential from publishing.

Production evidence: https://github.com/NVIDIA/NemoClaw/actions/runs/30189296902