fix(os): #1931 the debug variant pins the test registry into /etc/environment too

[VijitSingh97]

Closes #1931. Stacked on #1915 (feat/lan-registry-debug-variant, MERGE-READY at its head): the base is that branch so the diff is the fix alone; retarget to develop once #1915 merges.

What changes

• os/build-image.sh: the debug-variant tar-append (feat(os): #1892 a debug build against a non-default registry pins it into the boot units and trusts its CA #1915's block) also writes /etc/environment. The file is copied out of the exported rootfs (it carries PITHEAD_ENGINE=podman from the Dockerfile), the PITHEAD_REGISTRY=… line is appended, and the result goes into the tar as a leaf file. GNU tar extracts in order, so mkimage.sh's tar -xf lands the later copy, whole. A rootfs without the file is a loud refusal, not a silent skip.
• tests/os/verify-image-variant.sh: --test with a non-default PITHEAD_REGISTRY asserts the pin line AND the engine line in /etc/environment (the second proves the file was appended to, not replaced); release mode refuses any PITHEAD_REGISTRY= line there, in the same check that refuses the drop-ins.
• docs/dev/appliance-release.md: the debug-variant sentence names the file (shared docs/, disclosed per COMMON).

Why the image and not the harness: the harness runs ./pithead backup over SSH exactly as a developer on the --ssh variant does, which is what the variant is for, and the RC1 image fails that path for both. The release rootfs is untouched: the append runs only under a non-default registry with the test key.

What was RUN

• Synthetic tar on the host: a tar carrying etc/environment with the engine line; the block's own commands appended the pin; tar -xf extracted BOTH lines in one file and the sibling file survived. That is the override mkimage.sh:86 relies on.
• NEGATIVE control, the new assertion against the RC1 image (BUILD_COMMIT d7602bcc, built without this fix): verify-image.sh --test gives 119 passed, 1 failed, the one failure being the new /etc/environment row. The same image was 119/0 under the pre-fix verifier in the RC1 chain, so the delta is exactly the new row.
• bash -n, shfmt -i 4 -d, shellcheck -x -S warning on both scripts: clean. make lint-docs-voice and scripts/lint-file-budget.sh: OK.

What was NOT done

• POSITIVE control: a debug image built with this fix, verified 120/0, and a ./pithead backup over SSH on it that brings the stack back from the private registry. The bench is under the RC1 battery; this runs on the first free slot and the verdict lands here with its BUILD_COMMIT. Draft until then.
• Release mode on a real release build: the refusal is asserted textually only; no release image was built tonight.

Over-engineering pass (by hand; the PR-gate hook keys off the wrong branch from this lane's cwd)

• /etc/environment over /etc/profile.d/: a non-interactive ssh host './pithead …' never sources profile.d; PAM applies /etc/environment to every session, and the rootfs already uses it for the engine pin (Dockerfile:244).
• Append-over-copy rather than a Dockerfile RUN: keeps feat(os): #1892 a debug build against a non-default registry pins it into the boot units and trusts its CA #1915's invariant that the release rootfs is byte-identical to a build that never heard of a test registry.
• Not a pithead-side reader of a pinned file: a code path in the release script for a debug-only concern.
• Two scripts plus a doc sentence; no adjacent merge available (the variant material already lives in one sibling).

🤖 Generated with Claude Code

https://claude.ai/code/session_01NeSaJPWy7AkhYcYpGVkxBJ

[VijitSingh97]

Closed by the deletion of its base branch when #1915 squash-merged; the branch was rebased onto develop with --onto (one commit, tree identical to the measured head) and continues as #1939.