From de6a01acaaab917e1137d0423e2927fc10dd927c Mon Sep 17 00:00:00 2001
From: Joaquim Verges <joaquim.verges@gmail.com>
Date: Fri, 30 Oct 2026 09:09:14 -0700
Subject: [PATCH 1/3] Set up Mergepatrol

Co-authored-by: Nebula AI Agent <277912164+nebula-ai-agent[bot]@users.noreply.github.com>
---
 .agents/skills/mergepatrol/SKILL.md | 38 +++++++++++++++++++++++++++++
 .claude/skills/mergepatrol/SKILL.md | 38 +++++++++++++++++++++++++++++
 .mergepatrol/mergepatrol.yml        | 12 +++++++++
 3 files changed, 88 insertions(+)
 create mode 100644 .agents/skills/mergepatrol/SKILL.md
 create mode 100644 .claude/skills/mergepatrol/SKILL.md
 create mode 100644 .mergepatrol/mergepatrol.yml

diff --git a/.agents/skills/mergepatrol/SKILL.md b/.agents/skills/mergepatrol/SKILL.md
new file mode 100644
index 0000000..d7e48a2
--- /dev/null
+++ b/.agents/skills/mergepatrol/SKILL.md
@@ -0,0 +1,38 @@
+---
+name: mergepatrol
+description: This repo merges pull requests through Mergepatrol, a label-driven merge queue. Use when merging, landing or shipping a PR, queueing or dequeueing one, or reading a Mergepatrol comment or label on a PR.
+---
+
+# Mergepatrol
+
+Pull requests in this repo land through Mergepatrol's merge queue. Queue a PR with a label and let Mergepatrol merge it; merging by hand or pushing to the default branch races the queue.
+
+## The labels
+
+The trigger label is `label` in `.mergepatrol/mergepatrol.yml` on the default branch, `mergepatrol` when the file leaves it out. Below, `<label>` stands for it.
+
+- `<label>` queues the PR: `gh pr edit <number> --add-label <label>`. Removing it leaves the queue, and cancels the PR's run.
+- `<label>:priority`, beside `<label>`, puts the PR at the front of the queue.
+- `<label>:failed` is set by Mergepatrol when it ejects the PR.
+
+## What the queue does
+
+Mergepatrol rebases the PR onto the default branch, and may test it in a batch with other queued PRs. It resolves conflicts with an agent, runs the repo's `verify` commands, waits for the required checks, then merges with the repo's default merge method. When a required check fails, an agent commits a fix to the PR branch and the checks run again, a few times at most, unless `fix_ci` turns it off. The queue only serves PRs that target the default branch, and stacks of PRs (from `gh stack`) that merge into it.
+
+A PR from a fork merges only as it was when the label went on: a push to it after that takes it out of the queue, until a maintainer adds `<label>` again. It never joins a batch, gets no agent, and is ejected on a conflict or a failed check. Mergepatrol can push its rebase only while the author allows edits by maintainers.
+
+A stack is one item of the queue. The label on any of its PRs queues the whole stack, and the stack waits until every PR in it is ready. Mergepatrol rebases every layer when the stack is behind, and merges the stack all at once: every PR, or none. When it ejects a stack, every PR in it gets `<label>:failed`.
+
+The rebase rewrites the PR branch, and a fix adds a commit to it. Before pushing more commits to a queued PR, fetch it and rebase your work onto the remote branch. A push to a queued PR makes Mergepatrol start the PR over.
+
+## Reading its status
+
+Mergepatrol keeps one comment on each queued PR up to date. It says one of:
+
+- **On hold**: the PR is a draft, waits for a required review, or has changes requested. Mergepatrol comments the reason on the PR. It keeps its place, and runs once GitHub shows it ready.
+- **Ejected**: the rebase, the checks or the merge failed, and the comment says which. The trigger label is gone and `<label>:failed` is on. Fix the cause, push, then add `<label>` again.
+- **Merged**: done. The queue labels are removed.
+
+## Settings
+
+`.mergepatrol/mergepatrol.yml` sets the label, the batch size, the conflict resolver, the `verify` commands, and `fix_ci`. Mergepatrol reads it from the default branch, so a change takes effect once its PR merges.
diff --git a/.claude/skills/mergepatrol/SKILL.md b/.claude/skills/mergepatrol/SKILL.md
new file mode 100644
index 0000000..d7e48a2
--- /dev/null
+++ b/.claude/skills/mergepatrol/SKILL.md
@@ -0,0 +1,38 @@
+---
+name: mergepatrol
+description: This repo merges pull requests through Mergepatrol, a label-driven merge queue. Use when merging, landing or shipping a PR, queueing or dequeueing one, or reading a Mergepatrol comment or label on a PR.
+---
+
+# Mergepatrol
+
+Pull requests in this repo land through Mergepatrol's merge queue. Queue a PR with a label and let Mergepatrol merge it; merging by hand or pushing to the default branch races the queue.
+
+## The labels
+
+The trigger label is `label` in `.mergepatrol/mergepatrol.yml` on the default branch, `mergepatrol` when the file leaves it out. Below, `<label>` stands for it.
+
+- `<label>` queues the PR: `gh pr edit <number> --add-label <label>`. Removing it leaves the queue, and cancels the PR's run.
+- `<label>:priority`, beside `<label>`, puts the PR at the front of the queue.
+- `<label>:failed` is set by Mergepatrol when it ejects the PR.
+
+## What the queue does
+
+Mergepatrol rebases the PR onto the default branch, and may test it in a batch with other queued PRs. It resolves conflicts with an agent, runs the repo's `verify` commands, waits for the required checks, then merges with the repo's default merge method. When a required check fails, an agent commits a fix to the PR branch and the checks run again, a few times at most, unless `fix_ci` turns it off. The queue only serves PRs that target the default branch, and stacks of PRs (from `gh stack`) that merge into it.
+
+A PR from a fork merges only as it was when the label went on: a push to it after that takes it out of the queue, until a maintainer adds `<label>` again. It never joins a batch, gets no agent, and is ejected on a conflict or a failed check. Mergepatrol can push its rebase only while the author allows edits by maintainers.
+
+A stack is one item of the queue. The label on any of its PRs queues the whole stack, and the stack waits until every PR in it is ready. Mergepatrol rebases every layer when the stack is behind, and merges the stack all at once: every PR, or none. When it ejects a stack, every PR in it gets `<label>:failed`.
+
+The rebase rewrites the PR branch, and a fix adds a commit to it. Before pushing more commits to a queued PR, fetch it and rebase your work onto the remote branch. A push to a queued PR makes Mergepatrol start the PR over.
+
+## Reading its status
+
+Mergepatrol keeps one comment on each queued PR up to date. It says one of:
+
+- **On hold**: the PR is a draft, waits for a required review, or has changes requested. Mergepatrol comments the reason on the PR. It keeps its place, and runs once GitHub shows it ready.
+- **Ejected**: the rebase, the checks or the merge failed, and the comment says which. The trigger label is gone and `<label>:failed` is on. Fix the cause, push, then add `<label>` again.
+- **Merged**: done. The queue labels are removed.
+
+## Settings
+
+`.mergepatrol/mergepatrol.yml` sets the label, the batch size, the conflict resolver, the `verify` commands, and `fix_ci`. Mergepatrol reads it from the default branch, so a change takes effect once its PR merges.
diff --git a/.mergepatrol/mergepatrol.yml b/.mergepatrol/mergepatrol.yml
new file mode 100644
index 0000000..4054695
--- /dev/null
+++ b/.mergepatrol/mergepatrol.yml
@@ -0,0 +1,12 @@
+# Mergepatrol reads this file from the default branch. The dashboard opens a PR to change it.
+version: 1
+label: mergepatrol
+batch_size: 8
+resolver:
+  provider: anthropic
+  model: claude-opus-5-5
+  effort: medium
+verify: []
+fix_ci:
+  enabled: true
+  attempts: 2

