feat(setup): appliance mode — baked deps, /run units, GRUB skip (pithead#797 R1)

[VijitSingh97]

Phase R1 of pithead#797 (master installer image): an opt-in appliance mode so setup runs correctly on the Pithead appliance image — read-only root, volatile /etc overlay, and a boot leg that re-runs setup every boot. Every decision below was proven on the R0 bench recon (pithead#797, R0 comment), not predicted.

Originally stacked on #329 (grow-only HugePages sysctl, which this mode depends on); #329 squash-merged while this was in flight, so the branch is rebased onto develop and targets it directly.

The flag

RIGFORGE_APPLIANCE=1 — an env flag, not a config.json key. The caller is the image's boot path (not the operator), and the mode is a preset bundle over the existing env-overridable system-path seams (SYSTEMD_DIR, GRUB_DEFAULT, FSTAB, …) — the same surface R0 drove by hand with GRUB_DEFAULT=/nonexistent. Unset, nothing changes anywhere.

What the flag changes

Leg	Normal install	Appliance mode
Dependencies	apt/dnf/pacman install	never installs — verifies via command -v and fails naming missing tools (toolchain is baked at image build). A prebuilt tree needs envsubst only: the every-boot re-run keeps mining without a compiler, as the bench showed.
GRUB	merge cmdline params, update-grub, reboot	deliberate skip — the cmdline (incl. any 1GB-hugepage reservation) is image-owned. Without it XMRig runs 2MB pages at 100%: working, small known cost.
systemd units	/etc/systemd/system, enable	/run/systemd/system (SYSTEMD_DIR preset), enable --runtime — for the xmrig unit and every optional unit (autotune/watchdog/api/control).
msr autoload	modules-load.d/msr.conf drop-in	plain modprobe msr only — setup re-runs each boot, so a boot-time drop-in is persistence machinery for a layer the box doesn't have (smaller than writing /run/modules-load.d, same effect).
hugetlbfs	fstab append + mount -a	runtime mount calls only (idempotent via mountpoint -q)
limits.conf	memlock append for interactive runs	skipped — the unit already sets LimitMEMLOCK=infinity
Runtime tuning	modprobe msr, grow-only sysctl (#328), governor	unchanged — all work on a read-only root

setup --dry-run previews the appliance decisions with the same logic (shared _missing_appliance_tools, same flag checks) — never a second copy; the existing main()-steps drift guard also runs against the appliance plan.

Drive-by: _miner_held_hugepages collapsed to a single awk statement (behaviorally identical; landed via the format pass).

Tests

tests/run.sh: 1563 passed, 0 failed (+61 assertions in a new appliance suite): preset/override semantics, dep check pass/fail/prebuilt arms, GRUB-skip with a present+writable GRUB file, no modules-load drop-in with a present drop-in dir, runtime mounts with fstab/limits untouched, enable --runtime, dry-run parity incl. the main()-steps drift guard, and a full black-box setup run under the flag. make lint (ShellCheck + shfmt) and make lint-md clean.

What only the bench can verify (next bench session)

• systemctl enable --runtime end-to-end on the real appliance: unit + wants symlink in /run, miner up after a boot-leg re-run.
• Runtime mount -t hugetlbfs on the appliance (R0 used the fstab path; the direct-mount calls are new).
• The baked-toolchain image variant passing the new command -v check (R0's rw-remount install left cc resolution broken — the check should catch exactly that).
• Interaction with pithead's hugepage budget stays R2 scope (merged budget when local_miner.enabled); this PR keeps the tune_kernel's runtime HugePages write shrinks another consumer's pool — reserve grow-only #328 grow-only behavior only.

🤖 Generated with Claude Code