Refine STATUS/NOTE/INFO logging for consistent UX and accurate terminology

- doc/logging.md: rewrite INFO/NOTE sections, add sleep/blank-line table columns
  for NOTE/WARN/DIE, clarify when to use each level

- initrd/bin/key-init.sh: streamline status messages, use 'public keys'
  terminology consistently (keys are for verification, not signing),
  consolidate under single STATUS/STATUS_OK pair

- initrd/bin/gui-init.sh: remove noisy STATUS pairs (HOTP presence check,
  TOTP/HOTP generation, TPM reset), add STATUS_OK for HOTP verification

- initrd/bin/oem-factory-reset.sh: change INFO to NOTE for user guidance
  (questionnaire, key generation explanations), add STATUS_OK for
  key generation, TPM reset, firmware flash, checksum signing steps

- initrd/bin/gpg-gui.sh: change INFO to NOTE for gpg card-edit instructions
  (user-facing hand-off guidance)

- initrd/bin/seal-totp.sh: change INFO to STATUS for PCR reading,
  change STATUS to NOTE for TOTP secret manual input display

- initrd/bin/tpmr.sh: change INFO to WARN for TPM unseal failure
  (actionable problem, not just informational)

- initrd/bin/cbfs-init.sh: clarify STATUS message for full SPI flash dump,
  add STATUS_OK for successful flash read

- initrd/bin/kexec-seal-key.sh: add STATUS_OK for LUKS TPM Disk Unlock
  Key generation, slot addition, LUKS header measurement, PCR reads

- initrd/bin/seal-hotpkey.sh: add STATUS/STATUS_OK for HOTP secret
  writing to security dongle

- initrd/bin/unseal-hotp.sh: add STATUS/STATUS_OK for HOTP secret
  unsealing from TPM

- initrd/bin/lock_chip.sh: add STATUS_OK for chipset write protection lock

- initrd/bin/network-init-recovery.sh: add STATUS_OK for ethernet module
  loading, hardware clock sync, Dropbear SSH server start

- initrd/etc/gui_functions.sh: remove redundant STATUS_OK for dongle
  detection, add STATUS_OK for signing key verification only on match,
  update signing key guidance message

- initrd/etc/functions.sh: fix dongle VID wait loop: add sleep 0.1
  to avoid busy-wait, add iteration cap (30) as hard fallback when
  /proc/uptime is unavailable to prevent infinite loop

Signed-off-by: Thierry Laurion <insurgo@riseup.net>

Author: tlaurion

doc/logging.md

@@ -101,30 +101,34 @@ Use this in situations like:
 
 ## INFO
 
-INFO is for contextual information that may be of interest to end users, but that is not required
-for use of Heads.
+INFO is for technical/security operations that advanced users want to see.
 
-INFO always goes to debug.log. It is shown on the console in info and debug modes, and suppressed
-from the console in quiet mode (where the log file serves as the post-mortem record).
+INFO always goes to debug.log. It is shown on the console in **info** and **debug** modes, and suppressed
+from the console in **quiet** mode (where the log file serves as the post-mortem record).
 
-Users might use this to troubleshoot Heads configuration or behavior, but this should not require
-knowledge of Heads implementation or developer experience.
+INFO is for operations that:
+- Are technically detailed (TPM PCR extends, key generation, cryptographic operations)
+- Advanced users want to see when troubleshooting
+- Are NOT hand-off guidance (use NOTE for that)
+- Are NOT developer-facing logic tracing (use DEBUG for that)
 
 For example:
 
-* "Why can't I enable USB keyboard support?" `INFO "Not showing USB keyboard option, USB keyboard is always enabled for this board"`
-* "Why isn't Heads booting automatically?" `INFO "Not booting automatically, automatic boot is disabled in user settings"`
-* "Why didn't Heads prompt me for a password?" `INFO "Password has not been changed, using default"`
+* `INFO "TPM: Extending PCR[4] with hash abc123..."` — technical TPM operation
+* `INFO "TPM: Reading PCR values for TOTP sealing policy"` — TPM state capture
+* `INFO "Measuring /boot/vmlinuz into TPM PCR[4]"` — integrity measurement
 