From 868c1ea80892a8a96b59e90a52ee8e66907516a0 Mon Sep 17 00:00:00 2001
From: Joaquim Verges <joaquim.verges@gmail.com>
Date: Fri, 30 Oct 2026 09:09:24 -0700
Subject: [PATCH 2/3] Set Mergepatrol verify commands

The queue's agent can commit a conflict resolution or a CI fix to a PR
branch. With `verify: []` it pushed that commit unchecked and relied on
the required `build` check alone to catch a bad one. Required `build`
still gates every merge, so this was not a path to main, but it let
the agent push a broken resolution and gave it nothing to check its own
work with.

These mirror CI's `build` job except `pnpm test`, which needs Chromium
and ffmpeg that Mergepatrol's job image does not have. Each was run
locally from a clean install with browsers hidden: install 2s, check 2s,
knip 2s, typecheck 8s, site typecheck 2s, all well under the 600s
per-command limit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Nebula AI Agent <277912164+nebula-ai-agent[bot]@users.noreply.github.com>
---
 .mergepatrol/mergepatrol.yml | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/.mergepatrol/mergepatrol.yml b/.mergepatrol/mergepatrol.yml
index 4054695..7291c36 100644
--- a/.mergepatrol/mergepatrol.yml
+++ b/.mergepatrol/mergepatrol.yml
@@ -6,7 +6,16 @@ resolver:
   provider: anthropic
   model: claude-opus-5-5
   effort: medium
