fix(pin-gate): fail when a github pin names a sha unreachable from the default branch

[cdeust]

The hole

The pin gate compared versions only. A pin that names an unmerged PR head reads as current on every run — the version is right, the commit is doomed.

This is not hypothetical. #351 pinned cortex-viz at an unmerged PR head twice (ee0d41db, then 7e297ebc). Both were ahead of main. The squash-merge of cortex-viz#107 did orphan 7e297ebc — it reports diverged today. The marketplace would have kept serving a commit no branch reaches, and this gate would have stayed green throughout.

The check

PIN_SHA_UNREACHABLE — for any github source carrying a sha, require:

compare/{default_branch}...{sha}  ∈  {identical, behind}

compare/BASE...HEAD describes HEAD relative to BASE. With BASE = the default branch, identical means the pin is the tip and behind means it is an ancestor — both reachable. ahead and diverged mean the pin carries commits the branch does not: an unmerged PR head, which stops being reachable the moment that PR is squash-merged.

Status vocabulary source: GitHub REST — Compare two commits; status is exactly one of ahead / behind / identical / diverged.

Degradation contract — unchanged

An unresolvable repo (404) or a network failure emits a NOTICE and exits 0, matching every other network leg of this gate. A pin gate that hard-fails on a flaky API is a gate that gets disabled.

Proof

Check	Result
Suite	26/26
Mutation — REACHABLE_FROM_DEFAULT widened to accept ahead/diverged	2 failures, exactly the 2 new tests
End-to-end, live API	7e297ebc FAIL diverged · 1c1940e2 PASS · absent sha FAIL
Full gate on the real marketplace.json @ b29dfce0	exit 0, zero false positive
ruff (PLR2004 + E501 blocking)	clean

Diff is 159 insertions, 0 deletions — no existing behaviour altered.

Note on the automatised-pipeline mirror

The docstring's byte-identical claim holds. AP's canonical-drift job ran green on the last cron (2026-08-03 09:26Z); the current one-hunk divergence was introduced by the merge of #351 itself (b29dfce0, 2026-08-04 06:06Z) and the next cron would have caught it. AP must be re-synced from main after this merges — one resync, not two. The change is functionally inert there (AP declares a single plugin with source "./", no github source, no sha), but the byte-identity contract requires it.