-These do not include highly technical details.
-They can include configuration values or context, _but_ they should refer to configuration settings
-using the user-facing names in the configuration menus.
+Do NOT use INFO for:
+
+* User guidance or hand-off instructions — use **NOTE** (sleeps 3s, italic white, cannot be hidden)
+* High-level user-facing explanations — use **NOTE** or **STATUS**
+* Developer-facing logic/decisions — use **DEBUG**
 
 Use this in situations like:
 
-* Showing very high level decision-making information, understandable for users not familiar with
-  Heads implementation
-* Explaining a behavior that could reasonably be unexpected for some users
+* Reporting technical security operations (TPM extends, measurements, sealing)
+* Showing advanced configuration values that power users care about
+* Operations that belong in debug.log and info-mode console for audit/diagnostic purposes
 
 ## console
 
@@ -182,17 +186,12 @@ The console renders `OK message` (with a leading space) in bold green; debug.log
 
 ## NOTE
 
-NOTE is for contextual information explaining something that is _likely_ to be unexpected or
-confusing to users new to Heads.
-
-Unlike INFO, it cannot be hidden from the console. Use this only if the behavior is likely to be
-unexpected or confusing to many users. If it is only possibly unexpected, consider INFO instead.
-
-Do not overuse this above INFO. Adding too much output at NOTE causes users to ignore it.
+NOTE is for **user guidance that needs attention** — it sleeps 3 seconds and prints
+blank lines before/after so users cannot scroll past it unread.
 
-NOTE always goes to debug.log.
+NOTE uses **italic white** (`\033[3;37m`) and cannot be hidden from console in any output mode.
 
-Two specific patterns where NOTE is the right level:
+Use NOTE for two specific patterns:
 
 **Security reminders** — advice about consequences or risks the user should not overlook,
 but that do not indicate a current problem:
@@ -208,20 +207,30 @@ tool's prompts or output rather than Heads-formatted messages:
 * "Nitrokey 3 requires physical presence: touch the dongle when prompted" - hardware-level event
 * "Please authenticate with OpenPGP smartcard/backup media" - gpg auth flow follows
 
+**Questionnaire/setup guidance** — when walking users through configuration steps:
+
+* "The following questionnaire will help you configure the security components of your system"
+* "Each prompt requires a single letter answer (Y/n)"
+* "Master key and subkeys will be generated in memory and backed up to a dedicated LUKS container"
+
 For example:
 
 * "Proceeding with unsigned ISO boot" - booting without a verified signature is unexpected and
   carries risk; the user needs to know it is happening deliberately.
 * "TOTP secret no longer accessible: TPM secrets were wiped" - mid-session secret loss requires
   immediate user attention.
 
+Unlike INFO (technical operations for advanced users), NOTE is for **user-facing guidance**
+that requires the user's attention and cannot be hidden.
+
+Do not overuse this above INFO. Adding too much output at NOTE causes users to ignore it.
+
 ## WARN
 
 WARN is for output that indicates a problem. We think the user should act on it, but we are able
 to continue, possibly with degraded functionality.
 
 This is appropriate when _all_ of the following are true:
-
 * there is a _likely_ problem
 * we are able to continue, possibly with degraded functionality
 * the warning is _actionable_ - there is a reasonable change that could silence the warning
@@ -235,6 +244,9 @@ Warnings must be _actionable_ - only WARN if there is a reasonable change the us
 
 WARN always goes to debug.log.
 
+**WARN sleeps 1 second** and prints blank lines before/after (like NOTE) so users
+cannot scroll past it unread. WARN uses **bold yellow** (`\033[1;33m`).
+
 For example:
 
 * Warning when using default passphrases that are completely insecure is reasonable.
@@ -290,15 +302,17 @@ Users can choose one of three output levels for console information.
 Console output styling - chosen for accessibility across color-deficiency types (WCAG 1.4.1:
 color is never the sole signal; text prefixes carry meaning independently):
 
