push_to_pull_request_branch: bundle generated for current checkout branch, not the named pull_request_number — apply fails with "couldn't find remote ref" in multi-PR batch workflows

[dsyme]

Summary

push_to_pull_request_branch silently generates a git bundle for the wrong branch in multi-PR batch workflows, because the bundle's source branch is derived from the working-tree's current HEAD at MCP-call time, while the apply step independently derives the destination branch from the pull_request_number argument. When those two disagree, the apply step fails with:

Error: Failed to apply bundle: Failed to fetch bundle: fatal: couldn't find remote ref refs/heads/<pr-head-branch>

and the safe output never lands. The PR instead receives a warning comment:

Warning

The push_to_pull_request_branch operation failed: Failed to apply bundle. The code changes were not applied.

Where it happens

This is reproducible with batch workflows that loop over many PRs, git checkout each PR branch, and call push_to_pull_request_branch(pull_request_number=X). Observed in production runs of the github/github-automation Deep Clean workflow operating cross-repo against github/github (sparse, shallow checkout, PAT-authenticated):

• https://github.com/github/github-automation/actions/runs/28172063942 (job safe_outputs 83446470284)
• https://github.com/github/github-automation/actions/runs/28196257479 (job safe_outputs 83529619197)
• Failure comment: https://github.com/github/github/pull/437962#issuecomment-4800034680

Root cause

The source branch (what goes into the bundle) and the destination branch (where the apply step pushes) are computed from two independent, unreconciled sources:

1. MCP collection time — pushToPullRequestBranchHandler in actions/setup/js/safe_outputs_handlers.cjs strips any agent-supplied branch and sets:

   const detectedBranch = getCurrentBranch(repoCwd);
   entry.branch = detectedBranch;

   The accompanying comment encodes the (unenforced) assumption:

   Derive it from the current checkout: the working tree must be on the PR head ref because that's what the agent committed onto. The apply-time push job independently re-derives the destination from pulls.get(pull_number)...

   The bundle filename and its internal ref are then built from this entry.branch — generate_git_bundle.cjs runs git bundle create <file> <baseRef>..<branchName>, so the bundle contains refs/heads/<currentBranch>.

2. Apply time — actions/setup/js/push_to_pull_request_branch.cjs resolves the destination independently from the pull_request_number:

   const response = await githubClient.rest.pulls.get({ ... pull_number });
   branchName = pullRequest.head.ref;            // <- destination branch
   ...
   const bundleFetchRef = `refs/heads/${branchName}:${bundleRef}`;
   await exec.getExecOutput("git", ["fetch", bundleFilePath, bundleFetchRef], ...);

   while the bundle file itself is located via message.branch (the current-checkout branch) in resolve_transport_paths.cjs.

There is no validation that getCurrentBranch() corresponds to the PR identified by pull_request_number. When the agent's working tree is checked out on a different branch than the PR it names — which happens whenever tool calls interleave with git checkout, run in parallel, or execute out of order in a batch loop — the bundle is named after, and contains a ref for, branch A, but the apply step tries to git fetch refs/heads/B (B = the named PR's head). The bundle has no refs/heads/B, so git fetch fails with couldn't find remote ref refs/heads/B.

The agent in run 28172063942 actually observed the mismatch itself:

# Switch to 437916 branch for its push (the bundle ended up on 438016 so
# 437916 still needs a push)

Concrete evidence

Run 28196257479, message 1/12 (from the safe_outputs log):

Bundle file path: /tmp/gh-aw/aw-github-github-dsyme-deep-clean-style-mechanical-authorization-platform-reviewers-01-...bundle
Target branch:    dsyme/deep-clean/style-mechanical-lifecycle-reviewers-01-...
git fetch <...authorization-platform...bundle> refs/heads/dsyme/deep-clean/style-mechanical-lifecycle-reviewers-01-...:refs/bundles/...
fatal: couldn't find remote ref refs/heads/dsyme/deep-clean/style-mechanical-lifecycle-reviewers-01-...
Error: Failed to apply bundle

