[plan] EP022: Add branch existence pre-flight check to push_to_pull_request_branch handler

[github-actions]

Context

From Safe Output Health Report - 2026-03-22 (EP022 NEW).

The push_to_pull_request_branch handler currently attempts git fetch origin <branch> without first verifying the branch exists on the remote. When the branch is missing, git exits with code 128 — a cryptic error that doesn't explain the root cause or how to fix it. This also cascades to cancel all subsequent safe output messages.

Failing workflow run: §23392658504

Objective

Before the git fetch in push_to_pull_request_branch, add a pre-flight check using the GitHub API to verify the target branch exists. If it doesn't, fail with an actionable error message.

Files to Modify

• actions/setup/js/push_to_pull_request_branch.cjs — main handler (602 lines)

Approach

1. After resolving the PR number and branch name (around line ~330–380, before the git fetch), add a pre-flight check using the GitHub REST API:

   // Pre-flight: verify branch exists on remote
   try {
     await githubClient.request('GET /repos/{owner}/{repo}/git/ref/heads/{branch}', {
       owner: repoParts.owner,
       repo: repoParts.repo,
       branch: branchName,
     });
   } catch (err) {
     if (err.status === 404) {
       core.setFailed(
         `Branch '${branchName}' not found in ${repoParts.owner}/${repoParts.repo}. ` +
         `Ensure the target PR/branch exists before running this workflow. ` +
         `If the PR was merged or closed, you may need to recreate the branch.`
       );
       return;
     }
     throw err;
   }

2. The check should use the same githubClient already initialized with the appropriate token (cross-repo PAT or GITHUB_TOKEN)
3. Fail early with core.setFailed() (not throw) so the error is clear and doesn't cascade unnecessarily

Acceptance Criteria

• When the target branch does not exist, the handler fails immediately with an actionable error message referencing the branch name, repo, and remediation steps
• The error message does NOT cascade a "remaining safe outputs will be cancelled" warning (i.e., it should be treated as a graceful pre-flight failure, not a code push failure — consider using the skipCancelOnFail pattern if available)
• When the branch exists, behavior is unchanged
• make fmt-cjs && make lint-cjs pass
• Unit tests updated if applicable

Notes

• The current post-fetch check at line ~393 (git rev-parse --verify origin/${branchName}) is redundant with a successful API pre-flight but can remain as a safety net
• This is distinct from EP016 (PR title prefix validation) — today's failure occurs at the git fetch phase before any PR validation

Generated by Plan Command for issue #discussion #22230 · ◷

• expires on Mar 24, 2026, 4:46 AM UTC