@softspark/ai-toolkit 4.18.0 → 4.19.0

package/kb/procedures/rtk-upstream-sync-sop.md

@@ -1,279 +0,0 @@
----
-title: "SOP: rtk Upstream Sync"
-category: procedures
-service: ai-toolkit
-tags: [sop, rtk, rtk-pack, upstream, cross-build, telemetry, checksum, port-validation, advisory]
-version: "1.0.0"
-created: "2026-07-26"
-last_updated: "2026-07-26"
-description: "Procedure for moving rtk-pack to a newer upstream rtk release: detect the tag, review the files we depend on, re-validate the Python port that every coverage number rests on, rebuild five targets with telemetry undefined, verify silence, publish to our own release namespace, and bump the pack. Written after the v0.43.0 to v0.44.0 bump, which changed every file this SOP names."
----
-
-# SOP: rtk Upstream Sync
-
-Moves `rtk-pack` from one pinned upstream tag to the next.
-
-Currently pinned: **v0.44.0**, shipped as
-`softspark-rtk-v0.44.0-1`. The pin lives in
-`app/plugins/rtk-pack/plugin.json` under `upstream.version`.
-
-Upstream ships stable tags roughly every two to four weeks behind a long
-release-candidate train (300+ RCs preceded v0.44.0). Do not track RCs.
-
-Background and the measured numbers: `kb/history/completed/rtk-pack-integration-20260726.md`.
-
-## Why this SOP is not "just rebuild"
-
-The v0.43.0 to v0.44.0 bump was 200 commits and touched **every file listed in
-Phase 2 below**. It also inverted pipeline rewriting: v0.43.0 rewrote the first
-stage of a pipeline, v0.44.0 rewrites the last. A rebuild without the review
-step would have shipped that silently, and the coverage numbers quoted to users
-would have described a version we no longer ship.
-
-## Phase 1: Detect
-
-```bash
-gh api repos/rtk-ai/rtk/releases --paginate \
-  --jq '.[] | select(.tag_name | test("^v[0-9]")) | "\(.tag_name)\t\(.published_at)"' | head -5
-```
-
-Compare against `upstream.version` in `app/plugins/rtk-pack/plugin.json`.
-
-Cadence: on demand, plus a check folded into release preparation.
-
-## Phase 2: Review before building
-
-Fetch the diff for the areas the pack depends on:
-
-```bash
-gh api repos/rtk-ai/rtk/compare/<pinned>...<new> \
-  --jq '{ahead: .ahead_by, files: [.files[] | {f: .filename, add: .additions, del: .deletions}]}'
-```
-
-Read the changelog, then diff these specifically:
-
-| File | Why it matters |
-|---|---|
-| `src/discover/registry.rs` | rewrite eligibility, pipeline handling, the TOML call sites |
-| `src/discover/rules.rs` | the rule table and `IGNORED_PREFIXES` |
-| `src/discover/lexer.rs` | tokenisation and `contains_unattestable_construct` |
-| `src/core/toml_filter.rs` | the filter DSL, which affects users who write their own filters |
-| `src/hooks/trust.rs` | the trust gate and its paths |
-| `src/hooks/hook_cmd.rs` | the Claude hook contract and permission handling |
-| `src/core/telemetry.rs`, `src/core/telemetry_cmd.rs` | the compile-time endpoint gate |
-| `Cargo.toml`, `Cargo.lock` | native deps, the MSRV, and new advisories |
-
-**A change to the DSL, to trust handling, or to the permission flow is a
-stop-and-think, not a rebuild.** In particular:
-
-- The pack ships no filters of its own, so a DSL change cannot break us. It can
-  still break a **user's** `filters.toml`, which upstream then skips silently
-  (`toml_filter.rs:220-221`). Worth a release-note line, not a code change.
-- If `hook_cmd.rs` changes when `permissionDecision` is emitted, the trust
-  boundary documented in the pack README changes with it.
-- If `IGNORED_PREFIXES` or the `pipeline_final_safe` rule set moves, every
-  coverage number is stale.
-
-## Phase 3: Re-validate the port
-
-Every coverage and saving figure the pack quotes comes from `rtk_port.py`, a
-Python model of rtk's rewrite pipeline. **Anything short of full agreement
-invalidates those numbers until the port is fixed.** Tooling lives in
-`~/rtk-measurement-archive/`.
-
-```bash
-git clone --depth 1 --branch <new-tag> https://github.com/rtk-ai/rtk.git /tmp/rtk-new
-cd ~/rtk-measurement-archive
-
-# Rewrite assertions from the tag's own test block.
-python3 extract_cases.py /tmp/rtk-new/src/discover/registry.rs cases.json
-python3 validate_port.py cases.json
-
-# The entry gate both real hook paths apply before rewrite_command.
-# Its assertions live in lexer.rs; re-extract if that block moved.
-python3 -c "import entry_gate; print('gate import ok')"
-```
-
-Baseline at v0.44.0: **203/203** rewrite assertions, **35/35** gate assertions.
-
-If the port diverges, fix the port first, then re-measure:
-
-```bash
-python3 measure_gated.py gated 0:1224
-```
-
-Measure over the whole transcript pool, never the default 134-file window: at
-that size the projection swings 8.8x on an unchanged mechanism.
-
-### 3.1 Re-measure, do not just re-validate
-
-Port agreement proves rtk still rewrites the same commands. It says nothing
-about how much each rewrite saves, and that is where the value actually sits.
-
-**`rtk grep` carries 4.04 MB of the 5.66 MB measurable saving: 71% of the total
-rests on one family.** If upstream changes that one filter, the headline number
-moves even with the port at full agreement. Measured effectiveness has already
-diverged from expectation in both directions once: `rtk grep` measured 22.3%
-against 9.0% modelled, `rtk rg` 7.0% against 30% modelled.
-
-So on every bump, after the port passes, replay against the newly built binary:
-
-```bash
-python3 replay_rtk.py --pool 1300 --rtk <path-to-the-new-binary>
-```
-
-Compare per family against the recorded baseline:
-
-| Family | Measured at v0.44.0 | Share of total saving |
-|---|---:|---:|
-| `rtk grep` | 22.3% | 71% |
-| `rtk git` | 33.1% | 21% |
-| `rtk find` | 35.6% | 8% |
-
-**Act on the result, do not just record it.** If the total lands below the
-published kill number of **0.05% of input tokens**, the pack has stopped earning
-its supply-chain surface and retiring it is the correct outcome, exactly as the
-in-house filter was retired. The margin at v0.44.0 is 0.0615%, which is 1.23x
-the kill number, so a single-family regression is enough to cross it.
-
-## Phase 4: Rebuild
-
-```bash
-gh workflow run rtk-build.yml --ref main \
-  -f upstream_tag=<new-tag> -f build_revision=1 -f rust_version=<pinned> -f publish=false
-```
-
-Five targets: `x86_64-apple-darwin`, `aarch64-apple-darwin`,
-`x86_64-unknown-linux-musl`, `aarch64-unknown-linux-gnu`,
-`x86_64-pc-windows-msvc`. A target that will not build is dropped, not faked.
-
-Pin `rust_version` explicitly. Upstream uses unpinned `stable` with
-`warnings = "deny"`, so a new rustc lint can turn the build red with no change
-on either side.
-
-**Advisories.** The `audit` job blocks. Re-derive the disposition rather than
-carrying the previous one forward:
-
-```bash
-# Cross-reference the new lockfile against OSV without waiting for CI.
-python3 - <<'PY'
-import json, re, urllib.request, pathlib
-lock = pathlib.Path("/tmp/rtk-new/Cargo.lock").read_text()
-pkgs = [(re.search(r'^name = "([^"]+)"', b, re.M).group(1),
-         re.search(r'^version = "([^"]+)"', b, re.M).group(1))
-        for b in lock.split("[[package]]")[1:]
-        if re.search(r'^name = ', b, re.M) and re.search(r'^version = ', b, re.M)]
-q = [{"package": {"name": n, "ecosystem": "crates.io"}, "version": v} for n, v in pkgs]
-req = urllib.request.Request("https://api.osv.dev/v1/querybatch",
-    data=json.dumps({"queries": q}).encode(), headers={"Content-Type": "application/json"})
-res = json.load(urllib.request.urlopen(req, timeout=60))
-for (n, v), r in zip(pkgs, res["results"]):
-    if r.get("vulns"):
-        print(n, v, [x["id"] for x in r["vulns"]])
-PY
-```
-
-For each advisory decide, and record the reason in the workflow:
-
-- **In-range fix** (`cargo update -p <crate>` works): add the crate to
-  `RTK_CARGO_UPDATES` in `.github/workflows/rtk-build.yml`. Both the audit job
-  and every build job apply it, so we audit what we ship.
-- **Needs a `Cargo.toml` change**: that is a source modification and breaks the
-  NOTICE claim. Ignore with a written reason, or escalate.
-- **Carried-forward ignores**: re-check every `--ignore` still applies. The
-  quick-xml pair exists only because upstream pins `"0.37"`; **delete both the
-  moment upstream moves to 0.41 or later** rather than carrying them.
-
-## Phase 5: Verify
-
-CI asserts this per target and the run fails on any `fail` verdict:
-
-1. `RTK_TELEMETRY_URL` and `RTK_TELEMETRY_TOKEN` unset at build time
-2. the artifact starts and reports the expected version
-3. no telemetry state written into a sandboxed home
-4. on Linux, identical behaviour with no network route
-5. every archive holds exactly one flat entry
-
-Then check by hand:
-
-```bash
-gh run download <run-id> --dir /tmp/rtk-verify
-cd /tmp/rtk-verify && shasum -a 256 -c checksums.txt
-```
-
-Three things CI cannot tell you:
-
-- **`strings` markers.** Compare `tls_markers_present` per target against the
-  previous build. Their absence is an LLVM outcome under LTO, not a guarantee,
-  so a sudden appearance means the telemetry stack survived and is worth
-  understanding before shipping.
-- **Reproducibility.** Four of five targets are bit-reproducible; compare
-  extracted binaries, never the tarballs, because gzip records a timestamp.
-  `x86_64-pc-windows-msvc` differs by 24 bytes per link (MSVC timestamp plus a
-  CodeView GUID), so a changed Windows digest proves nothing on its own.
-- **Upstream has no test asserting network silence.** That property can regress
-  on any bump without turning their CI red. We own it.
-
-## Phase 6: Publish
-
-```bash
-gh workflow run rtk-build.yml --ref main \
-  -f upstream_tag=<new-tag> -f build_revision=1 -f rust_version=<pinned> -f publish=true
-```
-
-Creates `softspark-rtk-<upstream>-<revision>`. Bump the revision, not the
-upstream part, when rebuilding the same upstream tag.
-
-## Phase 7: Bump the pack
-
-In `app/plugins/rtk-pack/plugin.json`:
-
-- `upstream.version` to the new tag
-- `binary.release_tag` to the new release
-- every `assets.*.sha256` from the published `checksums.txt`
-- `version` (the pack's own) — bump it whether or not the upstream tag moved,
-  because `plugin update` skips a pack whose recorded version still matches, so
-  an unbumped pack never reaches installed users. The two fields are separate so
-  a pack-only fix does not pretend to be an upstream bump
-
-Then:
-
-```bash
-npm test          # tests/test_rtk_pack.bats asserts digest shape and layout
-python3 scripts/validate.py --strict
-python3 scripts/audit_skills.py --ci
-shellcheck --severity=warning app/hooks/*.sh app/plugins/*/hooks/*.sh
-```
-
-Verify a real install end to end, against the published release rather than a
-mirror:
-
-```bash
-H=$(mktemp -d)
-AI_TOOLKIT_DATA_DIR="$H" python3 app/plugins/rtk-pack/scripts/init.py
-AI_TOOLKIT_DATA_DIR="$H" python3 app/plugins/rtk-pack/scripts/status.py
-```
-
-## Phase 8: Ship
-
-The pack version bump reaches installed users through `ai-toolkit update`,
-which runs `plugin update --editor all --all`. A pack whose recorded version
-matches its manifest is skipped silently, so the bump in Phase 7 is what makes
-the update fire at all. Forgetting it means nobody gets the new binary.
-
-## Phase 9: Record the licence position
-
-If upstream relicenses, adds a `NOTICE`, or changes `DISCLAIMER.md`, update the
-NOTICE generated in `.github/workflows/rtk-build.yml`. It currently records two
-build-time differences: the undefined telemetry endpoint, and in-range lockfile
-security updates. If Phase 4 changes that set, the NOTICE text changes with it.
-
-`DISCLAIMER.md` is deliberately not redistributed because it states telemetry is
-collected by default, which our builds contradict. Re-check that this is still
-the reason before changing the decision.
-
-## Related
-
-- `kb/history/completed/rtk-pack-integration-20260726.md` — decisions, measurements, pre-mortem
-- `kb/history/completed/output-filter-retirement-20260726.md` — why premise validation comes first
-- `app/plugins/rtk-pack/README.md` — the user-facing trust boundary

package/scripts/verify_rtk_binary.py

@@ -1,335 +0,0 @@
-#!/usr/bin/env python3
-"""Verify a cross-built rtk binary is silent, and fingerprint it for drift.
-
-Phase 1 of kb/history/completed/rtk-pack-integration-20260726.md. "No telemetry symbols in
-the binary" is NOT a usable acceptance test: the guard is a runtime branch on a
-const (`telemetry.rs:23-26`), not a `#[cfg]`, and `Cargo.toml:51` sets
-`strip = true`, so a symbol check passes for the wrong reason. This script
-asserts what is actually checkable instead:
-
-  build-gate   RTK_TELEMETRY_URL / RTK_TELEMETRY_TOKEN unset at build time
-  runs         the binary starts and reports its version
-  no-state     a sandboxed run creates no telemetry state on disk
-  offline      a run with no network route behaves identically (Linux only)
-  fingerprint  size, digest and TLS-marker scan, recorded for drift detection
-
-Stdlib only. Emits JSON to stdout; exits non-zero if any assertion fails.
-"""
-from __future__ import annotations
-
-import argparse
-import hashlib
-import json
-import os
-import platform
-import re
-import shutil
-import subprocess
-import sys
-import tempfile
-from pathlib import Path
-
-# Compile-time telemetry inputs. Upstream injects these in its own release
-# workflow (release.yml:85-86); our builds must leave both undefined.
-TELEMETRY_BUILD_VARS = ("RTK_TELEMETRY_URL", "RTK_TELEMETRY_TOKEN")
-
-# Telemetry state rtk would create if it ever ran the ping path. Names come from
-# src/core/telemetry.rs (salt file) and the tracking DB under the data dir.
-TELEMETRY_STATE_GLOBS = ("**/rtk/*salt*", "**/rtk/telemetry*", "**/rtk/*consent*")
-
-# webpki-roots embeds CA subjects as readable DER. Their presence means rustls
-# survived LTO, which is advisory rather than a failure: it says the HTTP stack
-# was linked in, not that anything is sent. Recorded so drift is visible.
-TLS_MARKERS = (b"ISRG Root X1", b"DigiCert", b"Baltimore CyberTrust", b"GlobalSign")
-
-RUNNABLE_HERE = {
-    ("Darwin", "arm64"): {"aarch64-apple-darwin"},
-    ("Darwin", "x86_64"): {"x86_64-apple-darwin"},
-    ("Linux", "x86_64"): {"x86_64-unknown-linux-gnu", "x86_64-unknown-linux-musl"},
-    ("Linux", "aarch64"): {"aarch64-unknown-linux-gnu", "aarch64-unknown-linux-musl"},
-    ("Windows", "AMD64"): {"x86_64-pc-windows-msvc"},
-}
-
-# qemu-user turns the one genuinely cross-built target into a verifiable one.
-# Without it every assertion below reports "skipped" and the artifact ships
-# having been started exactly zero times.
-QEMU_FOR = {
-    "aarch64-unknown-linux-gnu": ("qemu-aarch64-static", "qemu-aarch64"),
-    "aarch64-unknown-linux-musl": ("qemu-aarch64-static", "qemu-aarch64"),
-}
-
-# Rosetta 2 does the same job on Apple silicon, which is what lets us verify an
-# x86_64 artifact built on an arm64 runner. Probed, never assumed: the image can
-# ship without it.
-ROSETTA_FOR = {"x86_64-apple-darwin": ("Darwin", "arm64")}
-
-
-class Failure(Exception):
-    pass
-
-
-def can_run_natively(target: str) -> bool:
-    return target in RUNNABLE_HERE.get((platform.system(), platform.machine()), set())
-
-
-def emulator_for(target: str) -> list | None:
-    """qemu invocation for this target, with the sysroot passed as a flag.
-
-    The prefix goes through `-L` rather than QEMU_LD_PREFIX because the offline
-    check runs under sudo, and sudo's env_reset strips the variable. A gnu
-    target is dynamically linked, so losing it means qemu cannot find
-    ld-linux-aarch64.so.1 and the process dies with 255 before main.
-    """
-    if can_run_natively(target) or platform.system() != "Linux":
-        return None
-    for candidate in QEMU_FOR.get(target, ()):
-        found = shutil.which(candidate)
-        if not found:
-            continue
-        prefix = os.environ.get("QEMU_LD_PREFIX", "")
-        return [found, "-L", prefix] if prefix else [found]
-    return None
-
-
-def rosetta_for(target: str) -> list | None:
-    if ROSETTA_FOR.get(target) != (platform.system(), platform.machine()):
-        return None
-    if shutil.which("arch") is None:
-        return None
-    try:
-        probe = subprocess.run(
-            ["arch", "-x86_64", "/usr/bin/true"], capture_output=True, timeout=30
-        )
-    except (OSError, subprocess.SubprocessError):
-        return None
-    return ["arch", "-x86_64"] if probe.returncode == 0 else None
-
-
-def launcher(target: str):
-    """(wrapper, how) for running this target here, or (None, reason)."""
-    if can_run_natively(target):
-        return [], "native"
-    emu = emulator_for(target)
-    if emu:
-        return emu, f"emulated via {Path(emu[0]).name}"
-    rosetta = rosetta_for(target)
-    if rosetta:
-        return rosetta, "translated via Rosetta 2"
-    return None, f"{target} is not runnable on {platform.system()}/{platform.machine()} and no emulator is installed"
-
-
-def sandbox_env(root: Path) -> dict:
-    """An environment whose config/data/cache all resolve inside root."""
-    env = dict(os.environ)
-    for var in TELEMETRY_BUILD_VARS:
-        env.pop(var, None)
-    env["HOME"] = str(root)
-    env["USERPROFILE"] = str(root)
-    env["XDG_CONFIG_HOME"] = str(root / "config")
-    env["XDG_DATA_HOME"] = str(root / "data")
-    env["XDG_CACHE_HOME"] = str(root / "cache")
-    env["APPDATA"] = str(root / "AppData" / "Roaming")
-    env["LOCALAPPDATA"] = str(root / "AppData" / "Local")
-    return env
-
-
-def run(binary: Path, args: list, env: dict, wrapper: list | None = None):
-    cmd = (wrapper or []) + [str(binary)] + args
-    proc = subprocess.run(cmd, env=env, capture_output=True, timeout=120)
-    return proc.returncode, proc.stdout.decode("utf-8", "replace"), proc.stderr.decode("utf-8", "replace")
-
-
-def check_build_gate() -> dict:
-    """The variables must be undefined in this environment too.
-
-    The workflow asserts this before `cargo build`; re-asserting here catches a
-    verification job that was handed a binary from a contaminated build.
-    """
-    leaked = [v for v in TELEMETRY_BUILD_VARS if os.environ.get(v)]
-    if leaked:
-        raise Failure(f"telemetry build variables are set: {', '.join(leaked)}")
-    return {"pass": True, "checked": list(TELEMETRY_BUILD_VARS)}
-
-
-def check_runs(binary: Path, target: str, upstream_tag: str) -> dict:
-    """Starts, identifies itself as rtk, and reports the version we asked for.
-
-    Without the identity assertion this check passes for any binary that exits
-    0 on an unknown flag, `/bin/echo` included.
-    """
-    wrapper, how = launcher(target)
-    if wrapper is None:
-        return {"pass": None, "skipped": how}
-    with tempfile.TemporaryDirectory() as tmp:
-        code, out, err = run(binary, ["--version"], sandbox_env(Path(tmp)), wrapper=wrapper)
-    if code != 0:
-        raise Failure(f"`rtk --version` exited {code}: {err.strip()[:200]}")
-    version = (out.strip() or err.strip())
-    if "rtk" not in version.lower():
-        raise Failure(f"`--version` output does not identify rtk: {version[:120]!r}")
-    expected = upstream_tag.lstrip("v")
-    if expected and expected not in version:
-        raise Failure(f"version {version[:120]!r} does not match upstream tag {upstream_tag}")
-    return {"pass": True, "version": version, "how": how}
-
-
-def check_no_state(binary: Path, target: str) -> dict:
-    """A real command must not leave telemetry state behind."""
-    wrapper, how = launcher(target)
-    if wrapper is None:
-        return {"pass": None, "skipped": how}
-    with tempfile.TemporaryDirectory() as tmp:
-        root = Path(tmp)
-        env = sandbox_env(root)
-        for args in (["--version"], ["--help"], ["git", "status"]):
-            run(binary, args, env, wrapper=wrapper)
-        found = sorted(
-            str(p.relative_to(root))
-            for pattern in TELEMETRY_STATE_GLOBS
-            for p in root.glob(pattern)
-            if p.is_file()
-        )
-    if found:
-        raise Failure(f"telemetry state created: {found}")
-    return {"pass": True, "sandbox_clean": True}
-
-
-def check_offline(binary: Path, target: str) -> dict:
-    """Run with no network route and assert identical behaviour.
-
-    `unshare -rn` gives a network namespace with only a down loopback, so any
-    outbound connection fails immediately. There is no equivalent that works
-    unprivileged on macOS or Windows runners, so this assertion is Linux-only
-    and reports itself skipped elsewhere rather than pretending to pass.
-    """
-    wrapper, how = launcher(target)
-    if wrapper is None:
-        return {"pass": None, "skipped": how}
-    if platform.system() != "Linux" or shutil.which("unshare") is None:
-        return {"pass": None, "skipped": "unshare(1) network namespaces are Linux-only"}
-
-    # Ubuntu 24.04 sets kernel.apparmor_restrict_unprivileged_userns=1, so the
-    # unprivileged form is refused on GitHub runners and this assertion silently
-    # became a skip. Fall back to passwordless sudo, which runners have.
-    #
-    # Each entry is (baseline, isolated): identical except for the network
-    # namespace. Comparing against a plain run instead would confound the
-    # network with sudo's env_reset, and the difference would be read as
-    # evidence about the binary when it is evidence about the harness.
-    isolators = [
-        (["unshare", "-r"], ["unshare", "-rn"]),
-        (["sudo", "-n", "unshare", "-r"], ["sudo", "-n", "unshare", "-rn"]),
-    ]
-    baseline = isolated = None
-    for base, iso in isolators:
-        if subprocess.run(iso + ["true"], capture_output=True, timeout=30).returncode == 0:
-            baseline, isolated = base, iso
-            break
-    if isolated is None:
-        return {"pass": None, "skipped": "no usable network namespace: unprivileged userns refused and sudo unavailable"}
-
-    with tempfile.TemporaryDirectory() as tmp:
-        env = sandbox_env(Path(tmp))
-        online_code, _, online_err = run(binary, ["--version"], env, wrapper=baseline + wrapper)
-        offline_code, _, offline_err = run(binary, ["--version"], env, wrapper=isolated + wrapper)
-    if online_code != 0:
-        # The baseline could not start inside the namespace, so the comparison
-        # says nothing about the binary. That is a harness limitation, not a
-        # defect in the artifact, and reporting it as a failure would blame the
-        # thing being measured for the measurement not working. Skip instead,
-        # and carry the reason so it is visible rather than silent.
-        return {
-            "pass": None,
-            "skipped": (
-                f"baseline run under {' '.join(baseline)} exited {online_code}, "
-                f"so the network comparison proves nothing"
-            ),
-            "detail": online_err.strip()[:200],
-        }
-    if offline_code != online_code:
-        raise Failure(
-            f"behaviour differs without a network route: online exit {online_code}, offline exit {offline_code}"
-        )
-    return {
-        "pass": True,
-        "exit_code": offline_code,
-        "stderr_empty": not offline_err.strip(),
-        "isolator": " ".join(isolated),
-    }
-
-
-def fingerprint(binary: Path) -> dict:
-    data = binary.read_bytes()
-    markers = sorted(m.decode() for m in TLS_MARKERS if m in data)
-    printable = re.findall(rb"[\x20-\x7e]{8,}", data)
-    return {
-        "size_bytes": len(data),
-        "sha256": hashlib.sha256(data).hexdigest(),
-        "tls_markers_present": markers,
-        "printable_string_count": len(printable),
-        "strings_digest": hashlib.sha256(b"\n".join(sorted(set(printable)))).hexdigest(),
-    }
-
-
-def main() -> int:
-    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
-    ap.add_argument("--binary", required=True, type=Path)
-    ap.add_argument("--target", required=True)
-    ap.add_argument("--upstream-tag", default="", help="recorded in the manifest for traceability")
-    ap.add_argument("--out", type=Path, help="write the manifest here as well as stdout")
-    args = ap.parse_args()
-
-    if not args.binary.is_file():
-        print(json.dumps({"error": f"no such binary: {args.binary}"}), file=sys.stderr)
-        return 2
-
-    checks = {}
-    failures = []
-    for name, fn in (
-        ("build_gate", lambda: check_build_gate()),
-        ("runs", lambda: check_runs(args.binary, args.target, args.upstream_tag)),
-        ("no_state", lambda: check_no_state(args.binary, args.target)),
-        ("offline", lambda: check_offline(args.binary, args.target)),
-    ):
-        try:
-            checks[name] = fn()
-        except Failure as exc:
-            checks[name] = {"pass": False, "reason": str(exc)}
-            failures.append(f"{name}: {exc}")
-        except (OSError, subprocess.SubprocessError) as exc:
-            checks[name] = {"pass": False, "reason": f"{type(exc).__name__}: {exc}"}
-            failures.append(f"{name}: {exc}")
-
-    # A target nobody could start here must not report "pass". Every runtime
-    # assertion would have been skipped, and a green tick on an artifact that
-    # was never executed is the same silent-pass trap this plan keeps finding.
-    ran_anything = checks.get("runs", {}).get("pass") is True
-    if failures:
-        verdict = "fail"
-    elif ran_anything:
-        verdict = "pass"
-    else:
-        verdict = "inconclusive"
-
-    manifest = {
-        "target": args.target,
-        "upstream_tag": args.upstream_tag,
-        "host": f"{platform.system()}/{platform.machine()}",
-        # Recorded because the emulated path only works when the workflow
-        # supplies the cross sysroot; a manifest that does not say so cannot be
-        # audited later.
-        "qemu_ld_prefix": os.environ.get("QEMU_LD_PREFIX", ""),
-        "checks": checks,
-        "fingerprint": fingerprint(args.binary),
-        "verdict": verdict,
-        "failures": failures,
-    }
-    text = json.dumps(manifest, indent=2, sort_keys=True)
-    print(text)
-    if args.out:
-        args.out.write_text(text + "\n", encoding="utf-8")
-    return 1 if failures else 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())