-| Level     | Style        | ANSI code    | Rationale                                                                                                           |
-|-----------|--------------|--------------|---------------------------------------------------------------------------------------------------------------------|
-| DIE       | bold red     | `\033[1;31m` | Red = universal danger signal; `!!! ERROR:` prefix is the semantic carrier                                          |
-| WARN      | bold yellow  | `\033[1;33m` | Most universally perceptible alert color across deuteranopia, protanopia, tritanopia                                |
-| NOTE      | italic white | `\033[3;37m` | White = highest-contrast neutral on dark consoles; italic separates NOTE from bold STATUS/WARN, no semantic hue     |
-| STATUS    | bold only    | `\033[1m`    | In-progress actions - bold without hue readable in every terminal theme; `>>` prefix differentiates semantically    |
-| STATUS_OK | bold green   | `\033[1;32m` | Confirmed success - green is universally understood as success; scannable at a glance against plain bold STATUS     |
-| INFO      | green        | `\033[0;32m` | Standard informational color; INFO is optional context, its absence on console is harmless                          |
-| INPUT     | bold white   | `\033[1;37m` | Maximum contrast (21:1) on VGA/dark consoles; no color dependency, readable under all deficiency types              |
+| Level     | Style        | ANSI code    | Sleep | Blank lines | Quiet mode | Purpose |
+|-----------|--------------|--------------|-------|-------------|------------|---------|
+| DIE       | bold red     | `\033[1;31m` | 0s    | Yes         | Visible    | Fatal errors - execution stops |
+| WARN      | bold yellow  | `\033[1;33m` | 1s    | Yes         | Visible    | Actionable problems - degraded operation |
+| NOTE      | italic white | `\033[3;37m` | 3s    | Yes         | Visible    | User guidance needing attention |
+| STATUS    | bold only    | `\033[1m`    | 0s    | No          | Visible    | In-progress action announcements |
+| STATUS_OK | bold green   | `\033[1;32m` | 0s    | No          | Visible    | Confirmed success outcomes |
+| INFO      | green        | `\033[0;32m` | 0s    | No          | Suppressed | Technical operations for advanced users |
+| INPUT     | bold white   | `\033[1;37m` | 0s    | No*         | Visible    | Interactive input prompts |
+
+\* INPUT prints a newline after user input, not before.
 
 debug.log and /dev/kmsg always receive plain text without ANSI codes.
 
@@ -310,10 +324,12 @@ This means callers never need to care about redirections: a caller that does
 Similarly, scripts that use stdout for a structured protocol can safely call STATUS,
 STATUS_OK, and any other logging function — log output never appears on stdout.
 
-NOTE, WARN and DIE print a blank line before and after the message so they stand out visually
-from surrounding output. STATUS and STATUS_OK do **not** — they are called frequently and blank
-lines would make output very noisy. Use NOTE when a sleep and blank lines are needed.
+NOTE (3s), WARN (1s), and DIE (0s) print blank lines before and after the message
+so they stand out visually from surrounding output.
+STATUS and STATUS_OK do **not** — they are called frequently and blank
+lines would make output very noisy.
 INPUT displays the prompt inline (no leading blank line); the cursor stays on the same line as the prompt.
+A blank line is printed after the user's input to separate it from subsequent output.
 
 ### None / Quiet - minimal console output
 

initrd/bin/cbfs-init.sh

@@ -24,10 +24,12 @@ if [ -z "$CONFIG_PCR" ]; then
 fi
 
 if [ "$CONFIG_CBFS_VIA_FLASHPROG" = "y" ]; then
+	#TODO: This is ugly workaround. see https://github.com/osresearch/flashtools/issues/10
 	# Use flashrom directly, because we don't have /tmp/config with params for flash.sh yet
-	STATUS "Reading board keys and configuration from SPI flash"
+	STATUS "Reading board keys and configuration from full SPI flash dump"
 	if /bin/flashprog -p internal --fmap -i COREBOOT -i FMAP -r /tmp/cbfs-init.rom; then
 		CBFS_ARG=" -o /tmp/cbfs-init.rom"
+		STATUS_OK "Full firmware image obtained"
 	else
 		WARN "Failed to read board keys and configuration from SPI flash - some features may not be available"
 	fi

initrd/bin/gpg-gui.sh

@@ -57,8 +57,8 @@ while true; do
 	"g")
 		confirm_gpg_card
 		STATUS "INSTRUCTIONS:"
-		INFO "Type 'admin' then 'generate' and follow the prompts to generate a GPG key"
-		INFO "Type 'quit' once the key is generated to exit GPG"
+		NOTE "Type 'admin' then 'generate' and follow the prompts to generate a GPG key"
+		NOTE "Type 'quit' once the key is generated to exit GPG"
 		gpg --card-edit >/tmp/gpg_card_edit_output
 		if [ $? -eq 0 ]; then
 			gpg_post_gen_mgmt

