[quality] test: unit coverage for elements/podman-vm/files/donate-clanker-bootstrap.py

[kubestellar-hive]

Test Improvement

Claimed ground: elements/podman-vm/files/donate-clanker-bootstrap.py (the file under test — unmodified), the new file tests/test_donate_clanker_bootstrap.py, one new podman-vm-check recipe in Justfile, and the existing tests/podman-vm-contract.sh (wired into that recipe, contents unmodified).

Why

donate-clanker-bootstrap.py (145 lines) is installed into the podman-vm guest disk. That disk ships no SSH and no guest agent, so a regression in it does not fail loudly — it produces a VM that boots to a login prompt and never registers with the Hive. Coverage of the script on the host was 0%; tests/podman-vm-contract.sh grep-asserts two of its lines but is not referenced by any workflow or Justfile recipe, so it never runs.

What this adds

tests/test_donate_clanker_bootstrap.py — 36 unittest cases, 93% line coverage of the script (the remainder is the if __name__ == "__main__" guard). The module is imported by path via importlib because its filename is not a Python identifier.

Unit	Covered behaviour
constants	PROTOCOL_VERSION == 2, the four REQUIRED_FIELDS, ENVELOPE_TIMEOUT outwaiting the host's 180s accept timeout
validate()	non-object envelope, version-1 and versionless rejection, each required field missing and each empty, multi-field error text, https:///wss:// accepted vs http:///ws:///bare host rejected, unknown optional fields ignored
worker_environment()	endpoint mapped onto both HIVE_WS_URL and HIVE_HUB, token/backend/run-id mapping, GOOSE_PROVIDER fallback to github_copilot (including the empty-string case), GOOSE_MODEL/GITHUB_COPILOT_TOKEN omitted when absent and exported when present, exact key set asserted so no name the worker cannot read is exported, raw envelope keys not leaked
read_envelope()	first line returned and trailing lines ignored, retry until the virtio port appears, empty-first-read retried rather than treated as fatal, blank line rejected, both timeout reason strings, past deadline never opens the channel, malformed JSON surfaces as JSONDecodeError
log()	stderr prefix, the /dev/kmsg mirror that tests/vm-boot.sh asserts on, unwritable /dev/kmsg swallowed
main()	full handshake writes a version-2 control_ack and execvs the worker; a rejected envelope is never acked, never execs, and exports no credentials

Justfile gains just podman-vm-check (host-only, no VM and no BuildStream) running the new tests plus tests/podman-vm-contract.sh. It is a new recipe placed in the VM section (~line 523) and does not modify catalog-check.

Disjointness

• fsdk-containers#209 [quality] claims scripts/generate_skill_index.py, tests/test_skill_index.py, and a skill-catalog-check recipe at Justfile ~line 230 — different script, different test file, different recipe, different region of the Justfile.
• fsdk-containers#218 [architect] claims elements/targets.json ownership inside tests/test_catalog_conformance.py — untouched here.

Verification

$ python3 -m unittest discover -s tests -p 'test_donate_clanker*.py'
Ran 36 tests in 0.63s
OK

$ python3 -m coverage report -m
elements/podman-vm/files/donate-clanker-bootstrap.py   69   5   93%   141-145

$ bash tests/podman-vm-contract.sh
podman-vm guest contract checks passed

No production code changed.

---

Filed by quality agent (hold-gated mode). Human review required.

— hive: agent=quality backend=copilot model=claude-opus-5