Implement batch merge train candidate validation

[cbusillo]

Objective

Implement the mechanism that makes the full train useful for many unrelated PRs: build one combined candidate from the ordered queued PRs, run CI once on that combined tree, and use the passing candidate as evidence before landing the original PRs in order.

Finish Line

For at least two queued PRs, Launchplane can build a deterministic batch candidate, observe required checks on that exact candidate commit, and produce a landing plan for the original PRs when the candidate passes.

Current Status

State: Complete through live proof. Launchplane planned, built, observed, landing-planned, and landed a two-PR batch against cbusillo/codex-skills:main. Candidate f1abab5009518ef6e61941c86be4ea1672264e00 passed train validation, landing-plan record merge-train-batch-landing-plan-20260514T013438Z-4bfcd33bf8ee0c9f was created, and land record merge-train-batch-landing-plan-20260514T013517Z-affd5d549244d89c merged PR #63 then #64.
Next action: Close or mark done after confirming no follow-up defects from the proof logs.
Blocked by: Nothing for candidate validation/landing proof; scheduler automation remains tracked in #605.
Last verified: 2026-05-14. Launchplane runs: plan 25835435391, build 25835453873, observe 25835478586, landing plan 25836427035, land 25836447245. Codex-skills PR #63 merged at 9a52ccb7c540a0fefbaeb9d1e97619be4b548d94; PR #64 merged at 303feeb1a3cae8ef2d9085b39fd351d3fba59bd2; latest codex-skills main CodeQL run 25836454301 succeeded.

Scope

• In: candidate train refs/branches or equivalent validation target, check observation, stale-candidate invalidation, cleanup, and adapter tests.
• Out: broad provider abstraction beyond GitHub unless required by the selected strategy.

Acceptance Criteria

• Batch candidate commits are deterministic, auditable, and tied to queue/batch records.
• Candidate construction applies queued PRs in queue order and stops at the first conflict.
• Required checks are evaluated against the candidate commit SHA.
• A changed queued PR head invalidates the batch candidate and forces rebuild/requeue.
• A passing candidate produces a PR-native landing plan with per-PR pre-merge verification requirements.
• A failing candidate can be split or reduced to isolate blockers without losing the rest of the queue.
• Candidate refs are cleaned up or retained according to policy without leaking long-lived clutter.
• GitHub API failures fail closed and do not merge from stale validation.

Relationships

• Blocked by semantics and queue records.
• Related to Inventory self-hosted runner lanes #413 and Control self-hosted runner lanes #414 for runner lane capacity/control.

Validation

• Mocked GitHub ref/check tests for two- and three-PR trains.
• Live dry-run with candidate creation disabled or read-only preview first, if supported.
• Live low-risk smoke only after cleanup and branch-protection behavior are proven.

Decisions

• First full-train implementation is batch candidate validation, not per-position speculative refs.
• Passing batch CI is necessary but not alone sufficient: Launchplane still verifies PR-native landing invariants before merging each original PR.

Open Questions

• Can all target repos safely run CI on Launchplane-created batch refs?
• What naming scheme should batch refs use to avoid collisions and simplify cleanup?
• What exact GitHub API sequence best creates the candidate while preserving merge-method semantics?