initrd/bin/gui-init.sh

@@ -249,11 +249,9 @@ gate_reseal_with_integrity_report() {
 			# starting the NK3 CCID teardown.  This safety call covers the
 			# case where scdaemon was restarted between then and now.
 			release_scdaemon
-			STATUS "Checking $DONGLE_BRAND presence before sealing"
 			DEBUG "gate_reseal_with_integrity_report: checking HOTP token presence"
 			if hotp_verification info >/dev/null 2>&1; then
 				token_ok="y"
-				STATUS_OK "$DONGLE_BRAND present and accessible"
 				break
 			fi
 			DEBUG "gate_reseal_with_integrity_report: HOTP token not accessible"
@@ -285,10 +283,9 @@ generate_totp_hotp() {
 	if [ "$CONFIG_TPM" != "y" ] && [ -x /bin/hotp_verification ]; then
 		# If we don't have a TPM, but we have a HOTP USB Security dongle
 		TRACE_FUNC
-		STATUS "Generating new HOTP secret"
 		/bin/seal-hotpkey.sh ||
 			DIE "Failed to generate HOTP secret"
-	elif STATUS "Generating new TOTP secret" && /bin/seal-totp.sh "$BOARD_NAME" "$tpm_owner_passphrase"; then
+	elif /bin/seal-totp.sh "$BOARD_NAME" "$tpm_owner_passphrase"; then
 		if [ -x /bin/hotp_verification ]; then
 			# If we have a TPM and a HOTP USB Security dongle
 			if [ "$CONFIG_TOTP_SKIP_QRCODE" != y ]; then
@@ -474,12 +471,14 @@ update_hotp() {
 	# PIN retry count is shown only before a retry so normal boots stay silent.
 	for attempt in 1 2 3; do
 		# Don't output HOTP codes to screen, so as to make replay attacks harder
+		STATUS "Verifying HOTP code"
 		hotp_verification check "$HOTP"
 		hotp_exit=$?
 		case "$hotp_exit" in
 		0)
 			HOTP="Success"
 			BG_COLOR_MAIN_MENU="normal"
+			STATUS_OK "HOTP code verified"
 			return
 			;;
 		4 | 7) # 4: code incorrect, 7: not a valid HOTP code — no point retrying same code
@@ -876,7 +875,6 @@ reset_tpm() {
 					prompt_missing_gpg_key_action || return 1
 					wait_for_gpg_card || true
 				else
-					STATUS_OK "TPM reset successful - updating /boot checksums and signatures"
 					if ! update_checksums; then
 						whiptail_error --title 'ERROR' \
 							--msgbox "Failed to update checksums / sign default config" 0 80
@@ -896,7 +894,6 @@ reset_tpm() {
 			fi
 
 			if [ -s /boot/kexec_key_devices.txt ] || [ -s /boot/kexec_key_lvm.txt ]; then
-				STATUS_OK "TPM reset successful - resealing TPM Disk Unlock Key (DUK)"
 				reseal_tpm_disk_decryption_key || prompt_missing_gpg_key_action
 			fi
 		else

initrd/bin/kexec-seal-key.sh

@@ -174,6 +174,7 @@ dd \
 	count=128 \
 	2>/dev/null ||
 	DIE "Unable to generate random key of 128 characters"
+STATUS_OK "LUKS TPM Disk Unlock Key generated"
 
 previous_luks_header_version=0
 for dev in $key_devices; do
@@ -261,6 +262,7 @@ for dev in $key_devices; do
 		--new-key-slot "$duk_keyslot" \
 		"$dev" "$DUK_KEY_FILE" ||
 		DIE "$dev: Unable to add LUKS TPM Disk Unlock Key to LUKS key slot $duk_keyslot"
+	STATUS_OK "$dev: LUKS TPM Disk Unlock Key added to slot $duk_keyslot"
 done
 
 # Now that we have setup the new keys, measure the PCRs
@@ -270,6 +272,7 @@ done
 STATUS "Measuring LUKS headers for TPM sealing policy"
 echo "$key_devices" | xargs /bin/qubes-measure-luks.sh ||
 	DIE "Unable to measure the LUKS headers"
+STATUS_OK "LUKS headers measured for TPM sealing policy"
 
 STATUS "Reading current PCR values for TPM sealing policy"
 pcrf="/tmp/secret/pcrf.bin"
@@ -293,6 +296,7 @@ DEBUG "Precomputing TPM future value for PCR6 sealing/unsealing of LUKS TPM Disk
 tpmr.sh calcfuturepcr 6 "/tmp/luksDump.txt" >>"$pcrf"
 # We take into consideration user files in cbfs
 tpmr.sh pcrread -a 7 "$pcrf"
+STATUS_OK "PCR values read for TPM sealing policy"
 
 # tpmr.sh seal may prompt for TPM owner password; avoid DO_WITH_DEBUG here so the
 # prompt remains visible on console. tpmr.sh logs command details internally.

initrd/bin/key-init.sh

@@ -22,17 +22,16 @@ if [ -d /.gnupg/keys ]; then
 	# This is legacy location for user's keys. cbfs-init takes for granted that keyring and trustdb are in /.gnupg
 	#  oem-factory-reset.sh generates keyring and trustdb which cbfs-init dumps to /.gnupg
 	# TODO: Remove individual key imports. This is still valid for distro keys only below.
-	STATUS "Importing user GPG keys"
 	gpg --import /.gnupg/keys/*.key  /.gnupg/keys/*.asc 2>/dev/null || WARN "Importing user's keys failed"
 fi
 
-# Import OS distribution signing keys used to authenticate ISO boots
-STATUS "Loading OS distribution signing keys for ISO boot authentication"
+# Load public keys for ISO verification
+STATUS "Loading public keys for ISO verification"
 gpg --homedir=/etc/distro/ --import /etc/distro/keys/* 2>/dev/null || WARN "Importing distro keys failed"
 #Set distro keys trust level to ultimate (trust anything that was signed with these keys)
 gpg --homedir=/etc/distro/ --list-keys --fingerprint --with-colons|sed -E -n -e 's/^fpr:::::::::([0-9A-F]+):$/\1:6:/p' |gpg --homedir=/etc/distro/ --import-ownertrust 2>/dev/null || WARN "Setting distro keys ultimate trust failed"
 gpg --homedir=/etc/distro/ --update-trust 2>/dev/null || WARN "Updating distro keys trust failed"
 
-# Add user's key so self-signed ISOs can also be booted from USB
-STATUS "Adding user GPG key as trusted for ISO signing"
-gpg --export | gpg --homedir=/etc/distro/ --import 2>/dev/null || WARN "Adding user's keys to distro keys failed"
+# Add user's public key to distro keyring to verify user-signed ISOs
+gpg --export | gpg --homedir=/etc/distro/ --import 2>/dev/null || WARN "Adding user's public key to distro keyring failed"
+STATUS_OK "Public keys loaded"

initrd/bin/lock_chip.sh

@@ -21,6 +21,7 @@ if [ -n "$APM_CNT" -a -n "$FIN_CODE" ]; then
 	# until the next system reset.
 	STATUS "Finalizing chipset write protection via SMI PR0 lockdown"
 	io386 -o b -b x $APM_CNT $FIN_CODE
+	STATUS_OK "Chipset write protection locked"
 else
 	NOTE "NOT finalizing chipset - lock_chip.sh called without valid APM_CNT and FIN_CODE"
 fi

initrd/bin/network-init-recovery.sh

@@ -60,6 +60,7 @@ ethernet_activation()
 			insmod.sh /lib/modules/$module.ko
 		fi
 	done
+	STATUS_OK "Ethernet network modules loaded"
 }
 
 # bring up the ethernet interface
@@ -113,10 +114,10 @@ if [ -n "$dev" ]; then
 						STATUS_OK "NTP time sync successful"
 					fi
 				fi
-				STATUS "Syncing hardware clock with system time (UTC)"
-				hwclock -w
-				date=$(date "+%Y-%m-%d %H:%M:%S %Z")
-				STATUS "Time: $date"
+			STATUS "Syncing hardware clock with system time (UTC)"
+			hwclock -w
+			date=$(date "+%Y-%m-%d %H:%M:%S %Z")
+			STATUS_OK "Hardware clock synced: $date"
 			fi
 		fi
 	fi
@@ -133,6 +134,7 @@ if [ -n "$dev" ]; then
 		# -B background
 		# -R create host keys
 		dropbear -B -R
+		STATUS_OK "Dropbear SSH server started"
 	fi
 	STATUS_OK "Network setup complete"
 	ifconfig $dev