Part of #786 (sub-issue D; decision record in the 2026-08-13 comment there). With A and B, this completes the pre-GA parity bar.
Goal
A physical-presence channel that can change any setting — including the never-approve set that no remote factor may touch — and that doubles as the forgot-password recovery path. Trust statement: hands on the machine, which is what host-CLI-only already means operationally.
Mechanism (decided semantics)
- Boot-time only, as a leg in
pithead-boot (no udev hot-insert in v1 — deliberate cut for simplicity; the 125-line boot script gains one stage, before render). The machine finds pithead-config.json on inserted FAT removable media and validates it with the existing pre-seed machinery (consume_preseed_config path).
- The console (all console devices, like the wizard token broadcast) shows the exact diff against the running config, then a countdown. Countdown completion applies; removing the media aborts; a keypress (when a keyboard is attached) applies immediately or aborts — but a keyboard is never required.
- The consumed config is marked/renamed on the stick after apply so it cannot re-apply on a later boot (same hygiene as the installer's consumed pre-seed).
- Tamper-evidence alarms (
wallet_changed, clearnet_exposed, …) fire on whatever the stick changed — the alarm channel is exactly for this.
Why credential-less, and why apply-on-countdown
Peer practice is unanimous that physical presence alone authorizes recovery: Home Assistant's media-authorized host-SSH unlock (insert + reboot, zero keyboard — for a capability more sensitive than a config change), Synology's reset button (resets admin password and disables 2FA, no credential), UniFi's recovery mode. Requiring the dashboard password here would break the most valuable use — recovering a box whose password is lost. Insert + power-cycle are the deliberate physical acts; an earlier draft's require-a-keypress was dropped because keyboard-less boxes are the norm and a keypress adds nothing against an attacker who is already standing at the machine. An attacker with hands on the box already owns it today (boot media, disk pull); this channel adds tamper-evidence, not a new exposure class. That accepted risk is written down here on purpose.
Coverage
Tier 1 for the diff/accept/consume logic; the KVM battery gets a boot-with-media leg (stage a config on a virtual FAT stick, boot, assert diff shown + applied + consumed + alarm fired).
Dependencies
None.
Part of #786 (sub-issue D; decision record in the 2026-08-13 comment there). With A and B, this completes the pre-GA parity bar.
Goal
A physical-presence channel that can change any setting — including the never-approve set that no remote factor may touch — and that doubles as the forgot-password recovery path. Trust statement: hands on the machine, which is what host-CLI-only already means operationally.
Mechanism (decided semantics)
pithead-boot(no udev hot-insert in v1 — deliberate cut for simplicity; the 125-line boot script gains one stage, before render). The machine findspithead-config.jsonon inserted FAT removable media and validates it with the existing pre-seed machinery (consume_preseed_configpath).wallet_changed,clearnet_exposed, …) fire on whatever the stick changed — the alarm channel is exactly for this.Why credential-less, and why apply-on-countdown
Peer practice is unanimous that physical presence alone authorizes recovery: Home Assistant's media-authorized host-SSH unlock (insert + reboot, zero keyboard — for a capability more sensitive than a config change), Synology's reset button (resets admin password and disables 2FA, no credential), UniFi's recovery mode. Requiring the dashboard password here would break the most valuable use — recovering a box whose password is lost. Insert + power-cycle are the deliberate physical acts; an earlier draft's require-a-keypress was dropped because keyboard-less boxes are the norm and a keypress adds nothing against an attacker who is already standing at the machine. An attacker with hands on the box already owns it today (boot media, disk pull); this channel adds tamper-evidence, not a new exposure class. That accepted risk is written down here on purpose.
Coverage
Tier 1 for the diff/accept/consume logic; the KVM battery gets a boot-with-media leg (stage a config on a virtual FAT stick, boot, assert diff shown + applied + consumed + alarm fired).
Dependencies
None.