@softspark/ai-toolkit 4.17.0 → 4.18.0

package/llms.txt

@@ -21,6 +21,7 @@
 - [Plan: Offline-First SLM Profile — Lightweight Mode for Local Models](kb/history/completed/offline-slm-profile-plan-20260411.md)
 - [Retirement: Native Tool-Output Filter](kb/history/completed/output-filter-retirement-20260726.md)
 - [Plan: Output & Token Discipline](kb/history/completed/output-token-discipline-plan-20260504.md)
+- [rtk Pack Integration](kb/history/completed/rtk-pack-integration-20260726.md)
 - [How-To Guides](kb/howto/README.md)
 - [Plan: Cloud Security Pack — Multi-Cloud Audit](kb/planning/cloud-security-pack-plan.md)
 - [Plan: Drop Cascade hooks after 2026-07-01 sunset](kb/planning/drop-cascade-hooks-after-sunset.md)
@@ -29,6 +30,7 @@
 - [SOP: AI Toolkit Maintenance](kb/procedures/maintenance-sop.md)
 - [SOP: Release Preparation](kb/procedures/release-preparation-sop.md)
 - [SOP: Release Verification](kb/procedures/release-verification-sop.md)
+- [SOP: rtk Upstream Sync](kb/procedures/rtk-upstream-sync-sop.md)
 - [Agents Catalog](kb/reference/agents-catalog.md)
 - [Anti-Pattern Registry Format](kb/reference/anti-pattern-registry-format.md)
 - [AI Toolkit Architecture](kb/reference/architecture-overview.md)

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.17.0",
+  "version": "4.18.0",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "4.17.0",
+  "version": "4.18.0",
   "description": "AI coding toolkit: 108 skills, 44 agents, 12 developer-tool integrations, recoverable native tool-output filtering, Claude Chat/Cowork export, safety constitution, SARIF audit, and signed npm provenance.",
   "keywords": [
     "claude",

package/scripts/audit_skills.py

@@ -454,6 +454,27 @@ def audit(toolkit_root: Path) -> list[Finding]:
             scan_secrets(agent_md, findings)
             scan_unicode(agent_md, findings)
 
+    # Scan plugin packs. Pack code ships and executes exactly like skill code,
+    # and rtk-pack's install script downloads and runs a native binary, so
+    # leaving app/plugins out of the HIGH gate exempted the highest-risk code
+    # in the repo from the check that exists to catch it.
+    plugins = app / "plugins"
+    if plugins.is_dir():
+        for pack_dir in sorted(plugins.iterdir()):
+            if not pack_dir.is_dir():
+                continue
+            for py in sorted(pack_dir.rglob("*.py")):
+                scan_file_patterns(py, PYTHON_HIGH, "HIGH", findings)
+                scan_file_patterns(py, PYTHON_WARN, "WARN", findings)
+                scan_secrets(py, findings)
+            for sh in sorted(pack_dir.rglob("*.sh")):
+                scan_file_patterns(sh, BASH_HIGH, "HIGH", findings)
+                scan_file_patterns(sh, BASH_WARN, "WARN", findings)
+                scan_secrets(sh, findings)
+            for md in sorted(pack_dir.rglob("*.md")):
+                scan_secrets(md, findings)
+                scan_unicode(md, findings)
+
     # Unicode safety across the rest of the shipped prompt surface.
     for extra in ("rules", "personas", "mcp-templates"):
         extra_dir = app / extra

package/scripts/plugin.py

@@ -76,8 +76,8 @@ CODEX_PLUGIN_ASSET_MARKER = "# ai-toolkit-managed: codex-plugin-hook"
 def _empty_state() -> dict:
     return {
         "targets": {
-            "claude": {"installed": []},
-            "codex": {"installed": []},
+            "claude": {"installed": [], "versions": {}},
+            "codex": {"installed": [], "versions": {}},
         }
     }
 
@@ -103,6 +103,13 @@ def load_state() -> dict:
                     installed = targets.get(editor, {}).get("installed", [])
                     if isinstance(installed, list):
                         state["targets"][editor]["installed"] = sorted(set(installed))
+                    # Absent in state written before versions were tracked, so
+                    # every pack looks stale once and is updated exactly once.
+                    versions = targets.get(editor, {}).get("versions", {})
+                    if isinstance(versions, dict):
+                        state["targets"][editor]["versions"] = {
+                            k: v for k, v in versions.items() if isinstance(v, str)
+                        }
     return state
 
 
@@ -118,6 +125,18 @@ def _installed_for(state: dict, editor: str) -> list[str]:
     return list(state.get("targets", {}).get(editor, {}).get("installed", []))
 
 
+def _installed_version(state: dict, editor: str, name: str) -> str:
+    return state.get("targets", {}).get(editor, {}).get("versions", {}).get(name, "")
+
+
+def _record_version(state: dict, editor: str, name: str, version: str) -> None:
+    state.setdefault("targets", {}).setdefault(editor, {}).setdefault("versions", {})[name] = version
+
+
+def _forget_version(state: dict, editor: str, name: str) -> None:
+    state.get("targets", {}).get(editor, {}).get("versions", {}).pop(name, None)
+
+
 def _set_installed(state: dict, editor: str, names: list[str]) -> None:
     state.setdefault("targets", {}).setdefault(editor, {})
     state["targets"][editor]["installed"] = sorted(set(names))
@@ -264,6 +283,11 @@ def _copy_plugin_scripts(name: str, pack_dir: Path, installed_items: list[str])
     for script_file in sorted(plugin_scripts_dir.iterdir()):
         if script_file.name.startswith("__"):
             continue
+        # copy2 on a directory raises IsADirectoryError and aborts the install
+        # halfway with nothing rolled back, so a pack that ships scripts/bin/
+        # or a stray __pycache__ would break it.
+        if not script_file.is_file():
+            continue
         dest = scripts_dest / script_file.name
         shutil.copy2(script_file, dest)
         if script_file.suffix in (".py", ".sh"):
@@ -271,8 +295,13 @@ def _copy_plugin_scripts(name: str, pack_dir: Path, installed_items: list[str])
         print(f"    Copied script: {script_file.name}")
         installed_items.append(f"script:{dest}")
 
-    init_script = plugin_scripts_dir / "init_db.py"
-    if init_script.is_file():
+    # `init.py` is the generic name; `init_db.py` predates it and is what
+    # memory-pack ships. A pack whose init script is named anything else is
+    # silently never run, and the install still reports success.
+    for candidate in ("init.py", "init_db.py"):
+        init_script = plugin_scripts_dir / candidate
+        if not init_script.is_file():
+            continue
         result = subprocess.run(
             ["python3", str(init_script)],
             capture_output=True,
@@ -280,8 +309,10 @@ def _copy_plugin_scripts(name: str, pack_dir: Path, installed_items: list[str])
         )
         if result.returncode == 0 and result.stdout.strip():
             print(f"    Init: {result.stdout.strip()}")
-        elif result.returncode != 0 and result.stderr.strip():
-            print(f"    WARN init failed: {result.stderr.strip()}")
+        elif result.returncode != 0:
+            detail = result.stderr.strip() or result.stdout.strip() or "no output"
+            print(f"    WARN init failed: {detail}")
+        break
 
 
 def _copy_plugin_hook_scripts(name: str, hook_specs: list[dict], installed_items: list[str]) -> None:
@@ -908,6 +939,10 @@ def install_pack(name: str, editor: str) -> bool:
     if name not in installed:
         installed.append(name)
     _set_installed(state, editor, installed)
+    # Recorded so `update --all` can skip a pack whose manifest has not moved.
+    # Without it, update removes and reinstalls every pack every time, which for
+    # a pack that downloads a binary means refetching it on every core update.
+    _record_version(state, editor, name, str(pack.get("version", "")))
     save_state(state)
     return True
 
@@ -941,17 +976,40 @@ def remove_pack(name: str, editor: str) -> bool:
 
     installed = [p for p in installed if p != name]
     _set_installed(state, editor, installed)
+    _forget_version(state, editor, name)
     save_state(state)
     return True
 
 
-def update_pack(name: str, editor: str) -> bool:
+def pack_update_pending(name: str, editor: str) -> tuple[bool, str, str]:
+    """(needs_update, installed_version, available_version) for one pack."""
+    state = load_state()
+    if name not in _installed_for(state, editor):
+        return False, "", ""
+    pack = find_pack(name)
+    if not pack:
+        return False, _installed_version(state, editor, name), ""
+    available = str(pack.get("version", ""))
+    current = _installed_version(state, editor, name)
+    return current != available, current, available
+
+
+def update_pack(name: str, editor: str, *, force: bool = False) -> bool:
     state = load_state()
     if name not in _installed_for(state, editor):
         print(f"  Plugin '{name}' is not installed for {editor} — use 'install' instead")
         return False
 
-    print(f"  Updating: {name} for {editor}")
+    pending, current, available = pack_update_pending(name, editor)
+    if not pending and not force:
+        # Silent no-op by design: `ai-toolkit update` runs this for every
+        # installed pack on every invocation.
+        return True
+
+    if current and available:
+        print(f"  Updating: {name} for {editor} ({current} -> {available})")
+    else:
+        print(f"  Updating: {name} for {editor}")
     remove_pack(name, editor)
     return install_pack(name, editor)
 
@@ -1090,6 +1148,34 @@ def _show_memory_stats() -> None:
         print(f"    DB: {_human_size(MEMORY_DB.stat().st_size)} (error reading stats)")
 
 
+def _show_pack_status(name: str, pack_dir: Path) -> None:
+    """Let a pack report its own state via scripts/status.py.
+
+    Generic counterpart to the install-time init.py hook. Before this, anything
+    beyond a hook listing meant another hardcoded `if name == ...` branch, which
+    is why memory-pack is the only pack that ever reported anything.
+
+    The script owns its output format; it is indented and shown verbatim.
+    Failure is not an error: status must never be the thing that breaks.
+    """
+    status_script = pack_dir / "scripts" / "status.py"
+    if not status_script.is_file():
+        return
+    try:
+        result = subprocess.run(
+            ["python3", str(status_script)],
+            capture_output=True,
+            text=True,
+            timeout=15,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        print(f"    (status unavailable: {exc})")
+        return
+    stream = result.stdout if result.stdout.strip() else result.stderr
+    for line in stream.strip().splitlines():
+        print(f"    {line}")
+
+
 def cmd_status(editors: list[str]) -> None:
     state = load_state()
     shown = False
@@ -1117,6 +1203,8 @@ def cmd_status(editors: list[str]) -> None:
                     print(f"    Hooks: {', '.join(h.name for h in hooks)}")
             if name == "memory-pack":
                 _show_memory_stats()
+            else:
+                _show_pack_status(name, Path(pack["_dir"]))
         print()
 
     if not shown and all(not _installed_for(state, editor) for editor in editors):
@@ -1199,24 +1287,56 @@ def _cmd_remove(args: list[str], editors: list[str]) -> None:
 def _cmd_update(args: list[str], editors: list[str]) -> None:
     if not args:
         print("Usage: ai-toolkit plugin update [--editor claude|codex|all] <pack-name> [...]")
-        print("       ai-toolkit plugin update [--editor claude|codex|all] --all")
+        print("       ai-toolkit plugin update [--editor claude|codex|all] --all [--dry-run]")
         sys.exit(1)
+
+    dry_run = "--dry-run" in args or "--list" in args
+    force = "--force" in args
+    everything = "--all" in args
+    explicit = [a for a in args if not a.startswith("--")]
+
     state = load_state()
     for editor in editors:
-        names = list(_installed_for(state, editor)) if "--all" in args else args
+        names = list(_installed_for(state, editor)) if everything else explicit
         if not names:
+            if everything:
+                # Nothing installed is the common case; do not make the core
+                # update noisy about it.
+                continue
             print(f"No plugins installed for {editor}.")
             print()
             continue
-        if "--all" in args:
-            print(f"Updating {len(names)} installed plugin(s) for {editor}...\n")
+
+        if dry_run:
+            pending = []
+            for name in names:
+                needs, current, available = pack_update_pending(name, editor)
+                if needs or force:
+                    pending.append(f"{name} ({current or 'unrecorded'} -> {available or 'unknown'})")
+            if pending:
+                print(f"Would update for {editor}: {', '.join(pending)}")
+            else:
+                print(f"All {len(names)} pack(s) up to date for {editor}")
+            print()
+            continue
+
         ok = 0
+        failed: list[str] = []
         for name in names:
-            if update_pack(name, editor):
-                ok += 1
-            print()
-        if "--all" in args:
+            try:
+                if update_pack(name, editor, force=force):
+                    ok += 1
+                else:
+                    failed.append(name)
+            except Exception as exc:  # noqa: BLE001
+                # A pack failure must never abort the run: `ai-toolkit update`
+                # calls this after the core update has already succeeded.
+                print(f"  WARN update failed for {name}: {exc}")
+                failed.append(name)
+        if everything and (failed or force):
             print(f"Updated: {ok}/{len(names)} packs for {editor}")
+            if failed:
+                print(f"  Failed: {', '.join(failed)}")
             print()
 
 

package/scripts/verify_rtk_binary.py

@@ -0,0 +1,335 @@
+#!/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())