A merge queue: one gated candidate per repository, batched, so landing never waits on a gate per pull #2058

Each repository now has one merge queue. Green, approved pulls join it, the queue gates one candidate built from all of them, and landing is refused unless the result is exactly the gated tree. The issue's acceptance tests pass, with one exception: the "at most 3 gate runs with one red among 4" bound only holds when the red pull is last in the queue. Elsewhere it takes 4, and no ordering of gates can guarantee better.

What changed

• The queue (src/checks/queue.ts, new). The candidate is main, then each queued pull's squash on top of the one before, oldest first. A pull that conflicts, or has nothing left to land, is left out and handled by the next sweep as before. The candidate is gated once. Green lands every step in order. Red bisects:

- The front half is gated by itself. - If the front half is green, it lands, and the rest is known red without another gate. - If the front half is red, the search continues inside it. - A single red step is the culprit. It gets the red decision, the comment naming the failing tests, and those tests are added to its fast tier, as before. - Pulls that turn green while a candidate is gating wait for the next candidate.

• Main ends at the gated tree. mergePull (action and core) takes an optional expect: { baseOid, treeOid }, and git/merge.ts merge takes an optional treeOid. Each queued landing is refused (base_moved) unless main is still where the step was built and the squash writes the tree that was gated. A release is cut once per candidate, at its last step.
• src/crew/autonomy.ts. landIfGreen is now admit (every check it ran before, unchanged) plus joining the queue; landGated is the old post-gate tail. sweepGreen admits every open pull, then queues them together, so one sweep is one candidate.
• src/checks/landing.ts. gateCandidate gates any candidate commit. gateOnLand is now a thin wrapper around it, used only by check-tiers.test.ts.
• /flow has a "Merge queue" card: per repository, queued, gating, and landed in the last hour (src/flow/queue.ts).

What to look at