The bundle is …authorization-platform… but the target branch is …lifecycle…. The bundle only contains refs/heads/…authorization-platform…, so fetching refs/heads/…lifecycle… cannot succeed.

Run 28172063942, message 1/11 shows the same pattern: bundle …minitest-assertions-marketplace… vs target branch …style-mechanical-hosted-compute….

Why the existing recovery paths don't catch it

The apply step has recovery logic for missing prerequisite commits (shallow/fetch-depth:1 races, cf. #32310/#32467) but that path only triggers when the bundle ref exists and is missing ancestors. Here the bundle ref is entirely absent (wrong branch name), so extractBundlePrerequisiteCommits() returns empty and the handler goes straight to throw new Error("Failed to fetch bundle: ..."). This is a different failure mode than the shallow-clone bundle issues (#31600, #32310, #32467) and from the create_pull_request ref-name mismatch (#31918, #32069), all of which are closed.

Suggested fixes (any one closes the gap)

1. Bind source to the named PR at MCP time. When pull_request_number / target is supplied, resolve the PR head ref via the API in pushToPullRequestBranchHandler and assert the current checkout matches it. If not, fail fast with a clear, actionable error (or check out the correct ref before generating the bundle) instead of silently bundling the wrong branch.

2. Make the apply step fetch the ref the bundle actually contains. Record the bundle's real source branch in the safe-output message and, at apply time, fetch that ref from the bundle, then update-ref the API-resolved destination head to the bundle tip. This decouples "ref inside bundle" from "destination branch name".

3. At minimum, add a guard + diagnostic in the apply handler: if message.branch (the bundle's source) differs from the resolved pullRequest.head.ref, emit an explicit error like "bundle was generated for branch A but PR #N head is branch B; the working tree was not on the PR head ref when push_to_pull_request_branch was called" rather than the opaque couldn't find remote ref.

Environment

• gh-aw safe-outputs runtime (MCP collection + apply jobs), cross-repo push with target-repo + per-handler github-token (PAT), sparse + shallow (fetch-depth: 1) checkout of the target repo.
• Engine: copilot (claude-sonnet model), batch workflow processing 10+ PRs per run.

[dsyme]

Design for the chosen fix (option 2): agent-supplied branch + bundle-ref-faithful apply

We're going with option 2, refined so the source branch is explicitly provided by the agent rather than inferred from the working-tree HEAD. This removes the unenforced "the working tree must currently be on the PR head ref" assumption that is the root cause.

1. Reinstate branch as a required input to the MCP tool

Today pushToPullRequestBranchHandler in actions/setup/js/safe_outputs_handlers.cjs explicitly strips any agent-supplied branch:

// Defensive strip: the input schema no longer declares a `branch` property...
const { branch: _agentBranch, ...sanitizedArgs } = args || {};
...
const detectedBranch = getCurrentBranch(repoCwd);   // <- inferred from HEAD
entry.branch = detectedBranch;

Instead:

• Re-declare branch in the tool's input schema (safe_outputs_tools.json / the push tool definition) and require it. The agent that just committed onto a branch knows exactly which branch it is; making it explicit eliminates the interleaving/parallel-checkout race entirely.
• entry.branch = <agent-supplied branch> (sanitized via the existing normalizeBranchName / filename-sanitization path).
• getCurrentBranch() becomes at most a fallback for backward-compat (or is dropped). The authoritative source is the agent input.

2. MCP-side validation is local only — do not consult the PR API

Crucially, the MCP collection step must not try to verify that branch matches the target PR's head ref, because the credentials needed to read the (possibly cross-repo) PR are not guaranteed to be available at MCP-collection time. The per-handler github-token / PAT is applied in the apply job, not necessarily during collection.

So the MCP handler validates branch using git only, in repoCwd:

• branch exists locally: git show-ref --verify --quiet refs/heads/<branch> (or git rev-parse --verify refs/heads/<branch>^{commit}). Fail with a clear error if not — "branch '' does not exist in the checkout; check it out and commit before calling push_to_pull_request_branch".
• branch is not empty and not equal to the resolved base_branch (reuse the existing equals-base-branch guard).
• There are commits to push on origin/<branch>..<branch> (the existing incremental-empty check).

No pulls.get(), no network, no token dependency at collection time.

3. Bundle generation is unchanged in shape, but now keyed off the explicit branch

generate_git_bundle.cjs already builds git bundle create <file> <baseRef>..<branchName>, producing a bundle that contains refs/heads/<branchName>. With branchName now = the agent-supplied branch, the bundle filename (/tmp/gh-aw/aw-<sanitized-branch>.bundle) and its internal ref are guaranteed consistent with what the agent intended, regardless of what HEAD is currently pointing at.

The branch is recorded in the safe-output JSONL message (it already flows through entry.branch; it's now authoritative and agent-controlled rather than inferred).

4. Apply step: fetch the ref the bundle actually contains, then update-ref the destination

In actions/setup/js/push_to_pull_request_branch.cjs the destination is still resolved independently and authoritatively from the PR — this is the security boundary and must stay:

const response = await githubClient.rest.pulls.get({ ..., pull_number });
const destinationBranch = normalizeBranchName(response.data.head.ref);

But the bundle fetch must use the bundle's own ref (= message.branch), not the destination:

// today (buggy): fetches refs/heads/<destinationBranch> from a bundle built for message.branch
const bundleFetchRef = `refs/heads/${branchName}:${bundleRef}`;

// proposed: fetch the ref the bundle actually contains
const sourceBranch = message.branch;                       // what the bundle was built from
const bundleFetchRef = `refs/heads/${sourceBranch}:${bundleRef}`;
await exec.getExecOutput("git", ["fetch", bundleFilePath, bundleFetchRef], ...);

// then point the API-resolved destination head at the bundle tip
await exec.exec("git", ["update-ref", `refs/heads/${destinationBranch}`, bundleRef], ...);
// ...checkout destinationBranch / push as today

resolveTransportPaths() already locates the bundle by message.branch, so the file and the fetched ref are now guaranteed to agree. This decouples "ref name inside the bundle" (source, agent-controlled) from "destination branch the push lands on" (resolved from the PR at apply time).

5. Security / threat model is preserved

• The agent supplying branch only selects which local source ref / bundle is used. The path is always re-derived to the sanitized /tmp/gh-aw/aw-<sanitized-branch>.bundle prefix, so a forged value cannot point outside the canonical location (same protection resolveTransportPaths already documents).
• The destination is still resolved authoritatively from pulls.get(pull_number).head.ref at apply time, with the existing fork-PR check, default/protected-branch check, and allowed-branches/labels gates. The agent cannot redirect the push to an arbitrary branch via the branch input.
• Net effect: agent controls what changes (the bundle it built locally), gh-aw controls where they land (the named PR's head), and the two are reconciled by update-ref rather than by an implicit "fetch a ref that may not exist" coincidence.

6. Add the guard + diagnostic anyway (option 3 as defense-in-depth)

If, after fetching, the bundle does not contain refs/heads/<message.branch> (corrupt/empty bundle, or a legacy mismatched message), fail with an explicit message naming both the bundle's source branch and the resolved destination, instead of the opaque couldn't find remote ref.

Net behavior change for callers

Batch/multi-PR workflows (e.g. Deep Clean) must pass branch explicitly on each push_to_pull_request_branch call. This is strictly more robust than relying on HEAD, and makes parallel/out-of-order safe-output tool calls correct by construction. Workflows that previously relied on the implicit current-branch behavior keep working only if they pass the branch; we should call this out in the changeset/migration notes (and optionally keep getCurrentBranch() as a deprecated fallback for one release).