fix(webhooks): resolve fresh pull request merge commits

CHANGELOG.md

@@ -10,6 +10,22 @@ Releases before v0.27.0 predate the changelog.
 
 ### Added
 
+- **Self-built pull-request test merges**: a local `preloop run --event
+  pull_request` now tests the merge of the pull request's *current* base tip
+  into the workspace head (the synthetic snapshot commit when the tree is
+  dirty), exactly like GitHub's `refs/pull/<n>/merge`, instead of the branch
+  alone. The engine fetches the base branch from the workspace's `origin`,
+  builds the merge with `git merge-tree`/`git commit-tree`, and serves it to
+  the run's jobs from an engine-served snapshot repository (the commit exists
+  only here). `github.sha` is the merge commit, `github.ref` stays
+  `refs/pull/<n>/merge`, and the payload's `base.sha`/`head.sha` carry the
+  fetched base tip and the merged head, so changed-file actions keep diffing
+  the user's changes. A conflicted pull request fails the submission (409)
+  listing the conflicted files, exactly where GitHub refuses to run
+  `pull_request` workflows; an unreachable base fails loudly instead of
+  testing a different tree. `--no-merge` restores testing the branch alone,
+  and `push` events are unchanged (they test the commit itself). The server
+  also validates and serves prebuilt merges for other submission paths.
 - Environment protection rules now come from GitHub. When a GitHub App (or
   `PRELOOP_GITHUB_TOKEN`) covers a repository, the rules for a job's
   `environment:` are read from the repository's environments API —
@@ -426,6 +442,13 @@ Releases before v0.27.0 predate the changelog.
   Legs of one matrix share that `job_order`, so among themselves they fall
   back to `job_id`.
 
+- **Fresh pull-request merge resolution**: Webhook-delivered `pull_request` and
+  `pull_request_review` runs poll for GitHub's live test merge and accept it
+  only when its second parent matches the payload head. If unavailable, the
+  engine builds a merge of the current base and pinned payload head and serves
+  it from its mirror; it never falls back to the bare pull-request head.
+  Conflicted pull requests do not start `pull_request` runs.
+
 - **Server integration tests no longer fail on a leaked static PAT**:
   `cargo test` shares one process environment across a whole test binary, so
   a `PRELOOP_GITHUB_TOKEN` set by a neighbouring test — or injected into the

crates/preloop-cli/src/main.rs

@@ -980,6 +980,14 @@ struct RunArgs {
         action = clap::ArgAction::Set
     )]
     pr_draft: bool,
+
+    /// Test the branch alone instead of the merge of the pull request's
+    /// current base tip into it. Only affects `--event pull_request` runs
+    /// against a local engine: by default those run on the merge (the base
+    /// tip is fetched from origin), like GitHub's `refs/pull/<n>/merge`.
+    /// Use this when the base branch cannot be fetched.
+    #[arg(long)]
+    no_merge: bool,
 }
 
 #[derive(Debug, Parser)]
