feat(api): gate apply start on confirmed sibling PR check holds

[aparajon]

Why this matters

Holding sibling PR checks is only a guardrail if it happens before the apply changes anything. A multi-hour copy/cutover started from the CLI must not race the flip: if the holds land late, a sibling PR can merge on a green check the apply is about to invalidate. This PR makes the holds a hard precondition of the apply itself — the drive does not start engine work until every sibling PR's check flip and hold comment are confirmed landed, and it fails closed on any uncertainty. Stack 6/7, on top of #940.

What it does

• Preflight gate (gateApplyStartOnCheckPreflight), run when a driver claims an apply, before engine work:
  • No merge gate consumer registered (no GitHub runtime) → skip; nothing to hold.
  • Apply has no tasks (a plan with no diff) → skip; an apply with no diff changes nothing, so there is nothing to hold against.
  • Otherwise: record a durable preflight request, kick the processor, and wait for the request to complete. A terminally failed request is re-armed with ReopenForRetry and re-kicked.
  • Timeout or storage error → the drive attempt is abandoned and the apply stays claimable; the gate never converts uncertainty into a started apply.
• Settle on every terminal state: completed applies always record a settle; failed/cancelled/errored applies record one when a preflight exists, so holds are always released by a re-plan against the real schema — never by cleanup alone.
• Gate outcome metric (schemabot.merge_gate.preflight_gate_total with passed / timeout / error): a sustained non-passed rate means the processor is failing to drain preflights and applies on GitHub-configured servers are not starting — the metric comment says exactly that.
• The core stays code-host neutral. The gate keys off the registered merge gate consumer and durable request state — never a GitHub type. Core-layer (pkg/api, pkg/storage, pkg/metrics) comments, logs, and metric docs describe that contract (a merge gate consumer, sibling change checks, a code-host outage); GitHub vocabulary lives only in the adapter (pkg/webhook, pkg/github), which is one implementation of the hold/re-plan fan-out. A future code-host integration registers its own consumer and renders the same stored state.
• Test harness now mirrors production: the default webhook integration handler starts the merge gate processor (the gate requires one), with an explicit no-processor constructor for tests that drive the drain lifecycle manually.

 driver claims apply
        │
        ▼
 consumer registered? ──no──► start engine work (no GitHub runtime)
        │yes
 apply has tasks? ────no────► start engine work (no diff, nothing held)
        │yes
 record preflight ──► kick processor ──► wait for holds confirmed
        │                                    │
        │ storage error / timeout            │ completed
        ▼                                    ▼
 abandon drive attempt                 start engine work
 (apply stays claimable,               (sibling checks now
  fail closed)                          action-required + commented)

Closing the loop: a commit pushed to a sibling PR while the apply is mid-flight would re-plan against the pre-apply schema and could mint a fresh green check — #942 closes that by storing such checks born held.

How it moves us toward the northstar

An apply's first observable effect is now telling every affected PR "this target is changing" — before a single row moves. Merge decisions and schema changes stop being able to race each other, which is exactly the safety bar a git-as-interface schema workflow has to clear.

The chain: #867 (storage) → #868 (drive-tail recording) → #866 (settle re-plan processor) → #939 (request kinds + hold storage) → #940 (preflight hold fan-out) → #941 (apply-start gate) → #942 (plan-time holds). Merges bottom-up; each PR retargets to main as its base merges.

🤖 Generated with Claude Code