phase-loop-runtime 0.7.20__tar.gz → 0.7.21__tar.gz

{phase_loop_runtime-0.7.20/src/phase_loop_runtime.egg-info → phase_loop_runtime-0.7.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phase-loop-runtime
-Version: 0.7.20
+Version: 0.7.21
 Summary: Harness-neutral phase-loop orchestration runtime and CLI
 Author-email: ViperJuice <viperjuice@users.noreply.github.com>
 License-Expression: Apache-2.0
@@ -49,7 +49,7 @@ To install just this runtime package directly:
 
 ```sh
 pip install phase-loop-runtime              # latest compatible release
-pip install phase-loop-runtime==0.7.20      # …or pin an exact version
+pip install phase-loop-runtime==0.7.21      # …or pin an exact version
 ```
 
 To pin a specific tag from source instead, substitute a tag from

{phase_loop_runtime-0.7.20 → phase_loop_runtime-0.7.21}/README.md

@@ -19,7 +19,7 @@ To install just this runtime package directly:
 
 ```sh
 pip install phase-loop-runtime              # latest compatible release
-pip install phase-loop-runtime==0.7.20      # …or pin an exact version
+pip install phase-loop-runtime==0.7.21      # …or pin an exact version
 ```
 
 To pin a specific tag from source instead, substitute a tag from

{phase_loop_runtime-0.7.20 → phase_loop_runtime-0.7.21}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "phase-loop-runtime"  # PyPI dist name; NOT "agent-harness" (an unrelated third-party PyPI project)
-version = "0.7.20"
+version = "0.7.21"
 description = "Harness-neutral phase-loop orchestration runtime and CLI"
 readme = "README.md"
 requires-python = ">=3.10"

{phase_loop_runtime-0.7.20 → phase_loop_runtime-0.7.21}/src/phase_loop_runtime/__init__.py

@@ -18,4 +18,4 @@ __all__ = [
     "state_ops",
 ]
 
-__version__ = "0.7.20"
+__version__ = "0.7.21"

{phase_loop_runtime-0.7.20 → phase_loop_runtime-0.7.21}/src/phase_loop_runtime/advisor_board/CONTRACTS.md

@@ -735,3 +735,107 @@ root, rejecting failures, omissions and terminal/admission mismatches. Preserve
 failed series; diagnose a changed candidate before another attempt. Validation
 uses that host's measured helper images. These receipts do not replace the
 historical bounded-success evidence verifier.
+
+The driver lives in the package, `phase_loop_runtime.agy_qualification`; the script
+is a shim over it, so an installed runtime can run it too (agent-harness#1076).
+
+### First-use self-qualification (agent-harness#1076)
+
+A non-release `agy` image is admitted only by verifying it, never by trusting it.
+
+- **Admission classes.** Every Gemini heartbeat leg carries exactly one class in
+  its profile evidence (`provider_admission_class`): `release_qualified` (digest in
+  `QUALIFIED_IMAGES`), `locally_qualified` (a verified local record), or
+  `qualification_candidate` (only inside a qualification run; never counted, never
+  persisted). The evidence's `provider_image_sha256` is the admitted image's own digest.
+- **VerifiedImage.** `PATH` is resolved once (a versioned-install symlink to its final
+  target), the target is opened once (`O_NOFOLLOW`, regular file, size cap) and read
+  into memory; that buffer is hashed and fills a sealed memfd, which is re-hashed.
+  Help measurement, the three live operations, board legs and the president execute
+  that memfd (an independent, re-hashed read of it per profile) and never open the path
+  again.
+- **Admission order.** (1) A release-qualified digest is admitted before any config,
+  store or network access. (2) If the user config sets `[agy] self_qualification = false`
+  (the repository config cannot), today's `gemini_heartbeat_capability_unavailable`
+  refusal is returned and nothing else is read. (3) A `failed` entry refuses
+  (`gemini_heartbeat_self_qualification_failed`) with no execution. (4) Help is measured
+  from the memfd only after a `provenance` entry verifies against the live key; the
+  `qualified` entry is then verified against the full live key, including that help
+  digest. (5) Otherwise the image is absent: legs and the president refuse; only the
+  whole-board preflight (`_preflight_gemini_heartbeat`) and `phase-loop
+  agy-qualification run` go on to first use. Legs re-admit by lookup rather than
+  receiving the preflight's Admission object; any future cross-process hand-off of an
+  image memfd must reuse the worker's seal check.
+- **Provenance** (coordinator process, nothing executes). Host platform from the running
+  host (D4: `linux-{x64,arm64}[-musl]`); the newest `agy_provenance.RECENCY_WINDOW`
+  stable releases (no prerelease, no draft); the exact platform asset; its URL equal to
+  `https://github.com/google-antigravity/antigravity-cli/releases/download/<tag>/<asset>`;
+  a strict `sha256:<hex>` asset digest equal to the streamed archive digest; exactly one
+  regular-file `antigravity` member (duplicates and links refuse), stream-hashed and
+  never extracted, equal to the image digest. The transport sends no credentials, has
+  no proxy support, uses the interpreter's compiled-in OpenSSL trust store (not
+  `SSL_CERT_FILE`/`SSL_CERT_DIR`), and follows at most three https redirects within
+  GitHub's download hosts. Fetch failure refuses `gemini_heartbeat_provenance_unavailable`;
+  no match refuses `gemini_heartbeat_provenance_unverified`.
+- **Behaviour.** Only after the provenance entry is written: help, then the three live
+  operations through the packaged driver and the release path's own validators. All
+  passing writes the `qualified` entry. Any observed isolation or identity violation (an
+  executable outside the helper policy, an unqualified provider image, a writable image
+  mount, an unverified network policy, a surviving process, a rejected record) writes a
+  `failed` entry at whatever stage it was seen (until `agy-qualification clear`). Only a
+  provider that was never observed running, a completion the provider did not answer
+  (HTTP 5xx, quota, auth), and our own local failure are transient, and cancellation writes
+  nothing. Transients are counted per key; the third consecutive one writes a `failed`
+  entry, success resets the count, and `agy-qualification clear` removes it. A lock waiter
+  that finds a transient recorded while it waited refuses without running or counting.
+- **Worker gate.** The qualification worker receives the image as an inherited fd and,
+  before hashing, requires a regular-file memfd with `F_SEAL_WRITE`, `F_SEAL_GROW`,
+  `F_SEAL_SHRINK` and `F_SEAL_SEAL` (`F_SEAL_FUTURE_WRITE` alone is refused). It admits
+  the fd as a candidate only if its digest is a release constant (the manual shim and the
+  upstream watch's prepared tree) or has a provenance entry for the current runtime
+  identity. It sets `PR_SET_PDEATHSIG`, so a killed coordinator leaves no worker.
+- **Store.** `$XDG_STATE_HOME/phase-loop/agy-qualification/hosts/<machine>/`, per user,
+  namespaced by machine-id. Directories 0700 and files 0600, owned by the euid, opened
+  `O_NOFOLLOW`; otherwise the store is absent to lookups and first use refuses
+  (`gemini_heartbeat_self_qualification_store_unsafe`). Every entry is HMAC-SHA256'd under
+  a per-host key over its type, the euid, the machine-id and a context recomputed from the
+  live key. The qualification entries (`provenance`, `qualified`, `failed`, `member_cache`,
+  `transient`) bind the image digest, platform and runtime identity, plus the asset name,
+  profile id or help digest as the type requires. The watch's `watch_push` entry binds the
+  branch, the version and the route-core base.
+  Without a readable machine-id, self-qualification refuses; the release path is unaffected.
+- **Lock.** One `flock` per host namespace; waiters are cancellable and heartbeat (the board
+  preflight writes a content-free `agy-qualification.json` progress record into the
+  board's stream directory and a line on stderr, throttled per phase), and re-check the
+  store after acquiring. Qualification happens once per key per user per host.
+- **Runtime identity (D2).** `__version__` plus the digests of the installed
+  `agy_qualification.ROUTE_CORE` files (`gemini_heartbeat.py`, `agy_qualification.py`,
+  `agy_provenance.py`), the same tuple `verify_qualified_agy_image.py --route-core` checks.
+- **Counting (D1).** At `governed_review`'s gate (the rule itself is
+  `agy_qualification.counts_toward_landing`), a usable heartbeat Gemini leg is a vote at every
+  tier only if its recorded class is `release_qualified` or `locally_qualified`. A
+  candidate leg, or a leg with no class (including legs from boards run before the class
+  existed: re-run the board), cannot approve; a blocking verdict from it still blocks. The
+  president's input builder applies the same rule (`agy_qualification.president_input_items`):
+  an uncounted non-blocking leg contributes a `not counted` item instead of its review, and an
+  uncounted `DISAGREE` keeps its objections. A leg is an agy leg by name or by the
+  coordinator's profile evidence. A
+  Gemini leg whose admitted digest appears in the reviewed artifact is flagged
+  (`gemini_seat_reviews_its_own_pin`, non-gating). Boards admit with the installed base
+  runtime, never the reviewed tree.
+- **Upstream watch.** `phase-loop agy-qualification watch` (a host timer on a subscribed
+  host; see `docs/ops/agy-upstream-watch.md`) proposes only the Linux x64 glibc release
+  route, from a fresh checkout of `main`, and opens a draft PR; it never merges. Each tick
+  makes exactly one ref write (a fresh `agy-watch/<version>-<utc>-<random>` branch, pushed
+  with an empty-expected-value lease and accepted only when `--porcelain` reports that exact
+  ref as newly created) and one object create (the PR). It never updates, force-pushes,
+  adopts, closes, edits or deletes anything that existed before the tick; the new PR body
+  names the own older PRs it supersedes for a maintainer to close. It requires `origin` to
+  have exactly one push URL, pushes to the remote NAME `origin` (never to the printed URL,
+  which git would resolve again). It compares no URL strings; a `--dry-run` pre-flight
+  must print exactly one `To` block, and the real push exactly one `To` block and one `*` row
+  for exactly the new ref. Both pushes carry `--no-verify`; the bot host's git/ssh
+  configuration is trusted. It pre-flights its store, records the
+  verified pushed oid in its own `watch_push` entry, and reads both the record and the
+  created PR back (the PR body's copy is display-only). "Up to date" requires that local record, `headRefOid` and `ls-remote` to
+  agree. It refuses when it cannot prove its open-PR listing complete.

{phase_loop_runtime-0.7.20 → phase_loop_runtime-0.7.21}/src/phase_loop_runtime/advisor_board/config.py

@@ -51,11 +51,14 @@ from .schema import (
 )
 
 # Recognised keys — anything else is a hard error (no silent drop).
-_KNOWN_TOP_KEYS: frozenset[str] = frozenset({"default_board", "boards", "president"})
+_KNOWN_TOP_KEYS: frozenset[str] = frozenset({"default_board", "boards", "president", "agy"})
 # A repository file configures the president ladder only: repo-level boards are not a
 # feature, so a ``[[boards]]`` there is refused rather than silently ignored.
 _KNOWN_REPO_TOP_KEYS: frozenset[str] = frozenset({"president"})
 _KNOWN_PRESIDENT_KEYS: frozenset[str] = frozenset({"ladder"})
+# agent-harness#1076 D3: the USER file's ``[agy] self_qualification = false`` restores the
+# hard refusal of a non-release agy image. A repository file cannot carry it.
+_KNOWN_AGY_KEYS: frozenset[str] = frozenset({"self_qualification"})
 # Repository-level config, relative to the repository root.
 REPO_CONFIG_RELATIVE_PATH = ".agent-harness/advisor-boards.toml"
 _KNOWN_BOARD_KEYS: frozenset[str] = frozenset(
@@ -212,6 +215,31 @@ def _parse_president(data: Mapping[str, Any], where: str) -> tuple[str, ...] | N
         raise BoardConfigError(f"{where} [president] ladder: {exc}") from exc
 
 
+def _parse_agy(data: Mapping[str, Any], where: str) -> bool:
+    """The user file's ``[agy] self_qualification`` (default ``True``), validated."""
+    raw = data.get("agy")
+    if raw is None:
+        return True
+    if not isinstance(raw, Mapping):
+        raise BoardConfigError(f"{where}: 'agy' must be a table")
+    _reject_unknown(raw.keys(), _KNOWN_AGY_KEYS, f"{where} [agy]")
+    return _require_bool(raw, "self_qualification", True, f"{where} [agy]")
+
+
+def load_agy_self_qualification(*, path: Path | None = None) -> bool:
+    """D3 (agent-harness#1076): whether first-use self-qualification is enabled.
+
+    Reads the user file only (this process's ``board_config_path()``). A malformed file
+    raises; the admission caller treats any error as opted out (today's refusal).
+    """
+    user_path = path if path is not None else board_config_path(None)
+    user = _load_toml(user_path)
+    if user is None:
+        return True
+    _reject_unknown(user.keys(), _KNOWN_TOP_KEYS, str(user_path))
+    return _parse_agy(user, str(user_path))
+
+
 def _user_config_path(env: Mapping[str, str] | None) -> Path | None:
     """The user file for ``env``: resolved from the GIVEN environment only.
 
@@ -343,6 +371,7 @@ def load_boards(
                 raise BoardConfigError(f"{cfg_path} is not valid TOML: {exc}") from exc
         _reject_unknown(data.keys(), _KNOWN_TOP_KEYS, str(cfg_path))
         _parse_president(data, str(cfg_path))  # a bad [president] fails at load too
+        _parse_agy(data, str(cfg_path))  # and a bad [agy] (agent-harness#1076)
         raw_boards = data.get("boards", [])
         if not isinstance(raw_boards, list):
             raise BoardConfigError(f"{cfg_path}: 'boards' must be an array of tables")

{phase_loop_runtime-0.7.20 → phase_loop_runtime-0.7.21}/src/phase_loop_runtime/advisor_board/fixtures/advisor-boards.example.toml

@@ -12,6 +12,12 @@
 # Optional: the board a bare `advisor-board` invocation resolves to.
 default_board = "default"
 
+# Optional (agent-harness#1076, user file only): first-use self-qualification of a genuine
+# upstream agy release whose digest is not release-qualified. On by default; `false`
+# restores the hard refusal (`gemini_heartbeat_capability_unavailable`).
+# [agy]
+# self_qualification = false
+
 # The default board reproduces today's 3-leg panel (byte-for-byte back-compat).
 # Its three seats, in panel-leg order, render to today's exact CLI invocations:
 #   codex  gpt-6-astra          effort=max  -> -c model_reasoning_effort=xhigh

{phase_loop_runtime-0.7.20 → phase_loop_runtime-0.7.21}/src/phase_loop_runtime/advisor_board/fixtures.py

@@ -76,6 +76,8 @@ CANONICAL_VALID_PAIRS: tuple[tuple[str, str], ...] = (
     ("gpt-6-astra", "codex"),
     ("gpt-6-astra", "opencode"),
     ("gpt-5.6-sol", "codex"),  # legacy default id remains expressible
+    ("gpt-6-sol", "codex"),  # explicit seat on user/ad-hoc boards (not a governed grok stand-in)
+    ("gpt-6-sol", "opencode"),  # same family; matches the production registry's runnable_by
     ("claude-sonnet-5", "claude"),
     ("claude-opus-5-5", "claude"),
     ("claude-fable-5-1", "claude"),

{phase_loop_runtime-0.7.20 → phase_loop_runtime-0.7.21}/src/phase_loop_runtime/advisor_board/registries.py

@@ -256,6 +256,7 @@ class DefaultHarnessRegistry:
 _MODEL_DEFS: tuple[tuple[str, str, str], ...] = (
     ("gpt-6-astra", "codex", "max"),
     ("gpt-5.6-sol", "codex", "max"),  # explicit legacy seat (fleet default before 2026-09-04)
+    ("gpt-6-sol", "codex", "max"),  # explicit seat (codex's own default model); not a board default
     ("claude-sonnet-5", "claude", "max"),
     ("claude-opus-4-8", "claude", "max"),
     # design-model-tier-taxonomy.md: claude-opus-5 is the new Claude heavy model.

phase_loop_runtime-0.7.21/src/phase_loop_runtime/agy_provenance.py

@@ -0,0 +1,313 @@
+"""Provenance of an upstream agy release asset (agent-harness#1076).
+
+Nothing here executes anything. It answers one question in the coordinator process:
+is this exact image digest the ``antigravity`` member of a stable upstream release
+asset for THIS host's platform, whose archive digest equals the digest GitHub
+publishes for that asset?
+
+The transport is pinned. It uses ``http.client`` (which has no proxy support), sends no
+``Authorization`` header, never reads ``.netrc``, credential helpers, token or proxy
+variables, and verifies TLS against the interpreter's compiled-in OpenSSL trust store
+(``ssl.get_default_verify_paths().openssl_*``), not ``SSL_CERT_FILE``/``SSL_CERT_DIR``.
+Integrity rests on the published digest, not the URL; redirects are followed over https
+only, to a fixed host allowlist, a bounded number of times.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from hashlib import sha256
+import glob
+import http.client
+import json
+import os
+import platform as _platform
+import posixpath
+import re
+import ssl
+import sys
+import tarfile
+from urllib.parse import urlsplit
+
+REPO = "google-antigravity/antigravity-cli"
+API_HOST = "api.github.com"
+RELEASES_PATH = f"/repos/{REPO}/releases?per_page=30"
+DOWNLOAD_PREFIX = f"https://github.com/{REPO}/releases/download/"
+# GitHub serves release downloads by a 302 from github.com to its asset CDN.
+REDIRECT_HOSTS = frozenset({"github.com", "release-assets.githubusercontent.com",
+                            "objects.githubusercontent.com"})
+MAX_REDIRECTS = 3
+# The member digest is only knowable by downloading each archive, so a tampered image
+# (which matches nothing) would otherwise download every release on every first use.
+# At least 2, so that a non-pinned in-window build can exercise the path live.
+RECENCY_WINDOW = 4
+MAX_LISTING_BYTES = 4_000_000
+MAX_ARCHIVE_BYTES = 128_000_000
+MAX_MEMBER_BYTES = 250_000_000
+MEMBER_NAME = "antigravity"
+USER_AGENT = "agent-harness-agy-provenance"
+
+UNAVAILABLE = "gemini_heartbeat_provenance_unavailable"
+UNVERIFIED = "gemini_heartbeat_provenance_unverified"
+UNSUPPORTED = "gemini_heartbeat_platform_unsupported"
+
+_TAG = re.compile(r"[0-9]+\.[0-9]+\.[0-9]+")
+_DIGEST = re.compile(r"sha256:([0-9a-f]{64})")
+
+
+class ProvenanceError(ValueError):
+    """A fixed, content-free provenance diagnostic."""
+
+
+@dataclass(frozen=True)
+class HostPlatform:
+    os: str
+    arch: str
+    libc: str
+
+    @property
+    def name(self) -> str:
+        return f"{self.os}-{self.arch}" + ("-musl" if self.libc == "musl" else "")
+
+    @property
+    def asset(self) -> str:
+        return f"agy_cli_{self.os}_{self.arch}" + ("_musl" if self.libc == "musl" else "") + ".tar.gz"
+
+
+@dataclass(frozen=True)
+class ReleaseAsset:
+    version: str
+    name: str
+    url: str
+    digest: str  # the archive's hex sha256, from GitHub's per-asset ``digest``
+
+
+@dataclass(frozen=True)
+class Provenance:
+    """A verified match: ``image_sha256`` is the member of ``asset``."""
+    image_sha256: str
+    platform: str
+    asset: ReleaseAsset
+
+
+_ARCH = {"x86_64": "x64", "amd64": "x64", "aarch64": "arm64", "arm64": "arm64"}
+
+
+def detect_platform(*, uname=os.uname, libc_ver=_platform.libc_ver,
+                    musl_loaders=lambda: glob.glob("/lib/ld-musl-*.so.1")) -> HostPlatform:
+    """The RUNNING host's platform (D4). Reads no config and no environment."""
+    info = uname()
+    if info.sysname != "Linux" or info.machine not in _ARCH:
+        raise ProvenanceError(UNSUPPORTED)
+    libc = libc_ver(sys.executable)[0]
+    if libc == "glibc":
+        kind = "glibc"
+    elif musl_loaders():
+        kind = "musl"
+    else:
+        raise ProvenanceError(UNSUPPORTED)
+    return HostPlatform("linux", _ARCH[info.machine], kind)
+
+
+def _trust_context() -> ssl.SSLContext:
+    paths = ssl.get_default_verify_paths()
+    cafile = paths.openssl_cafile if paths.openssl_cafile and os.path.isfile(paths.openssl_cafile) else None
+    capath = paths.openssl_capath if paths.openssl_capath and os.path.isdir(paths.openssl_capath) else None
+    if cafile is None and capath is None:
+        raise ProvenanceError(UNAVAILABLE)
+    context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    context.load_verify_locations(cafile=cafile, capath=capath)
+    return context
+
+
+class _Transport:
+    """https GET with no credentials, no proxy and the compiled-in trust store."""
+
+    def __init__(self, *, connection=http.client.HTTPSConnection, context_factory=_trust_context,
+                 timeout: float = 60):
+        self.connection, self.context_factory, self.timeout = connection, context_factory, timeout
+
+    def open(self, url: str, *, accept: str):
+        context = self.context_factory()
+        for _hop in range(MAX_REDIRECTS + 1):
+            parts = urlsplit(url)
+            if parts.scheme != "https" or parts.hostname not in REDIRECT_HOSTS | {API_HOST} \
+                    or parts.port not in (None, 443) or parts.username or parts.password:
+                raise ProvenanceError(UNAVAILABLE)
+            conn = self.connection(parts.hostname, 443, context=context, timeout=self.timeout)
+            target = parts.path + (f"?{parts.query}" if parts.query else "")
+            conn.request("GET", target, headers={"Accept": accept, "User-Agent": USER_AGENT})
+            response = conn.getresponse()
+            if response.status in (301, 302, 303, 307, 308):
+                # The Location of an asset download is a signed URL: never logged.
+                url = response.getheader("Location") or ""
+                response.close()
+                conn.close()
+                continue
+            if response.status != 200:
+                response.close()
+                conn.close()
+                raise ProvenanceError(UNAVAILABLE)
+            return response
+        raise ProvenanceError(UNAVAILABLE)
+
+
+def stable_releases(transport: _Transport, *, window: int = RECENCY_WINDOW) -> list[dict]:
+    """The newest ``window`` stable releases (no prerelease, no draft), newest first."""
+    try:
+        response = transport.open(f"https://{API_HOST}{RELEASES_PATH}", accept="application/vnd.github+json")
+        body = response.read(MAX_LISTING_BYTES + 1)
+        response.close()
+        if len(body) > MAX_LISTING_BYTES:
+            raise ProvenanceError(UNAVAILABLE)
+        releases = json.loads(body)
+    except (OSError, ValueError, http.client.HTTPException) as exc:
+        if isinstance(exc, ProvenanceError):
+            raise
+        raise ProvenanceError(UNAVAILABLE) from exc
+    if not isinstance(releases, list):
+        raise ProvenanceError(UNAVAILABLE)
+    stable = [r for r in releases if isinstance(r, dict) and r.get("draft") is False
+              and r.get("prerelease") is False and isinstance(r.get("tag_name"), str)
+              and _TAG.fullmatch(r["tag_name"])]
+    return stable[:window]
+
+
+def release_by_tag(transport: _Transport, tag: str) -> dict:
+    """One stable release by tag (the upstream watch re-fetches already-pinned members)."""
+    if not _TAG.fullmatch(tag):
+        raise ProvenanceError(UNVERIFIED)
+    try:
+        response = transport.open(f"https://{API_HOST}/repos/{REPO}/releases/tags/{tag}",
+                                  accept="application/vnd.github+json")
+        body = response.read(MAX_LISTING_BYTES + 1)
+        response.close()
+        release = json.loads(body)
+    except (OSError, ValueError, http.client.HTTPException) as exc:
+        if isinstance(exc, ProvenanceError):
+            raise
+        raise ProvenanceError(UNAVAILABLE) from exc
+    if (not isinstance(release, dict) or release.get("draft") is not False
+            or release.get("prerelease") is not False or release.get("tag_name") != tag):
+        raise ProvenanceError(UNVERIFIED)
+    return release
+
+
+def release_asset(release: dict, host: HostPlatform) -> ReleaseAsset:
+    """The exact platform asset of one release, with its URL and digest checked."""
+    tag = release.get("tag_name")
+    if not isinstance(tag, str) or not _TAG.fullmatch(tag):
+        raise ProvenanceError(UNVERIFIED)
+    matches = [a for a in release.get("assets") or () if isinstance(a, dict) and a.get("name") == host.asset]
+    if len(matches) != 1:
+        raise ProvenanceError(UNVERIFIED)
+    asset, = matches
+    url, digest = asset.get("browser_download_url"), asset.get("digest")
+    if url != f"{DOWNLOAD_PREFIX}{tag}/{host.asset}":
+        raise ProvenanceError(UNVERIFIED)
+    match = _DIGEST.fullmatch(digest) if isinstance(digest, str) else None
+    if match is None:
+        raise ProvenanceError(UNVERIFIED)
+    return ReleaseAsset(tag, host.asset, url, match.group(1))
+
+
+class _HashingReader:
+    """Feed every byte read by the tar reader through the archive digest, with a cap."""
+
+    def __init__(self, stream):
+        self.stream, self.digest, self.size = stream, sha256(), 0
+
+    def read(self, n=-1):
+        chunk = self.stream.read(1024 * 1024 if n is None or n < 0 else n)
+        self.size += len(chunk)
+        if self.size > MAX_ARCHIVE_BYTES:
+            raise ProvenanceError(UNVERIFIED)
+        self.digest.update(chunk)
+        return chunk
+
+    def drain(self):
+        while self.read(1024 * 1024):
+            pass
+
+
+def _normalized(name: str) -> str:
+    return posixpath.normpath(name.lstrip("/"))
+
+
+def read_member(stream, asset: ReleaseAsset, *, keep_bytes: bool = False) -> tuple[str, bytes | None]:
+    """Stream-hash the archive and its one ``antigravity`` member; never extract to disk.
+
+    Exactly one member may normalize to ``antigravity`` and it must be a regular file;
+    a duplicate, a link or a device of that name refuses. The archive digest must equal
+    the asset's published digest before the member digest is returned.
+    """
+    reader = _HashingReader(stream)
+    member_digest, member_bytes, seen = None, None, 0
+    try:
+        with tarfile.open(fileobj=reader, mode="r|gz") as bundle:
+            for member in bundle:
+                if _normalized(member.name) != MEMBER_NAME:
+                    continue
+                seen += 1
+                if seen > 1 or not member.isreg() or member.size > MAX_MEMBER_BYTES:
+                    raise ProvenanceError(UNVERIFIED)
+                handle = bundle.extractfile(member)
+                if handle is None:
+                    raise ProvenanceError(UNVERIFIED)
+                h, parts, size = sha256(), [], 0
+                while chunk := handle.read(1024 * 1024):
+                    size += len(chunk)
+                    if size > MAX_MEMBER_BYTES:
+                        raise ProvenanceError(UNVERIFIED)
+                    h.update(chunk)
+                    if keep_bytes:
+                        parts.append(chunk)
+                member_digest = h.hexdigest()
+                member_bytes = b"".join(parts) if keep_bytes else None
+        reader.drain()
+    except (tarfile.TarError, EOFError, OSError, http.client.HTTPException) as exc:
+        raise ProvenanceError(UNAVAILABLE if isinstance(exc, (OSError, http.client.HTTPException)) else UNVERIFIED) from exc
+    if seen != 1 or member_digest is None:
+        raise ProvenanceError(UNVERIFIED)
+    if reader.digest.hexdigest() != asset.digest:
+        raise ProvenanceError(UNVERIFIED)
+    return member_digest, member_bytes
+
+
+def fetch_member(transport: _Transport, asset: ReleaseAsset, *, keep_bytes: bool = False):
+    try:
+        response = transport.open(asset.url, accept="application/octet-stream")
+    except (OSError, http.client.HTTPException) as exc:
+        raise ProvenanceError(UNAVAILABLE) from exc
+    try:
+        return read_member(response, asset, keep_bytes=keep_bytes)
+    finally:
+        response.close()
+
+
+def find_provenance(image_sha256: str, *, host: HostPlatform, transport: _Transport | None = None,
+                    cached_member=lambda asset: None, remember_member=lambda asset, member: None,
+                    window: int = RECENCY_WINDOW) -> Provenance:
+    """Match ``image_sha256`` against the in-window stable releases for ``host``.
+
+    ``cached_member``/``remember_member`` are the store's authenticated member-digest
+    cache (keyed on the asset digest and runtime identity), so a repeat miss does not
+    download again. Any fetch failure refuses UNAVAILABLE; no match refuses UNVERIFIED.
+    """
+    transport = transport or _Transport()
+    for release in stable_releases(transport, window=window):
+        try:
+            asset = release_asset(release, host)
+        except ProvenanceError:
+            continue
+        member = cached_member(asset)
+        if member is None:
+            try:
+                member, _ = fetch_member(transport, asset)
+            except ProvenanceError as exc:
+                if str(exc) == UNAVAILABLE:
+                    raise
+                continue  # one malformed asset does not hide older in-window releases
+            remember_member(asset, member)
+        if member == image_sha256:
+            return Provenance(image_sha256, host.name, asset)
+    raise ProvenanceError(UNVERIFIED)