• Gate counts. With one red among 4: red last takes 3 gates; red first or third takes 4. With 4 candidates, one red, and only two gates left after the first red, you can't both find the culprit and gate the final tree in every case. Both orderings are tested.
• Landing is per pull, not one ref move. Main moves once per pull (each one is still the pull's own squash commit), not in a single update to the final commit. Because each step is guarded, if one is refused partway through (say a person pushes to main mid-batch), main is left at an ungated prefix and the rest wait for the next sweep. Making it a single atomic update would mean splitting mergePull into prepare and record; I didn't do that.
• The queue lives in memory. Membership is re-derived from the pulls on every sweep, so a restart loses nothing; the "queued" and "gating" numbers on /flow are this process's only.
• New test hook. provideChecksForTest in src/checks/service.ts lets a test stand in for the checks service.

Tests

• test/merge-queue.test.ts (new, added to GATE after 10/10 green random-order runs from flake-hunt admit) covers:

- 4 green pulls → 1 gate run, 4 landings, main's tree is the gated tree; - red last → 3 land, 1 handed back, ≤ 3 gates, and the next sweep doesn't gate it again; - red first → 3 land, ≤ 4 gates; - a pull that conflicts with one ahead of it is left out; - the base/tree guard refuses a wrong base and a wrong tree; - /flow shows queued 2 / gating 1 while a gate is held, then landed 3.

• No existing test was changed.
• The type check is clean, and the landing, autonomy, flow, release and cross suites pass (453 pass, 1 skip).
• In this sandbox, following.test.ts and origins-reconnect.test.ts fail on 5-second network timeouts. They fail on the base commit here too, so they're unrelated to this change.

🤖 Generated with Claude Code

Closes #2036

Each repository now has one merge queue. Green, approved pulls join it, the queue gates one candidate built from all of them, and landing is refused unless the result is exactly the gated tree. The queue's numbers (queued, gating, landed in the last hour) now show on /flow, in the terminal's Flow dialog and in the MCP flow tool.

On the issue's own test: "at most 3 gate runs with one red among 4" only holds when the red pull is last in the queue. Elsewhere it takes 4, and no ordering of gates can guarantee better. Both cases are tested.

What changed

• The queue (src/checks/queue.ts, new). The candidate is main, then each queued pull's squash on top of the one before, oldest first. A pull that conflicts, or has nothing left to land, is left out and handled by the next sweep as before. The candidate is gated once. Green lands every step in order. Red bisects:

- The front half is gated by itself. - If the front half is green, it lands, and the rest is known red without another gate. - If the front half is red, the search continues inside it. - A single red step is the culprit. It gets the red decision, the comment naming the failing tests, and those tests are added to its fast tier, as before. - Pulls that turn green while a candidate is gating wait for the next candidate.

• Main ends at the gated tree. mergePull (action and core) takes an optional expect: { baseOid, treeOid }, and git/merge.ts merge takes an optional treeOid. Each queued landing is refused (base_moved) unless main is still where the step was built and the squash writes the tree that was gated. A release is cut once per candidate, at its last step.
• src/crew/autonomy.ts. landIfGreen is now admit (every check it ran before, unchanged) plus joining the queue; landGated is the old post-gate tail. sweepGreen admits every open pull, then queues them together, so one sweep is one candidate.
• src/checks/landing.ts. gateCandidate gates any candidate commit. gateOnLand is now a thin wrapper around it, used only by check-tiers.test.ts.
• All three places read readQueues() (src/flow/queue.ts):

- /flow: a "Merge queue" card, one row per repository. - Terminal Flow dialog (src/tui/screens/flow.ts): one line per repository, with long names cut short. - MCP flow tool: a new queue field, also described in the tool's text.

The page header and the README now say where the queue shows.

What to look at

• Gate counts. With one red among 4: red last takes 3 gates; red first or third takes 4. With 4 candidates, one red, and only two gates left after the first red, you can't both find the culprit and gate the final tree in every case.
• Landing is per pull, not one ref move. Main moves once per pull (each one is still the pull's own squash commit), not in a single update to the final commit. Because each step is guarded, if one is refused partway through (say a person pushes to main mid-batch), main is left at an ungated prefix and the rest wait for the next sweep. Making it a single atomic update would mean splitting mergePull into prepare and record; I didn't do that.
• The queue lives in memory. Membership is re-derived from the pulls on every sweep, so a restart loses nothing; "queued" and "gating" are this process's numbers only.
• New test hook. provideChecksForTest in src/checks/service.ts lets a test stand in for the checks service.

Tests

• test/merge-queue.test.ts (new, added to GATE after 10/10 green random-order runs from flake-hunt admit) covers:

- 4 green pulls → 1 gate run, 4 landings, main's tree is the gated tree; - red last → 3 land, 1 handed back, ≤ 3 gates, and the next sweep doesn't gate it again; - red first → 3 land, ≤ 4 gates; - a pull that conflicts with one ahead of it is left out; - the base/tree guard refuses a wrong base and a wrong tree; - /flow, the terminal Flow dialog and the MCP flow tool all show queued 2 / gating 1 while a gate is held, then landed 3 after.

• No existing test was changed.
• After the latest commit, the type check is clean and the merge-queue, flow, MCP and cross suites pass (323 pass). Before it, the landing, autonomy and release suites passed too.
• In this sandbox, following.test.ts and origins-reconnect.test.ts fail on 5-second network timeouts. They fail on the base commit here too, so they're unrelated to this change.

🤖 Generated with Claude Code

Each repository now has one merge queue. Green pulls wait in it and go through the gate as one candidate. The queue shows up on /flow, in the terminal's Flow dialog and in the MCP flow tool. This update merges the latest main into the branch. The type check passes, and the 129 tests covering the merge queue, flow, conflicts and MCP pass; the forge's check runs the rest.

Merge conflicts. main added a "conflicted pulls" section to the same two places this branch added the merge queue. The two sections don't overlap, so both are kept:

• src/tui/screens/flow.ts: the Flow dialog reads both. It shows the merge queue table (queued, gating, landed in the last hour, per repository), then main's conflicted-pulls sentence when there is one.
• src/http/mcp.ts: the flow tool's output has main's conflicted block and this branch's queue block. The tool description now mentions both.

What to look at. The queue itself is in src/flow/queue.ts. Its tests are in test/merge-queue.test.ts.

🤖 Generated with Claude Code

Each repository now has one merge queue. Green, approved pulls wait in it and are built into one candidate, the gate runs on that candidate once, and every step lands guarded by base and tree. A red candidate is bisected: the green part lands and the culprit is handed back. The queue shows on /flow, in the terminal's Flow dialog and in the MCP flow tool. This round fixes the two things from review. The type check is clean, and the landing, autonomy, release, tiers and merge-queue suites pass (162 tests).

gateOnLand deleted (src/checks/landing.ts). Nothing in production called it any more; landIfGreen and sweepGreen both go through the queue and gateCandidate. Its unused imports are gone too.

Test changed: test/check-tiers.test.ts, "landing runs the full gate on the merge with its base". It used to call gateOnLand, which production no longer runs. It now builds the commit of the pull on its base and calls gateCandidate, then checks that the verdict names the failing test and the file to learn. The other half, recording what the culprit learns, is checked in test/merge-queue.test.ts: the "one red among four" test now asserts that handBack stored test/red.test.ts for the red pull.

A release for a partly landed candidate (src/checks/queue.ts, src/crew/autonomy.ts):

• Queued.land no longer takes a last flag.
• A new Queued.release(tip) hook is called once per candidate, from a finally, for the last step that actually landed. If step i is refused, steps 1 to i−1 still get their release cut, at the tip main is really at.
• landGated no longer cuts releases itself; the autonomy entry's release calls releaseOnLand.
• New test, "a later step refused…": three steps, the third refused, so exactly one release is cut, for step two at its tip.

Not done: when a step is refused, main still sits at a combination of the earlier steps that was never gated on its own. Beyond the warn log nothing records this, as review accepted for now.

🤖 Generated with Claude Code