frutebox-node 0.1.0__py3-none-any.whl

frutebox/packaging.py

@@ -0,0 +1,542 @@
+"""Package the node software so contributors can actually download and run it.
+
+The "downloadable software" is the provider node (``frutebox/`` + a tiny installer).
+This module builds a self-contained tarball on demand and produces the one-line
+installer the control plane serves at ``/install.sh``. No build infra, no
+registry — the accountable operator's own directory hands out the software:
+
+    curl -fsSL https://<directory>/install.sh | bash
+
+which downloads the tarball, makes a venv, installs deps, and leaves a
+``run-node.sh`` wrapper. Everything here is local file work; nothing is uploaded.
+"""
+from __future__ import annotations
+
+import hashlib
+import io
+import tarfile
+from pathlib import Path
+
+from . import signedconfig
+
+NODE_VERSION = "0.2.0"
+_PKG_DIR = Path(__file__).resolve().parent          # the frutebox/ package
+_PROJECT = _PKG_DIR.parent
+_ARCHIVE_ROOT = "frutebox-node"                        # top-level dir inside the tar
+
+# The installer that ships INSIDE the tarball (venv + deps + engine + model + launcher).
+# It provisions everything a plain laptop/desktop needs to serve real inference: a venv,
+# the Ollama engine, and a CPU-runnable model — mirroring what deploy/*.sh do for the
+# managed GPU nodes, but self-contained and cross-platform (Linux auto-install, macOS
+# points the user at the one-time Ollama download).
+_BUNDLED_INSTALL = """#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "$0")"
+echo "▶ creating virtualenv and installing dependencies …"
+python3 -m venv .venv
+. .venv/bin/activate
+pip install -q --upgrade pip
+pip install -q -r requirements.txt
+
+# --- MEDIA EXTRAS, REINSTALLED BECAUSE THE PACKAGE REFRESH DESTROYS THEM ----------------
+#
+# THE BUG, measured 2026-10-14 on frutebox-runpod-2. The media image is built with
+# the image-generation build arg, which pip-installs torch + diffusers into
+# `/opt/frutebox-node/.venv`. Then `deploy/runpod/entrypoint.sh` boots and does:
+#
+#     rm -rf frutebox-node && ... && tar -xzf node.tgz ... && bash install.sh
+#
+# `rm -rf` takes the venv with it, and the line above rebuilds a PLAIN venv (no
+# --system-site-packages), so every boot silently undid the entire media build. The node still
+# ADVERTISED image — `output_modalities` is set from GEN_MODALITIES — so the gateway dispatched
+# to it and every job came back:
+#
+#     RuntimeError: image generation is not available on this node: No module named 'torch'
+#
+# which the dispatch loop turned into "no node is serving 'image'". Hours were spent looking for
+# missing capacity in front of a node that was up, advertising correctly, and amputated at boot.
+#
+# IT GOES HERE, not in the Dockerfile, for one practical reason: this file ships in the node
+# package served by the directory, so it reaches every pod on the next boot without rebuilding and
+# pushing a ~10 GB image. `install.sh` is also NOT in `_AGENT_FILES`, so changing it does not move
+# the agent digest and cannot cause an attestation refusal.
+#
+# IDEMPOTENT AND NON-FATAL. If torch already imports (a correctly baked image, or a second boot
+# with a warm pip cache) this is a no-op. If the install fails, the node still starts and serves
+# TEXT — a node that refuses to boot because it cannot do images is worse than one that does the
+# half it can, and the gateway's own gate already refuses a modality nothing can serve.
+MEDIA_WANT="${FRUTEBOX_GEN_MODALITIES:-${STEVAI_GEN_MODALITIES:-}}"
+case ",${MEDIA_WANT}," in
+  *,image,*|*,audio,*|*,video,*)
+    if python -c "import torch" >/dev/null 2>&1; then
+      echo "▶ media extras already present"
+    else
+      echo "▶ installing media extras (torch, diffusers, transformers) for: ${MEDIA_WANT}"
+      # THE WHEEL MUST MATCH THE POD'S DRIVER, and the default PyPI wheel did not.
+      #
+      # MEASURED 2026-10-14: plain `pip install torch` installed a build for a newer CUDA than
+      # the node's driver, and torch then said
+      #     "CUDA initialization: The NVIDIA driver on your system is too old (found version 12080)"
+      # so `cuda_getDeviceCount()` returned 0, `imagegen.available()` was False, and the node
+      # honestly advertised no image modality. torch imported perfectly — the failure was one
+      # layer down, in the GPU it could not see, which reads identically from the outside.
+      #
+      # cu124 rather than cu128: `deploy/runpod/Dockerfile` allows CUDA 12.4 through 12.8, and a
+      # cu124 build runs on any driver at or above 12.4 (CUDA minor-version compatibility), while
+      # a wheel pinned to the newest allowed driver fails on every older one. Lowest allowed
+      # version is the only choice that works across the whole fleet.
+      #
+      # The fallback is deliberate and ordered: a pinned index that 404s for a future torch
+      # release must not leave the node with NO torch, and plain PyPI is still better than
+      # nothing on a CPU node.
+      pip install -q torch --index-url https://download.pytorch.org/whl/cu124 \
+        || pip install -q torch \
+        || echo "⚠ torch failed to install — this node will serve TEXT only"
+      pip install -q diffusers transformers accelerate safetensors soundfile \
+        || echo "⚠ media libraries failed to install — this node will serve TEXT only"
+
+      # PER-MODALITY RUNTIMES. Each generator's `available()` demands its OWN runtime, and a node
+      # that advertises without it fails every job routed to it — `audiogen` says so in as many
+      # words: "ANY GPU node advertised audio and then failed every job". So the checks and the
+      # installs are kept in step, modality by modality:
+      #   video  -> videogen.available() requires shutil.which("ffmpeg")
+      #   audio  -> audiogen.speech_runtime_available() imports kokoro or chatterbox; the registry
+      #            resolves speech to kokoro-82m (hexgrad/Kokoro-82M), so kokoro is the one to have
+      case ",${MEDIA_WANT}," in
+        *,video,*)
+          if command -v ffmpeg >/dev/null 2>&1; then
+            echo "▶ ffmpeg already present"
+          else
+            echo "▶ installing ffmpeg (videogen requires it on PATH)"
+            # APT FIRST, THEN A PIP-SHIPPED STATIC BINARY. apt needs root, a working mirror and no
+            # held lock; in a node container any of the three can be missing, and the only symptom
+            # is `shutil.which("ffmpeg")` staying false while the log says nothing. imageio-ffmpeg
+            # carries its own static build and needs none of that — but it does not put it on
+            # PATH, which is the only thing videogen.available() looks at, so it is linked.
+            (apt-get update -qq && DEBIAN_FRONTEND=noninteractive apt-get install -y -qq ffmpeg) \
+              >/dev/null 2>&1 || true
+            if ! command -v ffmpeg >/dev/null 2>&1; then
+              echo "▶ apt could not provide ffmpeg; falling back to imageio-ffmpeg"
+              pip install -q imageio-ffmpeg >/dev/null 2>&1 || true
+              FF="$(python -c "import imageio_ffmpeg,sys; sys.stdout.write(imageio_ffmpeg.get_ffmpeg_exe())" 2>/dev/null || true)"
+              if [ -n "$FF" ] && [ -x "$FF" ]; then
+                for d in /usr/local/bin "$HOME/.local/bin"; do
+                  mkdir -p "$d" 2>/dev/null && ln -sf "$FF" "$d/ffmpeg" 2>/dev/null && break
+                done
+              fi
+            fi
+            # SAY WHAT THE CHECK WILL SEE, not what we attempted. videogen.available() asks
+            # shutil.which("ffmpeg"); anything else is a story about an install.
+            if command -v ffmpeg >/dev/null 2>&1; then
+              echo "▶ ffmpeg on PATH at $(command -v ffmpeg)"
+            else
+              echo "⚠ ffmpeg still NOT on PATH — VIDEO will not be advertised"
+            fi
+          fi ;;
+      esac
+      case ",${MEDIA_WANT}," in
+        *,audio,*)
+          if python -c "import kokoro" >/dev/null 2>&1; then
+            echo "▶ kokoro already present"
+          else
+            echo "▶ installing kokoro (the registry's speech model is kokoro-82m)"
+            pip install -q kokoro soundfile >/dev/null 2>&1 || true
+            # REPORT WHAT THE CHECK ASKS: audiogen.speech_runtime_available() imports kokoro.
+            if python -c "import kokoro" >/dev/null 2>&1; then
+              echo "▶ kokoro importable"
+            else
+              echo "⚠ kokoro NOT importable — SPEECH will not be advertised"
+            fi
+          fi ;;
+      esac
+      python - <<'PYCHECK' || true
+# SAY WHETHER THE GPU IS ACTUALLY USABLE, here, at install time. Without this the only symptom
+# is a node that quietly advertises text, and the reason sits in a warning nobody reads.
+try:
+    import torch
+    print(f"▶ torch {torch.__version__}: cuda_available={torch.cuda.is_available()} "
+          f"devices={torch.cuda.device_count()}")
+    if not torch.cuda.is_available():
+        print("⚠ torch cannot see a GPU — media modalities will NOT be advertised. "
+              "Usually a driver/wheel CUDA mismatch; check the warning above.")
+except Exception as e:
+    print(f"⚠ torch import failed after install: {type(e).__name__}: {e}")
+PYCHECK
+    fi ;;
+esac
+
+# --- inference engine (Ollama) + a CPU-runnable model -----------------------
+# The node runs a REAL open-weight model through Ollama (see frutebox/inference.py).
+# Default model = $FRUTEBOX_OLLAMA_MODEL (the STEVAI_ spelling is still read), else
+# gemma3:4b (matches inference.py).
+MODEL="${FRUTEBOX_OLLAMA_MODEL:-${STEVAI_OLLAMA_MODEL:-gemma3:4b}}"
+if ! command -v ollama >/dev/null 2>&1; then
+  case "$(uname -s)" in
+    Linux)
+      echo "▶ installing Ollama (Linux) …"
+      curl -fsSL https://ollama.com/install.sh | sh ;;
+    Darwin)
+      echo "⚠ Ollama not found. Install it once on macOS from https://ollama.com/download"
+      echo "  (or 'brew install ollama'), then re-run ./install.sh." ;;
+    *)
+      echo "⚠ Ollama not found and no auto-installer for this OS — see https://ollama.com" ;;
+  esac
+fi
+# Least-privilege engine posture (see frutebox/engine_guard.py):
+#   * a NODE-PRIVATE model store, so network jobs never read, evict or grow the
+#     models you pulled for yourself;
+#   * bound to LOOPBACK, so nothing off this machine can reach the engine;
+#   * started with a MINIMAL environment via `env -i`, so the engine does not inherit
+#     the cloud credentials and API tokens sitting in your shell.
+# THE VARIABLE NAME dual-reads; THE DEFAULT PATH DOES NOT MOVE. `$HOME/.stevai` holds the pulled
+# model store — tens of GB on a real node — so changing the path orphans it and re-downloads
+# everything on the next boot. That is a data migration, not a rename (unfinished.md §6b). Both
+# names are exported so either spelling can be read downstream.
+FRUTEBOX_HOME="${FRUTEBOX_HOME:-${STEVAI_HOME:-$HOME/.stevai}}"
+export FRUTEBOX_HOME
+# STILL EXPORTED, and not an oversight: anything downstream that reads the old spelling must
+# keep working until the whole fleet has been rebuilt. Deleting this line is what "finishing
+# the rename" looks like, and it would break every running node.
+export STEVAI_HOME="$FRUTEBOX_HOME"
+export OLLAMA_MODELS="${OLLAMA_MODELS:-$FRUTEBOX_HOME/models}"
+export OLLAMA_HOST="${OLLAMA_HOST:-127.0.0.1:11434}"
+mkdir -p "$OLLAMA_MODELS" && chmod 700 "$FRUTEBOX_HOME" 2>/dev/null || true
+
+frutebox_start_engine() {
+  curl -sf "http://$OLLAMA_HOST/api/tags" >/dev/null 2>&1 && return 0
+  env -i HOME="$HOME" PATH="$PATH" \\
+      ${LANG:+LANG="$LANG"} ${TMPDIR:+TMPDIR="$TMPDIR"} \\
+      ${LD_LIBRARY_PATH:+LD_LIBRARY_PATH="$LD_LIBRARY_PATH"} \\
+      ${CUDA_VISIBLE_DEVICES:+CUDA_VISIBLE_DEVICES="$CUDA_VISIBLE_DEVICES"} \\
+      OLLAMA_HOST="$OLLAMA_HOST" OLLAMA_MODELS="$OLLAMA_MODELS" \\
+      OLLAMA_ORIGINS="http://127.0.0.1" \\
+      nohup ollama serve >"$FRUTEBOX_HOME/ollama.log" 2>&1 &
+  for i in $(seq 1 60); do
+    curl -sf "http://$OLLAMA_HOST/api/tags" >/dev/null 2>&1 && return 0; sleep 1
+  done
+  return 1
+}
+
+if command -v ollama >/dev/null 2>&1; then
+  echo "▶ starting Ollama and pulling model: $MODEL …"
+  frutebox_start_engine || echo "⚠ engine did not come up — run-node.sh will retry at launch."
+  ollama pull "$MODEL" || echo "⚠ could not pull $MODEL now — run-node.sh will retry at launch."
+fi
+echo
+echo "✅ frutebox node installed."
+echo "   Start sharing:  ./run-node.sh --name my-node --region eu-west \\\\"
+echo "                     --gateway-url ws://<gateway-host>/provider/ws"
+echo "   To point a laptop at the production gateway instead, set FRUTEBOX_GATEWAY_WS:"
+echo "     FRUTEBOX_GATEWAY_WS=wss://<gateway-host>/provider/ws ./run-node.sh --name my-laptop"
+"""
+
+_RUN_NODE = """#!/usr/bin/env bash
+# Launch the frutebox node. Any flags are passed straight to the provider agent.
+#
+# Gateway: pass --gateway-url, or set FRUTEBOX_GATEWAY_WS (the provider reads it when
+# the flag is absent, see frutebox/provider.py) to point a laptop at the real
+# production gateway, e.g.:
+#   FRUTEBOX_GATEWAY_WS=wss://<gateway-host>/provider/ws ./run-node.sh --name my-laptop
+#
+# Admission: if you were issued a signed node credential, drop it in a file next to
+# this script as `node-credential` (or set FRUTEBOX_NODE_CREDENTIAL / pass
+# --credential-file). The node presents it on connect and the gateway admits it
+# immediately — no manual approval to wait for, and it survives a control-plane
+# restart. Without one the node still connects and waits for operator approval.
+set -euo pipefail
+
+# NAME YOUR OWN DEATH. Under `set -e` any non-zero command ends this script instantly and silently,
+# and everything after it — including the `exec` that actually starts the node — simply never runs.
+# A pod that dies here looks identical from outside to a pod whose agent started and could not
+# reach a gateway: the container ends, the gateway logs nothing, and there is no message anywhere.
+# Two rented pods were spent on that ambiguity (2026-09-27, 2026-09-28) before the log was even
+# readable. `$LINENO` and `$BASH_COMMAND` cost nothing and remove the whole class.
+#
+# stderr on purpose: the RunPod entrypoint tees stderr into /var/log/node.log, which is the file
+# the :8081 sidecar publishes, so this reaches whoever is watching the boot.
+trap 'echo "run-node.sh FAILED at line $LINENO: $BASH_COMMAND (exit $?)" >&2' ERR
+
+cd "$(dirname "$0")"
+. .venv/bin/activate
+
+# Signed node credential: a local `node-credential` file wins, otherwise whatever is
+# already in the environment. Read from disk rather than the command line so the
+# ~4.5KB grant never shows up in the process list.
+CRED="${FRUTEBOX_NODE_CREDENTIAL:-${STEVAI_NODE_CREDENTIAL:-}}"
+if [ -z "$CRED" ] && [ -f node-credential ]; then
+  CRED="$(tr -d '[:space:]' < node-credential)"
+fi
+# BOTH NAMES EXPORTED. A pod spec setting either one boots, and an unadmitted node retries on a
+# backoff forever without saying why — so the cost of reading the wrong name here is a rented GPU
+# that connects, is refused, and bills until someone notices.
+export FRUTEBOX_NODE_CREDENTIAL="$CRED"
+export STEVAI_NODE_CREDENTIAL="$CRED"
+
+# Ensure the local Ollama engine is up and the advertised model is present, so the
+# node can actually serve inference the moment it connects.
+#
+# Engine posture (mirrors install.sh — see frutebox/engine_guard.py): node-private model
+# store, loopback-only bind, and started with a MINIMAL environment so it cannot
+# inherit your cloud credentials. If an engine is ALREADY answering we reuse it rather
+# than start a second one; in that case these settings are not ours to apply, so the
+# node is protected by the payload/endpoint guard alone.
+MODEL="${FRUTEBOX_OLLAMA_MODEL:-${STEVAI_OLLAMA_MODEL:-gemma3:4b}}"
+# THE VARIABLE NAME dual-reads; THE DEFAULT PATH DOES NOT MOVE. `$HOME/.stevai` holds the pulled
+# model store — tens of GB on a real node — so changing the path orphans it and re-downloads
+# everything on the next boot. That is a data migration, not a rename (unfinished.md §6b). Both
+# names are exported so either spelling can be read downstream.
+FRUTEBOX_HOME="${FRUTEBOX_HOME:-${STEVAI_HOME:-$HOME/.stevai}}"
+export FRUTEBOX_HOME
+# STILL EXPORTED, and not an oversight: anything downstream that reads the old spelling must
+# keep working until the whole fleet has been rebuilt. Deleting this line is what "finishing
+# the rename" looks like, and it would break every running node.
+export STEVAI_HOME="$FRUTEBOX_HOME"
+export OLLAMA_MODELS="${OLLAMA_MODELS:-$FRUTEBOX_HOME/models}"
+export OLLAMA_HOST="${OLLAMA_HOST:-127.0.0.1:11434}"
+mkdir -p "$OLLAMA_MODELS" && chmod 700 "$FRUTEBOX_HOME" 2>/dev/null || true
+
+if command -v ollama >/dev/null 2>&1; then
+  if ! curl -sf "http://$OLLAMA_HOST/api/tags" >/dev/null 2>&1; then
+    echo "▶ starting Ollama engine (loopback, private model store) …"
+    env -i HOME="$HOME" PATH="$PATH" \\
+        ${LANG:+LANG="$LANG"} ${TMPDIR:+TMPDIR="$TMPDIR"} \\
+        ${LD_LIBRARY_PATH:+LD_LIBRARY_PATH="$LD_LIBRARY_PATH"} \\
+        ${CUDA_VISIBLE_DEVICES:+CUDA_VISIBLE_DEVICES="$CUDA_VISIBLE_DEVICES"} \\
+        OLLAMA_HOST="$OLLAMA_HOST" OLLAMA_MODELS="$OLLAMA_MODELS" \\
+        OLLAMA_ORIGINS="http://127.0.0.1" \\
+        nohup ollama serve >"$FRUTEBOX_HOME/ollama.log" 2>&1 &
+    for i in $(seq 1 60); do
+      curl -sf "http://$OLLAMA_HOST/api/tags" >/dev/null 2>&1 && break; sleep 1
+    done
+  fi
+  # ONE MODEL PER PULL. `$MODEL` is a COMMA-SEPARATED LIST by design — `provider.py` splits it and
+  # says so ("one card can hold several models"), and the RunPod entrypoint exports the list of
+  # everything it actually pulled. Passed whole to `ollama pull` it becomes a model named
+  # "gemma3:4b,qwen3:4b", which the engine rejects:
+  #     Error: 400 Bad Request: invalid model name
+  # `|| true` then swallowed it, so the node started with the engine never warmed. Observed on a
+  # live pod 2026-09-28 — the first line the node log has ever shown, because until that day the
+  # log went to a file nothing wrote.
+  for _m in $(printf '%s' "$MODEL" | tr ',' ' '); do
+    [ -n "$_m" ] || continue
+    ollama list 2>/dev/null | grep -qF "$_m" || ollama pull "$_m" || true
+  done
+fi
+
+export FRUTEBOX_OLLAMA_MODEL="$MODEL"
+# Both spellings, like the credential above: a child process reading either one must work.
+export STEVAI_OLLAMA_MODEL="$MODEL"
+# `-u`, AND IT IS NOT COSMETIC. The RunPod entrypoint now pipes this into `tee` so the agent's
+# output reaches the file the :8081 sidecar serves. A pipe is not a TTY, so CPython switches
+# stdout to BLOCK buffering — the log then appears only in 8 KB chunks, and a crash loses whatever
+# is still in the buffer. The first run with `tee` showed exactly that: the engine warm-up error
+# was visible and the agent's own startup lines were not, which is the same blindness in a new
+# costume.
+exec python -u -m frutebox.provider "$@"
+"""
+
+_README = """frutebox node
+===========
+
+This is the software you run to contribute a machine to the frutebox network.
+It makes a single OUTBOUND connection to a gateway (no inbound ports, NAT-friendly)
+and runs AI jobs it receives — with your secrets never exposed, because prompts are
+redacted before they ever reach you.
+
+Install
+-------
+    ./install.sh
+
+install.sh sets up a Python venv, installs the Ollama engine (auto on Linux; on
+macOS install it once from https://ollama.com/download), and pulls a CPU-runnable
+model (default gemma3:4b, or $FRUTEBOX_OLLAMA_MODEL). A plain laptop/desktop is
+enough — no GPU required; the node auto-detects CPU/RAM and serves as a CPU node.
+
+Run
+---
+    ./run-node.sh --name my-node --region eu-west \\
+        --gateway-url ws://<gateway-host>/provider/ws
+
+Point a laptop at the production gateway with the FRUTEBOX_GATEWAY_WS env var
+(used when --gateway-url is omitted):
+
+    FRUTEBOX_GATEWAY_WS=wss://<gateway-host>/provider/ws ./run-node.sh --name my-laptop
+
+Other env vars: FRUTEBOX_OLLAMA_MODEL (model to pull/serve, default gemma3:4b),
+FRUTEBOX_NODE_CREDENTIAL (your signed admission credential — or save it to a file
+named `node-credential` beside run-node.sh, or pass --credential-file).
+Hardware class auto-detects; override with --compute-type / --memory-gb / --cpu-cores.
+
+Stop sharing at any time from the node dashboard (default http://127.0.0.1:8790)
+or remotely via the operator. Requires Python 3.10+.
+"""
+
+
+def _add_bytes(tar: tarfile.TarFile, arcname: str, data: bytes, mode: int = 0o644) -> None:
+    info = tarfile.TarInfo(f"{_ARCHIVE_ROOT}/{arcname}")
+    info.size = len(data)
+    info.mode = mode
+    tar.addfile(info, io.BytesIO(data))
+
+
+def build(dest_dir: Path | None = None) -> Path:
+    """Build (or rebuild) the node tarball and return its path."""
+    dest_dir = dest_dir or (_PROJECT / "dist")
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    out = dest_dir / f"frutebox-node-{NODE_VERSION}.tar.gz"
+
+    with tarfile.open(out, "w:gz") as tar:
+        # The package source (skip caches/artefacts).
+        def _filter(ti: tarfile.TarInfo):
+            base = Path(ti.name).name
+            if "__pycache__" in ti.name or base.endswith(".pyc"):
+                return None
+            return ti
+        tar.add(_PKG_DIR, arcname=f"{_ARCHIVE_ROOT}/frutebox", filter=_filter)
+        # requirements + installer + launcher + readme.
+        req = (_PROJECT / "requirements.txt")
+        req_bytes = req.read_bytes() if req.exists() else b""
+        _add_bytes(tar, "requirements.txt", req_bytes)
+        _add_bytes(tar, "install.sh", _BUNDLED_INSTALL.encode(), mode=0o755)
+        _add_bytes(tar, "run-node.sh", _RUN_NODE.encode(), mode=0o755)
+        _add_bytes(tar, "README.txt", _README.encode())
+    return out
+
+
+def get_or_build(dest_dir: Path | None = None) -> Path:
+    dest_dir = dest_dir or (_PROJECT / "dist")
+    out = dest_dir / f"frutebox-node-{NODE_VERSION}.tar.gz"
+    return out if out.exists() else build(dest_dir)
+
+
+class PackageRejected(Exception):
+    """The package manifest did not verify. The caller must NOT run the bytes it describes."""
+
+
+class NoVerifyKeyHere(PackageRejected):
+    """This node has no key to verify WITH. Distinct from a signature that failed, because the node's
+    decision differs — and deciding it on a substring of the message was one reworded sentence away from
+    turning a refusal into a warning."""
+
+
+def verify_package_manifest(manifest: dict, *, public_key: str = "") -> dict:
+    """FILE 22 — check the hybrid signature on a node-package manifest before running the package.
+
+    A SIGNATURE NOBODY VERIFIES IS DECORATION, which is the whole reason this exists next to the
+    endpoint that produces one. `/node-package` signs `{version, agent_digest}` with the repo's hybrid
+    signer (Ed25519 AND ML-DSA-65, both required — see `signing.mint_ticket`); this is the other half.
+
+    ⚠️ THE CALLER COMPARES THE DIGEST, and this function does not offer to. It had an `expect_digest`
+    parameter and the parameter had to go for the same reason `expect_version` did: only the caller knows
+    what a mismatch MEANS. For a running node, "same version, different digest" is signed evidence of the
+    wrong build and refuses, while "different version" is an ordinary rollout and must not — and a library
+    that rejected both would crash-loop the fleet on every release. Collapsing the two into one exception
+    inside here removed the information the decision needs. This returns the signed values; the caller
+    decides. (Another lane's `test_no_unsupplied_keyword_args` is what forced the question, by noticing the
+    parameter had only tests behind it.)
+
+    Raises `PackageRejected`. There is deliberately no "unsigned is fine" branch: a caller that wants
+    to tolerate an unsigned deployment checks `manifest["signed"]` itself and decides in the open.
+    """
+    # Verified through `signedconfig`, which owns both the seed and the verify key. Keeping the key
+    # names in one module is the point: see `sign_blob`.
+    try:
+        claims = signedconfig.verify_blob(
+            "node-package", str(manifest.get("signature") or ""), public_key=public_key)
+    except signedconfig.NoVerifyKey as e:
+        raise NoVerifyKeyHere(str(e)) from e
+    except signedconfig.ConfigRejected as e:
+        raise PackageRejected(str(e)) from e
+
+    # THE SIGNED VALUES WIN. Reading `agent_digest` off the unsigned envelope would make the signature
+    # ornamental: an attacker who cannot forge the ticket can still edit the field beside it.
+    signed_digest = str(claims.get("agent_digest") or "")
+    if not signed_digest:
+        raise PackageRejected("the signed manifest names no agent digest")
+    if str(manifest.get("agent_digest") or "") != signed_digest:
+        raise PackageRejected(
+            "the manifest's agent_digest does not match the signed one — the envelope was edited")
+    return {"version": str(claims.get("version") or ""), "agent_digest": signed_digest}
+
+
+_TARBALL_SHA: dict = {}
+
+
+def tarball_sha256(path: Path | None = None) -> str:
+    """SHA-256 of the node tarball this control plane serves.
+
+    ⚠️ THE ONE THING NOBODY COMPARED. `agent_digest` covers four modules; the TARBALL — `install.sh`,
+    `run-node.sh`, `requirements.txt` and 85 other files — was never hashed at all, and the installer is
+    `curl | tar | bash` with no check of any kind. So a fetcher had nothing to compare the bytes against
+    before executing them, whatever the manifest said.
+
+    Memoised on (path, mtime, size): the tarball is built once and served many times, and hashing a
+    multi-megabyte file per request is a cost with no reader.
+    """
+    p = path or get_or_build()
+    st = p.stat()
+    key = (str(p), st.st_mtime_ns, st.st_size)
+    hit = _TARBALL_SHA.get(key)
+    if hit:
+        return hit
+    h = hashlib.sha256()
+    with open(p, "rb") as fh:
+        for block in iter(lambda: fh.read(1 << 20), b""):
+            h.update(block)
+    out = h.hexdigest()
+    _TARBALL_SHA.clear()          # one entry: a rebuilt tarball must not leave the old hash behind
+    _TARBALL_SHA[key] = out
+    return out
+
+
+def installer_script(base_url: str) -> str:
+    """The `curl | bash` installer served by the control plane. `base_url` is the
+    directory's public URL (no trailing slash)."""
+    base = base_url.rstrip("/")
+    return f"""#!/usr/bin/env bash
+# frutebox node installer — fetches and installs the contributor software.
+#
+# ⚠️ IT COMPARES THE BYTES BEFORE IT RUNS THEM, and it did not. This was `curl | tar | bash install.sh`
+# with no check of any kind: whatever arrived was extracted and executed as the user. The signed manifest
+# existed and nothing on this path read it.
+#
+# What this closes: the bytes you downloaded are the bytes the control plane publishes. What it does NOT
+# close, stated rather than implied: this compares against a hash SERVED BY THE SAME HOST, so it is
+# integrity against corruption and against a swapped artifact, not attribution. The ML-DSA signature over
+# that hash is checked by the node itself at startup (`provider._check_own_build`), because verifying a
+# hybrid post-quantum signature in bash, before python exists, is not something this script can do.
+set -euo pipefail
+BASE="{base}"
+DEST="${{FRUTEBOX_NODE_DIR:-${{STEVAI_NODE_DIR:-frutebox-node}}}}"
+TARBALL="$(mktemp -t frutebox-node-XXXX).tar.gz"
+
+echo "▶ asking $BASE what it publishes …"
+MANIFEST="$(curl -fsSL "$BASE/node-package")"
+WANT="$(printf '%s' "$MANIFEST" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("tarball_sha256",""))')"
+if [ -z "$WANT" ]; then
+  echo "✖ the control plane published no tarball hash, so the download cannot be checked." >&2
+  echo "  Refusing to run unverified code. Upgrade the control plane, or install from source." >&2
+  exit 1
+fi
+
+echo "▶ downloading the frutebox node from $BASE …"
+curl -fsSL "$BASE/download/frutebox-node.tar.gz" -o "$TARBALL"
+GOT="$(shasum -a 256 "$TARBALL" | cut -d' ' -f1)"
+if [ "$GOT" != "$WANT" ]; then
+  rm -f "$TARBALL"
+  echo "✖ the download does not match what $BASE publishes." >&2
+  echo "  published: $WANT" >&2
+  echo "  received:  $GOT" >&2
+  echo "  Nothing has been extracted or run." >&2
+  exit 1
+fi
+echo "▶ verified: the download matches the published package."
+
+mkdir -p "$DEST"
+tar -xzf "$TARBALL" -C "$DEST" --strip-components=1
+rm -f "$TARBALL"
+cd "$DEST"
+bash install.sh
+echo
+echo "▶ installed into: $DEST"
+"""