-verify: []
+# Run in Mergepatrol's job sandbox after an agent resolves a conflict or commits a fix, before
+# anything is pushed, and offered to the agent to check its own work. They mirror CI's `build`
+# job except `pnpm test`, which needs Chromium and ffmpeg that the sandbox lacks. `build`, a
+# required check, still runs all of it on the head Mergepatrol pushes, before any merge.
+verify:
+  - pnpm install --frozen-lockfile
+  - pnpm check --error-on-warnings
+  - pnpm knip
+  - pnpm typecheck
+  - pnpm --filter @bugpatrol/site typecheck
 fix_ci:
   enabled: true
   attempts: 2

From 9b6537e3b30ee95941c8088d3e253abbc05094f5 Mon Sep 17 00:00:00 2001
From: Joaquim Verges <joaquim.verges@gmail.com>
Date: Fri, 30 Oct 2026 09:09:28 -0700
Subject: [PATCH 3/3] Make the required build check wait on Determinism

Main's ruleset requires one check, `build`. Mergepatrol merges once the
trunk's required checks pass and ignores the rest (Checks::verdict in
crates/github/src/checks.rs), so a PR whose Determinism run was red
would merge from the queue. Until now only a person reading the red X
stopped that.

The old `build` job is now `checks`. Determinism becomes a reusable
workflow that CI calls. A new `build` job needs both and fails unless
each succeeded. It runs on always(), because a job skipped after a
failed need counts as passed, to GitHub and to Mergepatrol (checks.rs
maps skipped to Passed) alike. The check name is unchanged, so the
ruleset needs no edit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Nebula AI Agent <277912164+nebula-ai-agent[bot]@users.noreply.github.com>
---
 .github/workflows/ci.yml          | 23 ++++++++++++++++++++++-
 .github/workflows/determinism.yml |  8 +++++---
 2 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 1b90ec2..7ef3444 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -9,7 +9,7 @@ permissions:
   contents: read
 
 jobs:
-  build:
+  checks:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -37,3 +37,24 @@ jobs:
       # The recording tests encode real video.
       - run: command -v ffmpeg || (sudo apt-get update && sudo apt-get install -y ffmpeg)
       - run: pnpm test
+
+  determinism:
+    uses: ./.github/workflows/determinism.yml
+
+  # The branch ruleset requires `build` and nothing else, and Mergepatrol merges
+  # once required checks pass, so this job carries every check that must hold.
+  # It runs on `always()` and fails unless each need succeeded: a job skipped
+  # after a failed need counts as passed, to GitHub and to Mergepatrol alike.
+  build:
+    needs: [checks, determinism]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - env:
+          RESULTS: ${{ toJSON(needs) }}
+        run: |
+          failed=$(echo "$RESULTS" | jq -r '[to_entries[] | select(.value.result != "success") | "\(.key): \(.value.result)"] | join(", ")')
+          if [ -n "$failed" ]; then
+            echo "::error::Required jobs did not succeed: $failed"
+            exit 1
+          fi
diff --git a/.github/workflows/determinism.yml b/.github/workflows/determinism.yml
index 93e0a3c..01a1d56 100644
--- a/.github/workflows/determinism.yml
+++ b/.github/workflows/determinism.yml
@@ -7,12 +7,14 @@
 #
 # So it runs on every commit, not nightly, and a failure here is treated as a
 # product defect rather than a flake to be retried.
+#
+# CI calls it, and its required `build` check passes only when this does: a
+# merge queue waits for required checks alone, so a separate workflow here
+# would be advisory.
 name: Determinism
 
 on:
-  pull_request:
-  push:
-    branches: [main]
+  workflow_call:
 
 permissions:
   contents: read