@@ -2877,10 +2885,9 @@ fn strip_branch_prefix(raw: &str) -> &str {
 
 /// Branch a `pull_request` run should be filtered against.
 ///
-/// GitHub applies `on.pull_request.branches` to the PR's *target* branch, not
-/// the head branch. Without this a local PR run filters on the checked-out
-/// branch and a workflow gated to `branches: [main]` never matches. Only
-/// derived when the payload does not already carry a base ref.
+/// GitHub applies `on.pull_request.branches` to the PR's target branch. When
+/// no target is supplied, use the remote's advertised default branch rather
+/// than the checked-out branch's tracking ref.
 fn default_local_filter_branch(
     event: &str,
     base: Option<&str>,
@@ -2897,20 +2904,34 @@ fn default_local_filter_branch(
     {
         return None;
     }
-    // An explicit `--base` is the user's stated PR target and names the branch
-    // filters apply to whether or not the ref exists locally — shallow clones
-    // and un-fetched bases are normal. Only the fallback needs a real ref,
-    // because it has nothing else to go on.
-    let base = match base {
-        Some(base) => base.to_owned(),
-        None => resolve_local_diff_base(None)?,
-    };
-    // Filters are written against branch names (`main`), not remote-qualified
-    // refs (`origin/main`), but branches can contain slashes (`feature/auth`).
+    let base = base.map(str::to_owned).or_else(local_default_branch)?;
     let name = strip_branch_prefix(&base).to_owned();
     (!name.is_empty()).then_some(name)
 }
 
+fn local_default_branch() -> Option<String> {
+    for remote in git_remotes() {
+        let output = std::process::Command::new("git")
+            .args([
+                "symbolic-ref",
+                "--quiet",
+                "--short",
+                &format!("refs/remotes/{remote}/HEAD"),
+            ])
+            .output();
+        let Ok(output) = output else {
+            continue;
+        };
+        if output.status.success() {
+            let branch = String::from_utf8_lossy(&output.stdout).trim().to_owned();
+            if !branch.is_empty() {
+                return Some(branch);
+            }
+        }
+    }
+    None
+}
+
 fn collect_local_reusable_workflows(
     workflow_path: &std::path::Path,
 ) -> anyhow::Result<BTreeMap<String, String>> {
@@ -3035,6 +3056,11 @@ async fn cmd_run(args: RunArgs) -> anyhow::Result<()> {
         // list the server was just handed.
         changed_paths_known: derived_changed_paths.is_some(),
         filter_branch: derived_filter_branch,
+        // A local `pull_request` run tests the merge of the current base tip
+        // into the head by default (like GitHub's `refs/pull/<n>/merge`);
+        // `--no-merge` is the explicit escape back to testing the branch
+        // alone.
+        no_merge: args.no_merge,
         // `--debug` keeps the failed runner waiting for a verdict;
         // `--preserve-on-failure` only keeps a completed failed VM for shell.
         preserve_on_failure,

crates/preloop-gha-protocol/src/lib.rs

@@ -203,6 +203,35 @@ pub struct PushRequest {
     pub dirty: bool,
 }
 
+/// A self-built pull-request test merge the engine must check out for a run.
+///
+/// GitHub computes a pull request's test merge asynchronously and this engine
+/// cannot wait for it, so the merge is built locally: `sha` is a two-parent
+/// merge commit (first parent the base tip, second the pull request head)
+/// that exists only in the engine's mirror. Jobs therefore fetch from the
+/// engine, never the forge. The engine validates that the mirror belongs to
+/// the named repository and that the commit has the claimed parents and tree.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct PrebuiltMerge {
+    /// The two-parent merge commit the run tests.
+    pub sha: String,
+    /// The merge commit's tree.
+    pub tree: String,
+    /// First parent: the base tip the merge was built against.
+    pub base_sha: String,
+    /// Second parent: the pull request's head commit.
+    pub head_sha: String,
+    /// Repository whose cache mirror contains this merge.
+    pub repository: String,
+    /// State-directory-relative path of the bare mirror holding the merge and
+    /// its parents (for example `checkout-cache/repositories/<key>.git`).
+    pub mirror_repository: String,
+    /// Pull request number, when known; labels `refs/pull/<n>/merge` in the
+    /// served repository.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub pull_request_number: Option<u64>,
+}
+
 /// Complete workflow request submitted to the control plane.
 #[derive(Debug, Clone, Serialize, Deserialize, Default)]
 pub struct WorkflowSubmission {
@@ -333,6 +362,18 @@ pub struct WorkflowSubmission {
     /// commit it did not test.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub push_tree: Option<String>,
+    /// Test the branch alone instead of the merge of the pull request's
+    /// current base tip into it. Only meaningful for `pull_request` events
+    /// (the CLI's `--no-merge`): the escape hatch when the base branch cannot
+    /// be fetched.
+    #[serde(default)]
+    pub no_merge: bool,
+    /// A self-built pull-request test merge the run must check out. Set when
+    /// the merge commit exists only in the engine (see [`PrebuiltMerge`]);
+    /// the engine serves it to the run's jobs regardless of checkout-cache
+    /// configuration.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub prebuilt_merge: Option<PrebuiltMerge>,
 }
 
 impl WorkflowSubmission {

crates/preloop-runner-server/Cargo.toml

@@ -125,6 +125,11 @@ name = "webhooks"
 path = "tests/webhooks.rs"
 required-features = ["test-support"]
 
+[[test]]
+name = "merge"
+path = "tests/merge.rs"
+required-features = ["test-support"]
+
 [[test]]
 name = "concurrency"
 path = "tests/concurrency.rs"

crates/preloop-runner-server/src/dispatch.rs

@@ -529,6 +529,8 @@ fn submission_from_effective(
         debug_on_failure: false,
         push: None,
         push_tree: None,
+        no_merge: false,
+        prebuilt_merge: None,
     }
 }