rigforge.sh

#!/usr/bin/env bash
#
# XMRig Worker Deployment Script
# Automates the provisioning of a high-performance Monero mining worker.
# Handles dependency installation, kernel tuning (HugePages/MSR), and service configuration.
#
# Sections, in order (search for "# --- "):
#   Logging utilities · Global variables · Helpers (idempotent edits, build math, GRUB)
#   Setup pipeline: prerequisites & config → workspace & deps → build → XMRig config → service/kernel
#   Orchestration (main) · Lifecycle (upgrade / uninstall)
#   Auto-tuning: memo & stats → power/thermal sensing → measurement → search → 'tune' command
#   Backup / restore · Commands (service control, version, apply, bench) · Doctor · Usage & dispatch
#

set -Eeuo pipefail

# --- Logging Utilities ---
# Color only when stdout is a terminal and NO_COLOR (https://no-color.org) is unset/empty (#144) —
# pipes, captures, CI logs, and the journal entries timer units write all get plain text. The
# ${_tty:+...} shape (instead of an if/else around the assignments) keeps every line executing on
# every run, so the no-pty CI coverage gate sees the whole block.
_tty=""
if [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then _tty=y; fi
C_RESET="${_tty:+\033[0m}"
C_GREEN="${_tty:+\033[1;32m}"
C_YELLOW="${_tty:+\033[1;33m}"
C_RED="${_tty:+\033[1;31m}"
C_BLUE="${_tty:+\033[1;34m}"
readonly C_RESET C_GREEN C_YELLOW C_RED C_BLUE
unset _tty

log() { echo -e "${C_GREEN}[INFO]${C_RESET} $1"; }
warn() { echo -e "${C_YELLOW}[WARN]${C_RESET} $1" >&2; }
error() {
    echo -e "${C_RED}[ERROR]${C_RESET} $1" >&2
    exit 1
}

# Names the phase currently running so the ERR trap can report where an unexpected failure happened.
CURRENT_STEP="starting up"
on_err() {
    local ec=$?
    echo -e "${C_RED}[ERROR]${C_RESET} rigforge aborted while ${CURRENT_STEP} (exit $ec)." >&2
    if [ -n "${BUILD_LOG:-}" ] && [ -f "${BUILD_LOG:-}" ]; then
        echo "  Build output is in: $BUILD_LOG — last lines:" >&2
        tail -n 20 "$BUILD_LOG" >&2 2>/dev/null || true
    fi
    echo "  Re-run with 'bash -x $0' to trace the exact command." >&2
}

# --- Global Variables ---
OS_TYPE="$(uname -s)" # Darwin: DEPRECATED 2026-09-14, unsupported/untested going forward (#493)
# Resolve symlinks to the real script directory, so an on-PATH link still finds config and assets.
# Portable (no `readlink -f`, which BSD/macOS lacks): follow links one hop at a time.
_script_dir() {
    local src="${1:-${BASH_SOURCE[0]}}" dir
    while [ -L "$src" ]; do
        dir=$(cd -P "$(dirname "$src")" &>/dev/null && pwd)
        src=$(readlink "$src")
        case "$src" in /*) ;; *) src="$dir/$src" ;; esac
    done
    cd -P "$(dirname "$src")" &>/dev/null && pwd
}

# Base for bundled assets and runtime state. RIGFORGE_HOME lets tests sandbox this real script so
# black-box runs remain isolated while coverage still credits the production file (#68).
SCRIPT_DIR="${RIGFORGE_HOME:-$(_script_dir)}"
# Operator for root-written files; timer units bake it into RIGFORGE_OPERATOR when SUDO_USER is absent.
REAL_USER="${SUDO_USER:-${RIGFORGE_OPERATOR:-${USER:-$(id -un)}}}"
CONFIG_JSON="$SCRIPT_DIR/config.json"
APPLIANCE_MARKER="${RIGFORGE_APPLIANCE_MARKER:-$SCRIPT_DIR/.rigforge-appliance}"
LEGACY_APPLIANCE_UNIT="${RIGFORGE_LEGACY_APPLIANCE_UNIT:-/run/systemd/system/xmrig.service}"
CONFIG_META_FILE="${RIGFORGE_CONFIG_META:-$SCRIPT_DIR/.rigforge-config-meta.json}" # #254 provenance sidecar
REBOOT_REQUIRED=false
SERVICE_INSTALLED=false
# True when the caller owns service restart; install_service then only writes/reloads/enables (#413).
SERVICE_NO_START=false

# Pinned XMRig release for reproducible builds; environment-overridable.
XMRIG_VERSION="${XMRIG_VERSION:-v6.26.0}"
XMRIG_COMMIT="${XMRIG_COMMIT:-b2ca72480c58d197e18c885d9fc1a0c8d517e60a}"
# Set to false when the pinned XMRig commit is already built, so a re-run/upgrade skips the (slow)
# recompile and the service restart — making re-runs idempotent (#4).
XMRIG_REBUILD=true

# Persist appliance behavior; recognize pre-marker Pithead installs by their runtime-only miner unit.
RIGFORGE_APPLIANCE="${RIGFORGE_APPLIANCE:-$({ [ -d "$APPLIANCE_MARKER" ] || { [ -f "$LEGACY_APPLIANCE_UNIT" ] && [ ! -e /etc/systemd/system/xmrig.service ]; }; } && printf 1 || printf 0)}"
if [ "$RIGFORGE_APPLIANCE" = 1 ]; then
    # Preset only — an explicit SYSTEMD_DIR in the environment (the test sandbox) still wins, and
    # the non-appliance default below keeps this value because it is now set.
    SYSTEMD_DIR="${SYSTEMD_DIR:-/run/systemd/system}"
fi
# Appliance enable/disable both need --runtime: its units and wants links live under /run, and a
# plain disable leaves a runtime link enabled (#353, verified on systemd 255).
ENABLE_RUNTIME=""
if [ "$RIGFORGE_APPLIANCE" = 1 ]; then ENABLE_RUNTIME="--runtime"; fi

# Writable system paths are overridable for the test sandbox; defaults remain the real locations.
LOGROTATE_DIR="${LOGROTATE_DIR:-/etc/logrotate.d}"
GRUB_DEFAULT="${GRUB_DEFAULT:-/etc/default/grub}"
FSTAB="${FSTAB:-/etc/fstab}"
LIMITS_CONF="${LIMITS_CONF:-/etc/security/limits.conf}"
MODULES_LOAD_DIR="${MODULES_LOAD_DIR:-/etc/modules-load.d}"
MODULES_FILE="${MODULES_FILE:-/etc/modules}"
SYSTEMD_DIR="${SYSTEMD_DIR:-/etc/systemd/system}"
HUGEPAGES_1G_DIR="${HUGEPAGES_1G_DIR:-/dev/hugepages1G}"
# Directory on PATH where `setup` installs the `rigforge` command (a symlink back to this script).
BIN_DIR="${BIN_DIR:-/usr/local/bin}"

# Read-only doctor paths, overridable for tests.
MEMINFO="${MEMINFO:-/proc/meminfo}"
# CPU flags source shared with util/proposed-grub.sh's pdpe1gb probe (#338).
CPUINFO="${CPUINFO:-/proc/cpuinfo}"
MSR_MODULE_DIR="${MSR_MODULE_DIR:-/sys/module/msr}"
GOVERNOR_FILE="${GOVERNOR_FILE:-/sys/devices/system/cpu/cpu0/cpufreq/scaling_governor}"
HUGEPAGES_1G_NR="${HUGEPAGES_1G_NR:-/sys/kernel/mm/hugepages/hugepages-1048576kB/nr_hugepages}"
NR_HUGEPAGES_FILE="${NR_HUGEPAGES_FILE:-/proc/sys/vm/nr_hugepages}"
# Hashrate-capping diagnostics (#67): RAM layout and effective loaded CPU clock.
DMIDECODE="${DMIDECODE:-dmidecode}"
RDMSR_BIN="${RDMSR_BIN:-rdmsr}" # msr-tools, for doctor's register-level MSR verification (#66)
CPUFREQ_MAX="${CPUFREQ_MAX:-/sys/devices/system/cpu/cpu0/cpufreq/cpuinfo_max_freq}"
CPU_SYSFS="${CPU_SYSFS:-/sys/devices/system/cpu}"
MIN_RAM_MTS="${MIN_RAM_MTS:-2666}"   # warn below this configured RAM speed (MT/s)
MIN_CLOCK_PCT="${MIN_CLOCK_PCT:-75}" # warn when the loaded clock is below this % of max boost
# BIOS/firmware advisory (#78): board identity and SMT state.
DMI_DIR="${DMI_DIR:-/sys/class/dmi/id}"
SMT_CONTROL="${SMT_CONTROL:-/sys/devices/system/cpu/smt/control}"
# Kernel lockdown state (#333); Secure Boot lockdown blocks every MSR write. Read, never infer.
LOCKDOWN_FILE="${LOCKDOWN_FILE:-/sys/kernel/security/lockdown}"

# systemd service name for the worker.
SERVICE_NAME="${SERVICE_NAME:-xmrig}"

# Detect whether we're being sourced (e.g. by the test suite). When sourced we only define
# functions/constants and skip running main, so functions can be exercised in isolation.
_RIGFORGE_SOURCED=0
if [ "${BASH_SOURCE[0]}" != "${0}" ]; then _RIGFORGE_SOURCED=1; fi

# Report which step failed on an unexpected error (skip when sourced by the test suite).
[ "$_RIGFORGE_SOURCED" = "0" ] && trap on_err ERR

# --- Helpers: idempotent edits, build math & GRUB cmdline ---

# Append a single line to a file only if that exact line is not already present (idempotent).
# Uses sudo so it works on root-owned system files; harmless when the file is user-writable.
append_once() {
    local file="$1" line="$2"
    grep -qFx "$line" "$file" 2>/dev/null || echo "$line" | sudo tee -a "$file" >/dev/null
}

# Inverse of append_once: remove every exact-match line from a file (idempotent). Used by `uninstall`.
remove_line() { # <file> <line>
    local file="$1" line="$2" tmp
    [ -f "$file" ] || return 0
    grep -qFx "$line" "$file" 2>/dev/null || return 0
    tmp=$(mktemp)
    grep -vFx "$line" "$file" >"$tmp" 2>/dev/null || true
    sudo cp "$tmp" "$file"
    rm -f "$tmp"
}

# Choose a safe build parallelism: don't exceed core count, and cap at ~1 job per 2 GB of RAM so the
# heavy XMRig/RandomX C++ translation units don't OOM low-memory hosts. Honors MEMINFO for testing.
compute_build_jobs() { # <ncpu>
    local mem_kb mem_gb jobs="$1" max
    mem_kb=$(awk '/^MemTotal:/ {print $2}' "${MEMINFO:-/proc/meminfo}" 2>/dev/null || echo 0)
    mem_kb="${mem_kb:-0}" # a meminfo with no MemTotal line yields empty (awk exits 0), not the || fallback
    mem_gb=$((mem_kb / 1024 / 1024))
    # Guard on mem_kb (readable at all), not mem_gb (truncates to 0 for BOTH a real sub-1GB host and an
    # unreadable meminfo) — a sub-1GB host must still hit the cap below (falls to the max<1 floor -> 1
    # job); only a genuinely unreadable meminfo should skip the cap and use all cores (#277).
    if [ "$mem_kb" -gt 0 ]; then
        max=$((mem_gb / 2))
        [ "$max" -lt 1 ] && max=1
        [ "$jobs" -gt "$max" ] && jobs="$max"
    fi
    [ "$jobs" -lt 1 ] && jobs=1
    echo "$jobs"
}

# SHA-256 of a file, portable (Linux sha256sum / macOS shasum).
_sha256() { # <file>
    if command -v sha256sum >/dev/null 2>&1; then sha256sum "$1"; else shasum -a 256 "$1"; fi | awk '{print $1}'
}

xmrig_already_built() {
    local marker="$WORKER_ROOT/xmrig/.rigforge-commit" sums="$WORKER_ROOT/xmrig/.rigforge-sha256"
    [ -x "$WORKER_ROOT/xmrig/build/xmrig" ] && [ -f "$marker" ] && [ "$(cat "$marker" 2>/dev/null)" = "$XMRIG_COMMIT" ] || return 1
    [ "$(cat "$WORKER_ROOT/xmrig/.rigforge-donate-min" 2>/dev/null)" = 0 ] || return 1
    [ ! -f "$sums" ] || [ "$(cat "$sums" 2>/dev/null)" = "$(_sha256 "$WORKER_ROOT/xmrig/build/xmrig")" ]
}

# Merge the HugePage/MSR kernel params we manage into an existing GRUB cmdline, preserving every
# other parameter and replacing only the ones we own (so re-runs don't accumulate). Echoes the merged
# cmdline. Usage: grub_merge_cmdline "<managed params>" "<current cmdline>"
grub_merge_cmdline() {
    local managed="$1" current="$2" preserved="" tok
    for tok in $current; do
        case "$tok" in
        hugepagesz=* | hugepages=* | default_hugepagesz=* | msr.allow_writes=*) ;; # ours — drop, re-added below
        *) preserved="${preserved:+$preserved }$tok" ;;
        esac
    done
    echo "${preserved:+$preserved }$managed"
}

# Drop only the kernel params RigForge manages (HugePages/MSR), preserving everything else. The inverse
# of what tune_kernel adds — used by `uninstall` to revert the GRUB cmdline.
grub_strip_managed() { # <current cmdline>
    local current="$1" preserved="" tok
    for tok in $current; do
        case "$tok" in
        hugepagesz=* | hugepages=* | default_hugepagesz=* | msr.allow_writes=*) ;; # ours — drop
        *) preserved="${preserved:+$preserved }$tok" ;;
        esac
    done
    printf '%s' "$preserved"
}

# Escape a value for use as the REPLACEMENT text of a `sed "s|pat|repl|"` command: backslash-prefix
# `\`, `&` (whole-match backreference) and the `|` delimiter. Without this, a pre-existing kernel
# param containing one of them (e.g. memmap=4G&2M) would silently corrupt /etc/default/grub (#134).
# Implemented with sed, not ${var//}, because bash 5.2's patsub_replacement changed `&` semantics
# in expansion replacements while our floor is bash 3.2.
_sed_escape_replacement() { # <value> -> escaped value on stdout
    printf '%s' "$1" | sed -e 's/[\\&|]/\\&/g'
}

# --- Setup: prerequisites & configuration ---

check_prerequisites() {
    log "Verifying system prerequisites..."
    if ! command -v jq &>/dev/null; then
        # Appliance mode never installs packages — same contract as install_dependencies: the read-only
        # image bakes everything at build, and an install here would silently violate it (pithead#797 R1).
        if [ "$RIGFORGE_APPLIANCE" = 1 ]; then
            error "jq is required but missing — appliance mode never installs packages; bake jq into the image."
        fi
        if [ "$OS_TYPE" == "Darwin" ]; then
            if command -v brew &>/dev/null; then
                log "Installing prerequisite: jq..."
                brew install jq
            else
                error "Homebrew is required on macOS to install dependencies."
            fi
        else
            log "Installing prerequisite: jq..."
            if command -v apt-get &>/dev/null; then
                # This is often the FIRST apt call on a fresh boot, so carry the same DPkg::Lock::Timeout
                # as install_dependencies (#74) — otherwise an unattended-upgrades lock fails it outright.
                sudo apt-get update -qq -o DPkg::Lock::Timeout=300 &&
                    sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq -o DPkg::Lock::Timeout=300 jq
            elif command -v dnf &>/dev/null; then
                sudo dnf install -y -q jq
            elif command -v pacman &>/dev/null; then
                sudo pacman -Sy --noconfirm jq
            else
                error "jq is required and no supported package manager was found. Please install jq manually."
            fi
        fi
    fi
}

ensure_config_exists() {
    if [ ! -f "$CONFIG_JSON" ]; then
        warn "Configuration file not found: $CONFIG_JSON"
        # `|| true`: on a non-interactive stdin (EOF) `read` returns non-zero, which would abort the run
        # via the ERR trap; instead fall through to the clear "configuration required" error below.
        read -r -p "Create a minimal configuration now? (y/N): " CREATE_CONF || true
        if [[ "$CREATE_CONF" =~ ^[Yy] ]]; then
            log "Starting interactive setup..."

            # Validate before writing; bounded retries also terminate on piped stdin/EOF.
            url_tries="${SETUP_URL_TRIES:-3}"
            IN_URL=""
            for i in $(seq 1 "$url_tries"); do
                read -r -p "Enter your pool URL (host:port, e.g. your-stack:3333): " IN_URL || break
                if [ -z "$IN_URL" ]; then
                    warn "A pool URL is required."
                    IN_URL=""
                    continue
                fi
                if ! [[ "$IN_URL" =~ :[0-9]+$ ]]; then
                    warn "Pool URL must include a port, e.g. $IN_URL:3333."
                    IN_URL=""
                    continue
                fi
                # Validate the host now, the same way parse_config will in a moment — otherwise a
                # host-less URL like ":3333" passes the port check, gets written, and then parse_config
                # hard-errors on it, leaving a broken config.json on disk that suppresses this prompt on
                # the re-run (the file now exists). Failing before the write keeps the user re-promptable.
                _host="${IN_URL%:*}"
                case "$_host" in
                \[*\])
                    if [[ "$_host" =~ ^\[[0-9A-Fa-f:]+\]$ ]]; then break; fi
                    warn "Pool URL '$IN_URL' has an invalid IPv6 literal (use [addr]:port)."
                    ;;
                *)
                    if [[ "$_host" =~ ^[A-Za-z0-9]([A-Za-z0-9.-]*[A-Za-z0-9])?$ ]]; then break; fi
                    warn "Pool URL host '$_host' is not a valid hostname or IP."
                    ;;
                esac
                IN_URL=""
            done
            if [ -z "$IN_URL" ]; then
                error "A valid pool URL (host:port) is required — giving up after $url_tries attempt(s)."
            fi

            # Optional stratum password; validate before creating the config.
            IN_PASS=""
            read -r -p "Stratum password, if your stack requires one (shown by 'pithead status'; Enter for none): " IN_PASS || true
            if [ -n "$IN_PASS" ] && ! [[ "$IN_PASS" =~ ^[[:graph:]]+$ ]]; then
                error "Stratum password must have no spaces or control characters."
            fi

            IN_SOCKS5=""
            case "$_host" in
            *.[Oo][Nn][Ii][Oo][Nn])
                log "An onion pool needs Tor. Using SOCKS proxy 127.0.0.1:9050; install and run Tor yourself."
                read -r -p "SOCKS proxy (host:port; Enter for 127.0.0.1:9050): " IN_SOCKS5 || true
                IN_SOCKS5="${IN_SOCKS5:-127.0.0.1:9050}"
                (_validate_host_port "$IN_SOCKS5" "SOCKS proxy" 9050) >/dev/null 2>&1 || error "SOCKS proxy must be a valid host:port."
                ;;
            esac

            # Omit unset fields to preserve the LAN config's minimal shape.
            (umask 077 && jq -n --arg url "$IN_URL" --arg pass "$IN_PASS" --arg socks5 "$IN_SOCKS5" \
                '{pools: [({url: $url} + (if $pass == "" then {} else {pass: $pass} end) + (if $socks5 == "" then {} else {socks5: $socks5} end))]}' >"$CONFIG_JSON")
            # The operator is told (below) to hand-edit this file to add a wallet / ACCESS_TOKEN, and the
            # first `apply` may be a long way off — chmod now so those secrets are never world-readable
            # in the interim (generate_xmrig_config's chmod 600 only runs on setup/apply). (#131)
            chmod 600 "$CONFIG_JSON"
            _reown_worker # hand the freshly-created config.json to the operator, even if setup later fails
            log "Created $CONFIG_JSON successfully."
            # New-user safety net: the minimal config has no wallet, so a PUBLIC-pool miner who stops here
            # would credit hashes to the hostname, not themselves — and nothing later (doctor included)
            # flags it, since it's a pool-side auth detail. Pithead users correctly need no wallet.
            warn "Mining to a PUBLIC pool (SupportXMR, etc.)? Add your Monero wallet as the pool \"user\" in"
            warn "$CONFIG_JSON and run 'sudo $0 apply', or your hashes credit '$(hostname)', not you."
            warn "Connecting to a Pithead stack instead? You're all set — no wallet needed."
        else
            error "Configuration file required to proceed."
        fi
    fi
}

# #412: every numeric range guard in this script was written as
# `! [[ $v =~ ^[0-9]+$ ]] || [ "$v" -gt MAX ]`, and that shape ACCEPTS the value it exists to reject
# when $v carries more digits than bash can evaluate: `[` returns **2** — an error, not "false" — and
# `if` reads any non-zero as false, so the else branch runs and no error fires. The only tell is a
# raw `[: ...: integer expression expected` on stderr, and where the caller redirects stderr there is
# no tell at all. #405 fixed one instance (a pool's port) with a digit-count guard; the shape was
# still live at ten more call sites — nine of them reachable, measured, and accepting a 20-digit
# value; the tenth (the api_allow_from IPv6 prefix) is unreachable because the surrounding regex
# already caps that field at three digits, and routes through here for uniformity. The guard lives
# HERE once rather than being re-derived per key and missed again on the next key somebody adds.
#
# The bound is the digit count of the key's OWN maximum: no value in range can be longer, so nothing
# legal is rejected — except a value zero-padded PAST that width, which the range test used to
# evaluate as decimal and keep. That trade is #405's, made again deliberately. For a key read out of
# JSON it is narrower than it looks: jq normalises a padded NUMBER before bash sees it (`065536` ->
# `65536`), so only a padded STRING (`"065536"`) is newly rejected. Padding within the width
# (`"05120"`, or `:08080` in #405) is untouched. All three shapes are pinned in tests/run.sh.
#
# Callers keep their own `error` messages: each names its key, its units and its range, and a shared
# message could name none of them. `_validate_host_port` keeps its own inline copy of this guard
# because it emits a DISTINCT digit-count message (#405) — the range wording there would quote a port
# that IS in range and tell the operator nothing.
_uint_in_range() { # <value> <min> <max> -> 0 iff a whole number bash can evaluate, within [min,max]
    local _v="$1" _min="$2" _max="$3"
    [[ "$_v" =~ ^[0-9]+$ ]] || return 1
    [ "${#_v}" -le "${#_max}" ] || return 1
    [ "$_v" -ge "$_min" ] && [ "$_v" -le "$_max" ]
}

# #400: ONE host:port validator, shared by a pool's `url` and its `socks5` proxy. The issue asks for
# the socks5 value to get "the same rules the pool URL gets" — a second copy of these four checks
# would satisfy that on the day it was written and drift the first time either side is touched, so
# the rules live in one place instead. <value> <label> <example-port>: the label leads the operator
# -facing message, and the example port makes the hint fit its key (a pool is :3333, a SOCKS5 proxy
# is :9050). Every check and every regex below is verbatim from the pool-url path it replaces.
_validate_host_port() { # <value> <label> <example-port>
    local _v="$1" _label="$2" _eg="$3" _h _p
    if ! [[ "$_v" =~ :[0-9]+$ ]]; then
        error "$_label '$_v' must include a port, e.g. $_v:$_eg."
    fi
    _h="${_v%:*}"
    _p="${_v##*:}"
    # Bound the digit count before arithmetic; huge values otherwise evade the range check.
    if [ "${#_p}" -gt 5 ]; then
        error "$_label port '$_p' in '$_v' has more than five digits; a port is 1-65535."
    fi
    if [ "$_p" -lt 1 ] || [ "$_p" -gt 65535 ]; then
        error "$_label port must be between 1 and 65535 (got '$_p' in '$_v')."
    fi
    # The host must be a valid hostname / FQDN / IPv4, or a bracketed IPv6 literal. This also
    # rejects the unfilled template placeholder (<...>), whitespace, and shell/URL metacharacters.
    # A v3 .onion is an ordinary hostname to this pattern, which is what makes #400 work at all.
    case "$_h" in
    \[*\]) [[ "$_h" =~ ^\[[0-9A-Fa-f:]+\]$ ]] || error "$_label '$_v' has an invalid IPv6 literal (use [addr]:port)." ;;
    *) [[ "$_h" =~ ^[A-Za-z0-9]([A-Za-z0-9.-]*[A-Za-z0-9])?$ ]] || error "$_label host '$_h' is not a valid hostname or IP." ;;
    esac
}

parse_config() {
    log "Parsing configuration..."
    # A missing config (e.g. `apply`/`tune` before `setup`) is a different, clearer error than bad JSON.
    if [ ! -f "$CONFIG_JSON" ]; then
        error "No configuration at $CONFIG_JSON — run 'sudo $0 setup' first (it creates one on first run)."
    fi
    if ! jq -e . "$CONFIG_JSON" >/dev/null 2>&1; then
        error "$CONFIG_JSON is not valid JSON."
    fi

    # HOME_DIR becomes a filesystem path we mkdir/cd/write under (with sudo), so validate it via the
    # shared resolver (the same one the privileged uninstall/backup/restore use, so none of them can act
    # on an unvalidated path).
    RAW_HOME=$(jq -r '.HOME_DIR // "DYNAMIC_HOME"' "$CONFIG_JSON")
    if ! WORKER_ROOT=$(_worker_root_for_home "$RAW_HOME"); then
        error "HOME_DIR must be \"DYNAMIC_HOME\" or an absolute path (letters, digits, . _ - /); got: '$RAW_HOME'."
    fi
    DONATION=$(jq -r '.DONATION // 0' "$CONFIG_JSON")
    if ! _uint_in_range "$DONATION" 0 100; then
        error "DONATION must be an integer between 0 and 100 (got: $DONATION)."
    fi
    # Pool(s). The pool target is XMRig's native `pools` array — the same structure XMRig uses
    # ({"url","user","pass","keepalive","tls",...}). Each entry needs a `url` of the form `host:port`;
    # every other field falls back to a Pithead-friendly default. List multiple entries for failover.
    # The pool `user` is left blank here and filled with the rig name in generate_xmrig_config.
    if ! jq -e '.pools | type == "array" and length > 0' "$CONFIG_JSON" >/dev/null 2>&1; then
        error "No pools configured. Set a 'pools' array in $CONFIG_JSON — e.g. {\"pools\": [{\"url\": \"your-pool-host:3333\"}]}."
    fi
    POOLS_JSON=$(jq -c '
        .pools | map({
            url: (.url // ""),
            user: (.user // ""),
            pass: (.pass // "x"),
            keepalive: (.keepalive // true),
            tls: (.tls // false),
            enabled: (.enabled // true)
        })
    ' "$CONFIG_JSON") || error "Could not parse 'pools' in $CONFIG_JSON."

    # tls-fingerprint (#115): re-attach the pin from the raw config, emitted ONLY when set — adding
    # it unconditionally (null) would change the generated config shape for every existing rig on
    # its next apply. A second single-line pass rather than lines inside the map above: kcov can't
    # attribute in-string program lines, and the patch-coverage gate needs every new line hittable.
    POOLS_JSON=$(jq -c --argjson base "$POOLS_JSON" '[$base, [.pools[] | ."tls-fingerprint"]] | transpose | map(.[0] + (if (.[1] // null) != null then {"tls-fingerprint": .[1]} else {} end))' "$CONFIG_JSON") || error "Could not parse 'pools' in $CONFIG_JSON."

    # Re-attach socks5 only when set, using the same shape/coverage rule as tls-fingerprint.
    POOLS_JSON=$(jq -c --argjson base "$POOLS_JSON" '[$base, [.pools[] | .socks5]] | transpose | map(.[0] + (if (.[1] // null) != null then {"socks5": .[1]} else {} end))' "$CONFIG_JSON") || error "Could not parse 'pools' in $CONFIG_JSON."

    # #265: jq's `//` treats an explicit false like null/missing, so the map above rewrites an
    # operator's "keepalive": false / "enabled": false to the true default. Restore explicit falses
    # from the raw config in another single-line pass (same kcov rationale as #115 above). Only a
    # boolean false matches `== false`; non-boolean junk flows through `//` untouched to validation.
    POOLS_JSON=$(jq -c --argjson base "$POOLS_JSON" '[$base, [.pools[] | [(.keepalive == false), (.enabled == false)]]] | transpose | map(.[0] + (if .[1][0] then {"keepalive": false} else {} end) + (if .[1][1] then {"enabled": false} else {} end))' "$CONFIG_JSON") || error "Could not parse 'pools' in $CONFIG_JSON."

    # Validate every pool field — fail fast with a clear message rather than writing a config XMRig
    # would choke on. url must be host:port: a valid hostname / IPv4 / bracketed-IPv6 host and a port
    # in 1-65535; user/pass reject whitespace and shell/control characters; keepalive/tls/enabled
    # must be booleans.
    # Iterate one compact JSON object per pool (robust even when a field like user is empty), and read
    # each field back with jq.
    while IFS= read -r _pool; do
        _u=$(jq -r '.url' <<<"$_pool")
        _user=$(jq -r '.user' <<<"$_pool")
        _pass=$(jq -r '.pass' <<<"$_pool")
        [ -n "$_u" ] || error "A pool entry has no url — set 'pools[].url' (host:port) in $CONFIG_JSON."
        _validate_host_port "$_u" "Pool url" 3333
        # SOCKS5 proxy (#400), per pool, emitted only when set. XMRig dials the pool through it and
        # sends the HOSTNAME in the CONNECT request (Client::Socks5::connect uses ATYP 0x03 for
        # anything that is not an IP literal), so the proxy resolves the name — which is what lets a
        # v3 .onion stratum work with no `socks5h` variant to ask for. Same host:port rules as the
        # pool url, via the shared validator, so an onion pool and its proxy cannot be judged by two
        # different standards.
        # #408: `""` is not "unset", and the two predicates used to disagree about that. The emit
        # step above keys on jq truthiness, so an empty string IS written into the generated
        # config; `// empty` here makes it indistinguishable from absent, so it skipped validation
        # entirely. Reject it rather than dropping the key — dropping is a silent downgrade for
        # tls-fingerprint (see below), and one rule for both keys stops them drifting apart again.
        if [ "$(jq -r 'has("socks5") and .socks5 == ""' <<<"$_pool")" = "true" ]; then
            error "Pool socks5 is an empty string — remove the key, or give it a host:port such as 127.0.0.1:9050."
        fi
        _s5=$(jq -r '.socks5 // empty' <<<"$_pool")
        if [ -n "$_s5" ]; then
            _validate_host_port "$_s5" "Pool socks5" 9050
        fi
        if [ -n "$_user" ] && ! [[ "$_user" =~ ^[A-Za-z0-9._:@+-]+$ ]]; then
            error "Pool user '$_user' has invalid characters (allowed: letters, digits, . _ - : @ +)."
        fi
        # #415: `pass` must be a STRING, checked before the charset rule below can be fooled. The
        # feed masks a set password to the {"__secret__": true} sentinel and _control_commit
        # resolves it back, but nothing stops a marker — or any other JSON object — reaching
        # config.json by a hand edit or by a future writer that forgets to resolve one. `jq -r`
        # renders an object as its JSON text, and the empty object `{}` renders as two graph
        # characters on one line, so it passes the check below and becomes the rig's literal
        # password. Type-check here so the guarantee does not depend on every writer remembering:
        # the same posture as the non-string tls-fingerprint rejection below.
        if [ "$(jq -r '.pass | type' <<<"$_pool")" != "string" ]; then
            error "Pool pass must be a string (got a $(jq -r '.pass | type' <<<"$_pool")). A masked-secret marker from the API feed is not a password — send the real value, or omit 'pass' entirely."
        fi
        if ! [[ "$_pass" =~ ^[[:graph:]]+$ ]]; then
            error "Pool pass must be non-empty with no spaces or control characters."
        fi
        # TLS fingerprint pin (#115): xmrig does NO cert verification for stratum without a pin
        # (v6.26.0 Tls.cpp:186 verifyFingerprint returns true when the pin is a NULL pointer), so
        # the fingerprint is the
        # ONLY server authentication stratum-TLS has. 64 hex chars, either case (xmrig compares
        # case-insensitively); passed verbatim, never normalized. A pin without tls:true is a hard
        # error — a silently-ignored pin would leave the operator believing they're protected.
        # #408: an EMPTY pin is not an absent one, and the difference is security-relevant. XMRig
        # v6.26.0 skips verification only when the pin is a null pointer; `""` parses to a non-null
        # empty String (Pool.cpp:129 -> String::operator=(const char *)), so Tls.cpp:186 falls
        # through to strncasecmp against every certificate and matches none — the pool never
        # connects. That is why this rejects rather than dropping the key: dropping it would turn
        # "refuse every cert" into "verify nothing", a silent downgrade introduced by the fix.
        if [ "$(jq -r 'has("tls-fingerprint") and ."tls-fingerprint" == ""' <<<"$_pool")" = "true" ]; then
            error "Pool tls-fingerprint is an empty string. Remove the key to connect without a pin, or set the cert's SHA-256 as 64 hex chars. An empty pin is not the same as no pin: xmrig compares it against every certificate and matches none, so the pool never connects."
        fi
        _fp=$(jq -r '."tls-fingerprint" // empty' <<<"$_pool")
        if [ -n "$_fp" ]; then
            if ! [[ "$_fp" =~ ^[0-9A-Fa-f]{64}$ ]]; then
                error "Pool tls-fingerprint must be the cert's SHA-256 as 64 hex chars (no colons). Get it with: echo | openssl s_client -connect $_u 2>/dev/null | openssl x509 -noout -fingerprint -sha256 | cut -d= -f2 | tr -d ':'"
            fi
            if [ "$(jq -r '.tls' <<<"$_pool")" != "true" ]; then
                error "Pool '$_u' sets tls-fingerprint but not \"tls\": true — the pin only applies to a TLS connection; set both or remove the fingerprint."
            fi
        fi
        for _f in keepalive tls enabled; do
            _bv=$(jq -r --arg f "$_f" '.[$f]' <<<"$_pool")
            case "$_bv" in true | false) ;; *) error "Pool $_f must be true or false (got: $_bv)." ;; esac
        done
    done < <(jq -c '.[]' <<<"$POOLS_JSON")

    # HTTP API token (OPTIONAL). By default the rig's read-only xmrig API is left OPEN — no token,
    # matching Pithead's stock no-auth probe of GET http://<rig>:8080/1/summary. Set ACCESS_TOKEN to
    # require a Bearer token instead and match it dashboard-side; see docs/pithead-integration.md.
    ACCESS_TOKEN=$(jq -r '.ACCESS_TOKEN // empty' "$CONFIG_JSON")

    # Opt-in firewall scoping (#142): restrict the read-only API port(s) to one source + loopback.
    # Empty (default) = RigForge manages no firewall. Accepts IPv4 or IPv6 address/CIDR (#243): the
    # strict per-family charset is the injection guard (the value reaches an nft file), and
    # API_ALLOW_FAMILY (ip|ip6) picks the nft match keyword.
    API_ALLOW_FROM=$(jq -r '.api_allow_from // empty' "$CONFIG_JSON")
    API_ALLOW_FAMILY=ip
    if [ -n "$API_ALLOW_FROM" ]; then
        if [[ "$API_ALLOW_FROM" =~ ^([0-9]{1,3}\.){3}[0-9]{1,3}(/[0-9]{1,2})?$ ]]; then
            local _a _b _c _d _p
            IFS='./' read -r _a _b _c _d _p <<<"$API_ALLOW_FROM"
            if [ "$_a" -gt 255 ] || [ "$_b" -gt 255 ] || [ "$_c" -gt 255 ] || [ "$_d" -gt 255 ] || [ "${_p:-0}" -gt 32 ]; then
                error "api_allow_from must be a valid IPv4/IPv6 address or CIDR (e.g. 192.168.1.0/24 or fd00::/64); got: '$API_ALLOW_FROM'."
            fi
            API_ALLOW_FAMILY=ip
        elif [[ "$API_ALLOW_FROM" =~ ^[0-9A-Fa-f:]+(/[0-9]{1,3})?$ ]] && [[ "$API_ALLOW_FROM" == *:*:* ]]; then
            # IPv6/CIDR: hex-and-colons charset (the injection guard) + >=2 colons + a 0-128 prefix.
            # nft rejects a truly malformed address at load, so this is the guard, not a full RFC
            # validator — same posture as the IPv4 octet check above.
            local _pfx=""
            case "$API_ALLOW_FROM" in */*) _pfx="${API_ALLOW_FROM##*/}" ;; esac
            if [ -n "$_pfx" ] && ! _uint_in_range "$_pfx" 0 128; then
                error "api_allow_from IPv6 prefix must be 0-128 (got: '$API_ALLOW_FROM')."
            fi
            API_ALLOW_FAMILY=ip6
        else
            error "api_allow_from must be an IPv4/IPv6 address or CIDR (e.g. 192.168.1.0/24 or fd00::/64); got: '$API_ALLOW_FROM'."
        fi
    fi
    # When set, the token is sent as an HTTP Authorization header, so keep it to safe, header-clean
    # characters. Empty is allowed and means "open API" (the default).
    if [ -n "$ACCESS_TOKEN" ] && ! [[ "$ACCESS_TOKEN" =~ ^[A-Za-z0-9._:@+-]+$ ]]; then
        error "ACCESS_TOKEN has invalid characters (allowed: letters, digits, . _ - : @ +): '$ACCESS_TOKEN'."
    fi

    # ACCESS_TOKENS (#516): an OPTIONAL name -> token map, one per consuming Pithead stack, so a bench
    # borrow never needs prod's ACCESS_TOKEN. Every entry authenticates :8081/:8082 like it does; only xmrig's :8080 stays master-only.
    ACCESS_TOKENS_JSON=$(jq -c '.ACCESS_TOKENS // {}' "$CONFIG_JSON" 2>/dev/null)
    jq -e 'type == "object" and all(.[]; type == "string")' <<<"$ACCESS_TOKENS_JSON" >/dev/null 2>&1 || error "ACCESS_TOKENS in $CONFIG_JSON must be a JSON object mapping names to string tokens."
    while IFS=$'\t' read -r _atn _att; do
        [[ "$_att" =~ ^[A-Za-z0-9._:@+-]+$ ]] || error "ACCESS_TOKENS.\"$_atn\" has invalid characters (allowed: letters, digits, . _ - : @ +): '$_att'."
    done < <(jq -r 'to_entries[] | [.key, .value] | @tsv' <<<"$ACCESS_TOKENS_JSON")

    # Opt-in periodic live auto-tuning (#46, #95): tri-state. "disabled" (default) installs no timer;
    # "performance" schedules a periodic tune for raw H/s; "efficiency" schedules one for hashrate-per-watt.
    # Legacy booleans still parse (true -> performance, false -> disabled); a typo hard-errors rather than
    # silently disabling tuning. AUTOTUNE_TARGET (perf|efficiency) is what autotune() and the unit consume.
    _at=$(jq -r '.autotune // "disabled"' "$CONFIG_JSON")
    case "$_at" in
    disabled | false | off | none | null | "") AUTOTUNE_MODE=disabled ;;
    performance | perf | true | on) AUTOTUNE_MODE=performance ;;
    efficiency | eff) AUTOTUNE_MODE=efficiency ;;
    *) error "Invalid \"autotune\" value '$_at' in config.json — use \"disabled\", \"performance\", or \"efficiency\"." ;;
    esac
    case "$AUTOTUNE_MODE" in efficiency) AUTOTUNE_TARGET=efficiency ;; *) AUTOTUNE_TARGET=perf ;; esac

    # Opt-in miner watchdog (#139): a periodic health check (same timer machinery as autotune) that
    # restarts a WEDGED miner — process alive, 0 H/s or API dead, the case systemd's Restart= can't
    # see — and, when max_temp_c is set, stops the miner above that temperature (restarting 5°C
    # below). A typo hard-errors: a recovery mechanism must not be silently disabled.
    _wd=$(jq -r '.watchdog // "disabled"' "$CONFIG_JSON")
    case "$_wd" in
    disabled | false | off | none | null | "") WATCHDOG_MODE=disabled ;;
    enabled | true | on) WATCHDOG_MODE=enabled ;;
    *) error "Invalid \"watchdog\" value '$_wd' in config.json — use \"disabled\" or \"enabled\"." ;;
    esac
    WATCHDOG_INTERVAL_MIN=$(jq -r '.watchdog_interval_min // 5' "$CONFIG_JSON")
    if ! _uint_in_range "$WATCHDOG_INTERVAL_MIN" 1 1440; then
        error "watchdog_interval_min must be a whole number of minutes, 1-1440 (got: $WATCHDOG_INTERVAL_MIN)."
    fi
    # Empty (the default) = no thermal cutoff. Opt-in because thermal_zone0's meaning varies by
    # board — a wrong cutoff on an unchecked sensor is worse than none. 40-110: below 40 a loaded
    # rig would never restart, above 110 is past any CPU's limit.
    MAX_TEMP_C=$(jq -r '.max_temp_c // empty' "$CONFIG_JSON")
    if [ -n "$MAX_TEMP_C" ]; then
        if ! _uint_in_range "$MAX_TEMP_C" 40 110; then
            error "max_temp_c must be empty (no thermal cutoff) or a whole number 40-110 °C (got: $MAX_TEMP_C)."
        fi
    fi

    # Co-resident reservation headroom (#305): MB of HugePages to leave for another workload on the box
    # (a co-located pithead stack), ADDED to RigForge's computed mining need when it sizes the GRUB
    # reservation and the runtime pool. RigForge stays the sole writer of the reservation; the caller
    # just declares "leave this much for the rest of the box." Default 0 (miner-only sizing). The upper
    # bound is generous (64 GB of 2MB pages) — this is a deliberate reservation, not a typo guard.
    HUGEPAGES_RESERVE_EXTRA_MB=$(jq -r '.hugepages_reserve_extra_mb // 0' "$CONFIG_JSON")
    if ! _uint_in_range "$HUGEPAGES_RESERVE_EXTRA_MB" 0 65536; then
        error "hugepages_reserve_extra_mb must be a whole number of MB, 0-65536 (got: $HUGEPAGES_RESERVE_EXTRA_MB)."
    fi
    # Total-pool ceiling (#398): a HARD CAP on the runtime pool RigForge will grow to, expressed in MB —
    # unlike hugepages_reserve_extra_mb (which ADDS declared headroom into the computed requirement),
    # this bounds the WRITE itself. It exists because no value of hugepages_reserve_extra_mb can fix a
    # double-count between that requirement and the grow-only write's availability check (rigforge#398):
    # a co-resident consumer's already-held pages land inside the requirement (as declared headroom) and
    # are simultaneously excluded from "available," so the shortfall the grow-only write computes counts
    # the same pages twice. A ceiling stops the WRITE from ever exceeding the box's declared honest
    # capacity, regardless of how that upstream arithmetic comes out. Default 0 = no ceiling (today's
    # behavior, unchanged) — only a caller that declares this key opts into the cap. An odd MB value
    # FLOORS to the 2MB page below (e.g. 5121 -> 2560 pages, 5120MB effective) — a cap must round
    # toward less memory, never more.
    HUGEPAGES_POOL_CEILING_MB=$(jq -r '.hugepages_pool_ceiling_mb // 0' "$CONFIG_JSON")
    if ! _uint_in_range "$HUGEPAGES_POOL_CEILING_MB" 0 65536; then
        error "hugepages_pool_ceiling_mb must be a whole number of MB, 0-65536 (got: $HUGEPAGES_POOL_CEILING_MB)."
    fi
    # First-class thread cap (#305): a CEILING on the RandomX thread count — min(auto-detected, threads).
    # Empty (default) = let XMRig/L3 sizing pick. A co-located miner sets this (e.g. nproc-2) to leave
    # the stack cores free. Sizing and the generated cpu.rx both honour it; it never raises the count.
    THREADS_CAP=$(jq -r '.threads // empty' "$CONFIG_JSON")
    if [ -n "$THREADS_CAP" ]; then
        if ! _uint_in_range "$THREADS_CAP" 1 1024; then
            error "threads must be empty (auto) or a whole number 1-1024 (got: $THREADS_CAP)."
        fi
    fi

    # Opt-in: install a `rigforge` command on PATH (a symlink in BIN_DIR). Off by default — setup makes
    # no system-wide convenience change you didn't ask for.
    ADD_TO_PATH=$(jq -r '.add_to_path // false' "$CONFIG_JSON")

    # Opt-in read-only sister API (#99): serves XMRig's /2/summary enriched with RigForge state
    # (tune/power/health/provenance) on its own port. Same posture as :8080 — read-only, LAN-bound,
    # gated by ACCESS_TOKEN or any named ACCESS_TOKENS entry (#516).
    _api=$(jq -r '.api // "disabled"' "$CONFIG_JSON")
    case "$_api" in
    disabled | false | off | none | null | "") API_MODE=disabled ;;
    enabled | true | on) API_MODE=enabled ;;
    *) error "Invalid \"api\" value '$_api' in config.json — use \"disabled\" or \"enabled\"." ;;
    esac
    API_PORT=$(jq -r '.api_port // 8081' "$CONFIG_JSON")
    if ! _uint_in_range "$API_PORT" 1 65535; then error "api_port must be a port number 1-65535 (got: $API_PORT)."; fi
    if [ "$API_PORT" = 8080 ]; then error "api_port 8080 collides with XMRig's own API — pick another port."; fi
    API_BIND=$(jq -r '.api_bind // "0.0.0.0"' "$CONFIG_JSON")
    [[ "$API_BIND" =~ ^[0-9A-Fa-f.:]+$ ]] || error "api_bind must be an IP address (got: $API_BIND)."

    # Opt-in WRITABLE control path (#236): a SEPARATE authenticated endpoint that lets the stack
    # apply config changes THROUGH RigForge (see docs/adr/0001), authenticated by ACCESS_TOKEN or any ACCESS_TOKENS entry (#516).
    _control=$(jq -r '.control // "disabled"' "$CONFIG_JSON")
    case "$_control" in
    disabled | false | off | none | null | "") CONTROL_MODE=disabled ;;
    enabled | true | on) CONTROL_MODE=enabled API_MODE=enabled ;; # #507: control implies api (unobservable without the read feed) — never the reverse, and api stays out of CONTROL_WRITABLE_KEYS below so it's never remote-settable
    *) error "Invalid \"control\" value '$_control' in config.json — use \"disabled\" or \"enabled\"." ;;
    esac
    CONTROL_PORT=$(jq -r '.control_port // 8082' "$CONFIG_JSON")
    if ! _uint_in_range "$CONTROL_PORT" 1 65535; then error "control_port must be a port number 1-65535 (got: $CONTROL_PORT)."; fi
    if [ "$CONTROL_PORT" = 8080 ]; then error "control_port 8080 collides with XMRig's own API — pick another port."; fi
    CONTROL_BIND=$(jq -r '.control_bind // "0.0.0.0"' "$CONFIG_JSON")
    [[ "$CONTROL_BIND" =~ ^[0-9A-Fa-f.:]+$ ]] || error "control_bind must be an IP address (got: $CONTROL_BIND)."
    if [ "$CONTROL_MODE" = enabled ]; then
        if [ "${API_MODE:-disabled}" = enabled ] && [ "$CONTROL_PORT" = "$API_PORT" ]; then
            error "control_port ($CONTROL_PORT) collides with the sister API port — pick another port."
        fi
        # Fail-closed dual auth: the writable path demands BOTH a Bearer token AND a pinned source —
        # missing either would expose an unauthenticated remote config write.
        [ -n "${ACCESS_TOKEN:-}" ] || error "control: \"enabled\" requires ACCESS_TOKEN — a writable API with no token is an open remote config write. Set ACCESS_TOKEN in config.json."
        [ -n "${API_ALLOW_FROM:-}" ] || error "control: \"enabled\" requires api_allow_from — the writable path must be pinned to the stack host. Set api_allow_from in config.json."
    fi

    # Opt-in REMOTE UPGRADE (#308, ADR 0002): a SECOND switch, layered on control:"enabled", that lets
    # the stack trigger a rig to upgrade its own RigForge to the latest release. Default off, and it
    # does NOT come up just because `control` is on. Rides the control channel's own auth, no auth of its own.
    _cu=$(jq -r '.control_upgrade // "disabled"' "$CONFIG_JSON")
    case "$_cu" in
    disabled | false | off | none | null | "") CONTROL_UPGRADE=disabled ;;
    enabled | true | on) CONTROL_UPGRADE=enabled ;;
    *) error "Invalid \"control_upgrade\" value '$_cu' in config.json — use \"disabled\" or \"enabled\"." ;;
    esac
    if [ "$CONTROL_UPGRADE" = enabled ] && [ "${CONTROL_MODE:-disabled}" != enabled ]; then
        error "control_upgrade requires control: \"enabled\" first — the remote-upgrade path rides the control channel's Bearer token and api_allow_from source pin (ADR 0002)."
    fi
    # #243/scan: an IPv6 api_allow_from only scopes traffic the APIs actually receive over IPv6, but
    # api_bind/control_bind default to IPv4 (0.0.0.0). Warn on the silent no-op — it fails safe (no
    # reachable v6 to scope), but the operator's intent isn't met until they bind "::".
    if [ "${API_ALLOW_FAMILY:-ip}" = ip6 ] && [[ "$API_BIND" != *:* ]] && [[ "$CONTROL_BIND" != *:* ]]; then
        warn "api_allow_from is IPv6 but api_bind/control_bind are IPv4 (0.0.0.0) — the APIs aren't reachable over IPv6, so the v6 scope takes no effect. Set api_bind/control_bind to \"::\" to serve + scope IPv6."
    fi

    # Privilege separation (#140): run the miner as this dedicated non-root system user. Empty
    # (default) keeps today's root behavior exactly. `root` is rejected — it would silently mean
    # "no separation". useradd-portable names only.
    MINER_USER=$(jq -r '.miner_user // empty' "$CONFIG_JSON")
    if [ -n "$MINER_USER" ]; then
        if [ "$MINER_USER" = "root" ]; then
            error "miner_user must be a non-root system username (empty = run as root, the default)."
        fi
        [[ "$MINER_USER" =~ ^[a-z_][a-z0-9_-]{0,31}$ ]] || error "miner_user '$MINER_USER' is not a valid system username (lowercase, digits, _ -; max 32 chars)."
    fi

    _warn_unknown_config_keys
}

# Typo lint (#138): a key parse_config doesn't read is silently ignored — worst case a security key
# ("ACESS_TOKEN") that the operator believes is protecting them. Warn (never error: an unknown key
# is at worst a no-op, and erroring would brick fleet applies on any future rename), name each
# unknown key with a case-insensitive did-you-mean, and point at the reference. Keys starting with
# `_` are the comment convention (config.reference.json's own _docs); RIG_NAME is reserved for the
# #1 image seed. Warn NAMES only, never values — a fat-fingered token must not land in a log.
_warn_unknown_config_keys() {
    local known="pools ACCESS_TOKEN ACCESS_TOKENS DONATION autotune add_to_path HOME_DIR api api_port api_bind api_allow_from miner_user RIG_NAME watchdog watchdog_interval_min max_temp_c control control_port control_bind control_upgrade hugepages_reserve_extra_mb hugepages_pool_ceiling_mb threads"
    local known_pool="url user pass keepalive tls enabled tls-fingerprint socks5"
    local k lk m lm hit hint unknown_seen=0
    while IFS= read -r k; do
        case "$k" in _*) continue ;; esac
        hit=""
        hint=""
        lk=$(printf '%s' "$k" | tr '[:upper:]' '[:lower:]')
        for m in $known; do
            if [ "$k" = "$m" ]; then
                hit=1
                break
            fi
            lm=$(printf '%s' "$m" | tr '[:upper:]' '[:lower:]')
            if [ "$lk" = "$lm" ]; then hint="$m"; fi
        done
        if [ -n "$hit" ]; then continue; fi
        if [ -n "$hint" ]; then warn "config.json: unknown key \"$k\" is ignored — did you mean \"$hint\"?"; else warn "config.json: unknown key \"$k\" is ignored."; fi
        unknown_seen=1
    done < <(jq -r 'keys[]' "$CONFIG_JSON" 2>/dev/null || true)
    while IFS= read -r k; do
        case "$k" in _*) continue ;; esac
        hit=""
        hint=""
        lk=$(printf '%s' "$k" | tr '[:upper:]' '[:lower:]')
        for m in $known_pool; do
            if [ "$k" = "$m" ]; then
                hit=1
                break
            fi
            lm=$(printf '%s' "$m" | tr '[:upper:]' '[:lower:]')
            if [ "$lk" = "$lm" ]; then hint="$m"; fi
        done
        if [ -n "$hit" ]; then continue; fi
        if [ -n "$hint" ]; then warn "config.json: unknown pool field \"$k\" is ignored — did you mean \"$hint\"?"; else warn "config.json: unknown pool field \"$k\" is ignored."; fi
        unknown_seen=1
    done < <(jq -r '(.pools // []) | map(keys[]) | unique | .[]' "$CONFIG_JSON" 2>/dev/null || true)
    if [ "$unknown_seen" = 1 ]; then warn "See config.reference.json for every supported key."; fi
}

# --- Setup: workspace & dependency install ---

prepare_workspace() {
    log "Preparing workspace at $WORKER_ROOT..."

    if [ ! -d "$WORKER_ROOT" ]; then
        mkdir -p "$WORKER_ROOT" 2>/dev/null || sudo mkdir -p "$WORKER_ROOT"
    fi

    # Fix permissions to ensure the current user can write
    if [ "${EUID:-$(id -u)}" -eq 0 ] || [ ! -w "$WORKER_ROOT" ]; then
        if [ "$OS_TYPE" == "Darwin" ]; then
            sudo chown -R "$REAL_USER" "$WORKER_ROOT"
        else
            sudo chown -R "$REAL_USER":"$REAL_USER" "$WORKER_ROOT"
        fi
    fi

    cd "$WORKER_ROOT"

    GIT_DIR="xmrig"
    TIMESTAMP=$(date +%Y%m%d_%H%M%S)

    # Archive the existing installation only when we're about to rebuild (a no-op re-run keeps it).
    if [ "$XMRIG_REBUILD" = true ] && [ -d "$GIT_DIR" ]; then
        log "Archiving existing worker installation..."
        mv "$GIT_DIR" "${GIT_DIR}-${TIMESTAMP}"
    fi

    # Prune old build archives so re-runs don't grow the disk without bound (keep the most recent
    # few). Override the retention count with KEEP_ARCHIVES. The `|| true` keeps an empty glob (no
    # archives yet) from tripping `set -e`/`pipefail`.
    local keep="${KEEP_ARCHIVES:-3}" archives
    # shellcheck disable=SC2012  # archive names are controlled (xmrig-YYYYmmdd_HHMMSS); ls -t orders by recency
    archives="$(ls -dt "${GIT_DIR}-"* 2>/dev/null || true)"
    if [ -n "$archives" ]; then
        printf '%s\n' "$archives" | tail -n +"$((keep + 1))" | while IFS= read -r old; do
            [ -n "$old" ] || continue
            log "Pruning old build archive: $(basename "$old")"
            rm -rf "$old" 2>/dev/null || sudo rm -rf "$old"
        done
    fi
}

# Package-manager detection (read-only) — sets DEP_LIST / DEP_CHECK / DEP_INSTALL, rc 1 when no
# manager is found. Split from install_dependencies so the setup --dry-run plan (#146) reuses the
# EXACT list and check — never a second copy to drift.
_detect_pkg_manager() {
    DEP_LIST=""
    DEP_CHECK=""
    DEP_INSTALL=""
    if command -v apt-get &>/dev/null; then
        DEP_LIST="git build-essential cmake libuv1-dev libssl-dev libhwloc-dev gettext-base python3"
        if [ "$OS_TYPE" == "Linux" ]; then
            # msr-tools (rdmsr): lets `doctor` verify the prefetcher MSR mod actually applied (#66).
            DEP_LIST="$DEP_LIST msr-tools"
            # cpupower's package name differs by distro: linux-tools-common on Ubuntu,
            # linux-cpupower on Debian. apt's install transaction is all-or-nothing, so one unknown
            # name would fail the ENTIRE dependency install — gcc/cmake included (#327). Probe with
            # apt-cache show (same guard as the kernel-versioned package below) and add only the
            # name this distro actually ships; when neither exists, warn and carry on — cpupower is
            # a tuning aid, never worth losing the compiler toolchain over.
            if apt-cache show linux-tools-common &>/dev/null; then
                DEP_LIST="$DEP_LIST linux-tools-common"
            elif apt-cache show linux-cpupower &>/dev/null; then
                DEP_LIST="$DEP_LIST linux-cpupower"
            else
                warn "No cpupower package found (tried linux-tools-common, linux-cpupower) — skipping it. Frequency tuning via cpupower may be unavailable."
            fi
            if apt-cache show "linux-tools-$(uname -r)" &>/dev/null; then
                DEP_LIST="$DEP_LIST linux-tools-$(uname -r)"
            fi
        fi
        # DPkg::Lock::Timeout waits for the apt/dpkg lock instead of failing — fresh boots often have
        # unattended-upgrades holding it for a minute or two (#74).
        DEP_INSTALL="sudo apt-get update -qq -o DPkg::Lock::Timeout=300 && sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq -o DPkg::Lock::Timeout=300 -o Dpkg::Options::='--force-confdef' -o Dpkg::Options::='--force-confold'"
        DEP_CHECK="dpkg -s"
    elif command -v dnf &>/dev/null; then
        DEP_LIST="git cmake libuv-devel openssl-devel hwloc-devel gettext gcc gcc-c++ make automake kernel-devel msr-tools"
        DEP_INSTALL="sudo dnf install -y"
        DEP_CHECK="rpm -q"
    elif command -v pacman &>/dev/null; then
        DEP_LIST="git cmake libuv openssl hwloc gettext base-devel"
        DEP_INSTALL="sudo pacman -Sy --noconfirm --needed"
        DEP_CHECK="pacman -Qi"
    else
        return 1
    fi
}

# Echo the packages from DEP_LIST that aren't installed (read-only, no root). $DEP_LIST are PACKAGE
# names (build-essential, libuv1-dev — most have no same-named binary), so the package manager is
# the authority for "is it installed", not `command -v` (which would both miss header-only -dev
# packages and let an unrelated PATH binary mask a genuinely-absent package).
_missing_deps() {
    local dep missing=""
    for dep in $DEP_LIST; do
        if ! $DEP_CHECK "$dep" &>/dev/null; then
            missing="$missing $dep"
        fi
    done
    printf '%s' "$missing"
}

# Appliance-mode tool check (pithead#797 R1), shared with the setup --dry-run plan (#146 — never a
# second copy to drift). Echoes the tools setup would actually invoke that are absent. `command -v`,
# not the package manager: on the appliance, dpkg/alternatives state rides the volatile /etc overlay
# and can be stale while the tools in /usr are fine (observed on the R0 bench after a reboot).
# envsubst renders the unit on every run; the compiler chain only matters when a build is pending —
# the R0 bench restored mining from a cached build with a half-broken toolchain, and the every-boot
# re-run must keep doing that.
_missing_appliance_tools() {
    local t missing="" tools="envsubst"
    [ "$XMRIG_REBUILD" = true ] && tools="git cmake make cc envsubst"
    for t in $tools; do
        command -v "$t" >/dev/null 2>&1 || missing="$missing $t"
    done
    printf '%s' "$missing"
}

install_dependencies() {
    # Appliance mode: the toolchain is baked into the image at build — apt cannot run on the
    # read-only root, and even a rw-remounted install leaves its /etc state on the volatile overlay
    # (pithead#797 R0 item 1). So never install here: verify and fail naming the missing tools —
    # that's an image build bug, not something a rig can fix at runtime.
    if [ "$RIGFORGE_APPLIANCE" = 1 ]; then
        local _missing
        _missing="$(_missing_appliance_tools)"
        if [ -n "$_missing" ]; then
            error "Appliance mode: required tool(s) missing from the image:$_missing. The toolchain must be baked at image build — package install cannot run on the read-only root."
        fi
        log "Appliance mode: dependencies are baked into the image — skipping package install."
        return 0
    fi
    if [ "$OS_TYPE" == "Darwin" ]; then
        log "Installing macOS dependencies..."
        if command -v brew &>/dev/null; then
            if [ "${EUID:-$(id -u)}" -eq 0 ]; then
                # Drop privileges for Homebrew if running as root
                sudo -u "$REAL_USER" brew install cmake libuv openssl hwloc
            else
                brew install cmake libuv openssl hwloc
            fi
        else
            error "Homebrew not found."
        fi
    else
        if ! _detect_pkg_manager; then
            warn "No supported package manager found. Please install dependencies manually."
            return
        fi
        local missing_deps
        missing_deps="$(_missing_deps)"

        if [ -n "$missing_deps" ]; then
            # `setup` is an automated provisioner (often run headless / over the release e2e), so install
            # the build dependencies non-interactively rather than prompting — an interactive `read` here
            # hit EOF and aborted the whole run under `set -e` on a non-tty stdin (#74).
            log "Installing required system dependencies:"
            echo -e "  ${C_YELLOW}$missing_deps${C_RESET}"
            eval "$DEP_INSTALL $missing_deps"
        else
            log "All system dependencies are already installed."
        fi
    fi
}

# --- Setup: build XMRig from source ---

compile_xmrig() {
    if [ "$XMRIG_REBUILD" != true ]; then
        log "XMRig $XMRIG_VERSION (commit ${XMRIG_COMMIT:0:12}) already built — skipping clone/compile."
        cd "$WORKER_ROOT/xmrig/build"
        return 0
    fi
    log "Cloning and patching XMRig source code ($XMRIG_VERSION)..."
    rm -rf xmrig
    git clone --quiet --branch "$XMRIG_VERSION" --depth 1 https://github.com/xmrig/xmrig.git

    local actual
    actual="$(git -C xmrig rev-parse HEAD)"
    [ "$actual" = "$XMRIG_COMMIT" ] || {
        rm -rf xmrig
        error "XMRig commit mismatch: expected $XMRIG_COMMIT, got $actual"
    }
    log "Verified XMRig $XMRIG_VERSION at commit $XMRIG_COMMIT"

    BUILD_LOG="$WORKER_ROOT/build.log"
    : >"$BUILD_LOG" 2>/dev/null || true

    sed "s/kDefaultDonateLevel = 1;/kDefaultDonateLevel = $DONATION;/; s/kMinimumDonateLevel = 1;/kMinimumDonateLevel = 0;/" xmrig/src/donate.h >xmrig/src/donate.h.new
    mv xmrig/src/donate.h.new xmrig/src/donate.h
    grep -Fxq "constexpr const int kDefaultDonateLevel = $DONATION;" xmrig/src/donate.h &&
        grep -Fxq 'constexpr const int kMinimumDonateLevel = 0;' xmrig/src/donate.h || error "XMRig donation patch verification failed; refusing to build."
    local cores jobs
    if [ "$OS_TYPE" == "Darwin" ]; then
        cores=$(sysctl -n hw.ncpu)
        jobs=$(compute_build_jobs "$cores")
        log "Compiling binary ($jobs of $cores cores; output -> $BUILD_LOG)..."
        mkdir -p xmrig/build && cd xmrig/build
        cmake .. -DWITH_HWLOC=ON -DOPENSSL_ROOT_DIR="$(brew --prefix openssl)" >>"$BUILD_LOG" 2>&1
    else
        cores=$(nproc)
        jobs=$(compute_build_jobs "$cores")
        log "Compiling binary ($jobs of $cores cores; output -> $BUILD_LOG)..."
        mkdir -p xmrig/build && cd xmrig/build
        cmake .. -DWITH_HWLOC=ON >>"$BUILD_LOG" 2>&1
    fi

    make -j"$jobs" >>"$BUILD_LOG" 2>&1

    echo "$XMRIG_COMMIT" >"$WORKER_ROOT/xmrig/.rigforge-commit"
    printf '0\n' >"$WORKER_ROOT/xmrig/.rigforge-donate-min"
    if [ -f "$WORKER_ROOT/xmrig/build/xmrig" ]; then
        _sha256 "$WORKER_ROOT/xmrig/build/xmrig" >"$WORKER_ROOT/xmrig/.rigforge-sha256"
    fi
}

# --- Setup: XMRig config generation (CPU / NUMA / MSR layout) ---

generate_xmrig_config() {
    log "Generating hardware-optimized XMRig configuration..."

    # Identify CPU Topology
    if [ "$OS_TYPE" == "Darwin" ]; then
        CPU_MODEL=$(sysctl -n machdep.cpu.brand_string)
    else
        # Anchor to "^Model name:" — as root, lscpu also prints a "BIOS Model name:" line (a DMI string
        # like "...  Unknown CPU @ 4.2GHz"), and an unanchored grep would concatenate both into one line.
        CPU_MODEL=$(lscpu | grep -E '^Model name:' | cut -d':' -f2 | xargs)
    fi
    LOG_FILE_PATH=""
    if [ "$RIGFORGE_APPLIANCE" = 1 ]; then
        sudo rm -f "$WORKER_ROOT/xmrig.log"
    else
        LOG_FILE_PATH="$WORKER_ROOT/xmrig.log"
    fi

    # Default optimization profile.
    #
    # We deliberately lean on XMRig's own auto-detection rather than matching CPU model names: with
    # asm=auto, rx=-1 (auto thread count, sized to L3) and wrmsr=true, XMRig picks the right assembly
    # path, thread layout and per-family MSR preset from the detected topology — and stays correct for
    # CPUs we'd never enumerate (new Zen/X3D SKUs, Intel hybrid P/E cores, etc.). See issue #44.
    #
    # On top of auto-detection we set defaults appropriate for a DEDICATED miner (issue #43):
    #   - yield=false  : busy-wait for maximum hashrate (we own the whole box)
    #   - priority=2   : win scheduling vs. background daemons (XMRig warns >2 can hang a desktop)
    #   - numa=true    : XMRig default; a no-op on single-socket, essential on multi-socket/EPYC
    #   - init-avx2=-1 : auto — already uses AVX2 for dataset init when the CPU supports it
    YIELD="false"
    PRIORITY="2"
    ASM="\"auto\""
    THREADS="-1"
    NUMA="true"
    PREFETCH=1
    WRMSR="true"
    RDMSR="true"
    HUGE_PAGES="true"
    MEMORY_POOL="true"
    ONE_GB_PAGES="true"
    # cpu.huge-pages-jit: false, matching XMRig's upstream default. XMRig documents it as only a "very
    # small boost on Ryzen, but hashrate is unstable" — not worth the jitter on a production rig (and it
    # would add noise to the `tune` search). $JIT maps to cpu.huge-pages-jit in the config below.
    JIT="false"
    INIT_AVX2="-1"
    # Lock down the HTTP API to READ-ONLY (restricted) so it can't be used to *control* the miner
    # remotely. Keep it bound to all interfaces, NOT localhost: Pithead reads per-rig stats from the
    # stack host via GET http://<rig>:8080/1/summary (read-only; OPEN by default — see ACCESS_TOKEN
    # above). Binding localhost would break that integration — see issue #24. Workers are expected to
    # live on a trusted LAN, which is why a read-only API with no token is a safe default there.
    HTTP_RESTRICTED="true"
    HTTP_HOST="0.0.0.0"

    # Privilege separation (#140): an unprivileged miner cannot write /dev/cpu/*/msr — RigForge
    # applies the MSR preset root-side (msr-apply, ExecStartPre) and xmrig must not try itself.
    if [ -n "${MINER_USER:-}" ]; then
        WRMSR="false"
        RDMSR="false"
    fi

    # macOS Specific Overrides (only the values that differ from the shared defaults above)
    if [ "$OS_TYPE" == "Darwin" ]; then
        ASM="true"
        WRMSR="false"
        RDMSR="false"
        HUGE_PAGES="false"
        MEMORY_POOL="false"
        ONE_GB_PAGES="false"
        HTTP_HOST="::"

        # Generate rx array [-1, -1, ...] based on core count
        CORES=$(sysctl -n hw.ncpu)
        THREADS="["
        for ((i = 0; i < CORES; i++)); do
            THREADS="${THREADS}-1"
            if [ "$i" -lt $((CORES - 1)) ]; then THREADS="${THREADS},"; fi
        done
        THREADS="${THREADS}]"
    fi

    # NOTE: we no longer special-case CPUs by model name (the old EPYC / Ryzen-X3D branches). XMRig's
    # auto-config is cache-aware and updated every release, so it sizes threads and picks asm/MSR/NUMA
    # better — and correctly — for any CPU, including ones a name table would miss or get wrong (the
    # old X3D branch pinned threads to ALL cores, which is wrong on dual-CCD parts like the 7950X3D
    # where only one CCD has the V-cache). See issue #44.
    if [ "$OS_TYPE" != "Darwin" ]; then
        log "Detected CPU: ${CPU_MODEL:-unknown} — using XMRig auto-tuning (threads, asm, MSR, NUMA auto-detected)."
        # ISA preflight (#338): surface missing AES-NI/AVX2 here, at the moment the rig is being
        # configured, instead of letting unsupported hardware mine silently slow. Warn, never abort:
        # XMRig still runs (soft AES / non-AVX2 init) and a knowingly-old rig is a valid choice.
        local _missing_isa
        _missing_isa=$(_cpu_missing_isa)
        [[ " $_missing_isa " == *" aes "* ]] && warn "This CPU has no AES-NI: RandomX falls back to soft AES, roughly 4x slower. Mining will work, but expect a fraction of a modern CPU's rate."
        [[ " $_missing_isa " == *" avx2 "* ]] && warn "This CPU has no AVX2: dataset init will be slower (steady-state hashrate is unaffected)."
    fi

    # Rig label for the pool `user` field (#22): any pool entry that didn't set its own `user` gets the
    # machine hostname, so the worker shows up named on the dashboard.
    FULL_USER="$(hostname)"

    # Build the whole XMRig config from scratch (issue #55). There's no template file to keep in sync:
    # the tuned parts (pools, donate-level, the http block, the cpu/randomx sections) come from the
    # variables above, and the few static defaults (autosave, randomx mode, opencl/cuda off) are
    # emitted inline. `jq -n` builds the object from null input; any tuned overrides are merged below.
    jq -n --argjson pools "$POOLS_JSON" \
        --arg user "$FULL_USER" \
        --arg access_token "$ACCESS_TOKEN" \
        --arg log "$LOG_FILE_PATH" \
        --argjson yield "$YIELD" \
        --argjson prio "$PRIORITY" \
        --argjson numa "$NUMA" \
        --argjson asm "$ASM" \
        --argjson rx "$THREADS" \
        --argjson prefetch "$PREFETCH" \
        --argjson jit "$JIT" \
        --argjson wrmsr "$WRMSR" \
        --argjson rdmsr "$RDMSR" \
        --argjson huge_pages "$HUGE_PAGES" \
        --argjson memory_pool "$MEMORY_POOL" \
        --argjson one_gb_pages "$ONE_GB_PAGES" \
        --argjson avx2 "$INIT_AVX2" \
        --argjson restricted "$HTTP_RESTRICTED" \
        --argjson donation "$DONATION" \
        --arg host "$HTTP_HOST" \
        '{
            autosave: true,
            cpu: {
                enabled: true,
                "huge-pages": $huge_pages,
                "huge-pages-jit": $jit,
                "memory-pool": $memory_pool,
                yield: $yield,
                priority: $prio,
                asm: $asm,
                rx: $rx
            },
            randomx: {
                init: -1,
                mode: "fast",
                "1gb-pages": $one_gb_pages,
                rdmsr: $rdmsr,
                wrmsr: $wrmsr,
                cache_qos: false,
                numa: $numa,
                scratchpad_prefetch_mode: $prefetch,
                "init-avx2": $avx2
            },
            pools: ($pools | map(.user = (if (.user // "") == "" then $user else .user end))),
            "donate-level": $donation,
            "donate-over-proxy": $donation,
            http: {
                enabled: true,
                host: $host,
                port: 8080,
                "access-token": (if $access_token == "" then null else $access_token end),
                restricted: $restricted
            },
            opencl: false,
            cuda: false
        } + (if $log == "" then {} else {"log-file": $log} end)' >config.json

    # Overlay any tuned knobs (#46) on top — kept in a separate file (written by `tune`) so the user's
    # config.json is never touched. A recursive merge lets tuning win for just the keys it sets.
    if [ -f "$WORKER_ROOT/tune-overrides.json" ]; then
        local _ovr
        _ovr=$(mktemp)
        if jq -s '.[0] * .[1]' config.json "$WORKER_ROOT/tune-overrides.json" >"$_ovr" 2>/dev/null; then
            mv "$_ovr" config.json
            log "Applied tuned overrides from tune-overrides.json."
        else
            rm -f "$_ovr"
        fi
    fi

    # First-class thread cap (#305): clamp cpu.rx to the ceiling AFTER any tune overlay, so a stale
    # tuned thread count can't exceed the operator's headroom guarantee (e.g. a co-located miner told to
    # stay at nproc-2). Auto (-1) or any value above the cap becomes the cap; a valid count at or under
    # the cap is left untouched — a true ceiling, never a raise.
    if [ -n "${THREADS_CAP:-}" ]; then
        local _capped
        _capped=$(jq --argjson cap "$THREADS_CAP" '.cpu.rx = (if (.cpu.rx | type) == "number" and .cpu.rx >= 1 and .cpu.rx <= $cap then .cpu.rx else $cap end)' config.json 2>/dev/null) && printf '%s\n' "$_capped" >config.json
    fi

    # The live config holds the pool/wallet and the API token, so keep it owner-only (a root `jq`
    # redirect would otherwise leave it world-readable). _reown_worker hands ownership to the operator
    # later; chmod here is preserved across that chown, and root (the service) reads it regardless.
    chmod 600 config.json

    if [ "$OS_TYPE" == "Linux" ]; then
        # Appliance mode: no logrotate drop-in — /etc is a volatile overlay and the image does not run
        # logrotate; log policy on the appliance belongs to the integration layer (pithead#797 R2),
        # which re-renders the miner's config every boot and can cap or journald-route the log there.
        if [ "$RIGFORGE_APPLIANCE" = 1 ]; then
            log "Appliance mode: skipping the logrotate policy (image-owned logging)."
            return
        fi
        log "Configuring log rotation policy..."
        # Install logrotate configuration
        sudo tee "$LOGROTATE_DIR/xmrig" >/dev/null <<EOF
    $LOG_FILE_PATH {
        daily
        missingok
        rotate 7
        compress
        delaycompress
        notifempty
        copytruncate
        minsize 50M
        create 0644 ${MINER_USER:-$REAL_USER} ${MINER_USER:-$REAL_USER}
    }
EOF
    fi
}

# --- Setup: service, kernel tuning & deployment ---

# Render the miner unit from its template (#140 made this shared: `apply` must re-render when
# miner_user changes, without install_service's enable/start side effects).
# Privilege separation (#140): create the dedicated system user on first use. Never deleted by
# uninstall (we can't prove we created it; an inert nologin user is safer than userdel). Called
# from BOTH install paths — setup (install_service) and apply's unit re-render — because apply is
# the documented config-change path for toggling miner_user; a unit saying User=<absent user>
# fails with status=217/USER (caught live on miner-0 during the v1.4.0 gate).
_ensure_miner_user() {
    if [ -n "${MINER_USER:-}" ] && ! id -u "$MINER_USER" >/dev/null 2>&1; then
        log "Creating system user '$MINER_USER' for the miner..."
        sudo useradd --system --no-create-home --shell /usr/sbin/nologin "$MINER_USER"
    fi
}

_render_xmrig_unit() {
    local msr_line=""
    # Root-side MSR application for an unprivileged miner: no `-` prefix — on an opted-in rig a
    # failed MSR write should be VISIBLE, and msr-apply itself exits 0 on the known-benign cases
    # (unknown CPU family, module missing) so it never wedges the Restart=always loop.
    if [ -n "${MINER_USER:-}" ]; then msr_line="ExecStartPre=+$SCRIPT_DIR/rigforge.sh msr-apply"; fi
    WORKER_ROOT="$WORKER_ROOT" MINER_USER_EFFECTIVE="${MINER_USER:-root}" MSR_APPLY_LINE="$msr_line" \
        envsubst '$BUILD_DIR $CPUPOWER_PATH $WORKER_ROOT $NFT_PATH $MINER_USER_EFFECTIVE $MSR_APPLY_LINE' \
        <"$SCRIPT_DIR/systemd/xmrig.service.template" | sudo tee "$SYSTEMD_DIR/$SERVICE_NAME.service" >/dev/null
}

install_service() {
    if [ "$OS_TYPE" == "Linux" ]; then
        log "Installing systemd service..."
        export BUILD_DIR="$WORKER_ROOT/xmrig/build"
        CPUPOWER_PATH=$(command -v cpupower || echo "/usr/bin/cpupower")
        export CPUPOWER_PATH
        NFT_PATH=$(command -v nft || echo "/usr/sbin/nft")
        export NFT_PATH

        _ensure_miner_user
        _render_xmrig_unit

        # Reload systemd daemon
        sudo systemctl daemon-reload

        # Enable service to start on boot (transiently in appliance mode — the boot leg re-enables)
        sudo systemctl enable ${ENABLE_RUNTIME:+"$ENABLE_RUNTIME"} "$SERVICE_NAME.service"

        if [ "$REBOOT_REQUIRED" = true ]; then
            # HugePages aren't reserved until the GRUB change takes effect on reboot — starting the miner
            # now would run it DEGRADED (no huge-page backing, Restart=always churn) until then. So only
            # enable it; it starts automatically after the reboot. (#audit A2)
            log "Service enabled — it will start automatically after you reboot."
        elif [ "${SERVICE_NO_START:-false}" = true ]; then
            # The CALLER owns the start/restart decision (#413). `upgrade` sets this: it must not start
            # a miner the operator — or the watchdog's thermal cutoff — deliberately left stopped, and on
            # a rebuild it must not restart twice. The unit is rendered, reloaded and enabled here;
            # nothing is started or restarted.
            log "Service unit installed and enabled — the caller decides whether to restart."
        elif [ "$XMRIG_REBUILD" = true ]; then
            # Restart only when the binary was rebuilt; otherwise just ensure it's running (a running
            # service is left undisturbed on a no-op re-run).
            log "Restarting XMRig service..."
            sudo systemctl restart "$SERVICE_NAME.service"
        else
            log "No rebuild — ensuring the service is running (no restart)."
            sudo systemctl start "$SERVICE_NAME.service"
        fi
        SERVICE_INSTALLED=true
    else
        warn "Service installation is not supported on $OS_TYPE."
    fi
}

# Install (or remove) the systemd timer that runs `autotune` periodically, based on the `autotune`
# config flag (#46). Idempotent: toggling the flag off cleanly removes the timer.
install_autotune() {
    [ "$OS_TYPE" == "Linux" ] || return 0
    local svc="$SYSTEMD_DIR/rigforge-autotune.service" tmr="$SYSTEMD_DIR/rigforge-autotune.timer"
    if [ "${AUTOTUNE_MODE:-disabled}" = "disabled" ]; then
        if [ -f "$tmr" ]; then
            sudo systemctl disable ${ENABLE_RUNTIME:+"$ENABLE_RUNTIME"} --now rigforge-autotune.timer 2>/dev/null || true
            sudo rm -f "$svc" "$tmr"
            sudo systemctl daemon-reload 2>/dev/null || true
            log "Periodic autotune disabled."
        fi
        return 0
    fi
    log "Enabling periodic autotune: $(_autotune_desc "$AUTOTUNE_MODE"), runs ${AUTOTUNE_ONCALENDAR:-monthly}..."
    # Bake operator, appliance posture, and target into the scheduled root run.
    SERVICE_NAME="$SERVICE_NAME" RIGFORGE_OPERATOR="$REAL_USER" RIGFORGE_APPLIANCE="$RIGFORGE_APPLIANCE" SCRIPT_DIR="$SCRIPT_DIR" AUTOTUNE_TARGET="${AUTOTUNE_TARGET:-perf}" \
        envsubst '$SERVICE_NAME $RIGFORGE_OPERATOR $RIGFORGE_APPLIANCE $SCRIPT_DIR $AUTOTUNE_TARGET' \
        <"$SCRIPT_DIR/systemd/rigforge-autotune.service.template" | sudo tee "$svc" >/dev/null
    AUTOTUNE_ONCALENDAR="${AUTOTUNE_ONCALENDAR:-monthly}" \
        envsubst '$AUTOTUNE_ONCALENDAR' \
        <"$SCRIPT_DIR/systemd/rigforge-autotune.timer.template" | sudo tee "$tmr" >/dev/null
    sudo systemctl daemon-reload
    sudo systemctl enable ${ENABLE_RUNTIME:+"$ENABLE_RUNTIME"} --now rigforge-autotune.timer 2>/dev/null || true
}

# Install (or remove) the systemd timer that runs the miner watchdog periodically, based on the
# `watchdog` config flag (#139). Same shape as install_autotune above; idempotent both ways.
install_watchdog() {
    [ "$OS_TYPE" == "Linux" ] || return 0
    local svc="$SYSTEMD_DIR/rigforge-watchdog.service" tmr="$SYSTEMD_DIR/rigforge-watchdog.timer"
    # #395: this function used to end on `systemctl enable ... || true`, so it returned 0 no matter
    # what happened above it — and its callers run it under `|| true`, which suppresses `set -e` for
    # the whole dynamic extent of the call. A failed unit write therefore aborted nothing, surfaced
    # nowhere, and left the caller free to record the change as applied. Each step that can GENUINELY
    # fail now records into rc and the function returns it, so a caller that looks gets the truth and
    # a caller that does not is no worse off than before. The `|| true` on enable/disable of a
    # possibly-absent timer stays deliberate: those are tolerated, the unit writes are not.
    local rc=0
    if [ "${WATCHDOG_MODE:-disabled}" = "disabled" ]; then
        if [ -f "$tmr" ]; then
            sudo systemctl disable ${ENABLE_RUNTIME:+"$ENABLE_RUNTIME"} --now rigforge-watchdog.timer 2>/dev/null || true
            sudo rm -f "$svc" "$tmr" || rc=1
            sudo systemctl daemon-reload 2>/dev/null || true
            if [ "$rc" -eq 0 ]; then
                log "Miner watchdog disabled."
            else
                warn "Could not remove the watchdog units ($svc, $tmr) — the old timer may still be running."
            fi
        fi
        return "$rc"
    fi
    log "Enabling the miner watchdog: a health check every ${WATCHDOG_INTERVAL_MIN:-5} min${MAX_TEMP_C:+, thermal cutoff ${MAX_TEMP_C}°C}..."
    # Only the cadence is baked into the units — the verb re-reads config.json every run, so an
    # `apply` after a max_temp_c or ACCESS_TOKEN edit needs no unit rewrite (and no token on disk).
    SERVICE_NAME="$SERVICE_NAME" RIGFORGE_OPERATOR="$REAL_USER" SCRIPT_DIR="$SCRIPT_DIR" \
        envsubst '$SERVICE_NAME $RIGFORGE_OPERATOR $SCRIPT_DIR' \
        <"$SCRIPT_DIR/systemd/rigforge-watchdog.service.template" | sudo tee "$svc" >/dev/null || rc=1
    WATCHDOG_INTERVAL_MIN="${WATCHDOG_INTERVAL_MIN:-5}" \
        envsubst '$WATCHDOG_INTERVAL_MIN' \
        <"$SCRIPT_DIR/systemd/rigforge-watchdog.timer.template" | sudo tee "$tmr" >/dev/null || rc=1
    sudo systemctl daemon-reload || rc=1
    sudo systemctl enable ${ENABLE_RUNTIME:+"$ENABLE_RUNTIME"} --now rigforge-watchdog.timer 2>/dev/null || true
    return "$rc"
}

# Sister API (#99/#164, xmrig-model): one tiny persistent python3-stdlib server ships pre-computed
# JSON from /run/rigforge-api; a systemd timer (`rigforge.sh api-refresh`) recomputes the files every
# 15 s. Requests never touch the miner. Toggle shape mirrors install_autotune above.
# Opt-in API firewall (#142): an own `inet rigforge` nft table scoping the read-only API port(s)
# to `api_allow_from` + loopback. nftables only (Ubuntu 24.04's native firewall — a ufw fallback
# would double the surface); own table so teardown is a single `destroy`. Matches only the API
# dports, so SSH and the outbound stratum connection are untouchable by construction. Applied now
# AND re-applied on boot via xmrig.service (the always-present anchor); removed with the table.
install_api_firewall() {
    [ "$OS_TYPE" == "Linux" ] || return 0
    [ -n "${WORKER_ROOT:-}" ] || return 0 # nowhere to stage the rule file yet
    local nft_file="$WORKER_ROOT/api-firewall.nft"
    if [ -z "${API_ALLOW_FROM:-}" ]; then
        if [ -f "$nft_file" ]; then
            command -v nft >/dev/null 2>&1 && sudo nft destroy table inet rigforge 2>/dev/null || true
            sudo rm -f "$nft_file"
            log "API firewall removed."
        fi
        return 0
    fi
    command -v nft >/dev/null 2>&1 || error "api_allow_from is set but 'nft' is missing — install nftables (sudo apt-get install nftables) or clear the key."
    # Port set: :8080 (XMRig's API) always, plus :8081 (the sister API) when it's enabled.
    local ports="8080"
    [ "${API_MODE:-disabled}" = enabled ] && ports="$ports, ${API_PORT:-8081}"
    [ "${CONTROL_MODE:-disabled}" = enabled ] && ports="$ports, ${CONTROL_PORT:-8082}"
    sudo tee "$nft_file" >/dev/null <<NFT
destroy table inet rigforge
table inet rigforge {
    chain api {
        type filter hook input priority filter; policy accept;
        tcp dport { $ports } iifname "lo" accept
        tcp dport { $ports } ${API_ALLOW_FAMILY:-ip} saddr $API_ALLOW_FROM accept
        tcp dport { $ports } drop
    }
}
NFT
    # Fail CLOSED: if nft rejects the ruleset (e.g. a charset-valid but structurally-invalid IPv6
    # slipped past parse_config's guard), the API ports are NOT scoped — never log success. This is
    # a security control, so a load failure is a hard error, not a warning swallowed by apply's
    # `install_api_firewall || true`.
    if ! sudo nft -f "$nft_file"; then
        error "API firewall FAILED to load — nft rejected the ruleset for api_allow_from='$API_ALLOW_FROM'. The API ports are NOT restricted. Fix api_allow_from and re-run."
    fi
    log "API firewall active — port(s) $ports reachable only from $API_ALLOW_FROM and loopback."
}
_wait_sister_api() {
    local host="$API_BIND" code i
    case "$host" in 0.0.0.0) host=127.0.0.1 ;; ::) host=::1 ;; esac
    case "$host" in *:*) host="[$host]" ;; esac
    for i in $(seq 1 15); do
        if systemctl is-active --quiet rigforge-api.service; then
            code=$(curl -q --noproxy '*' -s -o /dev/null -w '%{http_code}' --max-time 1 "http://$host:$API_PORT/health") || code=000
            case "$code" in 200 | 401 | 503) return 0 ;; esac
        fi
        sleep 1
    done
    warn "Sister API is not active and listening; check journalctl -u rigforge-api.service."
    return 1
}
install_api() {
    [ "$OS_TYPE" == "Linux" ] || return 0
    local svc="$SYSTEMD_DIR/rigforge-api.service" rsvc="$SYSTEMD_DIR/rigforge-api-refresh.service" rtmr="$SYSTEMD_DIR/rigforge-api-refresh.timer"
    if [ -f "$SYSTEMD_DIR/rigforge-api.socket" ]; then
        sudo systemctl disable ${ENABLE_RUNTIME:+"$ENABLE_RUNTIME"} --now rigforge-api.socket 2>/dev/null || true
        sudo rm -f "$SYSTEMD_DIR/rigforge-api.socket" "$SYSTEMD_DIR/rigforge-api@.service"
        sudo systemctl daemon-reload 2>/dev/null || true
    fi
    if [ "${API_MODE:-disabled}" = "disabled" ]; then
        if [ -f "$svc" ] || [ -f "$rtmr" ]; then
            sudo systemctl disable ${ENABLE_RUNTIME:+"$ENABLE_RUNTIME"} --now rigforge-api.service rigforge-api-refresh.timer 2>/dev/null || true
            sudo rm -f "$svc" "$rsvc" "$rtmr"
            sudo systemctl daemon-reload 2>/dev/null || true
            log "Sister API disabled."
        fi
        return 0
    fi
    command -v python3 >/dev/null 2>&1 || {
        warn 'The sister API server needs python3. Install it or disable api in config.json.'
        return 1
    }
    log "Enabling the sister API on $API_BIND:$API_PORT (read-only; token: $([ -n "${ACCESS_TOKEN:-}" ] && echo required || echo open); state refreshes every 15s)..."
    API_BIND="$API_BIND" API_PORT="$API_PORT" SCRIPT_DIR="$SCRIPT_DIR" envsubst '$API_BIND $API_PORT $SCRIPT_DIR' <"$SCRIPT_DIR/systemd/rigforge-api.service.template" | sudo tee "$svc" >/dev/null || return 1
    RIGFORGE_OPERATOR="$REAL_USER" SCRIPT_DIR="$SCRIPT_DIR" envsubst '$RIGFORGE_OPERATOR $SCRIPT_DIR' <"$SCRIPT_DIR/systemd/rigforge-api-refresh.service.template" | sudo tee "$rsvc" >/dev/null || return 1
    sudo tee "$rtmr" <"$SCRIPT_DIR/systemd/rigforge-api-refresh.timer.template" >/dev/null || return 1
    sudo systemctl daemon-reload || return 1
    sudo systemctl enable ${ENABLE_RUNTIME:+"$ENABLE_RUNTIME"} rigforge-api-refresh.timer || return 1
    sudo systemctl enable ${ENABLE_RUNTIME:+"$ENABLE_RUNTIME"} rigforge-api.service || return 1
    sudo systemctl restart rigforge-api-refresh.timer rigforge-api.service || return 1
    sudo systemctl start rigforge-api-refresh.service || return 1
    _wait_sister_api
}
install_control() {
    [ "$OS_TYPE" == "Linux" ] || return 0
    local svc="$SYSTEMD_DIR/rigforge-control.service" asvc="$SYSTEMD_DIR/rigforge-control-apply.service" apath="$SYSTEMD_DIR/rigforge-control-apply.path"
    local usvc="$SYSTEMD_DIR/rigforge-control-upgrade.service" upath="$SYSTEMD_DIR/rigforge-control-upgrade.path"
    if [ "${CONTROL_MODE:-disabled}" = "disabled" ]; then
        if [ -f "$svc" ] || [ -f "$apath" ] || [ -f "$upath" ]; then
            # #308: tear down the remote-upgrade units alongside the control path — they never outlive it.
            sudo systemctl disable ${ENABLE_RUNTIME:+"$ENABLE_RUNTIME"} --now rigforge-control.service rigforge-control-apply.path rigforge-control-upgrade.path 2>/dev/null || true
            sudo rm -f "$svc" "$asvc" "$apath" "$usvc" "$upath"
            sudo systemctl daemon-reload 2>/dev/null || true
            # Under load systemctl can transiently drop the stop half of `disable --now` (real
            # miner-0 gate, 2026-07-19: unit files removed, receiver left running orphaned — a live
            # write surface with control "disabled"). One explicit re-stop closes it; no-op when
            # the stop already landed.
            sudo systemctl stop rigforge-control.service 2>/dev/null || true
            log "Writable control path disabled."
        fi
        return 0
    fi
    command -v python3 >/dev/null 2>&1 || error "The control server needs python3 (stock on Ubuntu 24.04). Install it or set \"control\": \"disabled\"."
    log "Enabling the writable control path on $CONTROL_BIND:$CONTROL_PORT (token required, pinned to $API_ALLOW_FROM; changes staged and applied off the request path)..."
    CONTROL_BIND="$CONTROL_BIND" CONTROL_PORT="$CONTROL_PORT" SCRIPT_DIR="$SCRIPT_DIR" API_PORT="${API_PORT:-8081}" \
        envsubst '$CONTROL_BIND $CONTROL_PORT $SCRIPT_DIR $API_PORT' \
        <"$SCRIPT_DIR/systemd/rigforge-control.service.template" | sudo tee "$svc" >/dev/null
    RIGFORGE_OPERATOR="$REAL_USER" RIGFORGE_APPLIANCE="$RIGFORGE_APPLIANCE" SCRIPT_DIR="$SCRIPT_DIR" \
        envsubst '$RIGFORGE_OPERATOR $RIGFORGE_APPLIANCE $SCRIPT_DIR' \
        <"$SCRIPT_DIR/systemd/rigforge-control-apply.service.template" | sudo tee "$asvc" >/dev/null
    sudo tee "$apath" <"$SCRIPT_DIR/systemd/rigforge-control-apply.path.template" >/dev/null
    # #308: the remote-upgrade units ride ON TOP of the control path — installed only when
    # control_upgrade is ALSO enabled, removed otherwise, so `control` alone never carries a
    # code-update surface. Same envsubst/operator handback as the apply oneshot.
    if [ "${CONTROL_UPGRADE:-disabled}" = "enabled" ]; then
        RIGFORGE_OPERATOR="$REAL_USER" RIGFORGE_APPLIANCE="$RIGFORGE_APPLIANCE" SCRIPT_DIR="$SCRIPT_DIR" \
            envsubst '$RIGFORGE_OPERATOR $RIGFORGE_APPLIANCE $SCRIPT_DIR' \
            <"$SCRIPT_DIR/systemd/rigforge-control-upgrade.service.template" | sudo tee "$usvc" >/dev/null
        sudo tee "$upath" <"$SCRIPT_DIR/systemd/rigforge-control-upgrade.path.template" >/dev/null
        log "Remote upgrade ENABLED — the stack can trigger a RigForge self-upgrade to the latest release (default-off surface; ADR 0002)."
    elif [ -f "$upath" ] || [ -f "$usvc" ]; then
        sudo systemctl disable ${ENABLE_RUNTIME:+"$ENABLE_RUNTIME"} --now rigforge-control-upgrade.path 2>/dev/null || true
        sudo rm -f "$usvc" "$upath"
    fi
    sudo systemctl daemon-reload
    sudo systemctl enable ${ENABLE_RUNTIME:+"$ENABLE_RUNTIME"} --now rigforge-control-apply.path 2>/dev/null || true
    if [ "${CONTROL_UPGRADE:-disabled}" = "enabled" ]; then
        sudo systemctl enable ${ENABLE_RUNTIME:+"$ENABLE_RUNTIME"} --now rigforge-control-upgrade.path 2>/dev/null || true
    fi
    sudo systemctl enable ${ENABLE_RUNTIME:+"$ENABLE_RUNTIME"} rigforge-control.service 2>/dev/null || true
    # restart, not just enable --now: a bind/port/token/upgrade-flag change must be re-read (restart also starts).
    sudo systemctl restart rigforge-control.service 2>/dev/null || true
}

# #65 (read-only): the thread count the HugePages reservation is sized for — the tuned cpu.rx if
# `tune` pinned one (so setup + tune stay consistent), or an explicit RIGFORGE_THREADS override (the
# documented resize-then-re-tune path). Empty => proposed-grub.sh falls back to its L3 estimate.
_rx_setup_threads() {
    RX_SETUP_THREADS=""
    if [ -n "${RIGFORGE_THREADS:-}" ]; then
        RX_SETUP_THREADS="$RIGFORGE_THREADS"
    elif [ -f "$WORKER_ROOT/tune-overrides.json" ]; then
        RX_SETUP_THREADS=$(jq -r '.cpu.rx // empty' "$WORKER_ROOT/tune-overrides.json" 2>/dev/null) || RX_SETUP_THREADS=""
    fi
    case "$RX_SETUP_THREADS" in -1 | '' | *[!0-9]*) RX_SETUP_THREADS="" ;; esac
}

# Read-only GRUB computation shared by tune_kernel (the mutation half) and the setup --dry-run plan
# (#146): sets MANAGED (params we manage), CURRENT (the live cmdline), MERGED (#19 merge — never
# clobbers params the user/distro set). Callers guard on proposed-grub.sh + $GRUB_DEFAULT existing.
#
# POOL_CEILING_MB (#410): the declared hugepages_pool_ceiling_mb reaches the PERSISTED reservation
# here, not only the runtime write in _ensure_hugepages. Without it the boot pool comes up above the
# ceiling and the grow-only runtime guard can never bring it back down — a declared ceiling that
# holds until the next reboot and then silently stops holding. Passed to the cmdline-generating call
# ONLY: the two --runtime calls below and in tune_kernel ask for the miner's REQUIREMENT, which
# _ensure_hugepages weighs against availability before clamping the write, so clamping it there
# would move that decision instead of bounding the pool.
_grub_proposed() {
    MANAGED=$(RX_THREADS="$RX_SETUP_THREADS" RESERVE_EXTRA_MB="${HUGEPAGES_RESERVE_EXTRA_MB:-0}" THREADS_CAP="${THREADS_CAP:-}" POOL_CEILING_MB="${HUGEPAGES_POOL_CEILING_MB:-0}" "$SCRIPT_DIR/util/proposed-grub.sh" -q)
    MANAGED="${MANAGED#quiet splash }"
    CURRENT=$(sed -n 's/^GRUB_CMDLINE_LINUX_DEFAULT="\(.*\)"$/\1/p' "$GRUB_DEFAULT" | head -n1)
    MERGED=$(grub_merge_cmdline "$MANAGED" "$CURRENT")

    # Co-resident keep-existing guard (#305): when headroom is requested and the LIVE reservation already
    # backs miner + headroom, leave GRUB untouched (MERGED := CURRENT) rather than shrinking it or
    # switching page schemes — no reboot. The co-location contract (pithead#593): on a box whose ambient
    # reservation already covers stack + miner, RigForge changes nothing; the MSR boost, which does need
    # a reboot, stays a separate opt-in. Done here (not in tune_kernel) so `setup --dry-run` previews the
    # same no-reboot outcome. Scoped to co-resident mode (headroom > 0) so a normal host's sizing, MSR
    # enablement, and reboot behaviour are unchanged.
    if [ "${HUGEPAGES_RESERVE_EXTRA_MB:-0}" -gt 0 ] 2>/dev/null; then
        local _need _have
        _need=$(RX_THREADS="$RX_SETUP_THREADS" RESERVE_EXTRA_MB="${HUGEPAGES_RESERVE_EXTRA_MB:-0}" THREADS_CAP="${THREADS_CAP:-}" "$SCRIPT_DIR/util/proposed-grub.sh" --runtime 2>/dev/null) || _need=""
        _have=$(_cmdline_reserved_2mb "$CURRENT")
        if [ -n "$_need" ] && [ "$_have" -gt 0 ] 2>/dev/null && [ "$_have" -ge "$_need" ] 2>/dev/null; then
            MERGED="$CURRENT"
        fi
    fi
}

# Total HugePages a kernel cmdline reserves, in 2MB-equivalent pages (a 1G page = 512 × 2MB). Each
# `hugepages=N` pairs with the preceding `hugepagesz=`, or `default_hugepagesz=` if none precedes it —
# the kernel's own rule. Used by the #305 co-resident keep-existing guard to tell whether the LIVE
# reservation already backs miner + headroom.
_cmdline_reserved_2mb() { # <cmdline> -> reserved 2MB-equivalent pages
    # One awk statement (not a multi-line string): kcov credits it when a test exercises it.
    awk '{ cur=""; def=""; t=0; for (i=1;i<=NF;i++) { if ($i ~ /^hugepagesz=/) { split($i,a,"="); cur=a[2] } else if ($i ~ /^default_hugepagesz=/) { split($i,a,"="); def=a[2] } else if ($i ~ /^hugepages=/) { split($i,a,"="); n=a[2]+0; s=(cur!=""?cur:def); if (s=="1G"||s=="1073741824"||s=="1048576K") t+=n*512; else t+=n } } print t+0 }' <<<"$1"
}

# 2MB pages the running miner already holds (kB -> pages), 0 when stopped: pages it holds now are
# pages it re-uses across a restart, so they count as available when sizing the pool. HugetlbPages
# spans every page size, so a dataset sitting in 1GB pages overstates this credit — in exactly the
# case where the 2MB pool is not needed for the dataset, so nothing actually used goes unreserved.
_miner_held_hugepages() {
    local pid kb
    pid=$(systemctl show "$SERVICE_NAME.service" -p MainPID --value 2>/dev/null) || pid=""
    if [ -n "$pid" ] && [ "$pid" -gt 0 ] 2>/dev/null && [ -r "/proc/$pid/status" ]; then
        kb=$(awk '/^HugetlbPages:/ { print $2; exit }' "/proc/$pid/status" 2>/dev/null)
        echo $((${kb:-0} / 2048))
        return
    fi
    echo 0
}

# Grow-only runtime reservation (#328, the runtime half of #305's keep-existing guard): another
# consumer may hold pages from the same pool (a co-hosted pithead stack's p2pool/monerod), and
# writing our raw requirement shrinks that pool to its in-use floor — 0 free pages on both sides,
# measured live on the pithead#797 appliance bench. Ensure the miner's pages are AVAILABLE (free
# now, or already held by the running miner) and grow the pool by the shortfall only; never shrink
# a reservation someone else made. Idempotent: a re-run that finds enough available writes nothing.
# ponytail: with headroom configured AND the co-resident already running, its live pages and the
# headroom both count toward the target — a bounded over-reserve in the safe direction, UNLESS the
# box is too small to absorb it (rigforge#398 / pithead#1103: ~12 GiB requested on an 8 GiB box).
# hugepages_pool_ceiling_mb (see _ensure_hugepages) is the bound for a box that needs one; tighten
# this function itself to max(headroom, live use) only if a real box needs the difference instead.
_hugepages_avail() { # -> 2MB pages the miner could draw on right now (free + already held)
    local free held
    free=$(awk '/^HugePages_Free:/ { print $2; exit }' "$MEMINFO" 2>/dev/null) || free=""
    held=$(_miner_held_hugepages)
    echo $((${free:-0} + held))
}

_ensure_hugepages() { # <required 2MB pages>
    local required=$1 current avail target ceiling_pages
    current=$(cat "$NR_HUGEPAGES_FILE" 2>/dev/null) || current=0
    avail=$(_hugepages_avail)
    if [ "$avail" -ge "$required" ]; then
        log "HugePages pool already covers the miner ($avail of $required pages available; pool: $current) — leaving it as-is (#328)."
        return
    fi
    target=$((current + required - avail))
    # Total-pool ceiling (#398): hugepages_pool_ceiling_mb caps the WRITE itself rather than feeding
    # more headroom into the requirement above — the requirement/availability arithmetic can double-
    # count a co-resident consumer's already-held pages (rigforge#398), and no declared value of
    # hugepages_reserve_extra_mb can fix that from the requirement side. Absent (0, the default) this
    # whole block is skipped and the write below is byte-for-byte the pre-#398 arithmetic (#328).
    # FLOORED to whole 2MB pages (not rounded up like EXTRA_2MB_PAGES elsewhere): a cap must round
    # toward less memory, never more — an odd declared MB value (e.g. 5121) floors to the page below
    # (2560, 5120MB) rather than overshooting the declared ceiling by a page (security review finding
    # on the first version of this fix: ceil(MB/2) let an odd ceiling write one page past itself).
    # #412: no `2>/dev/null` on the comparison any more. That redirect was the SECOND half of the
    # defect: fed a value bash could not evaluate, `[ -gt 0 ]` returned 2, the `if` read it as false,
    # and the whole ceiling block was skipped with no message whatsoever — the pool grew uncapped
    # while the config declared a cap. parse_config now rejects such a value, so this can only ever
    # see a validated one; the explicit re-check is the backstop, because a cap that can be dropped
    # in silence is not a cap. It ERRORS rather than falling through: refusing to size the pool is
    # the safe direction when the declared bound is unenforceable.
    if ! _uint_in_range "${HUGEPAGES_POOL_CEILING_MB:-0}" 0 65536; then
        error "hugepages_pool_ceiling_mb is not a whole number of MB, 0-65536 at the HugePages write (got: '${HUGEPAGES_POOL_CEILING_MB:-}') — refusing to size the pool against an unenforceable ceiling (#412)."
    fi
    if [ "${HUGEPAGES_POOL_CEILING_MB:-0}" -gt 0 ]; then
        ceiling_pages=$((HUGEPAGES_POOL_CEILING_MB / 2))
        if [ "$target" -gt "$ceiling_pages" ]; then
            if [ "$ceiling_pages" -le "$current" ]; then
                warn "HugePages pool is already at its declared ceiling ($current pages, ${HUGEPAGES_POOL_CEILING_MB}MB) — the computed requirement ($target pages) exceeds it, so the pool is left as-is; the miner may run without a full HugePages share (#398)."
                return
            fi
            log "HugePages requirement ($target pages) exceeds the declared pool ceiling — capping the write at $ceiling_pages pages (${HUGEPAGES_POOL_CEILING_MB}MB) instead of growing further (#398)."
            target=$ceiling_pages
        fi
    fi
    sudo sysctl -w vm.nr_hugepages=$target
}

tune_kernel() {
    if [ "$OS_TYPE" != "Linux" ]; then
        log "Skipping kernel tuning (Not supported on $OS_TYPE)."
        return
    fi

    if [[ "$(uname -m)" == "x86_64" || "$(uname -m)" == "i686" ]]; then
        log "Enabling MSR module for hardware prefetcher tuning..."
        sudo modprobe msr 2>/dev/null || true
        if [ "$RIGFORGE_APPLIANCE" = 1 ]; then
            # The modprobe above is the whole job on the appliance: setup re-runs every boot (the
            # pithead boot leg), so a modules-load drop-in is persistence machinery for a
            # persistence layer the box doesn't have. Smaller than writing /run/modules-load.d
            # for the same effect — that dir is only read at boot, before this run exists.
            log "Appliance mode: msr loaded at runtime only (no modules-load drop-in — setup re-runs each boot)."
        elif [ -d "$MODULES_LOAD_DIR" ]; then
            echo "msr" | sudo tee "$MODULES_LOAD_DIR/msr.conf" >/dev/null
        elif [ -f "$MODULES_FILE" ]; then
            append_once "$MODULES_FILE" "msr"
        fi
    fi

    _rx_setup_threads
    [ -n "$RX_SETUP_THREADS" ] && log "Sizing the HugePages reservation for $RX_SETUP_THREADS mining thread(s) (#65)."

    log "Applying runtime memory tuning..."
    if [ -f "$SCRIPT_DIR/util/proposed-grub.sh" ]; then
        # Calculate exact requirement based on hardware, the tuned thread count, and 1GB page status
        REQUIRED_PAGES=$(RX_THREADS="$RX_SETUP_THREADS" RESERVE_EXTRA_MB="${HUGEPAGES_RESERVE_EXTRA_MB:-0}" THREADS_CAP="${THREADS_CAP:-}" "$SCRIPT_DIR/util/proposed-grub.sh" --runtime)
        log "Hardware-optimized HugePages: $REQUIRED_PAGES (2MB pages) calculated."
        _ensure_hugepages "$REQUIRED_PAGES"
    else
        # Fallback when proposed-grub.sh is missing: 3072 × 2MB = 6 GB of huge pages — enough for the
        # ~2.3 GB RandomX dataset plus per-thread scratchpads on a large desktop/server, without over-
        # reserving on smaller hosts. proposed-grub.sh computes an exact, hardware-sized value instead.
        warn "Utility script not found. Fallback to safe default (3072)."
        _ensure_hugepages 3072
    fi

    log "Configuring bootloader (GRUB) for persistent HugePages..."
    if [ "$RIGFORGE_APPLIANCE" = 1 ]; then
        # A deliberate skip, not the utility-not-found fallback below: on the appliance /boot is
        # read-only and the kernel cmdline (incl. any 1GB-hugepage reservation) is image-owned —
        # an unguarded update-grub took the whole R0 run down after a completed compile. Without
        # the 1G reservation XMRig falls back to 2MB pages at 100%: working, small known cost
        # (pithead#797 R0 item 2).
        log "Appliance mode: skipping GRUB updates — the kernel cmdline is image-owned."
    elif [ -f "$SCRIPT_DIR/util/proposed-grub.sh" ] && [ -f "$GRUB_DEFAULT" ]; then
        # proposed-grub.sh prints a generic "quiet splash" prefix plus the HugePage/MSR params we
        # manage. Keep only the params we manage and MERGE them into the existing cmdline so we don't
        # clobber other kernel parameters the user/distro set (#19 — boot-safety).
        _grub_proposed

        if [ "$CURRENT" = "$MERGED" ]; then
            # Either already optimal, or _grub_proposed's co-resident keep-existing guard (#305) set
            # MERGED := CURRENT because the ambient reservation already covers miner + headroom — either
            # way there's nothing to write and no reboot.
            log "GRUB is already configured for the required HugePages reservation (no reboot)."
        else
            sudo cp "$GRUB_DEFAULT" "$GRUB_DEFAULT.bak"
            sudo sed -i "s|^GRUB_CMDLINE_LINUX_DEFAULT=.*|GRUB_CMDLINE_LINUX_DEFAULT=\"$(_sed_escape_replacement "$MERGED")\"|" "$GRUB_DEFAULT"
            if command -v update-grub >/dev/null; then
                sudo update-grub
                REBOOT_REQUIRED=true
            else
                warn "'update-grub' not found. Please manually update your bootloader."
            fi
        fi
    else
        warn "Skipping GRUB updates (Utility not found or non-GRUB system)."
    fi
}

configure_limits() {
    if [ "$OS_TYPE" != "Linux" ]; then
        return
    fi

    # Appliance mode: mount hugetlbfs at RUNTIME only. The fstab lines would land on the volatile
    # /etc overlay and vanish at reboot (proven on the R0 bench) — setup re-runs each boot and just
    # mounts again. The limits.conf memlock append covers interactive runs only, which are not an
    # appliance concern: the unit already sets LimitMEMLOCK=infinity.
    if [ "$RIGFORGE_APPLIANCE" = 1 ]; then
        log "Appliance mode: mounting hugetlbfs at runtime (no fstab or limits.conf writes)..."
        sudo mkdir -p "$HUGEPAGES_1G_DIR"
        mountpoint -q /dev/hugepages 2>/dev/null ||
            sudo mount -t hugetlbfs hugetlbfs /dev/hugepages ||
            warn "Could not mount /dev/hugepages. Check 'dmesg' for details."
        mountpoint -q "$HUGEPAGES_1G_DIR" 2>/dev/null ||
            sudo mount -t hugetlbfs -o pagesize=1G hugetlbfs_1g "$HUGEPAGES_1G_DIR" ||
            warn "Could not mount $HUGEPAGES_1G_DIR (1G pages need an image-owned cmdline reservation)."
        return 0
    fi

    log "Configuring persistent HugePage mounts and memory limits..."
    sudo mkdir -p "$HUGEPAGES_1G_DIR"

    # Configure fstab for HugePage mounts (Idempotent)
    append_once "$FSTAB" "hugetlbfs /dev/hugepages hugetlbfs defaults 0 0"
    append_once "$FSTAB" "hugetlbfs_1g $HUGEPAGES_1G_DIR hugetlbfs pagesize=1G 0 0"

    sudo mount -a || warn "Mount operation returned errors. Check 'dmesg' for details."

    # Configure security limits for memlock (idempotent). Scope it to the mining user instead of every
    # account ("*") — the systemd service runs as root with its own LimitMEMLOCK=infinity, so this
    # entry only needs to cover manual/interactive runs by the operator (#13).
    append_once "$LIMITS_CONF" "$REAL_USER soft memlock unlimited"
    append_once "$LIMITS_CONF" "$REAL_USER hard memlock unlimited"
}

# Put a `rigforge` command on PATH: a symlink in BIN_DIR pointing at this script, so the operator can
# run `sudo rigforge <cmd>` from anywhere instead of `./rigforge.sh`. OPT-IN via `add_to_path` in
# config.json (off by default). Best-effort and idempotent — it never fails the deploy. `uninstall`
# removes it regardless, but only while it's still our symlink.
link_cli() {
    [ "${ADD_TO_PATH:-false}" = "true" ] || return 0
    local target="$SCRIPT_DIR/rigforge.sh" link="$BIN_DIR/rigforge"
    if [ ! -d "$BIN_DIR" ]; then
        warn "Skipped the 'rigforge' command — $BIN_DIR doesn't exist. Run it as './rigforge.sh' instead."
        return 0
    fi
    if [ -L "$link" ] && [ "$(readlink "$link" 2>/dev/null)" = "$target" ]; then
        return 0 # already our symlink — keep idempotent re-runs quiet
    fi
    if [ -e "$link" ] && [ ! -L "$link" ]; then
        warn "Didn't add the 'rigforge' command — $link already exists and isn't a RigForge symlink."
        return 0
    fi
    # Use sudo only when BIN_DIR isn't writable (it is when setup runs as root on Linux); empty prefix
    # otherwise. shellcheck SC2086: the unquoted prefix is intentional (it must vanish when empty).
    local sudo_pfx=""
    [ -w "$BIN_DIR" ] || sudo_pfx="sudo"
    # shellcheck disable=SC2086
    if $sudo_pfx rm -f "$link" 2>/dev/null && $sudo_pfx ln -s "$target" "$link" 2>/dev/null; then
        log "Installed the 'rigforge' command -> $link (try: 'sudo rigforge doctor' from anywhere)."
    else
        warn "Couldn't add the 'rigforge' command at $link (permissions?). Run it as './rigforge.sh' instead."
    fi
}

finish_deployment() {
    echo ""
    log "--------------------------------------------------------"
    log "Deployment Complete."
    if [ "$REBOOT_REQUIRED" = true ]; then
        warn "ACTION REQUIRED: A system reboot is mandatory to enable HugePages."
        warn "Please run 'sudo reboot' now."
    else
        log "Worker configured successfully. No reboot required."
    fi
    log "--------------------------------------------------------"
    echo ""
    if [ "$SERVICE_INSTALLED" = true ]; then
        if [ "$REBOOT_REQUIRED" = true ]; then
            log "Service enabled — it starts automatically after the reboot above (then: $0 status / logs)."
        else
            log "Service created. xmrig running in background (check: $0 status / logs)."
        fi
    else
        log "Start the miner with:"
        echo "  $0 start          # then: $0 status / logs / stop"
    fi
}

# --- Orchestration: main (setup) ---

# Decide whether the pinned XMRig needs (re)building. Call after parse_config (needs WORKER_ROOT).
decide_rebuild() {
    if xmrig_already_built; then
        XMRIG_REBUILD=false
        log "XMRig $XMRIG_VERSION already built at the pinned commit — recompile will be skipped."
    else
        XMRIG_REBUILD=true
    fi
}

# Re-own everything written as root back to the invoking operator. setup/upgrade/tune/apply/restore write
# files under WORKER_ROOT as root (the XMRig build, the generated config, logs, tune-overrides), and the
# first-run config.json is created as root under `sudo` — leaving a tree the operator can't edit, re-run
# `setup` over without sudo, or `git clean`. Reconcile ownership once at the end of each such command,
# rather than chmod-ing every individual `sudo cp`/`tee`. No-op unless we're root on Linux/macOS.
_reown_worker() {
    [ "$(id -u)" -eq 0 ] || return 0
    local owner
    case "$OS_TYPE" in
    Linux) owner="$REAL_USER:$REAL_USER" ;;
    Darwin) owner="$REAL_USER" ;;
    *) return 0 ;;
    esac
    if [ -n "${WORKER_ROOT:-}" ] && [ -e "$WORKER_ROOT" ]; then sudo chown -R "$owner" "$WORKER_ROOT" 2>/dev/null || true; fi
    if [ -f "$CONFIG_JSON" ]; then sudo chown "$owner" "$CONFIG_JSON" 2>/dev/null || true; fi
    # Privilege separation (#140): the unprivileged miner must keep write access to its autosaved
    # config and its log after the blanket re-own above. Every re-owning verb routes through here.
    if [ -n "${MINER_USER:-}" ] && [ "$OS_TYPE" = Linux ]; then
        sudo chown "$MINER_USER:$MINER_USER" "$WORKER_ROOT/xmrig/build/config.json" "$WORKER_ROOT/xmrig.log" 2>/dev/null || true
    fi
}

# setup --dry-run (#146): a numbered plan of exactly what setup WOULD do on this machine with this
# config, computed from read-only probes only — no sudo, no writes, no modprobe. A dedicated printer
# (not a DRY_RUN flag threaded through the mutating functions) because a printer can't mutate by
# construction; the drift risk is covered by a test asserting every CURRENT_STEP phrase in main()
# appears here. Step lines reuse those exact phrases — they're load-bearing for that test.
_setup_plan() {
    local n=0
    _p() {
        n=$((n + 1))
        printf '%2d. %s: %s\n' "$n" "$1" "$2"
    }
    echo "setup --dry-run — the plan for this machine ($(hostname), $OS_TYPE):"
    if command -v jq >/dev/null 2>&1; then
        _p "verifying prerequisites" "jq found; nothing to install"
    else
        _p "verifying prerequisites" "install jq (config-dependent details below unavailable until it exists)"
        echo "Dry run — nothing was changed. Run 'sudo $0 setup' to apply."
        return 0
    fi
    if [ ! -f "$CONFIG_JSON" ]; then
        _p "ensuring config exists" "would create $CONFIG_JSON interactively (pool URL prompt) — the rest of the plan depends on it"
        echo "Dry run — nothing was changed. Run 'sudo $0 setup' to apply."
        return 0
    fi
    _p "ensuring config exists" "use the existing $CONFIG_JSON"
    parse_config >/dev/null
    _p "parsing config" "pools: $(printf '%s' "$POOLS_JSON" | jq -r '[.[].url] | join(", ")' 2>/dev/null)"
    decide_rebuild >/dev/null 2>&1 || true
    if [ "$XMRIG_REBUILD" = true ]; then
        _p "checking the build" "build XMRig $XMRIG_VERSION (commit ${XMRIG_COMMIT:0:12}) — clone + compile"
    else
        _p "checking the build" "skip the build — XMRig $XMRIG_VERSION already built at the pinned commit"
    fi
    _p "preparing workspace" "workspace at $WORKER_ROOT (an existing prior install would be archived first)"
    if [ "$RIGFORGE_APPLIANCE" = 1 ]; then
        # Same check install_dependencies runs (shared _missing_appliance_tools — no second copy).
        local _mt
        _mt="$(_missing_appliance_tools)"
        if [ -n "$_mt" ]; then
            _p "installing dependencies" "appliance mode: FAIL — required tool(s) missing from the image:$_mt (the toolchain must be baked at image build)"
        else
            _p "installing dependencies" "appliance mode: baked into the image — no package install"
        fi
    elif [ "$OS_TYPE" = "Darwin" ]; then
        _p "installing dependencies" "install/verify via brew: cmake libuv openssl hwloc"
    elif _detect_pkg_manager; then
        local _md
        _md="$(_missing_deps)"
        if [ -n "$_md" ]; then
            _p "installing dependencies" "install packages:$_md"
        else
            _p "installing dependencies" "all dependencies already installed"
        fi
    else
        _p "installing dependencies" "no supported package manager found — manual install"
    fi
    if [ "$XMRIG_REBUILD" = true ]; then
        _p "compiling XMRig" "compile in $WORKER_ROOT/xmrig/build and record the binary SHA-256"
    else
        _p "compiling XMRig" "skipped (already built; SHA-256 record kept)"
    fi
    _p "generating XMRig config" "write $WORKER_ROOT/xmrig/build/config.json$([ -f "$WORKER_ROOT/tune-overrides.json" ] && echo ' + overlay tune-overrides.json')"
    if [ "$OS_TYPE" != "Linux" ]; then
        _p "tuning the kernel" "skipped (not supported on $OS_TYPE — no HugePages/MSR here)"
        _p "configuring limits" "skipped (Linux-only)"
        _p "installing the service" "none on macOS — run via '$0 start' (nohup) or the launchd login agent"
    else
        local _msr _pages="(proposed-grub.sh missing — fallback 3072)" _grubline="GRUB: will check at run time" _reboot=""
        _msr="write msr to $MODULES_LOAD_DIR/msr.conf (module autoload)"
        [ -e "$MODULES_LOAD_DIR/msr.conf" ] && _msr="msr module already configured"
        # Appliance arms: the same flag checks tune_kernel makes, previewed (pithead#797 R1). The
        # GRUB probe/diff below is also gated off — the appliance skip line must stand as-is.
        if [ "$RIGFORGE_APPLIANCE" = 1 ]; then
            _msr="modprobe msr at runtime only (appliance: no modules-load drop-in)"
            _grubline="skipping GRUB updates (appliance: the kernel cmdline is image-owned)"
        fi
        if [ -f "$SCRIPT_DIR/util/proposed-grub.sh" ]; then
            _rx_setup_threads
            _pages=$(RX_THREADS="$RX_SETUP_THREADS" RESERVE_EXTRA_MB="${HUGEPAGES_RESERVE_EXTRA_MB:-0}" THREADS_CAP="${THREADS_CAP:-}" "$SCRIPT_DIR/util/proposed-grub.sh" --runtime 2>/dev/null) || _pages="?"
            if [ "$RIGFORGE_APPLIANCE" != 1 ] && [ -f "$GRUB_DEFAULT" ]; then
                _grub_proposed
                if [ "$CURRENT" = "$MERGED" ]; then
                    _grubline="GRUB already configured (no reboot needed for it)"
                else
                    _grubline="GRUB cmdline: '$CURRENT' -> '$MERGED'"
                    _reboot=" — a reboot WILL be required"
                fi
            fi
        fi
        # Grow-only preview (#328): same availability check _ensure_hugepages runs, read-only.
        local _hpline="grow the pool so $_pages 2MB HugePages are available (grow-only runtime sysctl)"
        if [[ "$_pages" =~ ^[0-9]+$ ]] && [ "$(_hugepages_avail)" -ge "$_pages" ] 2>/dev/null; then
            _hpline="HugePages pool already covers the miner ($_pages pages needed) — no change"
        fi
        _p "tuning the kernel" "$_msr; $_hpline; $_grubline$_reboot"
        if [ "$RIGFORGE_APPLIANCE" = 1 ]; then
            _p "configuring limits" "appliance mode: mount hugetlbfs at runtime — no $FSTAB or $LIMITS_CONF writes (volatile /etc)"
        else
            local _f1="hugetlbfs /dev/hugepages hugetlbfs defaults 0 0" _f2="hugetlbfs_1g $HUGEPAGES_1G_DIR hugetlbfs pagesize=1G 0 0" _add=""
            grep -qxF "$_f1" "$FSTAB" 2>/dev/null || _add=" '$_f1'"
            grep -qxF "$_f2" "$FSTAB" 2>/dev/null || _add="$_add '$_f2'"
            if [ -n "$_add" ]; then
                _p "configuring limits" "append to $FSTAB:$_add; memlock unlimited for $REAL_USER in $LIMITS_CONF"
            else
                _p "configuring limits" "fstab already configured; memlock unlimited for $REAL_USER in $LIMITS_CONF"
            fi
        fi
        _p "installing the service" "render systemd/xmrig.service.template -> $SYSTEMD_DIR/$SERVICE_NAME.service (User=${MINER_USER:-root}), daemon-reload, enable${ENABLE_RUNTIME:+ $ENABLE_RUNTIME} --now"
    fi
    case "$AUTOTUNE_MODE" in
    disabled) _p "configuring autotune" "no periodic timer (autotune disabled) — an installed one would be removed" ;;
    *) _p "configuring autotune" "install rigforge-autotune.timer (monthly re-tune, target: $AUTOTUNE_MODE)" ;;
    esac
    case "$WATCHDOG_MODE" in
    disabled) _p "configuring the watchdog" "no watchdog timer (watchdog disabled) — an installed one would be removed" ;;
    *) _p "configuring the watchdog" "install rigforge-watchdog.timer (health check every ${WATCHDOG_INTERVAL_MIN}min${MAX_TEMP_C:+, thermal cutoff ${MAX_TEMP_C}°C})" ;;
    esac
    if [ "$API_MODE" = enabled ]; then
        _p "configuring the sister API" "install rigforge-api.service (:$API_PORT) + the 15s refresh timer"
    else
        _p "configuring the sister API" "disabled — installed units would be removed"
    fi
    if [ "$CONTROL_MODE" = enabled ]; then
        _p "configuring the control path" "install rigforge-control.service (:$CONTROL_PORT, writable, token+source pinned) + the staged applier"
    else
        _p "configuring the control path" "disabled — installed units would be removed"
    fi
    if [ -n "${API_ALLOW_FROM:-}" ]; then
        _p "configuring the API firewall" "nftables 'inet rigforge' table scoping the API port(s) to $API_ALLOW_FROM + loopback"
    else
        _p "configuring the API firewall" "no api_allow_from — no firewall scoping (an installed table would be removed)"
    fi
    if [ "$ADD_TO_PATH" = true ]; then
        _p "linking the rigforge command" "symlink $BIN_DIR/rigforge -> $SCRIPT_DIR/rigforge.sh"
    else
        _p "linking the rigforge command" "add_to_path is off — no symlink"
    fi
    _p "reconciling file ownership" "chown the worker tree back to $REAL_USER${MINER_USER:+ (config+log to $MINER_USER)}"
    _p "finishing up" "print the summary$([ "$OS_TYPE" = Linux ] && echo ' (and the reboot notice when HugePages changed)')"
    echo "Dry run — nothing was changed. Run 'sudo $0 setup' to apply."
}

_persist_appliance_mode() {
    if [ "$RIGFORGE_APPLIANCE" = 1 ]; then
        mkdir -m 700 "$APPLIANCE_MARKER" 2>/dev/null || [ -d "$APPLIANCE_MARKER" ] || error "Could not persist appliance mode at $APPLIANCE_MARKER."
    else
        rmdir "$APPLIANCE_MARKER" 2>/dev/null || [ ! -e "$APPLIANCE_MARKER" ] || error "Could not clear stale appliance mode at $APPLIANCE_MARKER."
    fi
}
main() {
    local _arg
    for _arg in "$@"; do
        case "$_arg" in
        --dry-run)
            _setup_plan
            return 0
            ;;
        *) error "Unknown option for setup: '$_arg' (use --dry-run). Run '$0 help'." ;;
        esac
    done
    _persist_appliance_mode
    CURRENT_STEP="verifying prerequisites"
    check_prerequisites
    CURRENT_STEP="ensuring config exists"
    ensure_config_exists
    CURRENT_STEP="parsing config"
    parse_config
    CURRENT_STEP="checking the build"
    decide_rebuild
    CURRENT_STEP="preparing workspace"
    prepare_workspace
    CURRENT_STEP="installing dependencies"
    install_dependencies
    CURRENT_STEP="compiling XMRig"
    compile_xmrig
    CURRENT_STEP="generating XMRig config"
    generate_xmrig_config
    CURRENT_STEP="tuning the kernel"
    tune_kernel
    CURRENT_STEP="configuring limits"
    configure_limits
    CURRENT_STEP="installing the service"
    install_service
    CURRENT_STEP="configuring autotune"
    install_autotune
    CURRENT_STEP="configuring the watchdog"
    install_watchdog
    CURRENT_STEP="configuring the sister API"
    install_api
    CURRENT_STEP="configuring the control path"
    install_control
    CURRENT_STEP="configuring the API firewall"
    install_api_firewall
    CURRENT_STEP="linking the rigforge command"
    link_cli # opt-in (add_to_path): put `rigforge` on PATH so the operator can run it from anywhere
    CURRENT_STEP="reconciling file ownership"
    _reown_worker # hand the build/config/logs back to the operator so they can edit + re-run without sudo
    CURRENT_STEP="finishing up"
    finish_deployment
}

# --- Lifecycle: upgrade & uninstall ---

# Wait until the worker API reports a live (non-zero) hashrate, up to ~90s — used after a restart so a
# freshly-started miner (still allocating the RandomX dataset) is warm before we measure it. True once live.
_wait_miner_live() { # [tries]
    local i hr tries="${1:-30}"
    for i in $(seq 1 "$tries"); do
        hr=$(_read_api_hashrate)
        [ -n "$hr" ] && awk -v hr="$hr" 'BEGIN{exit !(hr > 0)}' 2>/dev/null && return 0
        sleep 3
    done
    return 1
}

# After `upgrade` rebuilds XMRig, the fastest knobs can shift between versions — so re-tune the new build
# now if periodic autotune is enabled (the upgrade is the REAL trigger; the monthly timer is just a slow
# safety net). Otherwise point at a manual re-tune, since the carried-over overrides were measured on the
# old build. Extracted from upgrade() so it's unit-testable without the (heavy) rebuild path.
_post_upgrade_retune() {
    if [ "$OS_TYPE" = Linux ] && [ "${AUTOTUNE_MODE:-disabled}" != disabled ] && systemctl is-active --quiet "$SERVICE_NAME" 2>/dev/null; then
        log "Re-tuning the new build (autotune: $(_autotune_desc "$AUTOTUNE_MODE")) — knobs can shift between XMRig versions..."
        if _wait_miner_live; then
            autotune || warn "Post-upgrade autotune didn't complete — re-run 'sudo $0 tune --now' once the miner is warm."
        else
            warn "Miner isn't reporting a live hashrate yet — skipping the post-upgrade re-tune. Run 'sudo $0 tune --now' manually, or wait for the scheduled run."
        fi
    elif [ -f "$WORKER_ROOT/tune-overrides.json" ]; then
        warn "Saved tuning (tune-overrides.json) carried over from the previous build. The fastest knobs can shift between XMRig versions — re-run 'sudo $0 tune' (or 'tune --clear' to discard), or enable periodic autotune in config.json."
    fi
}

# Put what `upgrade` just wrote INTO EFFECT (#413). XMRig reads its config once at start and systemd
# runs the unit it has already loaded, so a regenerated build/config.json and a re-rendered unit are
# files on disk, not a changed rig, until the service restarts — the same "written, reported applied,
# never in effect" gap #413 is about, one layer further down. So an upgrade restarts, exactly as
# `apply` does after regenerating the same file.
#
# Deliberately NOT gated on "did the generated config actually change": the config we emit carries
# `autosave: true`, so XMRig rewrites build/config.json itself at runtime and the on-disk copy is never
# byte-identical to a freshly generated one. A before/after hash would therefore report "changed" on
# every rig on every upgrade — the same restart, dressed up as a measurement.
#
# A miner that was NOT running is never started here: the regenerated config and unit sit on disk and
# the next deliberate `start`/`apply` picks them up. An upgrade must respect a hold, whether it came
# from the operator or from the watchdog's thermal cutoff (#396's class). install_service's own start is
# suppressed via SERVICE_NO_START, so this is the ONLY place on the upgrade path that touches the
# running miner. Extracted from upgrade() so the decision is testable without the (heavy) rebuild path,
# the same reason _post_upgrade_retune above is.
_upgrade_restart() { # <was-active: yes|no>
    if [ "$OS_TYPE" != Linux ]; then
        log "Config regenerated. Restart the miner to apply ('$0 restart')."
        return 0
    fi
    if [ "$1" != yes ]; then
        log "The miner wasn't running, so it was left stopped — the regenerated config and reinstalled unit take effect at the next 'sudo $0 start'."
        return 0
    fi
    log "Restarting XMRig so the regenerated config and reinstalled unit take effect..."
    sudo systemctl restart "$SERVICE_NAME.service"
}

# upgrade --check: compare the local VERSION against GitHub's latest release tag, on demand only.
# This is the one place RigForge talks to GitHub's API, and it runs exactly when the operator types
# it — never scheduled, never piggybacked on another verb (SECURITY.md's "no version ping" promise
# stands because the check is explicit). Always returns 0: an update *hint* must never break a
# script that calls it. Reads one file and one URL; no parse_config, no root, no other side effects.
_upgrade_check() {
    local local_v remote_v url body highest
    local_v=$(tr -d '[:space:]' <"$SCRIPT_DIR/VERSION" 2>/dev/null || true) # guard inside the $() (#210)
    if [ -z "$local_v" ]; then
        warn "No VERSION file at $SCRIPT_DIR/VERSION — can't compare against the latest release."
        return 0
    fi
    body=$(curl -fsS --max-time 5 "https://api.github.com/repos/p2pool-starter-stack/rigforge/releases/latest" 2>/dev/null || true)
    if [ -z "$body" ]; then
        warn "Couldn't reach GitHub to check for a newer release — try again later."
        return 0
    fi
    remote_v=$(printf '%s' "$body" | jq -r '.tag_name // empty' 2>/dev/null || true)
    url=$(printf '%s' "$body" | jq -r '.html_url // empty' 2>/dev/null || true)
    remote_v="${remote_v#v}"
    if [ -z "$remote_v" ]; then
        warn "Couldn't reach GitHub to check for a newer release — try again later."
        return 0
    fi
    if [ "$local_v" = "$remote_v" ]; then
        log "RigForge $local_v is the latest release."
        return 0
    fi
    highest=$(printf '%s\n%s\n' "$local_v" "$remote_v" | sort -V | tail -n1)
    if [ "$highest" = "$remote_v" ]; then
        log "A newer RigForge is available: $remote_v (you have $local_v)."
        if [ -n "$url" ]; then
            log "Release notes: $url"
        fi
        log "Update: cd $SCRIPT_DIR && git fetch --tags && git checkout v$remote_v && sudo $0 upgrade  (development checkouts on a branch: git pull && sudo $0 upgrade)"
    else
        log "RigForge $local_v is ahead of the latest release ($remote_v) — development build."
    fi
    return 0
}

# Upgrade redeploys this release: regenerate config, reinstall every unit, re-tune, re-own, and restart. The COMPILE is
# what's conditional (only a changed XMRig pin needs one), not the upgrade. Skips the setup-only steps
# (dependency install, kernel tuning) — those don't change on a RigForge release.
upgrade() {
    local arg
    for arg in "$@"; do
        case "$arg" in
        --check)
            _upgrade_check
            return 0
            ;;
        *) error "Unknown option for upgrade: '$arg' (use --check). Run '$0 help'." ;;
        esac
    done
    _persist_appliance_mode
    check_prerequisites
    parse_config
    decide_rebuild
    # #413: reinstall the whole release even when the XMRig pin (and therefore build) is unchanged.
    local was_active=no
    if [ "$OS_TYPE" = Linux ] && systemctl is-active --quiet "$SERVICE_NAME" 2>/dev/null; then
        was_active=yes
    fi
    SERVICE_NO_START=true # _upgrade_restart below owns the restart decision, not install_service
    prepare_workspace
    compile_xmrig
    generate_xmrig_config
    install_service
    install_autotune
    install_watchdog
    install_api
    install_control
    install_api_firewall
    if [ "$XMRIG_REBUILD" = true ]; then
        log "Upgraded to XMRig $XMRIG_VERSION."
    else
        log "XMRig $XMRIG_VERSION (commit ${XMRIG_COMMIT:0:12}) was already built — regenerated the config and reinstalled the units."
    fi
    _upgrade_restart "$was_active"
    _post_upgrade_retune
    _reown_worker
}

# Map a HOME_DIR value to its worker root, validating it first. HOME_DIR becomes a filesystem path we
# mkdir / cd / write / `sudo rm -rf` under, so it must be the sentinel DYNAMIC_HOME (or empty/null) or a
# clean absolute path — no spaces, shell metacharacters, or `..` traversal. Echoes the worker root, or
# returns 1 (invalid) so every consumer fails closed rather than acting on a typo- or attacker-controlled
# path. Shared by parse_config and the privileged uninstall/backup/restore/doctor consumers.
_worker_root_for_home() { # <raw HOME_DIR> -> echoes "<root>", or returns 1 if invalid
    local raw="$1" trimmed
    if [ "$raw" = "DYNAMIC_HOME" ] || [ -z "$raw" ] || [ "$raw" = "null" ]; then
        echo "$SCRIPT_DIR/data/worker"
    elif [[ "$raw" =~ ^/[A-Za-z0-9._/-]+$ ]] && [[ "$raw" != *..* ]]; then
        # Syntactically valid is not enough: HOME_DIR feeds mkdir/cd/`sudo rm -rf`, so the
        # filesystem's own top levels ("/", "/etc", bare "/home", ...) must fail closed too. (#135)
        # ponytail: strips one trailing slash; the charset regex above already blocks anything
        # hostile — this is a fat-finger guard, not a security boundary.
        trimmed="${raw%/}"
        case "${trimmed:-/}" in
        / | /bin | /boot | /dev | /etc | /home | /lib | /lib64 | /media | /mnt | /opt | /proc | /root | /run | /sbin | /srv | /sys | /tmp | /usr | /var | /Applications | /Library | /System | /Users | /Volumes | /private)
            return 1
            ;;
        esac
        echo "$raw/worker"
    else
        return 1
    fi
}

# Resolve the worker root from config.json the same way parse_config would, but WITHOUT requiring a
# valid/complete config (echoes "" when there's no config). Refuses an invalid HOME_DIR (fails closed)
# so the privileged consumers never act on it. Shared by uninstall/doctor/backup/restore.
_worker_root_from_config() {
    local raw root
    [ -f "$CONFIG_JSON" ] || return 0
    raw=$(jq -r '.HOME_DIR // "DYNAMIC_HOME"' "$CONFIG_JSON" 2>/dev/null)
    if root=$(_worker_root_for_home "$raw"); then
        echo "$root"
    else
        error "Refusing to act on $CONFIG_JSON: HOME_DIR ('$raw') is not a clean absolute path. Fix it first."
    fi
}

# Cleanly revert everything setup changed (#12): the service, logrotate, fstab/limits/modules edits, the
# GRUB cmdline, the 1G mount, and the worker build/logs. Idempotent and conservative — it only removes
# the exact lines/files RigForge added; your config.json is left in place.
uninstall() {
    if [ "$OS_TYPE" != "Linux" ]; then
        error "uninstall manages Linux system changes and is only supported on Linux."
    fi
    local assume_yes=0 arg
    for arg in "$@"; do
        case "$arg" in
        -y | --yes) assume_yes=1 ;;
        *) error "Unknown option for uninstall: '$arg' (use -y|--yes). Run '$0 help'." ;;
        esac
    done
    if [ "$assume_yes" -eq 0 ]; then
        warn "This removes the xmrig service and reverts RigForge's system changes (fstab, limits, modules, GRUB)."
        # `|| true`: EOF on a piped/non-interactive stdin leaves ANS empty, so the default-No abort
        # below runs instead of the ERR trap (same guard as the setup prompts).
        read -r -p "Proceed with uninstall? (y/N): " ANS || true
        [[ "$ANS" =~ ^[Yy] ]] || {
            log "Aborted."
            return 0
        }
    fi

    # Work out the worker root the same way parse_config would, without requiring a valid config.
    local worker_root
    worker_root=$(_worker_root_from_config)

    # 1. systemd service (+ the optional autotune timer, #46)
    local _mu
    _mu=$(jq -r '.miner_user // empty' "$CONFIG_JSON" 2>/dev/null || true)
    if [ -n "$_mu" ] && id -u "$_mu" >/dev/null 2>&1; then
        # Exact-removal discipline: we only delete what we provably created, and we can't prove
        # that for a user. An inert nologin user is safer than a wrong userdel.
        log "Left system user '$_mu' in place — remove it yourself with: sudo userdel $_mu"
    fi
    if [ -f "$SYSTEMD_DIR/rigforge-api.socket" ] || [ -f "$SYSTEMD_DIR/rigforge-api.service" ]; then
        sudo systemctl disable ${ENABLE_RUNTIME:+"$ENABLE_RUNTIME"} --now rigforge-api.socket rigforge-api.service rigforge-api-refresh.timer 2>/dev/null || true
        sudo rm -f "$SYSTEMD_DIR/rigforge-api.socket" "$SYSTEMD_DIR/rigforge-api@.service" \
            "$SYSTEMD_DIR/rigforge-api.service" "$SYSTEMD_DIR/rigforge-api-refresh.service" "$SYSTEMD_DIR/rigforge-api-refresh.timer"
    fi
    if [ -f "$SYSTEMD_DIR/rigforge-control.service" ] || [ -f "$SYSTEMD_DIR/rigforge-control-apply.path" ] || [ -f "$SYSTEMD_DIR/rigforge-control-upgrade.path" ]; then
        # #308: tear down the remote-upgrade units too, or uninstall leaves a live code-update surface.
        sudo systemctl disable ${ENABLE_RUNTIME:+"$ENABLE_RUNTIME"} --now rigforge-control.service rigforge-control-apply.path rigforge-control-upgrade.path 2>/dev/null || true
        sudo rm -f "$SYSTEMD_DIR/rigforge-control.service" "$SYSTEMD_DIR/rigforge-control-apply.service" "$SYSTEMD_DIR/rigforge-control-apply.path" \
            "$SYSTEMD_DIR/rigforge-control-upgrade.service" "$SYSTEMD_DIR/rigforge-control-upgrade.path"
    fi
    command -v nft >/dev/null 2>&1 && sudo nft destroy table inet rigforge 2>/dev/null || true
    if [ -f "$SYSTEMD_DIR/rigforge-autotune.timer" ]; then
        sudo systemctl disable ${ENABLE_RUNTIME:+"$ENABLE_RUNTIME"} --now rigforge-autotune.timer 2>/dev/null || true
        sudo rm -f "$SYSTEMD_DIR/rigforge-autotune.timer" "$SYSTEMD_DIR/rigforge-autotune.service"
    fi
    if [ -f "$SYSTEMD_DIR/rigforge-watchdog.timer" ]; then
        sudo systemctl disable ${ENABLE_RUNTIME:+"$ENABLE_RUNTIME"} --now rigforge-watchdog.timer 2>/dev/null || true
        sudo rm -f "$SYSTEMD_DIR/rigforge-watchdog.timer" "$SYSTEMD_DIR/rigforge-watchdog.service"
    fi
    if [ -f "$SYSTEMD_DIR/$SERVICE_NAME.service" ]; then
        sudo systemctl stop "$SERVICE_NAME" 2>/dev/null || true
        sudo systemctl disable ${ENABLE_RUNTIME:+"$ENABLE_RUNTIME"} "$SERVICE_NAME" 2>/dev/null || true
        sudo rm -f "$SYSTEMD_DIR/$SERVICE_NAME.service"
        sudo systemctl daemon-reload 2>/dev/null || true
        log "Removed the $SERVICE_NAME service."
    fi

    # 2. logrotate policy
    sudo rm -f "$LOGROTATE_DIR/xmrig"

    # 3. fstab HugePage mounts
    remove_line "$FSTAB" "hugetlbfs /dev/hugepages hugetlbfs defaults 0 0"
    remove_line "$FSTAB" "hugetlbfs_1g $HUGEPAGES_1G_DIR hugetlbfs pagesize=1G 0 0"

    # 4. memlock limits (current per-user form + the legacy wildcard form, for older installs)
    remove_line "$LIMITS_CONF" "$REAL_USER soft memlock unlimited"
    remove_line "$LIMITS_CONF" "$REAL_USER hard memlock unlimited"
    remove_line "$LIMITS_CONF" "* soft memlock unlimited"
    remove_line "$LIMITS_CONF" "* hard memlock unlimited"

    # 5. msr module autoload
    sudo rm -f "$MODULES_LOAD_DIR/msr.conf"
    remove_line "$MODULES_FILE" "msr"

    # 6. 1G HugePage mount
    if command -v mountpoint >/dev/null 2>&1 && mountpoint -q "$HUGEPAGES_1G_DIR" 2>/dev/null; then
        sudo umount "$HUGEPAGES_1G_DIR" 2>/dev/null || true
    fi
    sudo rmdir "$HUGEPAGES_1G_DIR" 2>/dev/null || true

    # 7. GRUB cmdline — strip only the params we added
    if [ -f "$GRUB_DEFAULT" ]; then
        local cur stripped
        cur=$(sed -n 's/^GRUB_CMDLINE_LINUX_DEFAULT="\(.*\)"$/\1/p' "$GRUB_DEFAULT" | head -n1)
        stripped=$(grub_strip_managed "$cur")
        if [ "$cur" != "$stripped" ]; then
            sudo cp "$GRUB_DEFAULT" "$GRUB_DEFAULT.bak"
            sudo sed -i "s|^GRUB_CMDLINE_LINUX_DEFAULT=.*|GRUB_CMDLINE_LINUX_DEFAULT=\"$(_sed_escape_replacement "$stripped")\"|" "$GRUB_DEFAULT"
            if command -v update-grub >/dev/null; then
                sudo update-grub
                REBOOT_REQUIRED=true
            else
                warn "'update-grub' not found — revert your bootloader config manually."
            fi
            log "Reverted RigForge's GRUB kernel parameters."
        fi
    fi

    # 8. worker build + logs (leave config.json in the repo root)
    if [ -n "$worker_root" ] && [ -d "$worker_root" ]; then
        sudo rm -rf "$worker_root"
        log "Removed worker build/logs at $worker_root."
    fi
    rmdir "$APPLIANCE_MARKER" 2>/dev/null || true

    # 9. the `rigforge` CLI symlink — only if it's still ours (never touch a file we didn't create)
    if [ -L "$BIN_DIR/rigforge" ] && [ "$(readlink "$BIN_DIR/rigforge" 2>/dev/null)" = "$SCRIPT_DIR/rigforge.sh" ]; then
        sudo rm -f "$BIN_DIR/rigforge"
        log "Removed the 'rigforge' command ($BIN_DIR/rigforge)."
    fi

    log "Uninstall complete. config.json was left in place."
    if [ "$REBOOT_REQUIRED" = true ]; then
        warn "Reboot to fully release the HugePages reserved at boot."
    fi
}

# --- Auto-tuning: memoization, stats & acceptance (#46, #54) ---
#
# `tune` finds the fastest XMRig knob settings for THIS CPU and records the winner in a separate
# overrides file that generate_xmrig_config merges on top of the generated config — so your own
# config.json is never touched. Two state files live under the worker root:
#   tune-overrides.json — the winning knobs, merged into every generated config.
#   rigforge-tune.json  — the full search log (every candidate, its samples + median, the path taken).
#
# The search (#54) is an iterative, noise-aware coordinate hill-climb. Starting from one or more
# *seeds* it sweeps each knob in turn, measures each candidate as the MEDIAN of several runs (RandomX
# hashrate is jittery), and adopts a change only when it beats the current best by a minimum relative
# margin (TUNE_MIN_DELTA). It repeats until a full pass makes no improvement (plateau) or TUNE_MAX_ROUNDS
# is hit, memoizing every measured candidate so a combination is never benchmarked twice. The knobs are
# the ones whose best value genuinely varies per CPU: the RandomX scratchpad prefetch mode, `cpu.yield`,
# the RandomX thread count (`cpu.rx`, swept around L3/2 MB), and — only when the host actually has them
# reserved — `1gb-pages`. `cpu.priority` is available but off by default (it barely moves a dedicated-box
# benchmark; set TUNE_PRIORITIES to include it).

# The tuning session's shared state. Set by tune() and read by its helpers (kept as globals rather than
# threaded through every call, matching the rest of this script). S_* hold the current candidate.
TUNE_TMP=""
TUNE_BASE=""
TUNE_BIN=""
TUNE_OVERRIDES=""
MEMO_FILE=""
MEMO_SD_FILE=""       # per-candidate sample stddev, for the variance-aware acceptance gate (#63)
MEMO_THROTTLE_FILE="" # per-candidate throttle flag (1/0), for thermal-throttle rejection (#62)
MEMO_HPW_FILE=""      # per-candidate hashrate-per-watt, for the efficiency optimization target (#79)
RESULTS_FILE=""
TUNE_MODE=""
S_p=""
S_y=""
S_t=""
S_g=""
S_pr=""
S_hj=""                # cpu.huge-pages-jit (off by default; swept only if TUNE_HPJIT lists >1 value)
S_cq=""                # randomx.cache_qos  (off by default; swept only if TUNE_CACHEQOS lists >1 value)
S_wr=""                # randomx.wrmsr      (off by default; swept only if TUNE_WRMSR lists >1 value) (#66)
HILL_BEST=""           # set by _hillclimb (its result is returned via this global, not stdout — see below)
HP_CAP_THREADS=""      # #65: max thread count whose 2MB-page need fits the reservation (empty = check off)
_TUNE_SVC_STOPPED=0    # set by tune() when it stops the live service for a --bench run (#2)
_TUNE_LIVE_DIRTY=0     # #347: a live sweep is mid-flight — the overrides file holds a candidate, not a decision
_TUNE_PRE_OVERRIDES="" # #347: the overrides content from before the live sweep ("" = no file existed)

# Put a previous overrides snapshot back — write it (or remove the file when none existed) and re-apply
# it to the running miner. Shared by the A/B confirm's revert leg (#64) and the aborted-live-sweep trap
# (#347), so the abort path restores exactly the way a completed run does.
_restore_overrides() { # <previous_overrides_json>
    if [ -n "$1" ]; then printf '%s\n' "$1" | sudo tee "$TUNE_OVERRIDES" >/dev/null; else sudo rm -f "$TUNE_OVERRIDES"; fi
    _apply_runtime >/dev/null 2>&1 || true
}

# Restart the miner that a --bench run stopped, and clean the temp dir. Installed as an EXIT trap by
# tune() so the service comes back even if the run errors or is interrupted.
_tune_bench_cleanup() {
    # #347: an aborted LIVE sweep would otherwise persist the mid-sweep candidate — _measure_live applies
    # each one straight into tune-overrides.json and restarts the miner on it. Restore the pre-sweep
    # overrides FIRST: the restore itself restarts the service, and any restart must re-read the restored
    # file, never the candidate. tune() clears the flag once the winner deliberately lands in the file.
    if [ "${_TUNE_LIVE_DIRTY:-0}" = 1 ]; then
        _TUNE_LIVE_DIRTY=0
        log "Live sweep interrupted — restoring the pre-tune overrides and restarting the miner on them."
        _restore_overrides "$_TUNE_PRE_OVERRIDES"
    fi
    [ -n "${TUNE_TMP:-}" ] && rm -rf "$TUNE_TMP" 2>/dev/null
    if [ "${_TUNE_SVC_STOPPED:-0}" = 1 ]; then
        _TUNE_SVC_STOPPED=0
        log "Restarting the '$SERVICE_NAME' service."
        sudo systemctl start "$SERVICE_NAME" 2>/dev/null || true
    fi
}

# Median of the numbers passed as arguments (empty if none). RandomX hashrate is noisy, so we report
# the median of several runs per candidate rather than a single (or best) reading.
_median() {
    printf '%s\n' "$@" | sort -n | awk '
        {a[NR]=$1}
        END{ if(NR==0) exit; print (NR%2) ? a[(NR+1)/2] : (a[NR/2]+a[NR/2+1])/2 }'
}

# Tiny file-backed memo (bash 3.2 has no associative arrays). Keyed by the candidate tuple so the
# hill-climb — which revisits the current point as it sweeps each knob — never re-benchmarks a combo.
_memo_get() { awk -F'\t' -v k="$1" '$1==k{print $2; exit}' "$MEMO_FILE" 2>/dev/null; }
_memo_put() { printf '%s\t%s\n' "$1" "$2" >>"$MEMO_FILE"; }
# Parallel store for each candidate's sample stddev (kept out of the median memo so its value stays a
# bare number for every existing caller), and the state's memo key (#63).
_memo_sd_get() { awk -F'\t' -v k="$1" '$1==k{print $2; exit}' "$MEMO_SD_FILE" 2>/dev/null; }
_memo_sd_put() { printf '%s\t%s\n' "$1" "$2" >>"$MEMO_SD_FILE"; }
_memo_hpw_get() { awk -F'\t' -v k="$1" '$1==k{print $2; exit}' "$MEMO_HPW_FILE" 2>/dev/null; } # #79
_memo_hpw_put() { printf '%s\t%s\n' "$1" "$2" >>"$MEMO_HPW_FILE"; }
# #79: efficiency mode needs a power source. True if TUNE_POWER_CMD is set or RAPL is readable.
_power_supported() {
    [ -n "${TUNE_POWER_CMD:-}" ] && return 0
    [ -n "$(_rapl_sum energy_uj)" ] && return 0
    return 1
}
_memo_thr_get() { awk -F'\t' -v k="$1" '$1==k{print $2; exit}' "$MEMO_THROTTLE_FILE" 2>/dev/null; } # #62
_memo_thr_put() { printf '%s\t%s\n' "$1" "$2" >>"$MEMO_THROTTLE_FILE"; }
_state_key() { printf '%s|%s|%s|%s|%s|%s|%s|%s' "$S_p" "$S_y" "$S_t" "$S_g" "$S_pr" "$S_hj" "$S_cq" "$S_wr"; }
# Population stddev of the args (0 with fewer than 2).
_stddev() {
    printf '%s\n' "$@" | awk '{ s += $1; ss += $1 * $1; n++ } END { if (n < 2) { print 0; exit } m = s / n; v = ss / n - m * m; if (v < 0) v = 0; printf "%.4f", sqrt(v) }'
}
# Variance-aware acceptance (#63): the candidate wins only if its median beats the best by BOTH the
# TUNE_MIN_DELTA floor AND more than the combined sample-noise band (TUNE_SIGMA × √(sd_cand²+sd_best²)),
# so jitter on noisy hardware can't trigger a phantom adoption. sd is looked up by each combo's memo key.
_accept_better() { # <cand_median> <cand_key> <best_median> <best_key>
    # #62: a throttled candidate's reading is unreliable — never adopt it.
    if [ "$(_memo_thr_get "$2")" = 1 ]; then return 1; fi
    # #79: the efficiency target ranks by hashrate-per-watt instead of raw H/s. The variance band (#63)
    # carries over proportionally — each candidate's relative H/s spread applied to its hs_per_watt. Any
    # pair missing a power reading falls back to the raw-H/s comparison so the search still progresses.
    if [ "${TUNE_TARGET:-perf}" = efficiency ]; then
        local chpw bhpw
        chpw=$(_memo_hpw_get "$2")
        bhpw=$(_memo_hpw_get "$4")
        if [ -n "$chpw" ] && [ -n "$bhpw" ]; then
            awk -v c="$chpw" -v b="$bhpw" -v cm="$1" -v best="$3" -v csd="$(_memo_sd_get "$2")" -v bsd="$(_memo_sd_get "$4")" \
                -v delta="${TUNE_MIN_DELTA:-0.01}" -v sig="${TUNE_SIGMA:-1}" \
                'BEGIN { crel = (cm > 0 ? csd / cm : 0); brel = (best > 0 ? bsd / best : 0); band = sig * sqrt((c * crel) ^ 2 + (b * brel) ^ 2); exit !(c > b * (1 + delta) && (c - b) > band) }'
            return
        fi
    fi
    awk -v cm="$1" -v best="$3" -v csd="$(_memo_sd_get "$2")" -v bsd="$(_memo_sd_get "$4")" \
        -v delta="${TUNE_MIN_DELTA:-0.01}" -v sig="${TUNE_SIGMA:-1}" \
        'BEGIN { band = sig * sqrt(csd * csd + bsd * bsd); exit !(cm > best * (1 + delta) && (cm - best) > band) }'
}

# --- Auto-tuning: power & thermal sensing (#81) ---

# Best-effort temperature (°C) for the hashrate-per-watt view (#54). Defaults to the standard Linux
# thermal zone; TUNE_TEMP_CMD overrides. Read right after the loaded window (the cores are still hot).
_read_temp() {
    if [ -n "${TUNE_TEMP_CMD:-}" ]; then
        eval "$TUNE_TEMP_CMD"
        return 0
    fi
    [ "$OS_TYPE" = "Linux" ] || return 0
    local z="${THERMAL_ZONE:-/sys/class/thermal/thermal_zone0/temp}" h n
    if [ -r "$z" ]; then
        awk '{printf "%.1f", $1/1000}' "$z" 2>/dev/null
        return 0
    fi
    # No thermal zone: fall back to the CPU hwmon — k10temp (AMD) / coretemp (Intel), same
    # millidegree format (#208). None of the production boards exposes a thermal_zone, so without
    # this the watchdog's max_temp_c and tune's temperature sampling are blind on the real fleet.
    # Still best-effort: nothing readable -> empty, and every thermal consumer skips (a missing
    # sensor must never stop a healthy miner). NOTE k10temp reports Tctl — a control temperature
    # that runs high by design; check the live reading before choosing a cutoff.
    for h in "${HWMON_DIR:-/sys/class/hwmon}"/hwmon*; do
        n=$(cat "$h/name" 2>/dev/null || true)
        case "$n" in
        k10temp | coretemp)
            [ -r "$h/temp1_input" ] && awk '{printf "%.1f", $1/1000}' "$h/temp1_input" 2>/dev/null
            return 0
            ;;
        esac
    done
    return 0
}

# Power measurement (#81). hashrate-per-watt only means something if watts are sampled UNDER LOAD and
# averaged across the measurement window — the old code read once AFTER the bench (idle), collapsing the
# metric onto raw H/s. Two sources, both sampled during the load window:
#   - built-in RAPL: the CPU-package energy-counter delta over the window (Linux, root, no config);
#   - TUNE_POWER_CMD: an instantaneous-watts override (IPMI / smart plug / wall AC), polled + averaged.
# hs_per_watt is therefore RELATIVE within one method/machine — RAPL is CPU-package only, a smart plug is
# whole-wall AC — not an absolute or cross-rig figure. See docs/how-it-works.md.

# An instantaneous watts reading from the operator's override (empty if none).
_read_watts_now() {
    [ -n "${TUNE_POWER_CMD:-}" ] && eval "$TUNE_POWER_CMD"
    return 0
}

# Sum a RAPL sysfs metric (energy_uj or max_energy_range_uj) across the PACKAGE domains only — the
# top-level intel-rapl:N zones named "package-*" (AMD Zen + Intel both expose these here). DRAM/core
# subzones (intel-rapl:N:M) and psys are skipped so nothing is double-counted. RAPL_DIR is overridable
# for tests. Empty when RAPL isn't present/readable (needs root) — power then falls back to TUNE_POWER_CMD.
_rapl_sum() { # <energy_uj|max_energy_range_uj>
    [ "$OS_TYPE" = Linux ] || return 0
    local base="${RAPL_DIR:-/sys/class/powercap}" d v sum=0 got=0
    for d in "$base"/intel-rapl:*; do
        [ -r "$d/$1" ] || continue
        case "$(cat "$d/name" 2>/dev/null)" in package-*) ;; *) continue ;; esac
        v=$(cat "$d/$1" 2>/dev/null) || continue
        case "$v" in '' | *[!0-9]*) continue ;; esac
        sum=$((sum + v))
        got=1
    done
    [ "$got" = 1 ] && echo "$sum"
}

# Average watts from a package-energy delta: <e0_uj> <e1_uj> <max_total_uj> <elapsed_s>. Corrects a single
# counter wrap (e1<e0 -> + max). Empty (never errors under set -e) when inputs are missing or elapsed<=0.
# One-line awk so kcov attributes its coverage (a multi-line program in a string reads as uncovered).
_watts_from_energy() {
    awk -v e0="$1" -v e1="$2" -v mx="$3" -v secs="$4" 'BEGIN{if(e0==""||e1==""||secs+0<=0)exit;d=e1-e0;if(d<0&&mx+0>0)d+=mx;if(d<0)exit;printf "%.2f",(d/1e6)/secs}'
}

# Mean of the numeric args (empty if none) — averages instantaneous power samples over the window.
_mean() {
    [ "$#" -gt 0 ] || return 0
    printf '%s\n' "$@" | awk '{ s += $1; n++ } END { if (n > 0) printf "%.2f", s / n }'
}

# Wall-clock seconds with sub-second precision (GNU date) for timing the RAPL energy window (Linux path).
_now_s() { date +%s.%N 2>/dev/null; }

# --- Auto-tuning: config build & H/s measurement ---

# A candidate's knob values as an overrides snippet (the same shape tune writes for the winner).
_tune_knobs_json() { # <prefetch> <yield> <threads> <onegb> <priority> <hpjit> <cacheqos> <wrmsr>
    jq -cn --argjson p "$1" --argjson y "$2" --arg t "$3" --argjson g "$4" --argjson pr "$5" \
        --argjson hj "$6" --argjson cq "$7" --argjson wr "$8" '
        { randomx: { scratchpad_prefetch_mode: $p, "1gb-pages": $g, cache_qos: $cq, wrmsr: $wr },
          cpu: { yield: $y, priority: $pr, "huge-pages-jit": $hj,
                 rx: (if $t == "-1" then -1 else ($t|tonumber) end) } }'
}

# Materialize a full candidate config by merging the knob snippet over the base config.
_tune_config() { # <out> <prefetch> <yield> <threads> <onegb> <priority>
    local out="$1"
    shift
    _tune_knobs_json "$@" | jq -s '.[0] * .[1]' "$TUNE_BASE" - >"$out"
}

# Run `xmrig --bench=<size>` headlessly and echo its full output. XMRig's `--bench` prints the result and
# then waits for Ctrl+C instead of exiting (#75). It block-buffers stdout to a non-TTY, but flushes its
# `--log-file` per line — so we point that at a temp file and poll it for the 'benchmark finished' line
# (which carries the hashrate), then stop xmrig. We also keep stdout (a fake xmrig in the tests writes
# there and exits — process-gone ends the loop too). `http`/`pools`/`log-file`/`background` are stripped
# from the config so xmrig doesn't serve the API, mine, or daemonize. `BENCH_TIMEOUT` bounds a stuck run.
_xmrig_bench() { # <bin> <bench-size> <config|"">
    local bin="$1" size="$2" cfg="${3:-}" bcfg="" tmpcfg="" out logf xpid deadline freqs="" f
    local wsamples="" pe0="" pt0="" pmax="" w # #81: power-window state
    out="$(mktemp 2>/dev/null || echo "/tmp/rf-bo-$$")"
    logf="$(mktemp 2>/dev/null || echo "/tmp/rf-bl-$$")"
    if [ -n "$cfg" ] && [ -f "$cfg" ] && command -v jq >/dev/null 2>&1; then
        tmpcfg="$(mktemp 2>/dev/null || true)"
        if [ -n "$tmpcfg" ] && jq 'del(.http, .pools, ."log-file", .background)' "$cfg" >"$tmpcfg" 2>/dev/null; then bcfg="$tmpcfg"; fi
    fi
    # shellcheck disable=SC2086 # the :+ expansion is an intentional optional word
    "$bin" --bench="$size" ${bcfg:+--config="$bcfg"} --log-file="$logf" >"$out" 2>&1 &
    xpid=$!
    # #62: when asked, sample the effective CPU clock THROUGHOUT the (sustained) window and keep the min,
    # so the caller can tell a throttled run from a genuinely slow config. One sample up front covers a
    # very short (test) run; the poll loop adds samples across a real ~minutes-long benchmark.
    if [ -n "${BENCH_FREQ_FILE:-}" ]; then
        f=$(_cpu_eff_khz)
        [ -n "$f" ] && freqs="$f"
    fi
    # #81: bracket the same loaded window for power. With TUNE_POWER_CMD we poll instantaneous watts in the
    # loop; otherwise we read the RAPL package energy counter now and at the end and divide by the elapsed
    # time. Averaged into BENCH_WATTS_FILE, so hs_per_watt reflects LOAD power, not the old idle reading.
    if [ -n "${BENCH_WATTS_FILE:-}" ]; then
        if [ -n "${TUNE_POWER_CMD:-}" ]; then
            w=$(_read_watts_now)
            case "$w" in '') ;; *) wsamples="$w" ;; esac
        else
            # `|| true` (same idiom as _autotune_sample's RAPL guard, #81/#290): no powercap sysfs is an
            # expected "no RAPL" outcome, not a failure — an unguarded _rapl_sum here fires the ERR trap.
            pe0=$(_rapl_sum energy_uj || true)
            pt0=$(_now_s)
            pmax=$(_rapl_sum max_energy_range_uj || true)
        fi
    fi
    deadline=$(($(date +%s) + ${BENCH_TIMEOUT:-1800}))
    while kill -0 "$xpid" 2>/dev/null; do
        grep -qs 'benchmark finished' "$logf" "$out" && break
        [ "$(date +%s)" -ge "$deadline" ] && break
        if [ -n "${BENCH_FREQ_FILE:-}" ]; then
            f=$(_cpu_eff_khz)
            [ -n "$f" ] && freqs="$freqs $f"
        fi
        if [ -n "${BENCH_WATTS_FILE:-}" ] && [ -n "${TUNE_POWER_CMD:-}" ]; then
            w=$(_read_watts_now)
            case "$w" in '') ;; *) wsamples="$wsamples $w" ;; esac
        fi
        sleep 0.2
    done
    # #81: read the end-of-window energy BEFORE killing xmrig (still loaded), then average over the window.
    if [ -n "${BENCH_WATTS_FILE:-}" ]; then
        local pe1="" pt1="" secs="" wout=""
        if [ -n "${TUNE_POWER_CMD:-}" ]; then
            # shellcheck disable=SC2086 # intentional word-split of the sample list
            wout=$(_mean $wsamples)
        elif [ -n "$pe0" ]; then
            pe1=$(_rapl_sum energy_uj || true) # guard (#290): a mid-window sysfs read can still miss
            pt1=$(_now_s)
            secs=$(awk -v a="$pt0" -v b="$pt1" 'BEGIN { if (a == "" || b == "") exit; printf "%.3f", b - a }')
            wout=$(_watts_from_energy "$pe0" "$pe1" "${pmax:-0}" "$secs")
        fi
        printf '%s' "$wout" >"$BENCH_WATTS_FILE"
    fi
    # `|| true`: xmrig --bench exits ON ITS OWN when the benchmark finishes, so by here it's often already
    # gone — an unguarded kill then returns non-zero and, under set -Eeuo, fires the ERR trap INSIDE this
    # measurement subshell, aborting it before it echoes the result (→ spurious "aborted" spam + a 0 H/s
    # reading). Guarding it keeps the bench result intact whether or not xmrig is still alive.
    kill "$xpid" 2>/dev/null || true
    wait "$xpid" 2>/dev/null || true
    # The MEDIAN clock over the window — robust to the brief low-clock dataset-init phase, which the raw
    # min would mistake for thermal throttling (#62).
    # shellcheck disable=SC2086 # $freqs is an intentional word-split list of samples
    if [ -n "${BENCH_FREQ_FILE:-}" ]; then _median $freqs | awk 'NF{printf "%d", $0+0}' >"$BENCH_FREQ_FILE"; fi
    cat "$logf" "$out" 2>/dev/null
    rm -f "$out" "$logf" "$tmpcfg" 2>/dev/null || true
}

# One offline benchmark of a config file → peak H/s (empty on failure).
_bench_once() {
    local out
    out=$(_xmrig_bench "$TUNE_BIN" "${TUNE_BENCH:-10M}" "$1")
    # `|| true` (same idiom as the watchdog's `_read_api_hashrate || true` guard): a candidate with no H/s
    # line is expected (a zero-hashrate iteration, not a crash) — under pipefail this grep's failure would
    # otherwise ride out as _bench_once's own exit status and fire the ERR trap ("aborted while ...") at
    # every call site (#277).
    printf '%s' "$out" | _parse_hashrate || true
}

# Live measurement (#54): apply a candidate to the RUNNING miner, discard a warmup window, then take a
# few API samples over steady state and return their median. Heavier than --bench (it restarts the
# service per candidate) but reflects real-world conditions. Linux-only; reuses _read_api_hashrate.
_measure_live() { # <prefetch> <yield> <threads> <onegb> <priority> <hpjit> <cacheqos> <wrmsr>
    local tmp
    tmp=$(mktemp)
    _tune_knobs_json "$@" >"$tmp" && sudo cp "$tmp" "$TUNE_OVERRIDES"
    rm -f "$tmp"
    _apply_runtime >/dev/null 2>&1 || true
    sleep "${TUNE_LIVE_WARMUP:-60}"
    local i s samples=() n="${TUNE_LIVE_SAMPLES:-3}"
    # #81: bracket the steady-state window for power — RAPL energy delta over the window, or the mean of
    # instantaneous TUNE_POWER_CMD samples taken alongside the hashrate samples. Written to BENCH_WATTS_FILE.
    local wsamples="" pe0="" pt0="" pmax="" w
    if [ -n "${BENCH_WATTS_FILE:-}" ] && [ -z "${TUNE_POWER_CMD:-}" ]; then
        # `|| true` (#290/#301, same idiom as _autotune_sample's #81 guard): no powercap sysfs is an
        # expected "no RAPL" outcome, not a failure — an unguarded _rapl_sum here fires the ERR trap.
        pe0=$(_rapl_sum energy_uj || true)
        pt0=$(_now_s)
        pmax=$(_rapl_sum max_energy_range_uj || true)
    fi
    for i in $(seq 1 "$n"); do
        s=$(_read_api_hashrate)
        [ -n "$s" ] || s=0
        samples+=("$s")
        if [ -n "${BENCH_WATTS_FILE:-}" ] && [ -n "${TUNE_POWER_CMD:-}" ]; then
            w=$(_read_watts_now)
            case "$w" in '') ;; *) wsamples="$wsamples $w" ;; esac
        fi
        [ "$i" -lt "$n" ] && sleep "${TUNE_LIVE_INTERVAL:-30}"
    done
    if [ -n "${BENCH_WATTS_FILE:-}" ]; then
        local pe1="" pt1="" secs="" wout=""
        if [ -n "${TUNE_POWER_CMD:-}" ]; then
            # shellcheck disable=SC2086 # intentional word-split of the sample list
            wout=$(_mean $wsamples)
        elif [ -n "$pe0" ]; then
            pe1=$(_rapl_sum energy_uj || true) # guard (#301): a mid-window sysfs read can still miss
            pt1=$(_now_s)
            secs=$(awk -v a="$pt0" -v b="$pt1" 'BEGIN { if (a == "" || b == "") exit; printf "%.3f", b - a }')
            wout=$(_watts_from_energy "$pe0" "$pe1" "${pmax:-0}" "$secs")
        fi
        printf '%s' "$wout" >"$BENCH_WATTS_FILE"
    fi
    _median "${samples[@]}"
}

# Measure one candidate (memoized): median over TUNE_ITERS bench runs, or one live window. On a cache
# miss it also records the candidate — samples, median, and any temp/watts — to the results log.
_measure() { # <prefetch> <yield> <threads> <onegb> <priority> <hpjit> <cacheqos> <wrmsr> -> median H/s
    local p="$1" y="$2" t="$3" g="$4" pr="$5" hj="$6" cq="$7" wr="$8" key="$1|$2|$3|$4|$5|$6|$7|$8" cached
    cached=$(_memo_get "$key")
    if [ -n "$cached" ]; then
        printf '%s' "$cached"
        return 0
    fi

    local med samples=() s i cfg minfk="" bf watts="" wsamps=() wv
    if [ "$TUNE_MODE" = live ]; then
        : >"$TUNE_TMP/watts" # #81: _measure_live writes the under-load average watts here
        med=$(BENCH_WATTS_FILE="$TUNE_TMP/watts" _measure_live "$p" "$y" "$t" "$g" "$pr" "$hj" "$cq" "$wr")
        [ -n "$med" ] || med=0
        samples=("$med")
        watts=$(cat "$TUNE_TMP/watts" 2>/dev/null)
    else
        cfg="$TUNE_TMP/cand.json"
        _tune_config "$cfg" "$p" "$y" "$t" "$g" "$pr" "$hj" "$cq" "$wr"
        for i in $(seq 1 "${TUNE_ITERS:-5}"); do
            : >"$TUNE_TMP/freq"  # #62: _xmrig_bench writes the effective clock seen during this run
            : >"$TUNE_TMP/watts" # #81: ... and the average watts under load
            s=$(BENCH_FREQ_FILE="$TUNE_TMP/freq" BENCH_WATTS_FILE="$TUNE_TMP/watts" _bench_once "$cfg")
            [ -n "$s" ] || s=0
            samples+=("$s")
            bf=$(cat "$TUNE_TMP/freq" 2>/dev/null)
            # The freq writer above already floors to whole kHz (awk's OFMT prints large medians in
            # scientific notation, e.g. 4.6275e+06, which this floor would otherwise mangle into "4").
            # This is now just a belt-and-suspenders trim of a stray fractional part.
            bf=${bf%.*}
            case "$bf" in '' | *[!0-9]*) ;; *) if [ -z "$minfk" ] || [ "$bf" -lt "$minfk" ]; then minfk="$bf"; fi ;; esac
            wv=$(cat "$TUNE_TMP/watts" 2>/dev/null)
            case "$wv" in '' | *[!0-9.]*) ;; *) wsamps+=("$wv") ;; esac
        done
        med=$(_median "${samples[@]}")
        [ -n "$med" ] || med=0
        [ "${#wsamps[@]}" -gt 0 ] && watts=$(_median "${wsamps[@]}") # median load watts across the iters
    fi

    # #62: a candidate whose sustained clock fell below TUNE_MIN_FREQ_MHZ thermally throttled — its number
    # reflects the throttle, not the config, so flag it (logged + memoized) and never adopt it (gate below).
    local throttled=0 minfmhz=""
    if [ -n "$minfk" ] && [ "${TUNE_MIN_FREQ_MHZ:-0}" -gt 0 ] 2>/dev/null; then
        minfmhz=$((minfk / 1000))
        if [ "$minfmhz" -lt "$TUNE_MIN_FREQ_MHZ" ]; then throttled=1; fi
    fi
    if [ "$throttled" = 1 ]; then warn "  tune: candidate throttled to ${minfmhz} MHz (< ${TUNE_MIN_FREQ_MHZ} MHz min) — reading unreliable, skipping it." >&2; fi

    # #65: did this candidate's thread count exceed the HugePages reservation? Recorded per-candidate and
    # summarized at the end of tune. Only meaningful for a concrete count ("-1" lets XMRig auto-size to fit).
    local hpcapped=false
    if [ -n "${HP_CAP_THREADS:-}" ] && [ "$t" != "-1" ] && [ "$t" -gt "$HP_CAP_THREADS" ] 2>/dev/null; then hpcapped=true; fi

    local sd temp
    sd=$(_stddev "${samples[@]}") # sample spread, for the variance-aware acceptance gate (#63)
    # #81: watts is the median UNDER-LOAD reading collected during the window above (no longer a post-bench
    # idle sample), so hs_per_watt below ranks candidates by real load efficiency.
    temp=$(_read_temp)
    jq -cn --argjson p "$p" --argjson y "$y" --arg t "$t" --argjson g "$g" --argjson pr "$pr" \
        --argjson hj "$hj" --argjson cq "$cq" --argjson wr "$wr" --argjson med "$med" --arg samples "${samples[*]}" \
        --arg sd "${sd:-0}" --arg mf "${minfmhz:-}" --argjson thr "$throttled" --arg hpc "$hpcapped" --arg watts "${watts:-}" --arg temp "${temp:-}" '
        { prefetch_mode: $p, yield: $y, threads: ($t|tonumber), "1gb-pages": $g, priority: $pr,
          "huge-pages-jit": $hj, cache_qos: $cq, wrmsr: $wr,
          hashrate: $med, samples: ($samples|split(" ")|map(tonumber)), stddev: ($sd|tonumber),
          min_freq_mhz: (if $mf=="" then null else ($mf|tonumber) end), throttled: ($thr==1),
          hugepages_capped: ($hpc=="true"),
          watts: (if $watts=="" then null else ($watts|tonumber) end),
          temp_c: (if $temp=="" then null else ($temp|tonumber) end),
          hs_per_watt: (if $watts=="" or ($watts|tonumber)==0 then null else ($med/($watts|tonumber)) end) }' \
        >>"$RESULTS_FILE"
    # #79: store hashrate-per-watt for the efficiency-target gate (empty when there's no power reading).
    local hpw
    hpw=$(awk -v m="$med" -v w="${watts:-0}" 'BEGIN{if(w+0>0)printf "%.4f",m/w}')
    _memo_put "$key" "$med"
    _memo_sd_put "$key" "${sd:-0}"
    _memo_thr_put "$key" "$throttled"
    _memo_hpw_put "$key" "$hpw"
    printf '%s' "$med"
}

# Knob registry: the candidate values for each knob, and get/set of the current state (S_*). Encapsulates
# the bash-3.2-friendly indirection so the hill-climb loop stays generic over knob names.
_knob_values() {
    case "$1" in
    prefetch) echo "$TUNE_PREFETCH_MODES" ;;
    yield) echo "$TUNE_YIELDS" ;;
    threads) echo "$TUNE_THREADS" ;;
    onegb) echo "$TUNE_ONEGB" ;;
    priority) echo "$TUNE_PRIORITIES" ;;
    hpjit) echo "$TUNE_HPJIT" ;;
    cacheqos) echo "$TUNE_CACHEQOS" ;;
    wrmsr) echo "$TUNE_WRMSR" ;;
    esac
}
_knob_get() {
    case "$1" in
    prefetch) echo "$S_p" ;; yield) echo "$S_y" ;; threads) echo "$S_t" ;;
    onegb) echo "$S_g" ;; priority) echo "$S_pr" ;;
    hpjit) echo "$S_hj" ;; cacheqos) echo "$S_cq" ;; wrmsr) echo "$S_wr" ;;
    esac
}
_knob_set() {
    case "$1" in
    prefetch) S_p="$2" ;; yield) S_y="$2" ;; threads) S_t="$2" ;;
    onegb) S_g="$2" ;; priority) S_pr="$2" ;;
    hpjit) S_hj="$2" ;; cacheqos) S_cq="$2" ;; wrmsr) S_wr="$2" ;;
    esac
}
_measure_state() { _measure "$S_p" "$S_y" "$S_t" "$S_g" "$S_pr" "$S_hj" "$S_cq" "$S_wr"; }

# #65: HugePages-reservation awareness. A thread candidate that needs more 2MB pages than are reserved
# runs WITHOUT full huge-page backing, so its benchmark is an unfair lower bound. `avail` = the current
# reservation (HugePages_Total); `need` = proposed-grub.sh's page math for a thread count — the SAME
# source of truth `setup` uses, so the two never disagree. Both empty/0 when unavailable (e.g. macOS).
_hugepages_2m_avail() { # echoes the reserved 2MB page count, or nothing (never errors under set -e)
    [ -r "$MEMINFO" ] || return 0
    awk '/^HugePages_Total:/ {print $2; exit}' "$MEMINFO" 2>/dev/null
}
_hugepages_2m_need() { # <threads> -> 2MB pages needed (via proposed-grub.sh), empty if unavailable
    [ -f "$SCRIPT_DIR/util/proposed-grub.sh" ] || return 0
    RX_THREADS="$1" "$SCRIPT_DIR/util/proposed-grub.sh" --runtime 2>/dev/null
}

# A sensible RandomX thread count for this CPU (~one thread per 2 MB of L3, clamped to the core count),
# or empty if it can't be determined. RandomX peaks near L3/2 MB; more threads thrash the cache.
_l3_thread_center() {
    [ "$OS_TYPE" = "Linux" ] || return 0
    local l3 mb cores c
    l3=$(lscpu 2>/dev/null | awk -F: '/L3 cache/ {gsub(/^[ \t]+/,"",$2); print $2; exit}') || true
    [ -n "$l3" ] || return 0
    mb=$(printf '%s' "$l3" | awk '{ v=$1; u=$2;
        if (u ~ /Ki/) v=v/1024; else if (u ~ /Gi/) v=v*1024; else if (v>100000) v=v/1024/1024;
        printf "%d", v }') || true
    [ -n "$mb" ] && [ "$mb" -gt 0 ] 2>/dev/null || return 0
    cores=$(nproc 2>/dev/null || echo 0)
    c=$((mb / 2))
    [ "$c" -lt 1 ] && c=1
    [ "$cores" -gt 0 ] && [ "$c" -gt "$cores" ] && c="$cores"
    echo "$c"
}

# Physical core count (Core(s) per socket × Socket(s) from lscpu), or empty if undeterminable. RandomX
# often peaks at one thread per PHYSICAL core, because SMT siblings share the L2/L3 a thread needs.
_physical_cores() {
    [ "$OS_TYPE" = "Linux" ] || return 0
    local cps sk
    cps=$(lscpu 2>/dev/null | awk -F: '/^Core\(s\) per socket:/ {gsub(/[^0-9]/,"",$2); print $2; exit}')
    sk=$(lscpu 2>/dev/null | awk -F: '/^Socket\(s\):/ {gsub(/[^0-9]/,"",$2); print $2; exit}')
    [ -n "$cps" ] && [ -n "$sk" ] && [ "$cps" -gt 0 ] 2>/dev/null && [ "$sk" -gt 0 ] 2>/dev/null || return 0
    echo $((cps * sk))
}

# Thread-count candidates to benchmark: "-1" (XMRig's own L3-aware auto), the physical-core count and the
# logical-core count (to probe SMT-off vs SMT-on), and a ±2 window around the L3-derived center (~L3/2 MB
# per thread). All clamped to [1, logical cores] and de-duplicated. A wider, SMT-aware set than a bare
# ±1 window — thread placement/count is one of RandomX's biggest levers.
_thread_candidates() { # <center>
    local c="$1" cores phys list="-1" v
    cores=$(nproc 2>/dev/null || echo 0)
    phys=$(_physical_cores)
    for v in "$phys" "$cores" "$((c - 2))" "$((c - 1))" "$c" "$((c + 1))" "$((c + 2))"; do
        [ -n "$v" ] && [ "$v" -ge 1 ] 2>/dev/null || continue
        [ "$cores" -gt 0 ] && [ "$v" -gt "$cores" ] && continue
        case " $list " in *" $v "*) ;; *) list="$list $v" ;; esac
    done
    echo "$list"
}

# --- Auto-tuning: search strategies & seeding ---

# Coordinate hill-climb from the current S_* state: sweep each active knob, adopt the best value that
# beats the running best by TUNE_MIN_DELTA, and repeat rounds until a pass makes no gain (plateau).
# Echoes the best hashrate reached; leaves S_* at the winning combination.
_hillclimb() {
    # Returns its result in the HILL_BEST global and leaves S_* at the winning combination. It must be
    # called DIRECTLY (not via $(...)), because a command-substitution subshell would discard the S_*
    # mutations; the memo and results survive regardless because they are file-backed. Progress is
    # logged to stderr to keep stdout clean.
    local best best_key round=0 improved knob cur best_v best_here best_here_key v cand cand_key
    best=$(_measure_state)
    best_key=$(_state_key) # #63: track each best's memo key so the gate can read its sample spread
    while [ "$round" -lt "${TUNE_MAX_ROUNDS:-3}" ]; do
        round=$((round + 1))
        improved=0
        for knob in $ACTIVE_KNOBS; do
            cur=$(_knob_get "$knob")
            best_v="$cur"
            best_here="$best"
            best_here_key="$best_key"
            for v in $(_knob_values "$knob"); do
                [ "$v" = "$cur" ] && continue
                _knob_set "$knob" "$v"
                cand=$(_measure_state)
                cand_key=$(_state_key) # capture while S_* still holds the candidate
                _knob_set "$knob" "$cur"
                log "    try $knob=$v -> $cand H/s" >&2
                if _accept_better "$cand" "$cand_key" "$best_here" "$best_here_key"; then
                    best_here="$cand"
                    best_v="$v"
                    best_here_key="$cand_key"
                fi
            done
            if [ "$best_v" != "$cur" ]; then
                _knob_set "$knob" "$best_v"
                best="$best_here"
                best_key="$best_here_key"
                improved=1
                log "  adopt $knob=$best_v ($best H/s)" >&2
            fi
        done
        [ "$improved" -eq 0 ] && {
            log "  plateau after round $round." >&2
            break
        }
    done
    HILL_BEST="$best"
}

# Exhaustive grid search (#6; opt-in via TUNE_SEARCH=grid). Measures every combination of the knobs'
# candidate values and keeps the best — slower than the hill-climb but immune to local optima and knob
# interactions, worth it for this small discrete space. Inactive knobs have a single candidate, so they
# contribute one iteration each. Sets the G_* winner globals directly (tune()'s locals, via dynamic
# scope), so it must be called DIRECTLY, not in a $(...) subshell.
_gridsearch() {
    local vp vy vt vg vpr vhj vcq vwr hr
    for vp in $(_knob_values prefetch); do
        for vy in $(_knob_values yield); do
            for vt in $(_knob_values threads); do
                for vg in $(_knob_values onegb); do
                    for vpr in $(_knob_values priority); do
                        for vhj in $(_knob_values hpjit); do
                            for vcq in $(_knob_values cacheqos); do
                                for vwr in $(_knob_values wrmsr); do
                                    hr=$(_measure "$vp" "$vy" "$vt" "$vg" "$vpr" "$vhj" "$vcq" "$vwr")
                                    log "    grid prefetch=$vp yield=$vy threads=$vt 1gb=$vg prio=$vpr hpjit=$vhj cacheqos=$vcq wrmsr=$vwr -> $hr H/s" >&2
                                    if [ "$G_best" = "-1" ] || _accept_better "$hr" "$vp|$vy|$vt|$vg|$vpr|$vhj|$vcq|$vwr" "$G_best" "$G_best_key"; then
                                        G_best="$hr"
                                        G_best_key="$vp|$vy|$vt|$vg|$vpr|$vhj|$vcq|$vwr"
                                        G_p="$vp"
                                        G_y="$vy"
                                        G_t="$vt"
                                        G_g="$vg"
                                        G_pr="$vpr"
                                        G_hj="$vhj"
                                        G_cq="$vcq"
                                        G_wr="$vwr"
                                    fi
                                done
                            done
                        done
                    done
                done
            done
        done
    done
}

# The base config's value for the two off-by-default knobs (huge-pages-jit, cache_qos), so a seed starts
# from what the generated config actually uses (both default false). Shared by the seeds.
_seed_hj() { jq -r '.cpu."huge-pages-jit" // false' "$TUNE_BASE"; }
_seed_cq() { jq -r '.randomx.cache_qos // false' "$TUNE_BASE"; }
_seed_g() { jq -r '.randomx | if has("1gb-pages") then ."1gb-pages" else true end' "$TUNE_BASE"; } # base 1gb-pages value (default true)
# wrmsr seed: the base config's value as a single token (true/false/number). An array (advanced custom
# MSRs) isn't a sweepable scalar, so seed from the safe default 'true' and let the operator set TUNE_WRMSR.
_seed_wr() { jq -r '(.randomx | if has("wrmsr") then .wrmsr else true end) | if (type=="boolean" or type=="number") then tostring else "true" end' "$TUNE_BASE"; }

# Seed the state with XMRig's auto baseline (the generated config's own values; threads left to auto).
_seed_auto() {
    S_p=$(jq -r '.randomx.scratchpad_prefetch_mode // 1' "$TUNE_BASE")
    S_y=$(jq -r '.cpu.yield // false' "$TUNE_BASE")
    S_g=$(_seed_g)
    S_pr=$(jq -r '.cpu.priority // 2' "$TUNE_BASE")
    S_t="-1"
    S_hj=$(_seed_hj)
    S_cq=$(_seed_cq)
    S_wr=$(_seed_wr)
}
# Seed the state with an educated guess (a different starting point so the climb can escape a local
# optimum the auto seed lands in): prefetch=2, yield off, threads sized to L3/2 MB.
_seed_guess() {
    S_p="${TUNE_GUESS_PREFETCH:-2}"
    S_y=false
    S_pr=2
    S_g=$(_seed_g)
    S_t="${TUNE_GUESS_THREADS:-${THREAD_CENTER:--1}}"
    [ -n "$S_t" ] || S_t="-1"
    S_hj=$(_seed_hj)
    S_cq=$(_seed_cq)
    S_wr=$(_seed_wr)
}

# --- Auto-tuning: 'tune' command + live confirm / scheduled autotune ---

# User-facing description of a periodic-autotune target, in the SAME vocabulary the operator types in
# config.json ("performance"/"efficiency"/"disabled"). Accepts either the config mode or the internal
# target (perf -> performance), so every autotune surface — setup, apply, tune --history, the run log —
# speaks one consistent language (the offline `tune` command keeps its own "perf"/"--perf" vocabulary).
_autotune_desc() {
    case "$1" in
    efficiency) printf 'efficiency (hashrate-per-watt)' ;;
    disabled) printf 'disabled' ;;
    *) printf 'performance (raw hashrate)' ;;
    esac
}

# `tune --history`: a readable summary of this rig's tuning — what knobs are applied now, the last full
# `tune` run, and (Linux) the periodic autotune timer's recent decisions. Read-only and best-effort:
# every probe is guarded so it never aborts, and it degrades gracefully when nothing's been tuned yet.
_tune_history() { # <overrides_file> <log_file>
    local ovr="$1" logf="$2" when target best n recent sched next tgt has_log=0
    # Read the last full run's summary up front (the best hashrate goes with the winning knobs).
    if [ -s "$logf" ] && jq -e . "$logf" >/dev/null 2>&1; then
        has_log=1
        if [ "$OS_TYPE" = Darwin ]; then when=$(stat -f '%Sm' -t '%Y-%m-%d %H:%M' "$logf" 2>/dev/null || echo "?"); else when=$(date -r "$logf" '+%Y-%m-%d %H:%M' 2>/dev/null || echo "?"); fi
        target=$(jq -r '.target // "perf"' "$logf" 2>/dev/null || echo perf)
        best=$(jq -r '.best.hashrate // empty' "$logf" 2>/dev/null || true)
        n=$(jq -r '.results | length' "$logf" 2>/dev/null || echo 0)
    fi
    log "Tuning status for this rig"
    echo ""
    if [ -s "$ovr" ] && jq -e . "$ovr" >/dev/null 2>&1; then
        echo "  Winning tune options (applied — $ovr):"
        jq -r '[(.randomx.scratchpad_prefetch_mode|select(.!=null)|"prefetch_mode=\(.)"),(.cpu.rx|select(.!=null)|"threads=\(.)"),(.cpu.yield|select(.!=null)|"yield=\(.)"),(.randomx."1gb-pages"|select(.!=null)|"1gb-pages=\(.)"),(.cpu.priority|select(.!=null)|"priority=\(.)"),(.cpu."huge-pages-jit"|select(.!=null)|"huge-pages-jit=\(.)"),(.randomx.cache_qos|select(.!=null)|"cache_qos=\(.)"),(.randomx.wrmsr|select(.!=null)|"wrmsr=\(.)")]|.[]|"    • "+.' "$ovr" 2>/dev/null || true
        echo "    -> merged into the generated config; the miner is using these now."
    else
        echo "  Winning tune options: none yet — running XMRig's auto defaults."
        echo "    Run 'sudo $0 tune' to measure the fastest knobs for this CPU."
    fi
    echo ""
    if [ "$has_log" = 1 ]; then
        echo "  Last full tune ($when): target=${target:-perf}, ${n:-0} candidate(s) tried${best:+, best $best H/s}"
        echo "    full search log: $logf"
    else
        echo "  Last full tune: none recorded yet."
    fi
    echo ""
    if [ "$OS_TYPE" = Linux ] && command -v systemctl >/dev/null 2>&1 && systemctl cat rigforge-autotune.timer >/dev/null 2>&1; then
        echo "  Periodic autotune: enabled ($(systemctl is-active rigforge-autotune.timer 2>/dev/null || echo unknown))."
        tgt=$(systemctl cat rigforge-autotune.service 2>/dev/null | sed -nE 's/^Environment=AUTOTUNE_TARGET=//p' | head -1)
        [ -n "$tgt" ] && echo "    optimizing for: $(_autotune_desc "$tgt")"
        sched=$(systemctl cat rigforge-autotune.timer 2>/dev/null | sed -nE 's/^OnCalendar=//p' | head -1)
        next=$(systemctl show rigforge-autotune.timer -p NextElapseUSecRealtime --value 2>/dev/null || true)
        [ -n "$sched" ] && echo "    schedule: $sched${next:+ — next run: $next}"
        recent=$(journalctl -u rigforge-autotune.service --no-pager -o cat -n 500 2>/dev/null | sed -E 's/\x1b\[[0-9;]*m//g' | grep -aE 'autotune: (prefetch_mode=|best |no mode|could not)' | sed -E 's/^\[(INFO|WARN)\] autotune: //' | tail -5 || true)
        if [ -n "$recent" ]; then
            echo "    recent decisions:"
            printf '%s\n' "$recent" | sed 's/^/      /'
        else
            echo "    no runs logged yet — it fires on the schedule above."
        fi
        echo "    full log: journalctl -u rigforge-autotune"
    else
        echo "  Periodic autotune: off. Set \"autotune\": \"performance\" (or \"efficiency\") in config.json, then re-run 'sudo $0 setup' to enable it."
    fi
}

# Whether `tune` should re-exec itself under sudo: non-root + interactive (TTY) only, so sudo can actually
# prompt and we never surprise non-interactive callers (tests/cron/pipes). RIGFORGE_FORCE_ELEVATE=1 forces
# it regardless (the coverage test drives this path from a real child process).
_tune_should_elevate() {
    [ "${RIGFORGE_FORCE_ELEVATE:-0}" = 1 ] && return 0
    [ "$(id -u)" -ne 0 ] && [ -t 0 ]
}

tune() {
    # tune mutates system + worker state as root (stops the service, writes tuning as root), so auto-elevate
    # when run without sudo — a plain `rigforge tune` then just works (sudo prompts) instead of failing
    # partway with a cryptic error. Interactive-only (_tune_can_elevate): it keeps non-interactive callers
    # (the test suite, cron, pipes) on their existing path — no surprise elevation, and no re-exec loop if
    # `sudo` is a passthrough stub. `--history` is read-only, so it never needs root.
    local _hist=0 clear=0 target_set=0 now=0 now_long=0
    case " $* " in *" --history "*) _hist=1 ;; esac
    if [ "$_hist" = 0 ] && [ "$OS_TYPE" = Linux ] && _tune_should_elevate; then
        log "tune needs root — re-running with sudo..."
        exec sudo "$0" tune "$@"
    fi
    TUNE_MODE="${TUNE_MODE:-bench}"
    TUNE_CONFIRM="${TUNE_CONFIRM:-0}" # #64: A/B-confirm the winner against the previous config, live
    # #95: the optimization target defaults to the `autotune` config value (resolved by parse_config below);
    # a TUNE_TARGET env override or an explicit --perf/--efficiency flag wins.
    [ -n "${TUNE_TARGET:-}" ] && target_set=1
    while [ $# -gt 0 ]; do
        case "$1" in
        --clear) clear=1 ;;
        --live) TUNE_MODE=live ;;
        --bench) TUNE_MODE=bench ;;
        --confirm) TUNE_CONFIRM=1 ;;
        --efficiency)
            TUNE_TARGET=efficiency
            target_set=1
            ;; # #79: optimize hashrate-per-watt
        --perf)
            TUNE_TARGET=perf
            target_set=1
            ;;
        --now) now=1 ;;                      # quick on-demand live re-tune (= --short); the 'autotune' engine
        --short) now=1 ;;                    # explicit quick pass — the default depth for --now
        --long) TUNE_MODE=live now_long=1 ;; # full all-knob LIVE sweep (= --live), the thorough re-tune
        --history) TUNE_HISTORY=1 ;;         # show current tuning + last run + auto-tune decisions, then exit
        *) error "Unknown option for tune: '$1' (use --now, --short, --long, --live, --bench, --confirm, --efficiency, --perf, --history, or --clear). Run '$0 help'." ;;
        esac
        shift
    done

    # 'tune --now' (a.k.a. --short) is the on-demand live re-tune: a quick convergent pass against the
    # *running* miner (it IS the 'autotune' engine). 'tune --now --long' instead runs the FULL all-knob
    # live sweep — --long set TUNE_MODE=live and now_long above, so we fall through to the full tune below
    # rather than the quick engine. Exposing all of this under 'tune' gives one mental model — every manual
    # tune lives under 'tune' — and reserves "autotune" for the scheduled feature (config key + timer). The
    # 'autotune' verb still works as an alias for the quick pass, and is the verb the timer runs.
    if [ "$now" = 1 ] && [ "$now_long" != 1 ]; then
        [ "$OS_TYPE" = Linux ] || error "tune --now runs a live re-tune against the systemd service and is Linux-only."
        [ "$target_set" = 1 ] && AUTOTUNE_TARGET="$TUNE_TARGET" # honor --perf/--efficiency for this run
        autotune
        return
    fi

    parse_config # resolves WORKER_ROOT (and validates the config)
    # #95: default the target to what `autotune` is set to in config, unless the user was explicit above.
    [ "$target_set" = 1 ] || TUNE_TARGET="${AUTOTUNE_TARGET:-perf}"
    TUNE_OVERRIDES="$WORKER_ROOT/tune-overrides.json"
    local logf="$WORKER_ROOT/rigforge-tune.json"
    local pre_overrides="" # #64: the overrides in place BEFORE this run, to A/B against and revert to
    [ -f "$TUNE_OVERRIDES" ] && pre_overrides=$(cat "$TUNE_OVERRIDES" 2>/dev/null)

    if [ "${TUNE_HISTORY:-0}" = 1 ]; then
        _tune_history "$TUNE_OVERRIDES" "$logf" # read-only; works without a built worker
        return 0
    fi

    if [ "$clear" = 1 ]; then
        sudo rm -f "$TUNE_OVERRIDES" "$logf"
        log "Cleared tuning state. Run 'sudo $0 apply' to regenerate the baseline config."
        return 0
    fi

    if [ "$TUNE_MODE" = live ] && [ "$OS_TYPE" != "Linux" ]; then
        error "tune --live drives the running systemd service and is only supported on Linux."
    fi

    local build="$WORKER_ROOT/xmrig/build"
    TUNE_BIN="$build/xmrig"
    TUNE_BASE="$build/config.json"
    [ -x "$TUNE_BIN" ] && [ -f "$TUNE_BASE" ] || error "No built worker at $build. Run 'setup' first, then 'tune'."

    TUNE_BENCH="${TUNE_BENCH:-10M}" # longer = steadier and closer to sustained load. You tune once and
    # run for months, so the default favors thoroughness over speed; set TUNE_BENCH=1M for a quick pass.
    TUNE_ITERS="${TUNE_ITERS:-5}"            # median of 5 short benches: steadier than 3 against RandomX jitter (#3)
    TUNE_MIN_DELTA="${TUNE_MIN_DELTA:-0.01}" # minimum relative win (floor)
    TUNE_SIGMA="${TUNE_SIGMA:-1}"            # #63: also require the win to exceed this × the combined sample noise band
    # #79: efficiency mode ranks by hashrate-per-watt, which needs a power source. Without RAPL or
    # TUNE_POWER_CMD, fall back to perf rather than "optimizing" on a metric we can't measure.
    if [ "$TUNE_TARGET" = efficiency ] && ! _power_supported; then
        warn "tune --efficiency needs a power source (built-in RAPL or TUNE_POWER_CMD) — none available; optimizing for raw hashrate (perf) instead."
        TUNE_TARGET=perf
    fi
    local tgt_src=""
    [ "$target_set" = 1 ] || tgt_src=" (from your autotune config; override with --perf/--efficiency)"
    log "Optimization target: $(_autotune_desc "$TUNE_TARGET")${tgt_src}."
    # #62: a candidate whose effective clock dipped below this during its window thermally throttled and is
    # skipped. Default ~80% of max boost (all-core RandomX should hold well above that); 0 disables it.
    if [ -z "${TUNE_MIN_FREQ_MHZ:-}" ]; then
        local _maxk=""
        if [ -r "$CPUFREQ_MAX" ]; then _maxk=$(cat "$CPUFREQ_MAX" 2>/dev/null) || _maxk=""; fi
        if [ -n "$_maxk" ] && [ "$_maxk" -gt 0 ] 2>/dev/null; then TUNE_MIN_FREQ_MHZ=$((_maxk * 80 / 100 / 1000)); fi
    fi
    TUNE_MIN_FREQ_MHZ="${TUNE_MIN_FREQ_MHZ:-0}"
    TUNE_MAX_ROUNDS="${TUNE_MAX_ROUNDS:-3}"
    TUNE_SEARCH="${TUNE_SEARCH:-climb}" # climb = hill-climb (fast); grid = exhaustive (robust, slower) (#6)
    TUNE_SEEDS="${TUNE_SEEDS:-auto guess}"
    TUNE_PREFETCH_MODES="${TUNE_PREFETCH_MODES:-0 1 2 3}"
    TUNE_YIELDS="${TUNE_YIELDS:-true false}"
    TUNE_PRIORITIES="${TUNE_PRIORITIES:-2}" # single value => knob off by default
    # Off-by-default knobs (single value => not searched). huge-pages-jit can help some Ryzen but XMRig
    # warns it makes hashrate unstable; cache_qos is an Intel L3-CAT lever. Sweep with e.g.
    # TUNE_HPJIT="false true" (it then gets pinned only if it actually wins).
    TUNE_HPJIT="${TUNE_HPJIT:-$(_seed_hj)}"
    TUNE_CACHEQOS="${TUNE_CACHEQOS:-$(_seed_cq)}"
    # randomx.wrmsr (#66): off by default (single value = base config's). XMRig auto-picks a per-family MSR
    # preset for `true`; sweep alternatives with e.g. TUNE_WRMSR="true false" or a preset number
    # (TUNE_WRMSR="true 1"). Applied at miner start (no reboot), so it's a fair per-bench candidate.
    TUNE_WRMSR="${TUNE_WRMSR:-$(_seed_wr)}"

    # Thread-count knob: candidates around the L3-derived center (none if L3 can't be read, e.g. macOS).
    THREAD_CENTER=$(_l3_thread_center)
    if [ -n "$THREAD_CENTER" ]; then
        TUNE_THREADS="${TUNE_THREADS:-$(_thread_candidates "$THREAD_CENTER")}"
    else
        TUNE_THREADS="${TUNE_THREADS:--1}"
    fi

    # #65: the largest thread count whose 2MB-page need still fits the current reservation. Candidates
    # above it run without full huge-page backing (flagged per-candidate, summarized at the end). Derived
    # from a single need() probe (the per-thread marginal cost is 1 page). Empty disables the check.
    HP_CAP_THREADS=""
    if [ "$OS_TYPE" = Linux ]; then
        local _hpavail _hpneed1
        _hpavail=$(_hugepages_2m_avail) || _hpavail=""
        _hpneed1=$(_hugepages_2m_need 1) || _hpneed1=""
        if [ -n "$_hpavail" ] && [ "$_hpavail" -gt 0 ] 2>/dev/null && [ -n "$_hpneed1" ] && [ "$_hpneed1" -gt 0 ] 2>/dev/null; then
            HP_CAP_THREADS=$((_hpavail - (_hpneed1 - 1)))
            log "HugePages reservation backs up to $HP_CAP_THREADS threads ($_hpavail × 2MB pages reserved)."
        fi
    fi

    # 1gb-pages is reboot-bound (#54): flipping it only matters if the host actually has 1G HugePages
    # reserved (a GRUB change + reboot, done by `setup`). Sweep it only when they're present; otherwise
    # leave it at the base value and say so, rather than benchmarking a no-op.
    local nr=0
    [ -r "$HUGEPAGES_1G_NR" ] && nr=$(cat "$HUGEPAGES_1G_NR" 2>/dev/null || echo 0)
    if [ "${nr:-0}" -gt 0 ] 2>/dev/null; then
        TUNE_ONEGB="${TUNE_ONEGB:-true false}"
    else
        TUNE_ONEGB="$(_seed_g)"
        log "Note: 1G HugePages not reserved — skipping the 1gb-pages knob (it needs a GRUB change + reboot; run 'setup')."
    fi

    # Active knobs = those with more than one candidate value (the rest are fixed, not searched).
    ACTIVE_KNOBS=""
    local k n
    for k in prefetch yield threads onegb priority hpjit cacheqos wrmsr; do
        n=$(_knob_values "$k" | wc -w | tr -d ' ')
        [ "$n" -gt 1 ] && ACTIVE_KNOBS="$ACTIVE_KNOBS $k"
    done

    TUNE_TMP=$(mktemp -d)
    # Cleanup is armed the moment the temp dir exists — an ERR-abort anywhere below (live mode
    # included) must not leak it. _tune_bench_cleanup is idempotent and only restarts the service
    # when _TUNE_SVC_STOPPED says the bench path stopped it. (#135)
    trap '_tune_bench_cleanup' EXIT
    MEMO_FILE="$TUNE_TMP/memo"
    MEMO_SD_FILE="$TUNE_TMP/memo_sd"
    MEMO_THROTTLE_FILE="$TUNE_TMP/memo_throttle"
    MEMO_HPW_FILE="$TUNE_TMP/memo_hpw"
    RESULTS_FILE="$TUNE_TMP/results.jsonl"
    : >"$MEMO_FILE"
    : >"$MEMO_SD_FILE"
    : >"$MEMO_THROTTLE_FILE"
    : >"$MEMO_HPW_FILE"
    : >"$RESULTS_FILE"

    if [ "$TUNE_MODE" = live ]; then
        # #347: from here every candidate lands in tune-overrides.json and restarts the miner on it
        # (_measure_live). Mark the file dirty so the EXIT trap above restores the pre-sweep overrides
        # if the sweep doesn't reach its deliberate winner write below.
        _TUNE_PRE_OVERRIDES="$pre_overrides"
        _TUNE_LIVE_DIRTY=1
        log "Auto-tuning LIVE against the running miner (warmup ${TUNE_LIVE_WARMUP:-60}s, ${TUNE_LIVE_SAMPLES:-3} samples) — search=$TUNE_SEARCH, knobs={$ACTIVE_KNOBS}."
    else
        log "Auto-tuning via 'xmrig --bench=$TUNE_BENCH' (median of $TUNE_ITERS) — search=$TUNE_SEARCH, knobs={$ACTIVE_KNOBS}, min-delta=$TUNE_MIN_DELTA."
        log "Note: '--bench' measures Monero's RandomX (rx/0). For a different RandomX variant (e.g. rx/wow), use 'tune --live' so it measures your actual pool's algorithm."
    fi

    # In offline --bench mode, stop the running miner so the benchmark has the whole machine — CPU and the
    # reserved huge pages — to itself; a service mining alongside would contend for both and turn every
    # reading into noise. Restarted automatically afterwards (even on error/abort) via the cleanup trap.
    # --live mode measures the running service itself, so it must NOT stop it. (#2)
    if [ "$TUNE_MODE" = bench ] && [ "$OS_TYPE" = Linux ] && systemctl is-active --quiet "$SERVICE_NAME" 2>/dev/null; then
        log "Stopping the '$SERVICE_NAME' service for the benchmark run (restarted automatically afterwards)."
        sudo systemctl stop "$SERVICE_NAME" 2>/dev/null || true
        _TUNE_SVC_STOPPED=1
    fi

    local G_best="-1" G_best_key="" G_p="" G_y="" G_t="" G_g="" G_pr="" G_hj="" G_cq="" G_wr="" seed seed_hr
    if [ "$TUNE_SEARCH" = grid ]; then
        local combos=1 kk
        for kk in $ACTIVE_KNOBS; do combos=$((combos * $(_knob_values "$kk" | wc -w | tr -d ' '))); done
        log "Grid search: $combos combination(s) over {$ACTIVE_KNOBS} — exhaustive (no local-optimum risk), slower than the hill-climb."
        _gridsearch # sets the G_* winner globals directly (must NOT run in a subshell)
    else
        for seed in $TUNE_SEEDS; do
            case "$seed" in
            auto) _seed_auto ;;
            guess) _seed_guess ;;
            *)
                warn "Unknown tune seed '$seed' — skipping."
                continue
                ;;
            esac
            log "Seed '$seed': prefetch=$S_p yield=$S_y threads=$S_t 1gb=$S_g priority=$S_pr"
            _hillclimb # sets HILL_BEST and leaves S_* at this seed's winner (must NOT run in a subshell)
            seed_hr="$HILL_BEST"
            log "Seed '$seed' best: prefetch=$S_p yield=$S_y threads=$S_t ($seed_hr H/s)"
            if [ "$G_best" = "-1" ] || _accept_better "$seed_hr" "$(_state_key)" "$G_best" "$G_best_key"; then
                G_best="$seed_hr"
                G_best_key="$(_state_key)"
                G_p="$S_p"
                G_y="$S_y"
                G_t="$S_t"
                G_g="$S_g"
                G_pr="$S_pr"
                G_hj="$S_hj"
                G_cq="$S_cq"
                G_wr="$S_wr"
            fi
        done
    fi

    if [ -z "$G_p" ] || awk -v hr="$G_best" 'BEGIN{exit !(hr <= 0)}'; then
        rm -rf "$TUNE_TMP"
        error "Benchmarks produced no hashrate — check that the worker is built correctly."
    fi

    # Build the overrides snippet from the winning state. Always pin prefetch + yield; pin threads only
    # if a concrete count won (not auto), and priority / 1gb-pages only if they were actually swept — so
    # we never freeze a knob the search didn't explore.
    local ovr
    ovr=$(jq -n --argjson p "$G_p" --argjson y "$G_y" '{randomx:{scratchpad_prefetch_mode:$p}, cpu:{yield:$y}}')
    [ "$G_t" != "-1" ] && ovr=$(printf '%s' "$ovr" | jq --argjson t "$G_t" '.cpu.rx = $t')
    case " $ACTIVE_KNOBS " in *" priority "*) ovr=$(printf '%s' "$ovr" | jq --argjson pr "$G_pr" '.cpu.priority = $pr') ;; esac
    case " $ACTIVE_KNOBS " in *" onegb "*) ovr=$(printf '%s' "$ovr" | jq --argjson g "$G_g" '.randomx."1gb-pages" = $g') ;; esac
    case " $ACTIVE_KNOBS " in *" hpjit "*) ovr=$(printf '%s' "$ovr" | jq --argjson hj "$G_hj" '.cpu."huge-pages-jit" = $hj') ;; esac
    case " $ACTIVE_KNOBS " in *" cacheqos "*) ovr=$(printf '%s' "$ovr" | jq --argjson cq "$G_cq" '.randomx.cache_qos = $cq') ;; esac
    case " $ACTIVE_KNOBS " in *" wrmsr "*) ovr=$(printf '%s' "$ovr" | jq --argjson wr "$G_wr" '.randomx.wrmsr = $wr') ;; esac
    printf '%s\n' "$ovr" >"$TUNE_TMP/ovr.json" && sudo cp "$TUNE_TMP/ovr.json" "$TUNE_OVERRIDES"
    _TUNE_LIVE_DIRTY=0 # #347: the winner — a completed decision — now owns the file; the abort-restore stands down

    # Assemble the full search log: the winner, the search parameters, and every measured candidate.
    jq -s --argjson p "$G_p" --argjson y "$G_y" --arg t "$G_t" --argjson g "$G_g" --argjson pr "$G_pr" \
        --argjson hj "$G_hj" --argjson cq "$G_cq" --argjson wr "$G_wr" --arg target "$TUNE_TARGET" \
        --argjson hr "$G_best" --arg mode "$TUNE_MODE" --arg search "$TUNE_SEARCH" --arg seeds "$TUNE_SEEDS" \
        --argjson iters "$TUNE_ITERS" --argjson delta "$TUNE_MIN_DELTA" '
        { best: { scratchpad_prefetch_mode: $p, yield: $y, threads: ($t|tonumber), "1gb-pages": $g,
                  priority: $pr, "huge-pages-jit": $hj, cache_qos: $cq, wrmsr: $wr, hashrate: $hr },
          mode: $mode, target: $target, search: $search, seeds: ($seeds|split(" ")), iterations: $iters, min_delta: $delta,
          results: . }' "$RESULTS_FILE" >"$TUNE_TMP/log.json" && sudo cp "$TUNE_TMP/log.json" "$logf"

    local hpw=""
    hpw=$(jq -r '[.results[].hs_per_watt // empty] | if length>0 then max else empty end' "$logf" 2>/dev/null || true)
    rm -rf "$TUNE_TMP"

    log "Best: prefetch_mode=$G_p yield=$G_y threads=$G_t ($G_best H/s). Saved to $TUNE_OVERRIDES (log: $logf)."
    [ -n "$hpw" ] && log "Best efficiency observed: $hpw H/s per watt."
    if [ "$OS_TYPE" = Linux ]; then
        # #65: be honest about reservation-capped optima — any candidate that needed more 2MB HugePages
        # than reserved ran without full backing, so its number is a floor, not a fair comparison.
        local capped=""
        capped=$(jq -r '[.results[]|select(.hugepages_capped==true)|.threads]|unique|sort|map(tostring)|join(", ")' "$logf" 2>/dev/null) || capped=""
        if [ -n "$capped" ]; then
            warn "HugePages-capped: thread counts {$capped} need more 2MB pages than are reserved, so they ran WITHOUT full backing — their hashrate is a floor, not a fair reading. To explore them properly: 'sudo RIGFORGE_THREADS=<n> $0 setup', reboot, then re-tune."
        fi
        if [ "$G_t" != "-1" ]; then
            log "Note: cpu.rx is pinned to $G_t threads. 'setup' now sizes the HugePages reservation to the tuned thread count automatically — re-run 'sudo $0 setup' (reboot) if 'doctor' ever reports HugePages below 100%."
        fi
    fi
    if [ "$TUNE_CONFIRM" = 1 ] && [ "$OS_TYPE" = Linux ]; then
        _tune_confirm_live "$ovr" "$pre_overrides"
    elif [ "$TUNE_MODE" = live ]; then
        _apply_runtime >/dev/null 2>&1 || true
        log "Applied the winning config to the live miner."
    else
        log "Apply it: sudo $0 apply    (reset anytime with: sudo $0 tune --clear)"
        [ "$OS_TYPE" = Linux ] && log "Or confirm it live first: sudo $0 tune --confirm"
    fi
    _reown_worker # the tune-overrides / log were written via sudo — hand them back to the operator
}

# #64: A/B-confirm the tuned winner against the PREVIOUS config on the live miner. bench/grid measure in
# offline --bench conditions, which differ from production — so optionally apply the winner, measure it
# live over a window, then restore the previous config and measure THAT, and keep the winner only if it
# genuinely wins live (else leave the previous config in place). Reuses _sample_api_median + a margin.
_tune_confirm_live() { # <winner_overrides_json> <previous_overrides_json>
    local win_ovr="$1" pre_ovr="$2"
    local n="${TUNE_LIVE_SAMPLES:-3}" iv="${TUNE_LIVE_INTERVAL:-30}" warm="${TUNE_LIVE_WARMUP:-60}"
    local margin="${TUNE_CONFIRM_MARGIN:-${TUNE_MIN_DELTA:-0.01}}" win_hr base_hr
    log "Confirming the tuned config against the previous one on the live miner (A/B)..."
    _apply_runtime >/dev/null 2>&1 || true # the winner is already in TUNE_OVERRIDES from the search
    sleep "$warm"
    win_hr=$(_sample_api_median "$n" "$iv")
    [ -n "$win_hr" ] || win_hr=0
    _restore_overrides "$pre_ovr"
    sleep "$warm"
    base_hr=$(_sample_api_median "$n" "$iv")
    [ -n "$base_hr" ] || base_hr=0
    if awk -v w="$win_hr" -v b="$base_hr" -v m="$margin" 'BEGIN{exit !(w > b * (1 + m))}'; then
        printf '%s\n' "$win_ovr" | sudo tee "$TUNE_OVERRIDES" >/dev/null
        _apply_runtime >/dev/null 2>&1 || true
        log "Confirmed: the tuned config wins live ($win_hr vs $base_hr H/s) — kept and applied."
    else
        log "Reverted: the tuned config did NOT beat the previous one live ($win_hr vs $base_hr H/s) — restored the previous config."
    fi
}

# Merge a prefetch-mode change INTO the existing overrides file, preserving every other tuned knob it
# already holds (#46 fix: autotune used to overwrite the whole file, silently dropping a prior `tune`'s
# threads/yield/1gb-pages). A no-op-safe `{}` base is used when no overrides exist yet.
_autotune_set_prefetch() { # <overrides_file> <mode>
    local f="$1" m="$2" base='{}' tmp
    [ -f "$f" ] && base=$(cat "$f" 2>/dev/null)
    [ -n "$base" ] || base='{}'
    tmp=$(mktemp)
    if printf '%s' "$base" | jq --argjson m "$m" '.randomx.scratchpad_prefetch_mode = $m' >"$tmp" 2>/dev/null; then
        sudo cp "$tmp" "$f"
    fi
    rm -f "$tmp"
}

# #347: autotune's abort protection. Each trial merges a candidate prefetch mode into the overrides file
# and restarts the miner on it — an abort mid-sweep would otherwise persist that candidate. The EXIT trap
# restores the pre-sweep mode through the SAME settle step the clean path ends with, so the two cannot
# diverge. The merge-based restore (_autotune_set_prefetch) preserves any offline-`tune` knobs, exactly
# like the sweep's own writes.
_AUTOTUNE_DIRTY=0
_AUTOTUNE_PRE_MODE=""
_AUTOTUNE_OVR_FILE=""
_autotune_settle() { # <mode> — merge the mode into the overrides and leave the miner running on it
    _autotune_set_prefetch "$_AUTOTUNE_OVR_FILE" "$1"
    _apply_runtime >/dev/null 2>&1 || true
}
_autotune_cleanup() {
    if [ "${_AUTOTUNE_DIRTY:-0}" = 1 ]; then
        _AUTOTUNE_DIRTY=0
        log "autotune: sweep interrupted — restoring prefetch_mode=$_AUTOTUNE_PRE_MODE."
        _autotune_settle "$_AUTOTUNE_PRE_MODE"
    fi
}

# Sample the live miner for one candidate: median H/s over the window and, for the efficiency target,
# the average package watts over that SAME window — prints "hr<TAB>watts" (watts empty for perf or when
# no power source). RAPL brackets the sampling window; a TUNE_POWER_CMD override is polled once per
# sample and averaged (parity with tune's _measure_live, #81). Perf skips power entirely (no overhead).
_autotune_sample() { # <n> <interval> <target>
    local n="${1:-3}" iv="${2:-10}" target="${3:-perf}" hr watts="" i s out=() polls=() e0 e1 mx t0 t1
    if [ "$target" != efficiency ]; then
        printf '%s\t' "$(_sample_api_median "$n" "$iv")"
        return 0
    fi
    if [ -n "${TUNE_POWER_CMD:-}" ]; then
        for i in $(seq 1 "$n"); do
            s=$(_read_api_hashrate)
            [ -n "$s" ] || s=0
            out+=("$s")
            s=$(_read_watts_now)
            [ -n "$s" ] && polls+=("$s")
            [ "$i" -lt "$n" ] && [ "$iv" -gt 0 ] 2>/dev/null && sleep "$iv"
        done
        hr=$(_median "${out[@]}")
        [ "${#polls[@]}" -gt 0 ] && watts=$(_mean "${polls[@]}")
    else
        e0=$(_rapl_sum energy_uj || true)
        t0=$(_now_s)
        hr=$(_sample_api_median "$n" "$iv")
        if [ -n "$e0" ]; then
            e1=$(_rapl_sum energy_uj || true)
            mx=$(_rapl_sum max_energy_range_uj || true)
            t1=$(_now_s)
            watts=$(_watts_from_energy "$e0" "$e1" "$mx" "$(awk -v a="$t0" -v b="$t1" 'BEGIN{printf "%.3f", (b - a)}')")
        fi
    fi
    printf '%s\t%s' "${hr:-0}" "$watts"
}
# Score a sample for the active target: efficiency -> hashrate-per-watt (falls back to raw H/s if watts
# are missing so the sweep still progresses); perf -> raw H/s. Drives both ranking and the margin gate.
_autotune_score() { # <target> <hr> <watts>
    if [ "$1" = efficiency ] && [ -n "$3" ] && awk -v w="$3" 'BEGIN{exit !(w > 0)}'; then
        awk -v h="$2" -v w="$3" 'BEGIN{printf "%.4f", h / w}'
    else
        printf '%s' "${2:-0}"
    fi
}
# Human-readable sample for the log line: "10700 H/s" or "10700 H/s, 83.10 W, 128.84 H/s/W".
_autotune_fmt() { # <target> <hr> <watts>
    if [ "$1" = efficiency ] && [ -n "$3" ] && awk -v w="$3" 'BEGIN{exit !(w > 0)}'; then
        awk -v h="$2" -v w="$3" 'BEGIN{printf "%s H/s, %.2f W, %.2f H/s/W", h, w, h / w}'
    else
        printf '%s H/s' "${2:-0}"
    fi
}

# autotune (#46, #95): ONE convergent live pass against the running miner. It reads the current hashrate
# from the worker's HTTP API (median of a few samples — live numbers are noisy), then sweeps EVERY
# prefetch mode it isn't already on — applying each (MERGED into the overrides file, preserving any
# offline-`tune` knobs), restarting, and measuring over a warmup window — and adopts the best, but only
# if it beats the baseline by a margin (else it keeps the current mode). The target (#95) decides what
# "best" means: "performance" ranks raw H/s; "efficiency" ranks hashrate-per-watt (falling back to perf
# with a warning when no power source exists, like `tune --efficiency`). So a single run converges the
# prefetch knob (~minutes). Once converged it's stable, so re-tuning is event-driven: `upgrade` runs it
# after a rebuild (the fastest knobs can shift between XMRig versions — the real trigger), and a slow
# safety-net timer catches drift. With `autotune: "performance"|"efficiency"` in config.json, setup
# installs that timer (default monthly; AUTOTUNE_ONCALENDAR) with the target baked into the unit. Median +
# margin keep noisy readings from sticking. For a thorough sweep of ALL knobs, run `tune`.
autotune() {
    if [ "$OS_TYPE" != "Linux" ]; then
        error "autotune drives the live systemd service and is only supported on Linux."
    fi
    # The scheduled run gets AUTOTUNE_TARGET from the systemd unit's env (baked at setup); capture it
    # before parse_config re-derives one from config.json so the unit's choice wins. An interactive run
    # (no unit env) falls through to the config value.
    local target_env="${AUTOTUNE_TARGET:-}"
    parse_config
    local overrides="$WORKER_ROOT/tune-overrides.json"
    local n="${AUTOTUNE_SAMPLES:-3}" iv="${AUTOTUNE_INTERVAL:-10}" warm="${AUTOTUNE_WARMUP:-60}"
    local margin="${AUTOTUNE_MARGIN:-0.01}" modes="${AUTOTUNE_MODES:-0 1 2 3}"
    local target="${target_env:-${AUTOTUNE_TARGET:-perf}}"
    local cur base_hr base_w base_score best_mode best_score m hr w sc last_applied s unit

    # #95: efficiency ranks by hashrate-per-watt, which needs a power source; without one, optimize raw
    # H/s instead (same fallback as `tune --efficiency`).
    if [ "$target" = efficiency ] && ! _power_supported; then
        warn "autotune: efficiency target needs a power source (RAPL or TUNE_POWER_CMD) — none available; falling back to performance (raw hashrate) instead."
        target=perf
    fi
    [ "$target" = efficiency ] && unit="H/s/W" || unit="H/s"
    cur=$(jq -r '.randomx.scratchpad_prefetch_mode // 1' "$overrides" 2>/dev/null || echo 1)

    # Baseline = the mode running right now (no restart needed to measure it).
    s=$(_autotune_sample "$n" "$iv" "$target")
    base_hr=${s%%$'\t'*}
    base_w=${s#*$'\t'}
    [ -n "$base_hr" ] && [ "$base_hr" != 0 ] || {
        warn "autotune: could not read a live hashrate from the API — is the miner running? Skipping."
        return 0
    }
    base_score=$(_autotune_score "$target" "$base_hr" "$base_w")
    best_mode="$cur"
    best_score="$base_score"
    last_applied="$cur"
    log "autotune: optimizing for $(_autotune_desc "$target"); live-sweeping prefetch modes [$modes] against the running miner; baseline mode=$cur at $(_autotune_fmt "$target" "$base_hr" "$base_w") (median of $n)."

    # #347: arm the abort-restore before the first candidate lands in the overrides file.
    _AUTOTUNE_PRE_MODE="$cur"
    _AUTOTUNE_OVR_FILE="$overrides"
    _AUTOTUNE_DIRTY=1
    trap '_autotune_cleanup' EXIT

    # Try every OTHER mode once, live; track the running best by the target's score.
    for m in $modes; do
        [ "$m" = "$cur" ] && continue
        _autotune_set_prefetch "$overrides" "$m"
        _apply_runtime >/dev/null 2>&1 || true
        last_applied="$m"
        sleep "$warm"
        s=$(_autotune_sample "$n" "$iv" "$target")
        hr=${s%%$'\t'*}
        w=${s#*$'\t'}
        [ -n "$hr" ] || hr=0
        sc=$(_autotune_score "$target" "$hr" "$w")
        log "autotune: prefetch_mode=$m measured $(_autotune_fmt "$target" "$hr" "$w")."
        if awk -v sc="$sc" -v b="$best_score" 'BEGIN{exit !(sc > b)}'; then
            best_mode="$m"
            best_score="$sc"
        fi
    done

    # Adopt the winner only if it beats the baseline by the margin (noise guard); else keep the current mode.
    if [ "$best_mode" != "$cur" ] && awk -v b="$best_score" -v base="$base_score" -v m="$margin" 'BEGIN{exit !(b > base * (1 + m))}'; then
        log "autotune: best is prefetch_mode=$best_mode at $best_score $unit (vs $base_score baseline) — applying it."
    else
        best_mode="$cur"
        log "autotune: no mode beat the baseline by the margin — keeping prefetch_mode=$cur ($base_score $unit)."
    fi
    # Leave the chosen mode running (the sweep may have ended on a different one).
    if [ "$last_applied" != "$best_mode" ]; then
        _autotune_settle "$best_mode"
    fi
    _AUTOTUNE_DIRTY=0 # #347: a deliberate final mode is in place; the abort-restore stands down
}

# Raw /2/summary JSON from the worker's HTTP API (loopback), or empty when curl/API_CMD is
# missing/unreachable (#143). Pithead's dashboard separately reads `/1/summary` from the stack host —
# both are valid XMRig endpoints, the divergence is intentional. Overridable for tests via API_CMD
# (evaluated as-is — a raw hashrate for _read_api_hashrate's own check below, a full JSON body for
# every other caller). Shared by tune/autotune/status and the sister API's stats superset — was two
# near-identical readers, _read_api_summary + _xmrig_summary_json (#353).
# ALWAYS returns 0 with an empty body when the API is unreachable — curl's exit never escapes. There
# was a "propagate" mode that let it, so an unreachable miner would "surface upstream"; nothing
# upstream ever read that status (every caller branches on an empty body) and it broke two ways under
# the ERR trap (#364). Unguarded callers aborted outright: on a rig (bash 5.2) an API refusing
# connections killed tune/autotune's sampling loop with exit 7 mid-sweep — the failure #210 hit on
# miner-0. And on bash 3.2 (macOS) even GUARDED callers printed the banner: set -E inherits the trap
# into the $( ) each caller reads through, and 3.2 does not carry the caller's suppressed-errexit
# context (`( ... ) || true`) into that child, so the trap fires there once per frame the failure
# unwinds — `status` emitted "[ERROR] rigforge aborted while running 'status'" TWICE for a stopped
# miner while still exiting 0. Swallowing here kills both shapes for every reader at once. The API is
# open (read-only) with no token by default; only send a Bearer when ACCESS_TOKEN is set (XMRig 401s a
# token it never asked for). Branches on the Bearer header rather than an empty-array curl arg — an
# empty array trips set -u on bash 3.2 (macOS).
_bearer_curl() { # <token> <curl args...>
    local token="$1"
    shift
    printf 'header = %s\n' "$(printf 'Authorization: Bearer %s' "$token" | jq -Rs .)" | curl --config - "$@"
}
_read_api_summary() {
    local url="http://127.0.0.1:8080/2/summary"
    if [ -n "${API_CMD:-}" ]; then
        eval "$API_CMD" || true # the override stands in for the API — a failing one means "unreachable", not "crash"
        return
    fi
    command -v curl >/dev/null 2>&1 || return 0
    if [ -n "${ACCESS_TOKEN:-}" ]; then
        _bearer_curl "$ACCESS_TOKEN" -fsS --max-time 5 "$url" 2>/dev/null || true
    else
        curl -fsS --max-time 5 "$url" 2>/dev/null || true
    fi
}

# Same never-fails contract as its reader: `|| true` covers the jq leg too, so a malformed body (or a
# missing jq) can't ride pipefail out and trip the ERR trap in a caller's $( ) either (#364).
_read_api_hashrate() {
    if [ -n "${API_CMD:-}" ]; then
        eval "$API_CMD" || true
        return
    fi
    _read_api_summary | jq -r '.hashrate.total[0] // empty' 2>/dev/null || true
}

# Median of N live API hashrate samples, <interval> seconds apart. Smooths the jittery live reading so a
# transient spike/dip can't drive an autotune keep/reject on its own. n<=1 (or interval 0) skips sleeps.
_sample_api_median() { # <n> <interval>
    local n="${1:-3}" iv="${2:-10}" i s out=()
    for i in $(seq 1 "$n"); do
        s=$(_read_api_hashrate)
        [ -n "$s" ] || s=0
        out+=("$s")
        [ "$i" -lt "$n" ] && [ "$iv" -gt 0 ] 2>/dev/null && sleep "$iv"
    done
    _median "${out[@]}"
}

# --- Backup / restore ---
#
# A worker's expensive, hard-to-recreate state is just its config and its tuning — the XMRig build and
# the system tuning are regenerated by `setup`. `backup` snapshots config.json + the tuning files into a
# portable tarball; `restore` puts them back: after data loss on this machine, or onto OTHER identical
# machines so you tune once and roll the result out across a fleet. (Tuning is CPU-specific — only reuse
# it between identical CPUs.) Mirrors Pithead's backup/restore UX.

# The secret-bearing staging dir shared by backup/restore/support_bundle below — a script global (like
# TUNE_TMP), not `local`, because each function's EXIT trap must still resolve it when it actually
# fires: on a clean run that's after the function has already returned, where a `local` would be out
# of scope and die "unbound variable" under set -u (#353). One at a time is safe: the three verbs are
# mutually exclusive per invocation, same as tune()/autotune() sharing TUNE_TMP.
STAGE_DIR=""

# backup: write config.json + tuning into a timestamped tar.gz under ./backups (owner-only).
backup() {
    local arg
    for arg in "$@"; do
        case "$arg" in
        -y | --yes) ;; # accepted for symmetry with restore; backup has no prompt to skip
        *) error "Unknown option for backup: '$arg' (use -y|--yes). Run '$0 help'." ;;
        esac
    done
    [ -f "$CONFIG_JSON" ] || error "No config.json to back up. Run 'setup' first."

    local wr included="config.json" f
    wr=$(_worker_root_from_config)
    STAGE_DIR=$(mktemp -d)
    # Cleanup is armed the moment the temp dir exists — a set -e abort anywhere below (disk full,
    # tar failure) must not leak this secret-bearing staging content (config.json, tokens). Same
    # EXIT-trap treatment tune() got in #135. (#353)
    trap 'rm -rf "$STAGE_DIR"' EXIT
    cp "$CONFIG_JSON" "$STAGE_DIR/config.json"
    # The tuning files live under the worker root; include whichever exist (a fresh worker has none yet).
    for f in tune-overrides.json rigforge-tune.json rigforge-bios.json; do
        if [ -n "$wr" ] && [ -f "$wr/$f" ]; then
            cp "$wr/$f" "$STAGE_DIR/$f"
            included="$included $f"
        fi
    done
    # A small manifest for provenance — handy when rolling a tune out across a fleet.
    jq -n --arg v "$(cmd_version)" --arg host "$(hostname 2>/dev/null)" --arg files "$included" \
        '{rigforge: $v, source_host: $host, files: ($files | split(" "))}' >"$STAGE_DIR/rigforge-backup.json" 2>/dev/null || true

    local backups_dir="$SCRIPT_DIR/backups" stamp archive
    mkdir -p "$backups_dir"
    stamp=$(date +%Y%m%d-%H%M%S)
    archive="$backups_dir/rigforge-backup-$stamp.tar.gz"
    (umask 077 && tar -czf "$archive" -C "$STAGE_DIR" .)
    chmod 600 "$archive" 2>/dev/null || true

    log "Backed up: $included"
    log "Saved to:  $archive"
    log "Restore with: $0 restore $archive"
}

# restore [-y|--yes] <archive>: put config.json + tuning back from a backup archive.
restore() {
    local assume_yes=0 archive="" arg
    for arg in "$@"; do
        case "$arg" in
        -y | --yes) assume_yes=1 ;;
        -*) error "Unknown option for restore: '$arg' (use -y|--yes). Run '$0 help'." ;;
        *) [ -n "$archive" ] || archive="$arg" ;;
        esac
    done
    [ -n "$archive" ] || error "Usage: $0 restore [-y|--yes] <archive.tar.gz>"
    [ -f "$archive" ] || error "Archive not found: $archive"

    warn "Restore will OVERWRITE config.json and any saved tuning (tune-overrides.json) on this machine."
    if [ "$assume_yes" -eq 0 ]; then
        read -r -p "Continue and overwrite? (y/N): " CONFIRM || true
        [[ "$CONFIRM" =~ ^[Yy] ]] || {
            log "Restore cancelled."
            return 0
        }
    fi

    STAGE_DIR=$(mktemp -d)
    # Cleanup is armed the moment the temp dir exists — a set -e abort anywhere below (an error() call
    # included: EXIT traps fire for those same as any other exit) must not leak this secret-bearing
    # staging content. Same EXIT-trap treatment tune() got in #135. (#353)
    trap 'rm -rf "$STAGE_DIR"' EXIT
    tar -xzf "$archive" -C "$STAGE_DIR" 2>/dev/null || error "Could not extract $archive — is it a RigForge backup?"
    [ -f "$STAGE_DIR/config.json" ] || error "Archive has no config.json — not a RigForge backup."
    # Validate the staged config BEFORE it ever touches the live one — same subshell idiom as
    # _control_commit (rigforge.sh:~3652): parse_config's error() only exits the subshell, so a bad
    # backup can be rejected without corrupting this shell's CONFIG_JSON. shellcheck flags this as
    # SC2031 (info), same as there — intentional, not suppressed.
    (CONFIG_JSON="$STAGE_DIR/config.json" && parse_config) >/dev/null 2>&1 || error "Backup's config.json failed validation — existing config left untouched."
    if [ -f "$STAGE_DIR/rigforge-backup.json" ]; then
        local src
        src=$(jq -r '.source_host // empty' "$STAGE_DIR/rigforge-backup.json" 2>/dev/null)
        [ -n "$src" ] && log "Backup was made on host: $src"
    fi

    # config.json -> repo root; tuning -> the worker root resolved from the RESTORED config (so it lands
    # correctly even if this machine's paths differ from the source's).
    cp "$STAGE_DIR/config.json" "$CONFIG_JSON"
    _stamp_config_meta restore # #254: attribute this config to a restore (bumps revision if it differs)
    local restored="config.json" wr f
    wr=$(_worker_root_from_config)
    for f in tune-overrides.json rigforge-tune.json rigforge-bios.json; do
        if [ -f "$STAGE_DIR/$f" ]; then
            mkdir -p "$wr" 2>/dev/null || sudo mkdir -p "$wr"
            cp "$STAGE_DIR/$f" "$wr/$f" 2>/dev/null || sudo cp "$STAGE_DIR/$f" "$wr/$f"
            restored="$restored $f"
        fi
    done

    log "Restored: $restored"
    case " $restored " in
    *" tune-overrides.json "*)
        warn "Tuning is CPU-specific — only reuse it between identical CPUs; on different hardware, re-tune ('sudo $0 tune')."
        ;;
    esac
    log "Next: 'sudo $0 setup' to build + apply (or 'sudo $0 apply' if XMRig is already built)."
    WORKER_ROOT="$wr" _reown_worker # restored config.json + tuning were written as root
}

# Structural secret redaction for the support bundle (#147): jq path operations only — NEVER sed
# over secret values (a regex that misses one quoting variant leaks; a JSON path can't). Tokens and
# pool passwords go entirely; the pool user (usually a wallet) keeps first-4…last-4 so a maintainer
# can still tell rigs apart and spot the same-wallet-wrong-field misconfig.
_redact_config() {
    jq 'def mask: if length > 12 then .[0:4] + "…" + .[-4:] else "<redacted>" end; (if (.ACCESS_TOKEN // "") != "" then .ACCESS_TOKEN = "<redacted>" else . end) | (if (.ACCESS_TOKENS // {}) != {} then .ACCESS_TOKENS = (.ACCESS_TOKENS | map_values("<redacted>")) else . end) | (if .http?."access-token" != null then .http."access-token" = "<redacted>" else . end) | (if .pools then .pools = (.pools | map((if (.pass // "") != "" then .pass = "<redacted>" else . end) | (if (.user // "") != "" then .user = (.user | mask) else . end))) else . end)'
}

# support-bundle (#147): everything a maintainer needs to debug a miner, nothing secret, one local
# tarball (never uploaded anywhere — the no-phone-home posture in SECURITY.md). No root required;
# root-only probes inside doctor degrade to their own warn lines, which is itself useful signal.
support_bundle() {
    local arg
    for arg in "$@"; do
        error "Unknown option for support-bundle: '$arg' (it takes no options). Run '$0 help'."
    done
    [ -f "$CONFIG_JSON" ] || error "No config.json to collect. Run 'setup' first."

    local wr collected="" skipped="" f
    wr=$(_worker_root_from_config)
    STAGE_DIR=$(mktemp -d)
    # Cleanup is armed the moment the temp dir exists — a set -e abort anywhere below must not leak
    # this secret-bearing staging content. Same EXIT-trap treatment tune() got in #135. (#353)
    trap 'rm -rf "$STAGE_DIR"' EXIT
    _take() { collected="$collected $1"; }
    _skip() { skipped="$skipped $1"; }

    cmd_version >"$STAGE_DIR/version.txt" && _take version.txt
    # Subprocess, not a function call: doctor's error-exits can't kill the bundle. Strip ANSI codes.
    ("$0" doctor </dev/null 2>&1 || true) | sed -e $'s/\x1b\[[0-9;]*m//g' >"$STAGE_DIR/doctor.txt" && _take doctor.txt
    # Fail closed: if jq can't redact a file, the file stays OUT of the bundle — never the original.
    if _redact_config <"$CONFIG_JSON" >"$STAGE_DIR/config.redacted.json" 2>/dev/null; then
        _take config.redacted.json
    else
        rm -f "$STAGE_DIR/config.redacted.json"
        _skip "config.redacted.json(unparseable)"
    fi
    if [ -n "$wr" ] && [ -f "$wr/xmrig/build/config.json" ]; then
        if _redact_config <"$wr/xmrig/build/config.json" >"$STAGE_DIR/xmrig-config.redacted.json" 2>/dev/null; then
            _take xmrig-config.redacted.json
        else
            rm -f "$STAGE_DIR/xmrig-config.redacted.json"
            _skip "xmrig-config.redacted.json(unparseable)"
        fi
    fi
    if [ -n "$wr" ] && [ -f "$wr/xmrig.log" ]; then
        tail -n 500 "$wr/xmrig.log" >"$STAGE_DIR/xmrig.log.tail" 2>/dev/null && _take xmrig.log.tail
    fi
    for f in tune-overrides.json rigforge-tune.json; do
        [ -n "$wr" ] && [ -f "$wr/$f" ] && cp "$wr/$f" "$STAGE_DIR/$f" && _take "$f"
    done
    for f in "$SERVICE_NAME.service" rigforge-autotune.service rigforge-autotune.timer; do
        [ -f "$SYSTEMD_DIR/$f" ] && cp "$SYSTEMD_DIR/$f" "$STAGE_DIR/$f" 2>/dev/null && _take "$f"
    done
    {
        uname -a
        if [ "$OS_TYPE" = Linux ]; then
            lscpu 2>/dev/null || true
            free -h 2>/dev/null || true
        else
            sysctl -n machdep.cpu.brand_string 2>/dev/null || true
            sysctl -n hw.memsize 2>/dev/null || true
        fi
    } >"$STAGE_DIR/system.txt" 2>/dev/null && _take system.txt
    jq -n --arg v "$(cmd_version)" --arg host "$(hostname 2>/dev/null)" --arg files "${collected# }" --arg skipped "${skipped# }" \
        '{rigforge: $v, source_host: $host, files: ($files | split(" ")), not_collected: (["journalctl (system-wide)", "shell history", "unredacted configs", "backups/"] + (if $skipped != "" then ($skipped | split(" ")) else [] end))}' \
        >"$STAGE_DIR/manifest.json" 2>/dev/null || true

    local stamp archive
    stamp=$(date +%Y%m%d-%H%M%S)
    archive="$SCRIPT_DIR/rigforge-support-$(hostname 2>/dev/null)-$stamp.tar.gz"
    (umask 077 && tar -czf "$archive" -C "$STAGE_DIR" .)
    chmod 600 "$archive" 2>/dev/null || true

    log "Collected:${collected}"
    log "NOT collected: journalctl, shell history, unredacted configs, ./backups (tokens and pool passwords are redacted; pool user/wallet is masked to first-4…last-4)."
    log "Bundle: $archive"
    log "Review the extracted contents before attaching it to a public issue."
}

# --- Commands: macOS (DEPRECATED 2026-09-14, unsupported/untested — #493) & systemd service control (#11) ---

# Service-control verbs. On Linux they wrap the systemd unit; on macOS (no systemd) start/stop/restart/
# status/logs manage XMRig directly, so the same commands work on both. `enable`/`disable` install/remove
# a per-user launchd LaunchAgent (macOS's analogue of boot-start — it runs the miner at login). When the
# agent is installed launchd OWNS the miner, so the run verbs delegate to launchctl; otherwise they
# manage an ad-hoc background process tracked by a PID file. (A headless always-on Mac would instead want
# a /Library/LaunchDaemons unit — out of scope for this dev/light-use target.)

# macOS paths/state. Resolved from config.json (no parse_config needed).
_mac_paths() { # sets MAC_WR / MAC_BIN / MAC_CFG / MAC_PID
    MAC_WR=$(_worker_root_from_config)
    MAC_BIN="$MAC_WR/xmrig/build/xmrig"
    MAC_CFG="$MAC_WR/xmrig/build/config.json"
    MAC_PID="$MAC_WR/xmrig.pid"
}
_mac_pid() { # echo the live ad-hoc miner PID (empty if not running)
    local pid
    [ -f "$MAC_PID" ] || return 0
    pid=$(cat "$MAC_PID" 2>/dev/null)
    [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null && echo "$pid"
}
_mac_label() { echo "com.rigforge.$SERVICE_NAME"; }
_mac_plist() { echo "${HOME:-/tmp}/Library/LaunchAgents/$(_mac_label).plist"; }
_mac_enabled() { [ -f "$(_mac_plist)" ]; } # the login agent is installed => launchd owns the miner
_mac_agent_pid() { launchctl list "$(_mac_label)" 2>/dev/null | awk -F'= ' '/"PID"/{gsub(/[^0-9]/,"",$2); print $2; exit}'; }

mac_start() {
    _mac_paths
    [ -x "$MAC_BIN" ] || error "No built worker at $MAC_BIN. Run 'setup' first."
    [ -f "$MAC_CFG" ] || error "No generated config at $MAC_CFG. Run 'setup' first."
    if _mac_enabled; then
        launchctl start "$(_mac_label)" 2>/dev/null || true
        log "Started the miner (login agent)."
        return 0
    fi
    local pid
    pid=$(_mac_pid)
    [ -n "$pid" ] && {
        log "Miner already running (pid $pid)."
        return 0
    }
    # Background it from the build dir (XMRig writes its own log-file per the config); record the PID.
    (cd "$MAC_WR/xmrig/build" && {
        nohup "$MAC_BIN" --config="$MAC_CFG" >/dev/null 2>&1 &
        echo $! >"$MAC_PID"
    })
    log "Started the miner (pid $(cat "$MAC_PID" 2>/dev/null)). Follow it with '$0 logs'; stop with '$0 stop'."
}
mac_stop() {
    _mac_paths
    if _mac_enabled; then
        launchctl stop "$(_mac_label)" 2>/dev/null || true
        log "Stopped the miner (login agent). It starts again at login or '$0 start'; remove it with '$0 disable'."
        return 0
    fi
    local pid
    pid=$(_mac_pid)
    [ -n "$pid" ] || {
        log "Miner is not running."
        rm -f "$MAC_PID" 2>/dev/null
        return 0
    }
    kill "$pid" 2>/dev/null || true
    rm -f "$MAC_PID" 2>/dev/null
    log "Stopped the miner (pid $pid)."
}
mac_status() {
    _mac_paths
    if _mac_enabled; then
        local apid
        apid=$(_mac_agent_pid)
        if [ -n "$apid" ]; then log "Miner is running (login agent, pid $apid)."; else log "Miner is enabled (login agent) but not running."; fi
        return 0
    fi
    local pid
    pid=$(_mac_pid)
    if [ -n "$pid" ]; then log "Miner is running (pid $pid)."; else log "Miner is not running."; fi
}
mac_logs() {
    _mac_paths
    local lf="$MAC_WR/xmrig.log"
    [ -f "$lf" ] || error "No log yet at $lf — start the miner first ('$0 start')."
    tail -f "$lf"
}
mac_enable() {
    _mac_paths
    [ -x "$MAC_BIN" ] || error "No built worker at $MAC_BIN. Run 'setup' first."
    [ -f "$MAC_CFG" ] || error "No generated config at $MAC_CFG. Run 'setup' first."
    # Hand ownership to launchd: stop any ad-hoc miner so there's no competing process.
    local pid
    pid=$(_mac_pid)
    [ -n "$pid" ] && {
        kill "$pid" 2>/dev/null || true
        rm -f "$MAC_PID"
    }
    local plist
    plist=$(_mac_plist)
    mkdir -p "$(dirname "$plist")"
    # KeepAlive=SuccessfulExit:false -> launchd restarts the miner if it crashes, but NOT after a clean
    # `stop` (XMRig exits 0 on SIGTERM); RunAtLoad starts it now and at every login.
    cat >"$plist" <<PLIST
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key><string>$(_mac_label)</string>
    <key>ProgramArguments</key>
    <array>
        <string>$MAC_BIN</string>
        <string>--config=$MAC_CFG</string>
    </array>
    <key>WorkingDirectory</key><string>$MAC_WR/xmrig/build</string>
    <key>RunAtLoad</key><true/>
    <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
    <key>StandardOutPath</key><string>$MAC_WR/xmrig.launchd.log</string>
    <key>StandardErrorPath</key><string>$MAC_WR/xmrig.launchd.log</string>
</dict>
</plist>
PLIST
    launchctl unload "$plist" 2>/dev/null || true
    launchctl load -w "$plist" 2>/dev/null || error "launchctl could not load $plist."
    log "Enabled: the miner starts at login (and is starting now). Manage it with '$0 start/stop/status'; remove with '$0 disable'."
}
mac_disable() {
    local plist
    plist=$(_mac_plist)
    if [ -f "$plist" ]; then
        launchctl unload "$plist" 2>/dev/null || true
        rm -f "$plist"
        log "Disabled: removed the login agent (miner stopped; won't start at login)."
    else
        log "No login agent is installed."
    fi
}

# One-glance live summary from a single /2/summary fetch (#143). Facts only, no ✓/! judgment
# markers (that's doctor's job); plain aligned lines stay grep-friendly. Never sudo, never prompts.
_status_api_summary() {
    local body hs pool up acc rej hp
    body=$(_read_api_summary)
    if [ -z "$body" ]; then
        echo "RigForge: worker API not reachable at 127.0.0.1:8080 (miner stopped or still starting)."
        return 0
    fi
    # One jq fork for every field, tab-separated (bash-3.2-safe read into locals). /2/summary reports
    # hugepages as a [loaded, total] pages array — @tsv rejects nested arrays (exit 5, killing the whole
    # row on every healthy rig, #341), so serialize it; scalar/absent shapes pass through untouched.
    IFS=$(printf '\t') read -r hs pool up acc rej hp < <(printf '%s' "$body" |
        jq -r '[(.hashrate.total[0] // 0), (.connection.pool // "?"), (.uptime // 0), (.connection.accepted // 0), (.connection.rejected // 0), (.hugepages // "" | if type == "array" then join("/") else . end)] | @tsv' 2>/dev/null) || true
    [ -n "${hs:-}" ] || return 0 # half-up API / unparseable body: stay quiet, platform block follows
    printf '  %-10s %s H/s\n' "Hashrate:" "$hs"
    printf '  %-10s %s\n' "Pool:" "$pool"
    printf '  %-10s %s\n' "Uptime:" "$(_render_duration "$up")"
    printf '  %-10s %s accepted / %s rejected\n' "Shares:" "$acc" "$rej"
    [ -n "$hp" ] && printf '  %-10s %s\n' "HugePages:" "$hp"
    echo
}

# Seconds -> "Nd Nh Nm" (integer math only; no bc).
_render_duration() {
    local s="${1:-0}" d h m
    case "$s" in *[!0-9]*) s=0 ;; esac
    d=$((s / 86400)) h=$((s % 86400 / 3600)) m=$((s % 3600 / 60))
    if [ "$d" -gt 0 ]; then printf '%dd %dh %dm' "$d" "$h" "$m"; elif [ "$h" -gt 0 ]; then printf '%dh %dm' "$h" "$m"; else printf '%dm' "$m"; fi
}

svc_status() {
    [ "$OS_TYPE" = "Linux" ] || {
        mac_status
        # parse_config in a subshell: it error-exits on a bad config, and ACCESS_TOKEN only exists
        # after it — a bad/missing config must degrade to the platform block, never crash status.
        (parse_config >/dev/null 2>&1 && _status_api_summary) || true
        return
    }
    (parse_config >/dev/null 2>&1 && _status_api_summary) || true
    # Read-only: `systemctl status` is world-readable, so no sudo (don't prompt for a password to look).
    systemctl status "$SERVICE_NAME" || true # `status` exits non-zero when stopped; not an error
}
svc_logs() {
    [ "$OS_TYPE" = "Linux" ] || {
        mac_logs
        return
    }
    # Read-only: the operator who ran setup is in the `adm` group and can follow the service journal
    # without sudo, so don't prompt for a password just to read logs (use `sudo rigforge logs` if a more
    # locked-down account can't read it).
    journalctl -u "$SERVICE_NAME" -f || true # -f exits 130 on Ctrl-C
}
svc_start() {
    [ "$OS_TYPE" = "Linux" ] || {
        mac_start
        return
    }
    sudo systemctl start "$SERVICE_NAME" && log "Started $SERVICE_NAME."
}
svc_stop() {
    [ "$OS_TYPE" = "Linux" ] || {
        mac_stop
        return
    }
    sudo systemctl stop "$SERVICE_NAME" && log "Stopped $SERVICE_NAME."
}
svc_restart() {
    [ "$OS_TYPE" = "Linux" ] || {
        mac_stop
        mac_start
        return
    }
    sudo systemctl restart "$SERVICE_NAME" && log "Restarted $SERVICE_NAME."
}
svc_enable() {
    [ "$OS_TYPE" = "Linux" ] || {
        mac_enable
        return
    }
    sudo systemctl enable ${ENABLE_RUNTIME:+"$ENABLE_RUNTIME"} "$SERVICE_NAME" && log "Enabled $SERVICE_NAME (starts on boot)."
}
svc_disable() {
    [ "$OS_TYPE" = "Linux" ] || {
        mac_disable
        return
    }
    sudo systemctl disable ${ENABLE_RUNTIME:+"$ENABLE_RUNTIME"} "$SERVICE_NAME" && log "Disabled $SERVICE_NAME (won't start on boot)."
}
# --- Commands: version, apply & bench ---

# Tab completion (#145): PRINT a completion script, install nothing — the operator opts in with
# `source <(rigforge completion bash)` or by writing it to the completions dir. Static on purpose
# (zero deps, no callback into rigforge at tab-time); the suite diffs _rigforge_verbs against the
# dispatch case, so adding a verb without updating this list fails CI. The internal hyphenated
# verbs (api-refresh, msr-apply, control-apply, control-upgrade) and the -v/-h flag spellings are deliberately not completed.
_completion_bash() {
    cat <<'RIGFORGE_COMPLETION'
_rigforge_verbs="setup upgrade uninstall tune autotune watchdog doctor bios status logs start up stop down restart enable disable apply bench backup restore support-bundle version help completion"
_rigforge() {
    local cur verb
    cur="${COMP_WORDS[COMP_CWORD]}"
    verb="${COMP_WORDS[1]:-}"
    if [ "$COMP_CWORD" -eq 1 ]; then
        COMPREPLY=($(compgen -W "$_rigforge_verbs" -- "$cur"))
        return
    fi
    case "$verb" in
    tune) COMPREPLY=($(compgen -W "--now --short --long --live --bench --confirm --efficiency --perf --history --clear" -- "$cur")) ;;
    setup | apply) COMPREPLY=($(compgen -W "--dry-run" -- "$cur")) ;;
    upgrade) COMPREPLY=($(compgen -W "--check" -- "$cur")) ;;
    bios) COMPREPLY=($(compgen -W "--perf --efficiency" -- "$cur")) ;;
    uninstall | backup) COMPREPLY=($(compgen -W "-y --yes" -- "$cur")) ;;
    restore) COMPREPLY=($(compgen -W "-y --yes" -- "$cur") $(compgen -f -- "$cur")) ;;
    completion) COMPREPLY=($(compgen -W "bash zsh" -- "$cur")) ;;
    esac
}
complete -F _rigforge rigforge rigforge.sh ./rigforge.sh
RIGFORGE_COMPLETION
}

cmd_completion() {
    case "${1:-}" in
    bash) _completion_bash ;;
    zsh)
        # bashcompinit runs the same script under zsh — one verb list, not two to drift apart.
        echo "autoload -U +X bashcompinit && bashcompinit"
        _completion_bash
        ;;
    *) error "Usage: $0 completion bash|zsh" ;;
    esac
}

cmd_version() {
    local v="unknown"
    if [ -f "$SCRIPT_DIR/VERSION" ]; then v="$(tr -d '[:space:]' <"$SCRIPT_DIR/VERSION")"; fi
    echo "RigForge $v"
}

# Extract the peak "<N> H/s" hashrate from xmrig output (empty if none). Robust to format variations:
# it just takes the largest H/s number printed. Shared by `bench` and `tune`.
_parse_hashrate() {
    grep -oiE '[0-9]+(\.[0-9]+)?[[:space:]]*H/s' | grep -oE '[0-9]+(\.[0-9]+)?' | sort -nr | head -n1
}

# Surface the periodic-autotune target on a top-level `apply` (#95) so the operator can see what the
# scheduled run optimizes for. Linux-only (the timer is Linux-only); tune/autotune invoke apply with output
# redirected, so this only shows on a direct `apply`. Reflects the `autotune` value apply just parsed.
_autotune_apply_notice() {
    [ "$OS_TYPE" = Linux ] || return 0
    log "Periodic autotune: $(_autotune_desc "${AUTOTUNE_MODE:-disabled}")."
}

# #396: is the miner stopped ON PURPOSE right now? "On purpose" is deliberately mechanical — the unit
# is INSTALLED and systemd reports it exactly `inactive` — because the two ways a rig is legitimately
# offline both land there and neither leaves anything else to read: the watchdog's thermal cutoff runs
# `systemctl stop` (and drops watchdog.thermal-hold), and an operator's manual stop leaves no marker at
# all. Reading the run-state instead of the marker is what covers the second case, and it needs no
# knowledge of WHY the rig is down.
#
# Every other answer means "restart", which is the pre-#396 behaviour, so this can only ever narrow:
#   * unit file absent  — `is-active` says `inactive` for an unknown unit too, so without this check an
#     `apply` before `setup` would report "left stopped" instead of failing on the restart as it does
#     today. A quiet success in place of a loud failure is the regression this half prevents.
#   * `failed`          — systemd gave up restarting a crashed miner. Nobody chose that; `apply` should
#     still revive it, exactly as it did before.
#   * `activating` / `deactivating` / anything else — mid-transition, not a decision.
_miner_deliberately_stopped() {
    [ "$OS_TYPE" = Linux ] || return 1
    [ -f "$SYSTEMD_DIR/$SERVICE_NAME.service" ] || return 1
    [ "$(systemctl is-active "$SERVICE_NAME" 2>/dev/null || true)" = inactive ]
}

# The config-regen + restart core of `apply`, WITHOUT touching the autotune timer. Used directly by
# tune/autotune — which call it in a loop and own the timer themselves — so they don't re-render the unit
# on every prefetch trial.
#
# `preserve-run-state` (#396) is passed by `apply` and by nothing else. With it, a rig that is
# deliberately stopped is left stopped: the regenerated config sits on disk and takes effect at the next
# deliberate start (the operator's, or the watchdog's own tick once the temperature is back under the
# cutoff). Without it the unconditional restart stands — and `tune`/`autotune`/`_restore_overrides` MUST
# keep it: they call this in a loop and measure the running miner between trials, and tune's --bench leg
# stops the service itself and relies on the re-apply to bring it back, so a blanket preserve would
# strand a tune run instead of a held rig. Opt-in per call site, not a global.
_apply_runtime() { # [preserve-run-state]
    parse_config
    local build="$WORKER_ROOT/xmrig/build"
    [ -d "$build" ] || error "No built worker at $build. Run 'setup' first."
    # Sampled BEFORE the regen, so the decision is about the state the operator or the watchdog left the
    # rig in — nothing between here and the restart below changes it.
    local held=no
    [ "${1:-}" = preserve-run-state ] && _miner_deliberately_stopped && held=yes
    (cd "$build" && generate_xmrig_config)
    if [ "$OS_TYPE" != "Linux" ]; then
        log "Config regenerated. Restart the miner to apply."
    elif [ "$held" = yes ]; then
        # The thermal hold is named only when it is there, and only to explain the stop — the decision
        # above never reads the marker, so a manual stop with no marker takes the same branch.
        local why=""
        [ -f "$WORKER_ROOT/watchdog.thermal-hold" ] && why=" (the watchdog is holding it below max_temp_c)"
        log "Applied config. $SERVICE_NAME was stopped$why, so it was left stopped — the new config takes effect at the next 'sudo $0 start'."
    else
        sudo systemctl restart "$SERVICE_NAME" && log "Applied config and restarted $SERVICE_NAME."
    fi
    _reown_worker
}

# apply (#11): re-read config.json and regenerate the live XMRig config, then restart — WITHOUT
# recompiling. The fast path after editing config.json. As the config-change path it also RECONCILES the
# periodic-autotune timer with config (#95) — so changing the `autotune` target and running `apply`
# actually takes effect (not just shows the new value) — then reports the target. install_autotune is the
# autotune analog of restarting the service; its own log is suppressed in favour of the single status line.
# apply --dry-run (#146): the three-line plan — symmetric with setup --dry-run.
_apply_plan() {
    parse_config >/dev/null
    echo "apply --dry-run — the plan:"
    echo " 1. regenerate $WORKER_ROOT/xmrig/build/config.json$([ -f "$WORKER_ROOT/tune-overrides.json" ] && echo ' (+ overlay tune-overrides.json)')"
    if [ "$OS_TYPE" = Linux ] && _miner_deliberately_stopped; then
        # #396: the plan states the decision apply will actually make. Saying "restart" here while the
        # run leaves the rig held is the same class of lie as reporting a skipped step as applied.
        echo " 2. re-render the unit (User=${MINER_USER:-root}); $SERVICE_NAME is stopped and stays stopped — the config takes effect at the next 'sudo $0 start'"
    elif [ "$OS_TYPE" = Linux ]; then
        echo " 2. re-render the unit (User=${MINER_USER:-root}) and restart $SERVICE_NAME"
    else
        echo " 2. restart the miner manually ('$0 restart') — no service on $OS_TYPE"
    fi
    echo " 3. reconcile the autotune timer + watchdog + sister API + control path + firewall to config (autotune: $AUTOTUNE_MODE, api: $API_MODE, control: $CONTROL_MODE)"
    echo "Dry run — nothing was changed. Run 'sudo $0 apply' to apply."
}

apply() {
    local _arg
    for _arg in "$@"; do
        case "$_arg" in
        --dry-run)
            _apply_plan
            return 0
            ;;
        *) error "Unknown option for apply: '$_arg' (use --dry-run). Run '$0 help'." ;;
        esac
    done
    if [ "$OS_TYPE" = Linux ] && [ -f "$SYSTEMD_DIR/$SERVICE_NAME.service" ]; then
        parse_config
        _ensure_miner_user
        NFT_PATH=$(command -v nft || echo "/usr/sbin/nft")
        export NFT_PATH
        export BUILD_DIR="$WORKER_ROOT/xmrig/build"
        CPUPOWER_PATH=$(command -v cpupower || echo "/usr/bin/cpupower")
        export CPUPOWER_PATH
        _render_xmrig_unit
        sudo systemctl daemon-reload 2>/dev/null || true
    fi
    _apply_runtime preserve-run-state
    local _wd_rc=0 _api_rc=0
    if [ "$OS_TYPE" = Linux ]; then
        install_autotune >/dev/null 2>&1 || true
        install_watchdog >/dev/null 2>&1 || _wd_rc=1
        install_api || _api_rc=1
        install_control >/dev/null 2>&1 || true
        install_api_firewall || true
        _autotune_apply_notice
    fi
    _stamp_config_meta "${RIGFORGE_CONFIG_SOURCE:-local}" "${RIGFORGE_CONFIG_CHANGE_ID:-}"
    _apply_pool_check
    if [ "$_wd_rc" -ne 0 ]; then
        RIGFORGE_APPLY_FAIL_REASON="could not re-render the watchdog units"
        warn "The miner watchdog units could NOT be re-rendered ($SYSTEMD_DIR/rigforge-watchdog.{service,timer}) — the watchdog is still on its PREVIOUS schedule, whatever config.json now says. Check free disk space and sudo rights, then re-run 'sudo $0 apply'."
    fi
    if [ "$_api_rc" -ne 0 ]; then
        RIGFORGE_APPLY_FAIL_REASON="could not start the sister API"
        warn "The configured sister API could NOT be reconciled; check journalctl -u rigforge-api.service, then re-run 'sudo $0 apply'."
    fi
    [ "$_wd_rc" -eq 0 ] && [ "$_api_rc" -eq 0 ]
}

# #343: apply's honesty check. "Applied config and restarted" used to be the last word even when the
# rig then sat at 0 H/s forever (an unresolvable pools[0].url just loops on DNS errors, silently) —
# so after the restart + reconcile, ask the miner itself: poll its local API briefly for a live pool
# connection and WARN when none appears. Warn, never refuse: the pool may be legitimately down at
# apply time and the config is already applied, so the exit code stays 0 (doctor is the judgmental
# verb). Only apply() calls this — tune/autotune restart via _apply_runtime and verify liveness
# their own way (_wait_miner_live). Tries/interval overridable for the suite.
_apply_pool_check() {
    [ "$OS_TYPE" = Linux ] || return 0                                  # no restart happened (macOS apply only regenerates)
    systemctl is-active --quiet "$SERVICE_NAME" 2>/dev/null || return 0 # stopped service: nothing to verify
    local tries="${APPLY_POOL_TRIES:-5}" iv="${APPLY_POOL_IVL:-3}" i st="" pool="" n=""
    for i in $(seq 1 "$tries"); do
        IFS="$(printf '\t')" read -r st pool n _ <<EOF
$(_pool_conn_status)
EOF
        [ "$st" = connected ] && break
        [ "$i" -lt "$tries" ] && sleep "$iv"
    done
    case "$st" in
    connected) log "Miner reports a live pool connection to ${pool:-?}." ;;
    disconnected) warn "Miner restarted, but reports NO live pool connection (pool: ${pool:-?}, ${n:-0} failed attempt(s)) — check pools[0].url in config.json, or the pool may be down. Watch: $0 logs" ;;
    *) warn "Couldn't reach the worker API (127.0.0.1:8080) to confirm a pool connection — check '$0 status' in a minute." ;;
    esac
}

# --- Writable control path applier (#236) ---

_fsync_paths() {
    python3 - "$@" <<'PY'
import os, sys
for path in sys.argv[1:]:
    fd = os.open(path, os.O_RDONLY | (os.O_DIRECTORY if os.path.isdir(path) else 0))
    try: os.fsync(fd)
    finally: os.close(fd)
PY
}

# Merge an allowlisted, parse-valid staged change into config.json after snapshotting the old one.
# rc 0 = committed, 1 = invalid/rejected, 2 = install failed with old config restored, and 3 =
# storage failed after rename and recovery is uncertain. The caller records the matching terminal.
_control_commit() { # <staged.json> <backups-dir>
    local staged="$1" backups="$2"
    local CONTROL_WRITABLE_KEYS="pools DONATION autotune watchdog watchdog_interval_min max_temp_c"
    local change allow badkeys stamp backup cand msg
    change=$(cat "$staged" 2>/dev/null) || {
        echo "rejected unreadable-staged-file"
        return 1
    }
    # Structural re-validation (never trust the spool blindly): a non-empty JSON object, keys ⊆ allowlist.
    printf '%s' "$change" | jq -e 'type == "object" and length > 0' >/dev/null 2>&1 || {
        echo "rejected not-a-config-object"
        return 1
    }
    allow=$(jq -n --arg s "$CONTROL_WRITABLE_KEYS" '$s | split(" ")')
    badkeys=$(printf '%s' "$change" | jq -r --argjson a "$allow" '[keys[] | select(. as $k | $a | index($k) | not)] | join(",")')
    if [ -n "$badkeys" ]; then
        echo "rejected non-writable-keys:$badkeys"
        return 1
    fi
    if [ "$RIGFORGE_APPLIANCE" = 1 ] && printf '%s' "$change" | jq -e 'has("pools")' >/dev/null; then
        echo "rejected appliance-pools-read-only:change the pool in Pithead configuration (rig.json for the rig role)"
        return 1
    fi
    # #257: remote control may tune thermal protection, not remove it. This duplicates the receiver
    # check as an applier-side backstop for anything staged out of band; local apply remains capable.
    local wd_new mt_new
    wd_new=$(printf '%s' "$change" | jq -r 'if has("watchdog") then (.watchdog | tostring | ascii_downcase) else "-" end')
    case "$wd_new" in disabled | false | off | none | "" | null)
        echo "rejected safety-watchdog-cannot-be-disabled"
        return 1
        ;;
    esac
    if printf '%s' "$change" | jq -e 'has("max_temp_c")' >/dev/null 2>&1; then
        mt_new=$(printf '%s' "$change" | jq -r '.max_temp_c // ""')
        if [ -z "$mt_new" ] || ! _uint_in_range "$mt_new" 40 110; then
            echo "rejected safety-max_temp_c-out-of-band"
            return 1
        fi
    fi
    # #415: resolve masked pool secrets before jq's array-replacing overlay. Match a stored pool by
    # (url,user), keep only a real stored secret, and reject any sentinel left unresolved. The raw
    # config view matters: normalized POOLS_JSON invents pass="x" for an absent password (#429).
    if printf '%s' "$change" | jq -e '(.pools | type) == "array"' >/dev/null 2>&1; then
        local resolved unresolved
        # One jq, two output lines: the surviving markers first, the resolved config second. The
        # marker check is a post-condition on the merged pools rather than a second pre-scan — after
        # the merge, a marker that is STILL there is exactly one the rig could not resolve. Reading it
        # out of the same pass also covers a marker in a pool key this resolver does not handle, which
        # a pre-scan of the two known keys would have waved through into config.json, and it leaves a
        # single failure branch: a scan that cannot RUN is no longer a separate outcome to name.
        resolved=$(printf '%s' "$change" | jq -r --slurpfile base "$CONFIG_JSON" 'def pkey: [(.url? // ""), (.user? // "")]; def lut: reduce ((.pools? // []) | reverse | .[]) as $p ({}; if ($p | type) == "object" then .[$p | pkey | tojson] = $p else . end); def stored($lut; $k): ($lut[pkey | tojson] // {} | .[$k]) as $v | if ($v | type) == "string" and $v != "" then $v else null end; ($base[0] | lut) as $lut | (.pools |= map(if type == "object" then . as $p | reduce ("pass", "tls-fingerprint") as $k (.; ($p | stored($lut; $k)) as $keep | if $keep != null and ((($p[$k] | type) == "object" and $p[$k].__secret__ == true) or ($p | has($k) | not)) then .[$k] = $keep else . end) else . end)) as $r | ([$r.pools[]? | select(type == "object") | to_entries[] | select((.value | type) == "object" and .value.__secret__ == true) | .key] | unique | join(",")), ($r | tojson)' 2>/dev/null) || {
            echo "rejected secret-merge-failed"
            return 1
        }
        unresolved=${resolved%%$'\n'*}
        change=${resolved#*$'\n'}
        if [ -n "$unresolved" ]; then
            echo "rejected unresolvable-secret-marker:$unresolved"
            return 1
        fi
    fi
    # Build the candidate: current config with ONLY the allowlisted staged keys overlaid (pools and
    # other arrays replace, scalars replace). Filter again so a stray key can never ride in.
    cand="$CONFIG_JSON.control.$$"
    if ! jq -n --slurpfile base "$CONFIG_JSON" --argjson chg "$change" --argjson a "$allow" '$base[0] * ($chg | with_entries(select(.key as $k | $a | index($k))))' >"$cand" 2>/dev/null; then
        rm -f "$cand"
        echo "rejected merge-failed"
        return 1
    fi
    # The merged config must be valid RigForge config BEFORE it lands — parse_config is the
    # authoritative semantic gate (pool shapes, ranges, the dual-auth rule). Run it isolated so a
    # failure can't corrupt the caller's globals, and so a bad change can never reach config.json.
    if ! msg=$( (CONFIG_JSON="$cand" && parse_config) 2>&1); then
        rm -f "$cand"
        echo "rejected invalid-config:$(printf '%s' "$msg" | grep -o '\[ERROR\][^\"]*' | head -1 | sed "s/'.*//")"
        return 1
    fi
    # Only now, with a valid candidate, snapshot the old config and commit. A backup is a HARD
    # precondition (ADR): never commit a change without first snapshotting the config it replaces —
    # if the snapshot can't be written, reject the whole change and leave config.json untouched.
    stamp=$(date -u +%Y%m%d-%H%M%S)
    backup="$backups/config-$stamp.json"
    if ! mkdir -p "$backups" || ! (umask 077 && cp "$CONFIG_JSON" "$backup"); then
        rm -f "$cand" "$backup" # #438: a cp that died mid-copy leaves a TRUNCATED snapshot behind
        echo "rejected backup-failed"
        return 1
    fi
    # Pin the secret-bearing candidate to 0600 before mv inherits its mode (#434). rc 2: a valid change
    # could not be installed, old config still live. rc 3: uncertain.
    if ! chmod 600 "$cand"; then
        rm -f "$cand" "$backup"
        echo "failed commit-chmod-failed"
        return 2
    fi
    # Flush the two files and both directory entries, never every filesystem on the host (#472).
    # A pre-rename failure leaves the old config live; a post-rename failure restores it from the
    # already-flushed backup. rc 3 is the honest last resort when even that recovery cannot persist.
    local config_dir backup_parent
    config_dir=$(dirname "$CONFIG_JSON")
    backup_parent=$(dirname "$backups")
    if ! _fsync_paths "$cand" "$backup" "$backups" "$backup_parent"; then
        rm -f "$cand" "$backup"
        echo "failed commit-sync-failed"
        return 2
    fi
    if ! mv -f "$cand" "$CONFIG_JSON"; then
        rm -f "$cand" "$backup"
        echo "failed commit-install-failed"
        return 2
    fi
    if ! _fsync_paths "$CONFIG_JSON" "$config_dir"; then
        if cp "$backup" "$cand" && chmod 600 "$cand" && _fsync_paths "$cand" && mv -f "$cand" "$CONFIG_JSON" && _fsync_paths "$CONFIG_JSON" "$config_dir"; then
            rm -f "$backup"
            echo "failed commit-sync-failed"
            return 2
        fi
        rm -f "$cand"
        echo "failed commit-sync-uncertain:$backup"
        return 3
    fi
    echo "committed $backup"
    return 0
}

# Prune config-backups/ to the retention cap and hand it to the operator so they can inspect or
# restore old configs without sudo (recovery = `cp config-backups/config-<stamp>.json config.json`
# then `sudo rigforge apply`). Override the cap with KEEP_CONFIG_BACKUPS. #438: named for BOTH jobs.
_sweep_config_backups() { # <backups-dir>
    local dir="$1" keep="${KEEP_CONFIG_BACKUPS:-20}" old
    # shellcheck disable=SC2012  # names are controlled (config-YYYYmmdd-HHMMSS.json); ls -t orders by recency
    old=$(ls -t "$dir"/config-*.json 2>/dev/null | tail -n +"$((keep + 1))" || true)
    [ -z "$old" ] || printf '%s\n' "$old" | while IFS= read -r f; do [ -n "$f" ] && rm -f "$f"; done
    if [ "$(id -u)" -eq 0 ] && [ -n "${REAL_USER:-}" ]; then sudo chown -R "$REAL_USER" "$dir" 2>/dev/null || true; fi
}

# The apply + liveness check control-apply gates its rollback on. Split out so tests can stub it.
# #395: apply's exit status was discarded here — the liveness wait ran regardless and its verdict
# became the whole answer, so an apply that failed for a reason the miner's hashrate cannot show
# (a watchdog unit that would not write) still reported success. Gate on it: a failed apply is a
# failed apply, and control_apply's rollback branch is the designed response to one.
_control_do_apply() {
    # #396: sampled BEFORE the apply, like its fast-path sibling — a rig can be LEGITIMATELY stopped when
    # a change lands (thermal hold, manual stop) and `apply` leaves it that way. Without this the wait
    # below would read the operator's own decision as this change's failure, roll a good change back, and
    # then blame a "liveness failure" nobody could observe (the rollback re-apply leaves it held too).
    # Success is "the run-state did not DEGRADE": only a rig that WAS live must come back live. Sampled
    # here, not read out of _apply_runtime, so this function stays checkable on its own.
    local was_held=no
    _miner_deliberately_stopped && was_held=yes
    apply >/dev/null 2>&1 || return 1
    [ "$was_held" = no ] || return 0
    _wait_miner_live "${CONTROL_LIVE_TRIES:-20}"
}

# #395: the specific cause of the most recent apply failure, when the failing path knows one the
# liveness wait could not have observed. Set by that path, read and cleared by control_apply, which
# falls back to its existing wording when this is empty — so no pre-existing reason string changes.
RIGFORGE_APPLY_FAIL_REASON=""

# #381 (from #344 item 1): a live walkthrough measured a single restart-free key
# (watchdog_interval_min) taking ~62s round-trip through POST /apply, because _control_do_apply
# above re-runs the ENTIRE apply() pipeline — regenerate xmrig's config, re-render its unit, restart
# the service, then wait out _wait_miner_live's pool-liveness retries — for every change, even one
# that never touches xmrig at all.
#
# CONTROL_FAST_PATH_KEYS is a CLOSED allowlist, checked as a SUBSET match (never a "not on the slow
# list" complement) by _control_fast_path_eligible below: a changed-keys set takes the fast path only
# when EVERY key in it is in this list, so an unrecognised key — including any future addition to
# CONTROL_WRITABLE_KEYS that nobody has re-proven restart-free here — falls through to the full,
# restart-safe path by construction. Evidence per key (grep rigforge.sh for both to re-check):
#
#   watchdog_interval_min — bakes into ONLY rigforge-watchdog.timer's OnUnitActiveSec, rendered by
#     install_watchdog. It never reaches generate_xmrig_config or the xmrig unit template, so xmrig
#     itself has nothing to reload; install_watchdog (the SAME function the full path already calls
#     unconditionally on every apply, see apply() above) is sufficient — it re-renders the timer and
#     daemon-reloads it.
#   max_temp_c — never rendered into ANY unit. install_watchdog's own comment records why: "only the
#     cadence is baked into the units — the verb re-reads config.json every run, so an apply after a
#     max_temp_c ... edit needs no unit rewrite". The watchdog verb picks it up on its next scheduled
#     run; nothing beyond the config.json write _control_commit already did is needed here.
#
# pools/DONATION change xmrig's OWN generated config (restarting it is the only way xmrig serves the new
# values) and autotune/watchdog (the flag, not the interval) govern install_* paths this issue has not
# audited for restart-freedom. All four stay on the full path. Never widen this list without the same
# evidence trail (a grep proving the key reaches neither generate_xmrig_config nor a unit template).
CONTROL_FAST_PATH_KEYS="watchdog_interval_min max_temp_c"

# True (rc 0) iff <keys-csv> is non-empty and every key in it is in CONTROL_FAST_PATH_KEYS. A single
# key outside the list — or an empty/malformed keys-csv (e.g. control_apply's "?" sentinel when jq
# couldn't read the staged file's keys) — fails CLOSED to "not eligible", so the caller takes the
# full apply() path. Subset match, never complement: this can only be talked into "eligible" by a key
# that is actually named on the allowlist above, so the allowlist growing is the only way this
# function's answer changes for a given input.
_control_fast_path_eligible() { # <keys-csv>
    local keys="$1" k found=0
    [ -n "$keys" ] || return 1
    local IFS=','
    for k in $keys; do
        [ -n "$k" ] || continue
        found=1
        case " $CONTROL_FAST_PATH_KEYS " in
        *" $k "*) ;;
        *) return 1 ;;
        esac
    done
    [ "$found" -eq 1 ]
}

# The restart-free counterpart to _control_do_apply (#381). Only reached when
# _control_fast_path_eligible says every changed key is provably restart-free (see
# CONTROL_FAST_PATH_KEYS above), so this DELIBERATELY skips apply()/_apply_runtime entirely: no
# generate_xmrig_config, no xmrig unit re-render, no `systemctl restart` of the miner, no
# _wait_miner_live retry loop, no _apply_pool_check. It reuses install_watchdog verbatim — the same
# call the full apply() makes unconditionally on every run — rather than re-implementing unit
# rendering, so the fast and full paths cannot drift on what "restart-free" actually renders. It
# still stamps provenance exactly like apply() does, via the same RIGFORGE_CONFIG_SOURCE /
# RIGFORGE_CONFIG_CHANGE_ID dynamic-scope contract, so config_meta on the read feed does not depend on
# which path served the change.
#
# Success is "the run-state did not DEGRADE", not "is currently active" (security review finding on
# the original version of this function, which gated on is-active alone): a rig can be LEGITIMATELY
# stopped before this change lands — a watchdog thermal hold, or an operator's manual stop — and by
# construction the fast path never touches the xmrig unit or service, so a stopped rig staying
# stopped (or even coming back up on its own) is correct, not a failure; the new value takes effect
# on its own schedule (the watchdog's next tick). Only a transition from active to inactive is a real
# regression worth the caller's rollback. No thermal-hold-marker special-casing needed: the
# before/after comparison covers every "was already down" case with less machinery.
_control_do_apply_fast() {
    local was_active is_active
    was_active=1
    systemctl is-active --quiet "$SERVICE_NAME" 2>/dev/null && was_active=0
    parse_config
    # #395: install_watchdog IS this path's entire effect — both fast-path keys reach the rig only through
    # it. Swallowing its failure recorded "applied" for a change that never landed, the precise lie the
    # status contract exists to prevent. Bail before stamping provenance (a change that did not take
    # effect is not the config in force); the caller then takes the same full-pipeline rollback.
    if ! install_watchdog >/dev/null 2>&1; then
        RIGFORGE_APPLY_FAIL_REASON="could not re-render the watchdog units"
        return 1
    fi
    _stamp_config_meta "${RIGFORGE_CONFIG_SOURCE:-local}" "${RIGFORGE_CONFIG_CHANGE_ID:-}"
    is_active=1
    systemctl is-active --quiet "$SERVICE_NAME" 2>/dev/null && is_active=0
    [ "$was_active" -eq 1 ] && return 0
    [ "$is_active" -eq 0 ]
}

# A status record for the receiver's GET /status (mode 644 so the DynamicUser server reads it back) —
# a terminal outcome, or control_upgrade's non-terminal `started` marker (#320).
_control_status() { # <status-file> <status> <cid> <keys-csv> <reason> <backup>
    local f="$1" cid="$3" body cdir
    mkdir -p "$(dirname "$f")"
    # #257: warnings[] flags a safety-relevant change (watchdog / max_temp_c = thermal protection) even
    # when allowed, so the operator and dashboard can require an extra confirm. Additive to the shape.
    body=$(jq -n --arg s "$2" --arg c "$3" --arg k "$4" --arg r "$5" --arg b "$6" --arg src control --arg when "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '{status: $s, change_id: $c, source: $src, applied_at: $when, changed_keys: ($k | split(",") | map(select(length > 0))), reason: (if $r == "" then null else $r end), backup: (if $b == "" then null else $b end), warnings: ($k | split(",") | map(select(. == "watchdog" or . == "max_temp_c")) | map("thermal protection changed: " + .))}')
    printf '%s' "$body" >"$f.tmp.$$" 2>/dev/null && mv -f "$f.tmp.$$" "$f" && chmod 644 "$f" 2>/dev/null || true
    [ "$2" = started ] || RIGFORGE_CONTROL_TERMINAL_WRITTEN=1 # #509: `started` (#320) is the one non-terminal status written here
    # #255: also index by change_id, so a caller can GET /status?change_id=<cid> after a concurrent
    # change overwrote status.json. cid is server-generated 16-hex; guard it anyway (it becomes a
    # filename). Keep only the last ~20 outcomes.
    if [[ "$cid" =~ ^[0-9a-f]{16}$ ]]; then
        cdir="$(dirname "$f")/changes"
        mkdir -p "$cdir"
        printf '%s' "$body" >"$cdir/$cid.json.tmp.$$" 2>/dev/null && mv -f "$cdir/$cid.json.tmp.$$" "$cdir/$cid.json" && chmod 644 "$cdir/$cid.json" 2>/dev/null || true
        # shellcheck disable=SC2012  # names are controlled 16-hex; ls -t orders by recency
        ls -t "$cdir"/*.json 2>/dev/null | tail -n +21 | while IFS= read -r old; do [ -n "$old" ] && rm -f "$old"; done
        # A terminal apply record supersedes the receiver's pending marker (#344); an upgrade id has none.
        rm -f "$(dirname "$f")/pending/$cid.json" 2>/dev/null || true
    fi
}

# #509/#535: control_apply and control_upgrade record an outcome on every branch, but the work between
# them can still end the process (error()'s bare `exit 1`, systemd's SIGTERM): a claimed change with no
# terminal record and nothing to re-drive it, a poller stuck on `pending`/`started`. Both verbs arm this
# EXIT floor once they claim; RUN is <status-file> <cid> <keys-csv> <verb's reason>. Globals, since a
# verb's locals are out of scope when the trap fires and `set -u` would fail it, making the rc 1.
RIGFORGE_CONTROL_TERMINAL_WRITTEN="" RIGFORGE_CONTROL_RUN=()
_control_run_incomplete() {
    [ -n "${RIGFORGE_CONTROL_TERMINAL_WRITTEN:-}" ] && return 0
    [ "${#RIGFORGE_CONTROL_RUN[@]}" -eq 4 ] || return 0
    _control_status "${RIGFORGE_CONTROL_RUN[0]}" failed "${RIGFORGE_CONTROL_RUN[1]}" "${RIGFORGE_CONTROL_RUN[2]}" "${RIGFORGE_CONTROL_RUN[3]}" ""
    return 0
}

_with_control_lock() {
    exec 8>"${RIGFORGE_CONTROL_LOCK:-/run/rigforge-control/consumer.lock}" || error "Could not open the privileged control lock."
    flock -x 8 || error "Could not take the privileged control lock."
    "$@"
}
_control_claim_staged() { # <untrusted spool file> <change id>: echo frozen root-only path
    local src="$1" cid="$2" proc="${RIGFORGE_CONTROL_PROCESSING:-/run/rigforge-control}" staged claim
    staged="$proc/$cid.json"
    claim="$proc/.claim-$cid"
    if [ -L "$proc" ] || [ ! -d "$proc" ] || [ "$(stat -c '%u:%g:%a' "$proc" 2>/dev/null)" != "0:0:700" ] || [ -e "$claim" ] || [ -L "$claim" ] || [ -e "$staged" ] || [ -L "$staged" ]; then
        rm -rf -- "$src"
        return 1
    fi
    if ! mv -f "$src" "$claim" 2>/dev/null; then
        rm -rf -- "$src"
        return 1
    fi
    if [ -L "$claim" ] || [ ! -f "$claim" ]; then
        rm -rf -- "$claim"
        return 1
    fi
    if ! (umask 077 && head -c 65537 "$claim" >"$staged") || [ "$(wc -c <"$staged" 2>/dev/null || echo 65537)" -gt 65536 ] || ! chmod 600 "$staged" || ! _fsync_paths "$staged" || ! rm -f "$claim" || ! _fsync_paths "$proc"; then
        rm -rf -- "$claim" "$staged"
        return 1
    fi
    printf '%s' "$staged"
}
# control-apply (#236): the privileged half of the writable control path, run by the
# rigforge-control-apply.path unit when the receiver stages a change. Applies the NEWEST staged change
# (older ones are superseded, so we never restart twice), reconciles the live miner, and rolls back to
# the pre-change snapshot if it doesn't come back live. Every path records a status and returns 0 — a
# bad request must not wedge the oneshot, and #509's EXIT floor holds that true when one dies mid-apply.
control_apply() {
    [ "$OS_TYPE" != "Linux" ] && error "control-apply is driven by the rigforge-control-apply.path unit and is Linux-only."
    parse_config
    local state="${RIGFORGE_CONTROL_STATE:-/var/lib/rigforge-control}" spool status backups
    spool="$state/spool"
    status="$state/status.json"
    backups="$SCRIPT_DIR/config-backups"
    local newest older cid change_keys result rc backup staged
    newest=$(ls -t "$spool"/pending-*.json 2>/dev/null | head -1) || true
    if [ -z "$newest" ]; then
        log "control-apply: nothing staged."
        return 0
    fi
    older=$(ls -t "$spool"/pending-*.json 2>/dev/null | tail -n +2) || true
    if [ -n "$older" ]; then
        printf '%s\n' "$older" | while IFS= read -r f; do [ -n "$f" ] && rm -f "$f"; done
    fi
    cid=$(basename "$newest" .json)
    cid="${cid#pending-}"
    if ! staged=$(_control_claim_staged "$newest" "$cid"); then
        _control_status "$status" failed "$cid" "?" "could not secure the staged change" ""
        warn "control-apply: could not freeze change $cid in the root-only processing directory."
        return 0
    fi
    change_keys=$(jq -r 'keys | join(",")' "$staged" 2>/dev/null || echo "?")
    RIGFORGE_CONTROL_TERMINAL_WRITTEN="" RIGFORGE_CONTROL_RUN=("$status" "$cid" "$change_keys" "the apply run ended before recording an outcome (aborted or killed mid-apply); config.json may already hold the change — check config-backups/ and re-run apply")
    trap _control_run_incomplete EXIT # #509: the spool entry is claimed; nothing else will retry it
    # Tested inner/outer failures preserve the commit rc without firing errexit/ERR (#426/#364).
    rc=0
    result=$(_control_commit "$staged" "$backups" || exit $?) || rc=$?
    rm -f "$staged"
    # A valid change whose install failed is `failed`, not an invalid-input `rejected` (#434/#438).
    if [ "$rc" -eq 2 ]; then
        _sweep_config_backups "$backups" || true # never abort before the terminal status (#434)
        _control_status "$status" failed "$cid" "$change_keys" "$result" ""
        warn "control-apply: change $cid could not be committed (${result#failed }) — config.json untouched."
        return 0
    fi
    if [ "$rc" -eq 3 ]; then
        backup="${result#failed commit-sync-uncertain:}"
        _control_status "$status" failed "$cid" "$change_keys" "$result" "$backup"
        warn "control-apply: change $cid hit a storage error after install; restore $backup and re-run apply."
        return 0
    fi
    if [ "$rc" -ne 0 ]; then
        _control_status "$status" rejected "$cid" "$change_keys" "$result" ""
        warn "control-apply: change $cid rejected (${result#rejected }) — config.json untouched."
        return 0
    fi
    backup="${result#committed }"
    _sweep_config_backups "$backups" || true # same guard; pre-existing exposure on this path
    # #254: attribute this (and the rollback re-apply) to the control path with its change_id, which the
    # nested apply()'s _stamp_config_meta reads via dynamic scope.
    local RIGFORGE_CONFIG_SOURCE=control RIGFORGE_CONFIG_CHANGE_ID="$cid"
    # #381: dispatch on the closed fast-path allowlist. Only the CLASSIFICATION differs — both write the
    # same "applied", and EITHER failing falls through to the same full-pipeline rollback, so a wrong
    # "eligible" verdict (or a fast path failing for an unrelated reason) stays restart-safe.
    local fast=0 apply_ok=0 fail_reason=""
    # #395: cleared before the attempt (no stale cause from an earlier change) and snapshotted straight
    # after (the ROLLBACK's own apply must not overwrite why this change failed).
    RIGFORGE_APPLY_FAIL_REASON=""
    if _control_fast_path_eligible "$change_keys"; then
        fast=1
        log "control-apply: committed change $cid (keys: $change_keys); applying (fast path — xmrig untouched)..."
        _control_do_apply_fast && apply_ok=1
    else
        log "control-apply: committed change $cid (keys: $change_keys); applying..."
        _control_do_apply && apply_ok=1
    fi
    fail_reason="$RIGFORGE_APPLY_FAIL_REASON"
    if [ "$apply_ok" -eq 1 ]; then
        _control_status "$status" applied "$cid" "$change_keys" "" "$backup"
        if [ "$fast" -eq 1 ]; then
            log "control-apply: change $cid applied (fast path)."
        else
            log "control-apply: change $cid applied."
        fi
    else
        warn "control-apply: change $cid ${fail_reason:-did not come back live} — rolling back to $backup."
        # #276: guard the cp explicitly (not just -e/ERR) — an unreadable backup must still write a
        # terminal status, not ERR-trap the oneshot into serving the stale previous outcome forever.
        if ! cp "$backup" "$CONFIG_JSON" 2>/dev/null; then
            _control_status "$status" failed "$cid" "$change_keys" "rollback backup unreadable: $backup" "$backup"
            return 0
        fi
        # #276: both restore config.json; only one leaves the miner hashing. The reason pins which.
        local why="${fail_reason:-miner did not return to a live hashrate}"
        if _control_do_apply; then
            # #396: the re-apply leaves a deliberately stopped rig stopped (and succeeds by design), so
            # unconditional "and live" would assert a liveness nobody checked — the #395 lie, again.
            local back="rolled back and live"
            _miner_deliberately_stopped && back="rolled back; the rig was already stopped and stays stopped"
            _control_status "$status" rolled_back "$cid" "$change_keys" "$why; $back" "$backup"
        elif [ -n "$fail_reason" ]; then
            # #395: the re-apply failed for the SAME reason the change did (units that still will not
            # write). A failed apply short-circuits before _wait_miner_live, so the miner may be hashing
            # fine throughout: say what is known. The arm below keeps the liveness wording it earned.
            _control_status "$status" rolled_back "$cid" "$change_keys" "$why; config rolled back, but the re-apply hit the same failure" "$backup"
        else
            _control_status "$status" rolled_back "$cid" "$change_keys" "$why; rollback re-apply also failed to restore liveness" "$backup"
        fi
    fi
    return 0
}

# Pre-dial throttle for the remote-upgrade path (#308, ADR 0002 D6): a persisted stamp under a flock
# bounds how often a rig will fetch from GitHub / rebuild, so a looping or hostile trigger can't turn
# the fleet into a beacon or thrash the miner with rebuilds. Returns 0 if allowed (and stamps the
# attempt), 1 if still inside the window, 2 if the throttle state itself is unusable (fail-closed,
# #321). Default 6h; override with CONTROL_UPGRADE_MIN_INTERVAL (s).
_control_upgrade_throttle_ok() { # <state-dir>
    local dir="$1" stamp="$1/upgrade-last" now min="${CONTROL_UPGRADE_MIN_INTERVAL:-21600}" last=0
    now=$(date +%s)
    mkdir -p "$dir" 2>/dev/null || true
    # Can't open the lock (unwritable/full state dir)? Fail CLOSED (#321): this guard exists to bound
    # how often a compromised trigger can make the rig dial out, and a degraded state dir is exactly
    # what an attacker might arrange — fail-open would invert the posture right there. An operator
    # with a broken state dir has bigger problems than a delayed upgrade. rc 2 (not 1) so the caller
    # reports the real cause instead of "throttled — retry later".
    exec 9>"$dir/.upgrade-throttle.lock" 2>/dev/null || {
        warn "control-upgrade: couldn't take the throttle lock under $dir — refusing the upgrade (fail-closed; check the state dir)."
        return 2
    }
    flock 9 2>/dev/null || true
    [ -f "$stamp" ] && last=$(cat "$stamp" 2>/dev/null || echo 0)
    case "$last" in '' | *[!0-9]*) last=0 ;; esac
    if [ $((now - last)) -lt "$min" ] 2>/dev/null; then
        exec 9>&-
        return 1
    fi
    printf '%s\n' "$now" >"$stamp" 2>/dev/null || true
    exec 9>&-
    return 0
}

# The fetch + reachability + checkout + rebuild half of control-upgrade, split out so the orchestration
# is unit-testable with this stubbed (like control-apply's _control_do_apply). Returns 0 on a successful
# checkout+build of <ref>, nonzero otherwise. <ref> is a validated vX.Y.Z tag (forward) or a prior
# tag/commit (rollback). D5: the git checkout IS the fetch and the commit hash pins the whole tree; no
# signing, GitHub over TLS is the trust root. D10: a forward tag's commit must be reachable from
# origin/main — the branch releases are cut from (kills a tag pointing at a dangling/side commit).
# NOT origin/HEAD: a fresh clone resolves that to develop (the repo default), and release tags are
# merge commits on main that develop doesn't contain, so every legit upgrade would be refused (#318).
# A clone without origin/main (e.g. single-branch) refuses too — fail closed, deploy from a full clone.
# Immutable releases lock the tag→commit binding at the platform layer. Every git call pins `-c safe.directory="$SCRIPT_DIR"`: the
# oneshot runs as root with NO $HOME, so git can't read root's safe.directory config and would fatal on
# "dubious ownership" of the operator-owned install — every git op silently failing the upgrade (a real
# miner-0 e2e finding the stubbed unit suite couldn't reach, since it stubs git).
_control_upgrade_do() { # <ref>
    local ref="$1" cobj
    git -C "$SCRIPT_DIR" -c safe.directory="$SCRIPT_DIR" fetch --quiet --tags origin 2>/dev/null || return 1
    if printf '%s' "$ref" | grep -qE '^v[0-9]+\.[0-9]+\.[0-9]+$'; then
        cobj=$(git -C "$SCRIPT_DIR" -c safe.directory="$SCRIPT_DIR" rev-parse -q --verify "refs/tags/$ref^{commit}" 2>/dev/null) || return 1
        git -C "$SCRIPT_DIR" -c safe.directory="$SCRIPT_DIR" merge-base --is-ancestor "$cobj" origin/main 2>/dev/null || return 1
    fi
    git -C "$SCRIPT_DIR" -c safe.directory="$SCRIPT_DIR" checkout --quiet --force "$ref" 2>/dev/null || return 1
    # Run the NEW code's upgrade: regenerate the config, reinstall the units, restart so both are in
    # effect, and rebuild XMRig first if the pin changed. Every clause was aspirational until #413 —
    # `upgrade` returned early on an unchanged pin, which is every published release pair.
    "$SCRIPT_DIR/rigforge.sh" upgrade >/dev/null 2>&1
}

# control-upgrade (#308, ADR 0002): the privileged half of the REMOTE-UPGRADE path, run by the
# rigforge-control-upgrade.path unit when the receiver stages an upgrade intent. Fetches the target
# RigForge release and applies it, health-gated with rollback to the prior version. Every failure path
# returns 0 with a recorded status (served by the receiver's GET /status) — a bad request must not
# wedge the oneshot. The staged version IS the target (D4) — the dashboard re-derives latest host-side,
# this verb makes no version check of its own: it bounds what it will act on (D4/D10) so a compromised
# trigger can only ever land a real, reachable, NEWER release — never an arbitrary tag, a downgrade, or
# a dangling commit.
control_upgrade() {
    [ "$OS_TYPE" != "Linux" ] && error "control-upgrade is driven by the rigforge-control-upgrade.path unit and is Linux-only."
    parse_config # need API_PORT etc. so the post-build liveness check can read the miner
    local state="${RIGFORGE_CONTROL_STATE:-/var/lib/rigforge-control}" spool status
    spool="$state/spool"
    status="$state/status.json"
    local newest older cid target installed old_tag staged
    newest=$(ls -t "$spool"/upgrade-*.json 2>/dev/null | head -1) || true
    if [ -z "$newest" ]; then
        log "control-upgrade: nothing staged."
        return 0
    fi
    older=$(ls -t "$spool"/upgrade-*.json 2>/dev/null | tail -n +2) || true
    [ -n "$older" ] && printf '%s\n' "$older" | while IFS= read -r f; do [ -n "$f" ] && rm -f "$f"; done
    cid=$(basename "$newest" .json)
    cid="${cid#upgrade-}"
    if ! staged=$(_control_claim_staged "$newest" "$cid"); then
        _control_status "$status" failed "$cid" version "could not secure staged upgrade (processing directory, move, or symlink)" ""
        warn "control-upgrade: could not freeze $cid in the root-only processing directory."
        return 0
    fi
    # #320: a NON-terminal record once the intent is claimed (D8 move done, nothing can swap it), so a
    # poller can tell this run from the PREVIOUS change's outcome; the terminal record below overwrites
    # it. A run that dies first gets the EXIT floor's `failed` (#535): only SIGKILL or power loss is left.
    RIGFORGE_CONTROL_TERMINAL_WRITTEN="" RIGFORGE_CONTROL_RUN=("$status" "$cid" version "the upgrade run ended before recording an outcome (aborted or killed mid-fetch/build); the checkout may be half-updated and this upgrade will not be retried — check the installed version and re-request the upgrade")
    trap _control_run_incomplete EXIT # #535: the spool entry is claimed; nothing else will retry it
    _control_status "$status" started "$cid" version "" ""
    # Strict field whitelist (D4): exactly {"version":"vX.Y.Z"}. Never sourced/evaled; anything else refused.
    target=$(jq -r 'if (type == "object" and (keys | sort) == ["version"] and (.version | type == "string")) then .version else empty end' "$staged" 2>/dev/null)
    rm -f "$staged"
    if ! [[ "$target" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
        _control_status "$status" failed "$cid" version "staged upgrade target malformed (want vX.Y.Z)" ""
        warn "control-upgrade: malformed target for $cid — refused."
        return 0
    fi
    installed=$(tr -d '[:space:]' <"$SCRIPT_DIR/VERSION" 2>/dev/null || true)
    # D10 monotonic anti-rollback: never install a version <= the one running. A compromised trigger
    # can't pin a rig to an older, known-vulnerable release (reachability + immutable releases cover
    # tag-moving / dangling commits; this covers downgrade and no-op).
    if [ -n "$installed" ]; then
        local want="${target#v}" highest
        if [ "$want" = "$installed" ]; then
            # #320: an idempotent no-op, not a failure — the rig is exactly where the operator wants it.
            _control_status "$status" noop "$cid" version "already on $target — nothing to upgrade" ""
            log "control-upgrade: already on $target."
            return 0
        fi
        highest=$(printf '%s\n%s\n' "$installed" "$want" | sort -V | tail -n1)
        if [ "$highest" != "$want" ]; then
            _control_status "$status" failed "$cid" version "refused a downgrade: $target is not newer than v$installed" ""
            warn "control-upgrade: $target <= installed v$installed — refused (anti-rollback)."
            return 0
        fi
    fi
    # D6 throttle: bound how often a rig fetches/rebuilds. rc 2 = throttle state unavailable — a
    # fail-closed refusal (#321) that must read as a broken rig, not as "throttled — retry later".
    local thr_rc=0
    _control_upgrade_throttle_ok "$state" || thr_rc=$?
    if [ "$thr_rc" -eq 2 ]; then
        _control_status "$status" failed "$cid" version "throttle state unavailable under $state — refused (fail-closed)" ""
        warn "control-upgrade: throttle state unavailable — refused."
        return 0
    elif [ "$thr_rc" -ne 0 ]; then
        # #320: distinct from failed — the consumer's right move is retry-later, not alarm.
        _control_status "$status" throttled "$cid" version "throttled — too soon since the last upgrade attempt" ""
        warn "control-upgrade: throttled."
        return 0
    fi
    old_tag=$(git -C "$SCRIPT_DIR" -c safe.directory="$SCRIPT_DIR" describe --tags --exact-match 2>/dev/null || git -C "$SCRIPT_DIR" -c safe.directory="$SCRIPT_DIR" rev-parse HEAD 2>/dev/null || true)
    log "control-upgrade: $cid -> $target (from ${old_tag:-unknown}); fetching + building..."
    local RIGFORGE_CONFIG_SOURCE=control RIGFORGE_CONFIG_CHANGE_ID="$cid"
    if _control_upgrade_do "$target" && _wait_miner_live "${CONTROL_LIVE_TRIES:-20}"; then
        # #320: echo the landed version — the poller shouldn't have to cross-read the miner API for it.
        _control_status "$status" applied "$cid" version "upgraded to $target" ""
        log "control-upgrade: $cid applied — now on $target."
    else
        # ANY forward failure rolls back — a reachability/build error OR the miner not returning to a live
        # hashrate. Rollback re-runs _control_upgrade_do, which checks out AND rebuilds the old ref, so a
        # failed forward attempt never leaves the tree pinned to an unbuilt $target: that would make
        # VERSION read $target, short-circuit every future retry ("already on"), and run unverified code
        # on every later invocation. A build failure after checkout is a real on-disk change, not "no
        # change applied" — this reverts it (#308 security review, the build-failed branch was the gap).
        warn "control-upgrade: $target did not come up cleanly — rolling back to ${old_tag:-previous}."
        if [ -n "$old_tag" ] && _control_upgrade_do "$old_tag" && _wait_miner_live "${CONTROL_LIVE_TRIES:-20}"; then
            _control_status "$status" rolled_back "$cid" version "upgrade to $target failed; rolled back to $old_tag and live" ""
            warn "control-upgrade: $cid rolled back to $old_tag."
        else
            _control_status "$status" failed "$cid" version "upgrade to $target failed and rollback to ${old_tag:-previous} did not restore a live miner — manual intervention needed" ""
            warn "control-upgrade: $cid FAILED and rollback did not restore liveness — manual intervention needed on this rig."
        fi
    fi
    return 0
}

# Miner watchdog (#139): ONE health check per invocation — rigforge-watchdog.timer provides the
# cadence. Two jobs systemd's Restart= can't do: restart a WEDGED miner (process alive, 0 H/s or
# API dead — two consecutive strikes, so one restart-in-progress or dataset-init blip never
# triggers it), and an opt-in thermal cutoff (stop above max_temp_c, start again 5°C below — the
# hysteresis is fixed: big enough to outlast the post-restart heat-up on the rigs we run, small
# enough not to strand the miner, and one less knob to typo). State lives in $WORKER_ROOT (which
# _reown_worker already re-owns): a bare-integer strike counter and a thermal-hold marker file.
# The health probe reuses _read_api_hashrate (ACCESS_TOKEN Bearer handled there, token never
# logged) and _read_temp (THERMAL_ZONE/TUNE_TEMP_CMD overrides handled there).
watchdog() {
    if [ "$OS_TYPE" != "Linux" ]; then
        error "watchdog drives the live systemd service and is only supported on Linux."
    fi
    parse_config
    local fails_f="$WORKER_ROOT/watchdog.fails" hold_f="$WORKER_ROOT/watchdog.thermal-hold" t hr f
    t=$(_read_temp)
    # Thermal hold first: WE stopped the miner, so the not-active check below must not short-circuit
    # the recovery. Start again only once we're 5°C under the cutoff (or the cutoff was removed).
    if [ -f "$hold_f" ]; then
        if [ -z "$MAX_TEMP_C" ]; then
            rm -f "$hold_f"
            sudo systemctl start "$SERVICE_NAME" 2>/dev/null || true
            log "watchdog: max_temp_c is no longer set — thermal hold lifted, miner started."
        elif [ -n "$t" ] && awk -v t="$t" -v m="$MAX_TEMP_C" 'BEGIN { exit !(t < m - 5) }'; then
            rm -f "$hold_f"
            sudo systemctl start "$SERVICE_NAME" 2>/dev/null || true
            log "watchdog: temp ${t}°C is below $((MAX_TEMP_C - 5))°C — thermal hold lifted, miner started."
        else
            log "watchdog: thermal hold active (temp ${t:-unreadable}°C, resumes below $((MAX_TEMP_C - 5))°C) — miner stays stopped."
        fi
        return 0
    fi
    if ! systemctl is-active --quiet "$SERVICE_NAME" 2>/dev/null; then
        rm -f "$fails_f"
        log "watchdog: $SERVICE_NAME is not active — dead-process recovery is systemd's (Restart=). Nothing to do."
        return 0
    fi
    # Thermal cutoff (opt-in). An unreadable temp skips this — a missing sensor must not stop a
    # healthy miner.
    if [ -n "$MAX_TEMP_C" ] && [ -n "$t" ] && awk -v t="$t" -v m="$MAX_TEMP_C" 'BEGIN { exit !(t > m) }'; then
        sudo systemctl stop "$SERVICE_NAME" 2>/dev/null || true
        touch "$hold_f"
        warn "watchdog: temp ${t}°C is above max_temp_c=${MAX_TEMP_C}°C — miner stopped (starts again below $((MAX_TEMP_C - 5))°C)."
        return 0
    fi
    # Wedge check: the API probe returns empty (unreachable) or the live hashrate (a float). An
    # unreachable API is a STRIKE, not a crash — _read_api_hashrate swallows curl's refused/timeout
    # exit itself (#364), so this unguarded assignment can't errexit the check (verified on a rig:
    # the old reader aborted here with exit 7, the current one returns empty). #210 needed a
    # `|| true` here for exactly that; the reader now owns the guarantee, so the guard is gone.
    hr=$(_read_api_hashrate)
    if [ -z "$hr" ] || awk -v h="$hr" 'BEGIN { exit !(h == 0) }'; then
        # Guard INSIDE the $( ): on bash 3.2 a caller-side `|| true` does NOT stop the ERR trap
        # firing in the child, because 3.2 doesn't carry suppressed errexit into it (#210/#364).
        f=$(cat "$fails_f" 2>/dev/null || true)
        [[ "$f" =~ ^[0-9]+$ ]] || f=0
        f=$((f + 1))
        if [ "$f" -ge 2 ]; then
            rm -f "$fails_f"
            sudo systemctl restart "$SERVICE_NAME" 2>/dev/null || true
            warn "watchdog: miner wedged ($f consecutive checks with 0 H/s or an unreachable API) — restarted."
        else
            printf '%s\n' "$f" >"$fails_f"
            log "watchdog: unhealthy check ($f/2: 0 H/s or API unreachable) — restarting at 2 in a row."
        fi
        return 0
    fi
    rm -f "$fails_f"
    log "watchdog: healthy ($hr H/s)."
}

# bench (#11): run a one-off xmrig --bench and report the hashrate. A quick perf/health check.
bench() {
    parse_config
    local bin="$WORKER_ROOT/xmrig/build/xmrig" cfg="$WORKER_ROOT/xmrig/build/config.json"
    [ -x "$bin" ] || error "No built worker at $bin. Run 'setup' first."
    local b="${BENCH:-1M}" out hr
    log "Running 'xmrig --bench=$b' (this can take a minute or two)..."
    out=$(_xmrig_bench "$bin" "$b" "$cfg")             # strips the API/pool/log-file and stops xmrig once done (#75)
    hr=$(printf '%s' "$out" | _parse_hashrate) || true # empty when nothing hashed; handled below
    # A healthy bench must (a) report a hashrate — proving the build ran, the config parsed and the
    # RandomX dataset initialised — and (b) not have hit a fatal allocation/config error (XMRig's
    # "MEMORY ALLOC FAILED" covers a failed dataset / HugePages / memlock allocation). On failure, echo
    # the raw XMRig output so a broken build/config is diagnosable — this is what the release smoke
    # check (tests/smoke.sh, #61) gates on.
    if printf '%s' "$out" | grep -qiE 'MEMORY ALLOC FAILED|unable to (open|parse) config|error parsing config'; then
        printf '%s\n' "$out" >&2
        error "Benchmark hit a fatal memory/config error — see the XMRig output above."
    fi
    if [ -z "$hr" ]; then
        printf '%s\n' "$out" >&2
        error "Could not read a hashrate from the benchmark output — see the XMRig output above."
    fi
    log "Benchmark hashrate: $hr H/s"
}

# doctor (#45): verify the optimizations actually took effect. Read-only and best-effort — it never
# changes the system, just reports PASS/WARN with actionable hints. Linux-only checks.
_ck_ok() { echo -e "  ${C_GREEN}✓${C_RESET} $1"; }
_ck_warn() { echo -e "  ${C_YELLOW}!${C_RESET} $1"; }
_ck_info() { echo -e "  ${C_BLUE}∙${C_RESET} $1"; } # neutral context line (#78), not a pass/fail check
# Read a /sys/class/dmi/id field (board/BIOS identity; world-readable). Empty if missing. #78.
_dmi() {
    [ -r "$DMI_DIR/$1" ] || return 0
    tr -d '\n' <"$DMI_DIR/$1" 2>/dev/null
    return 0
}

# #67/#78 helper. _mem_summary parses `dmidecode -t memory` into "<populated-DIMMs> <channels>
# <min configured MT/s> <max rated MT/s>" — channels from BOTH the Locator and Bank Locator (whichever
# yields more), the configured speed is the RUNNING one, the rated speed is the module's SPD/XMP "Speed".
# #78 compares the two speeds to spot a memory profile that isn't enabled. _cpu_eff_khz averages the
# per-core scaling_cur_freq (clock under load).
_mem_summary() {
    # One-line awk (kcov can't see coverage of a multi-line program inside a string): per Memory Device,
    # count populated DIMMs + distinct channels, and track the min configured (cf) and max rated (rt) speed.
    # Channels: desktop boards encode the channel in Bank Locator (`BANK 0`/`P0 CHANNEL A`); server boards
    # (EPYC/Threadripper) repeat one Bank Locator (`BANK 0`) for every DIMM and instead carry the channel in
    # the Locator's letter group (`DIMM_P0_A0`..`DIMM_P0_H0` = channels A..H). Count distinct channels in
    # EACH field and take whichever is larger, so server boards aren't mis-flagged as single-channel (#108).
    # Trailing `|| true`: dmidecode needs root, so a non-root `doctor` makes the pipeline non-zero under
    # `set -o pipefail`; without this the command substitution in doctor would trip errexit and abort the
    # whole health check. Always exit 0 — empty/zeroed output (handled as "run as root") instead.
    "$DMIDECODE" -t memory 2>/dev/null | awk 'function flush(){if(sz~/[0-9]+ *[GMgm][Bb]/){pop++;if(ch!="")chans[ch]=1;if(lc!="")lchans[lc]=1;if(cf+0>0&&(minc==0||cf+0<minc))minc=cf+0;if(rt+0>maxr)maxr=rt+0};sz="";ch="";lc="";cf="";rt=""} /^Memory Device/{flush();next} /^[ \t]*Size:/{v=$0;sub(/^[^:]*:[ \t]*/,"",v);sz=v} /Bank Locator:/{v=$0;sub(/^[^:]*:[ \t]*/,"",v);ch=v} /^[ \t]*Locator:/{v=$0;sub(/^[^:]*:[ \t]*/,"",v);if(match(v,/[A-Za-z][0-9]+$/))lc=toupper(substr(v,RSTART,1))} /^[ \t]*Speed:/{if(match($0,/[0-9]+/))rt=substr($0,RSTART,RLENGTH)} /Configured Memory Speed:/{if(match($0,/[0-9]+/))cf=substr($0,RSTART,RLENGTH)} END{flush();nc=0;for(c in chans)nc++;nl=0;for(c in lchans)nl++;if(nl>nc)nc=nl;printf "%d %d %d %d",pop+0,nc+0,minc+0,maxr+0}' || true
}
_cpu_eff_khz() {
    local f v sum=0 n=0
    for f in "$CPU_SYSFS"/cpu[0-9]*/cpufreq/scaling_cur_freq; do
        [ -r "$f" ] || continue
        v=$(cat "$f" 2>/dev/null)
        case "$v" in '' | *[!0-9]*) continue ;; esac
        sum=$((sum + v))
        n=$((n + 1))
    done
    if [ "$n" -gt 0 ]; then echo $((sum / n)); fi # always exit 0 (empty output when no data)
}

# Kernel lockdown level (#333). securityfs prints every level with the ACTIVE one in square brackets,
# e.g. "none [integrity] confidentiality" (security/lockdown/lockdown.c:lockdown_read). Echoes just the
# bracketed level; empty when the file is absent or unreadable (lockdown LSM not built in, securityfs
# not mounted, or a non-root reader) — "unknown", never "off". Always exits 0: an unreadable probe is
# missing information, not a failure, and must not trip the ERR trap.
_lockdown_state() { # -> none|integrity|confidentiality, or empty when unknown
    [ -r "$LOCKDOWN_FILE" ] || return 0
    sed -nE 's/.*\[([a-z]+)\].*/\1/p' "$LOCKDOWN_FILE" 2>/dev/null | head -1
    return 0
}

# RandomX ISA preflight (#338, the last acceptance criterion from #1): echo which of aes / avx2 the
# CPU lacks, from the kernel's flags line. RandomX without AES-NI silently falls back to XMRig's
# soft-AES path (~4x slower) and without AVX2 dataset init slows — neither aborts anything, so a rig
# on unsupported hardware "works" at a mysteriously bad rate unless somebody says why. Judged ONLY
# when an x86-style "flags" line exists: no flags line (macOS has no /proc, ARM cpuinfo says
# "Features", sandboxes stub the file) means unknown, and unknown never manufactures an issue — the
# same stance as #333's lockdown probe. `-w` so vaes/avx2_vnni style neighbors can't false-match.
_cpu_missing_isa() { # -> "aes", "avx2", "aes avx2", or empty when all present / undeterminable
    grep -q '^flags' "$CPUINFO" 2>/dev/null || return 0
    local missing=""
    grep -qw aes "$CPUINFO" || missing="aes"
    grep -qw avx2 "$CPUINFO" || missing="$missing${missing:+ }avx2"
    printf '%s' "$missing"
    return 0
}

# True when lockdown is at a level that blocks MSR writes (#333). LOCKDOWN_MSR sits below
# LOCKDOWN_INTEGRITY_MAX in enum lockdown_reason (include/linux/security.h), so both `integrity` and
# `confidentiality` deny the write; only `none` permits it.
_lockdown_blocks_msr() { # <level> -> 0 when MSR writes are denied
    case "$1" in integrity | confidentiality) return 0 ;; *) return 1 ;; esac
}

# #66 MSR-verification helpers. doctor confirms the prefetcher MSR mod actually took effect — not just
# that the `msr` module loaded — in two layers: XMRig's own log line (always available) and an rdmsr
# read-back (when msr-tools is installed), which catches a write a hypervisor / kernel-lockdown silently
# dropped even though XMRig reported success.

# Return the last XMRig MSR result from its file log or bounded journal.
# #367: the line is written at miner START, so on a long-lived worker it sits near the BEGINNING of a
# log that can reach 100MB+ — `awk` scanning the whole file on every `doctor` got expensive. `grep`
# (C-speed) finds every match and `tail -1` keeps the same last-match semantics; a naive `tail`-first
# approach would miss the line entirely on a big file, so don't "optimize" this into one.
_msr_log_status() { # <logfile>
    { if [ -f "$1" ]; then cat "$1"; elif [ "$OS_TYPE" = Linux ]; then journalctl -u "$SERVICE_NAME" --no-pager -o cat -n 5000 2>/dev/null; fi; } |
        sed -E 's/\x1b\[[0-9;]*m//g' | grep -E 'msr +register values for' | tail -1 | awk '{p="";if(match($0,/"[^"]+"/))p=substr($0,RSTART+1,RLENGTH-2);if(index($0,"set successfully")>0){st="ok";pr=p}else if(index($0,"FAILED")>0||index($0,"failed")>0||index($0,"cannot")>0){st="fail";pr=p}else{st="none";pr=p}} END{if(NR==0)printf "none\t";else printf "%s\t%s",st,pr}' || true
}

# The (register, value, mask) triples XMRig writes per MSR preset — verified against XMRig v6.26.0
# (src/crypto/rx/RxConfig.cpp). mask "-" means a whole-register (no-mask) write, so the register equals
# the value exactly regardless of firmware; "~0x20" is encoded as ffffffffffffffdf. Only the presets we
# verify on real hardware are listed — for any other preset, doctor relies on XMRig's log confirmation.
# Detect which MSR preset fits this CPU — the same family/model mapping XMRig's RxConfig uses,
# limited to the presets _msr_preset_regs carries (verified on real hardware).
_msr_detect_preset() { # -> preset name, or "" for unknown
    local vendor family model
    vendor=$(lscpu 2>/dev/null | sed -nE 's/^Vendor ID:[ \t]+//p' | head -1)
    family=$(lscpu 2>/dev/null | sed -nE 's/^CPU family:[ \t]+//p' | head -1)
    model=$(lscpu 2>/dev/null | sed -nE 's/^Model:[ \t]+//p' | head -1)
    case "$vendor" in
    AuthenticAMD)
        case "$family" in
        23) printf 'ryzen_17h' ;;
        25)
            # Zen4 lives in family 25 models 0x60-0x7f (96-127); the rest of family 25 is Zen3.
            if [ "${model:-0}" -ge 96 ] 2>/dev/null && [ "${model:-0}" -le 127 ] 2>/dev/null; then printf 'ryzen_19h_zen4'; else printf 'ryzen_19h'; fi
            ;;
        26) printf 'ryzen_1Ah_zen5' ;;
        esac
        ;;
    GenuineIntel) printf 'intel' ;;
    esac
}

# Apply the MSR preset root-side (#140): the unprivileged miner can't write /dev/cpu/*/msr, so the
# unit's ExecStartPre=+ runs this as root before xmrig starts. Exits 0 on the known-benign cases
# (unknown family, no msr module) so Restart=always never wedges; a real write failure is fatal
# and visible — an opted-in operator must know the ~10-15% MSR boost didn't apply.
msr_apply() {
    [ "$OS_TYPE" = Linux ] || error "msr-apply writes Linux MSRs and is only supported on Linux."
    [ "$(id -u)" -eq 0 ] || error "msr-apply needs root (it writes /dev/cpu/*/msr) — it is normally run by the systemd unit."
    parse_config >/dev/null
    local preset regs reg val mask cpu old new
    preset=$(_msr_detect_preset)
    if [ -z "$preset" ]; then
        warn "no MSR preset for this CPU family — mining continues without the MSR boost."
        return 0
    fi
    modprobe msr 2>/dev/null || true
    if ! command -v wrmsr >/dev/null 2>&1; then
        warn "wrmsr (msr-tools) not found — mining continues without the MSR boost."
        return 0
    fi
    regs=$(_msr_preset_regs "$preset")
    while read -r reg val mask; do
        if [ -z "$reg" ]; then continue; fi
        if [ "$mask" = "-" ]; then
            wrmsr -a "$reg" "0x$val"
        else
            # Masked register: read-modify-write per CPU — the unmasked bits differ per core's prior
            # state, so -a would clobber them. Same masked-compare semantics as _msr_rdmsr_verify.
            for cpu in "${CPU_SYSFS:-/sys/devices/system/cpu}"/cpu[0-9]*; do
                cpu="${cpu##*cpu}"
                old=$("${RDMSR_BIN:-rdmsr}" -p"$cpu" -0 "$reg" 2>/dev/null || true)
                case "$old" in '' | *[!0-9A-Fa-f]*) continue ;; esac
                new=$(printf '%016x' $(((0x$old & ~0x$mask) | (0x$val & 0x$mask))))
                wrmsr -p"$cpu" "$reg" "0x$new"
            done
        fi
    done <<EOF
$regs
EOF
    printf '%s' "$preset" >"$WORKER_ROOT/.rigforge-msr-preset"
    log "MSR preset '$preset' applied root-side (miner runs unprivileged)."
}

_msr_preset_regs() { # <preset> -> lines "reg value mask"
    case "$1" in
    ryzen_19h_zen4 | ryzen_1Ah_zen5)
        printf '%s\n' '0xc0011020 0004400000000000 -' '0xc0011021 0004000000000040 ffffffffffffffdf' \
            '0xc0011022 8680000401570000 -' '0xc001102b 000000002040cc10 -'
        ;;
    ryzen_19h)
        printf '%s\n' '0xc0011020 0004480000000000 -' '0xc0011021 001c000200000040 ffffffffffffffdf' \
            '0xc0011022 c000000401570000 -' '0xc001102b 000000002000cc10 -'
        ;;
    ryzen_17h)
        printf '%s\n' '0xc0011020 0000000000000000 -' '0xc0011021 0000000000000040 ffffffffffffffdf' \
            '0xc0011022 0000000001510000 -' '0xc001102b 000000002000cc16 -'
        ;;
    intel)
        printf '%s\n' '0x1a4 000000000000000f -'
        ;;
    esac
}

# Read each of a preset's registers via rdmsr and check the bits XMRig controls (value & mask) match.
# Sets _MSR_OK / _MSR_TOTAL / _MSR_BAD. Best-effort: needs rdmsr (msr-tools) + the msr module + root.
_msr_rdmsr_verify() { # <preset> -> sets _MSR_OK / _MSR_TOTAL / _MSR_UNREAD / _MSR_BAD
    _MSR_OK=0
    _MSR_TOTAL=0
    _MSR_UNREAD=0 # registers rdmsr couldn't read (not root / module absent) — distinct from a value mismatch
    _MSR_BAD=""
    local reg val mask actual want got regs
    regs=$(_msr_preset_regs "$1")
    [ -n "$regs" ] || return 0
    while read -r reg val mask; do
        [ -n "$reg" ] || continue
        _MSR_TOTAL=$((_MSR_TOTAL + 1))
        [ "$mask" = "-" ] && mask="ffffffffffffffff"
        actual=$("$RDMSR_BIN" -p0 -0 "$reg" 2>/dev/null || true) # guard INSIDE $(): a failing rdmsr mustn't trip the ERR trap
        case "$actual" in '' | *[!0-9A-Fa-f]*)
            _MSR_UNREAD=$((_MSR_UNREAD + 1))
            continue
            ;;
        esac
        # 64-bit masked compare: these constants set bit 63 (e.g. 0x8680…), so they're negative under bash's
        # signed intmax_t arithmetic — but want/got are masked identically, so the bit patterns compare equal.
        want=$((0x$val & 0x$mask))
        got=$((0x$actual & 0x$mask))
        if [ "$got" = "$want" ]; then _MSR_OK=$((_MSR_OK + 1)); else _MSR_BAD="$_MSR_BAD $reg"; fi
    done <<EOF
$regs
EOF
}

# --- Sister API (#99): read-only stats superset on its own port ---

# {watts, hs_per_watt} over a 1-second RAPL energy window; nulls when unmeasurable (no RAPL /
# non-root). RAPL only — TUNE_POWER_CMD is an operator-session env var whose value is eval'd, and
# config-derived text must never reach eval inside a network-facing handler.
_api_power_json() { # <hashrate|"">
    local hr="${1:-}" e0 e1 t0 t1 mx w=""
    e0=$(_rapl_sum energy_uj || true)
    t0=$(_now_s)
    if [ -n "$e0" ]; then
        sleep 1
        e1=$(_rapl_sum energy_uj || true)
        t1=$(_now_s)
        mx=$(_rapl_sum max_energy_range_uj || true)
        w=$(_watts_from_energy "$e0" "$e1" "${mx:-0}" "$(awk -v a="$t0" -v b="$t1" 'BEGIN{printf "%.3f", b - a}')")
    fi
    jq -n --arg w "$w" --arg hr "$hr" '{watts: (if $w == "" then null else ($w | tonumber) end), hs_per_watt: (if $w == "" or $hr == "" or ($w | tonumber) == 0 then null else (($hr | tonumber) / ($w | tonumber)) end)}'
}

# Tune/autotune state as JSON — the machine-readable sibling of _tune_history (same sources, same
# systemctl reads). Every jq program here is single-line: kcov cannot attribute in-string lines.
_api_tune_json() {
    local ovr="$WORKER_ROOT/tune-overrides.json" logf="$WORKER_ROOT/rigforge-tune.json"
    local applied=null target=null best=null n=null aten=false atgt="" asched="" anext=""
    if [ -s "$ovr" ] && jq -e . "$ovr" >/dev/null 2>&1; then applied=$(cat "$ovr"); fi
    if [ -s "$logf" ] && jq -e . "$logf" >/dev/null 2>&1; then
        target=$(jq -c '.target // null' "$logf" 2>/dev/null || echo null)
        best=$(jq -c '.best.hashrate // null' "$logf" 2>/dev/null || echo null)
        n=$(jq -c '.results | length' "$logf" 2>/dev/null || echo null)
    fi
    if [ "$OS_TYPE" = Linux ] && command -v systemctl >/dev/null 2>&1 && systemctl cat rigforge-autotune.timer >/dev/null 2>&1; then
        aten=true
        atgt=$(systemctl cat rigforge-autotune.service 2>/dev/null | sed -nE 's/^Environment=AUTOTUNE_TARGET=//p' | head -1)
        asched=$(systemctl cat rigforge-autotune.timer 2>/dev/null | sed -nE 's/^OnCalendar=//p' | head -1)
        anext=$(systemctl show rigforge-autotune.timer -p NextElapseUSecRealtime --value 2>/dev/null || true)
    fi
    jq -n --argjson applied "$applied" --argjson target "$target" --argjson best "$best" --argjson n "$n" --argjson aten "$aten" --arg atgt "$atgt" --arg asched "$asched" --arg anext "$anext" '{applied: $applied, target: $target, last_best_hs: $best, candidates_tried: $n, autotune: {enabled: $aten, target: (if $atgt == "" then null else $atgt end), schedule: (if $asched == "" then null else $asched end), next: (if $anext == "" then null else $anext end)}}'
}

# Health probes reuse doctor's helpers so wire and human reports agree.
_health_json() {
    local sa=false hp_total="" hp1g="" gov="" msr_st="" wr="" logf="" mem pop nch spd rated smt="" bv="" bn="" pct="" thr=null xmp=null effk maxk
    if [ "$OS_TYPE" = Linux ] && command -v systemctl >/dev/null 2>&1 && systemctl is-active --quiet "$SERVICE_NAME" 2>/dev/null; then sa=true; fi
    hp_total=$(awk '/^HugePages_Total:/ {print $2}' "$MEMINFO" 2>/dev/null || true)
    hp1g=$(cat "$HUGEPAGES_1G_NR" 2>/dev/null || true)
    gov=$(cat "$GOVERNOR_FILE" 2>/dev/null || true)
    wr=$(_worker_root_from_config)
    [ -n "$wr" ] && logf=$(jq -r '."log-file" // empty' "$wr/xmrig/build/config.json" 2>/dev/null || true)
    msr_st=$(_msr_log_status "${logf:-/nonexistent}" | cut -f1)
    mem=$(_mem_summary)
    read -r pop nch spd rated <<<"${mem:-0 0 0 0}"
    if [ "${rated:-0}" -gt 0 ] 2>/dev/null && [ "${spd:-0}" -gt 0 ] 2>/dev/null; then
        if [ "$spd" -lt "$rated" ]; then xmp=false; else xmp=true; fi
    fi
    smt=$(cat "$SMT_CONTROL" 2>/dev/null || true)
    bv=$(_dmi board_vendor)
    bn=$(_dmi board_name)
    if [ "$sa" = true ]; then
        maxk=$(cat "$CPUFREQ_MAX" 2>/dev/null || true)
        effk=$(_cpu_eff_khz)
        if [ -n "$effk" ] && [ "${maxk:-0}" -gt 0 ] 2>/dev/null; then
            pct=$((effk * 100 / maxk))
            if [ "$pct" -lt "$MIN_CLOCK_PCT" ]; then thr=true; else thr=false; fi
        fi
    fi
    jq -n --argjson sa "$sa" --arg hpt "${hp_total:-}" --arg hp1g "${hp1g:-}" --arg gov "$gov" --arg msr "${msr_st:-none}" --arg pop "${pop:-0}" --arg nch "${nch:-0}" --arg spd "${spd:-0}" --arg rated "${rated:-0}" --argjson xmp "$xmp" --arg smt "$smt" --arg bv "$bv" --arg bn "$bn" --arg pct "${pct:-}" --argjson thr "$thr" '{service_active: $sa, hugepages_total: (if $hpt == "" then null else ($hpt | tonumber) end), hugepages_1g: (if $hp1g == "" then null else ($hp1g | tonumber) end), governor: (if $gov == "" then null else $gov end), msr: $msr, ram: {modules: ($pop | tonumber), channels: ($nch | tonumber), mts: ($spd | tonumber), rated_mts: ($rated | tonumber)}, xmp: $xmp, smt: (if $smt == "" then null else $smt end), firmware: {vendor: (if $bv == "" then null else $bv end), board: (if $bn == "" then null else $bn end)}, clock_pct_of_boost: (if $pct == "" then null else ($pct | tonumber) end), throttling: $thr}'
}

# Watchdog state as JSON (#212): when the watchdog stops the miner, the sister API is the one
# component still alive — a thermally-held rig must say "held, resumes below N" on the wire, not
# look mystery-dead. Reads the same state files watchdog() writes; absent or garbled files
# degrade to defaults and never fail the refresh.
_watchdog_json() {
    local wr hold=false strikes t=""
    if [ "${WATCHDOG_MODE:-disabled}" = disabled ]; then
        jq -n '{mode: "disabled"}'
        return 0
    fi
    wr=$(_worker_root_from_config)
    [ -n "$wr" ] && [ -f "$wr/watchdog.thermal-hold" ] && hold=true
    strikes=$(cat "$wr/watchdog.fails" 2>/dev/null || true)
    [[ "$strikes" =~ ^[0-9]+$ ]] || strikes=0
    t=$(_read_temp 2>/dev/null || true)
    jq -n --argjson hold "$hold" --arg mt "${MAX_TEMP_C:-}" --arg t "$t" --arg s "$strikes" '{mode: "enabled", thermal_hold: $hold, max_temp_c: (if $mt == "" then null else ($mt | tonumber) end), resumes_below_c: (if $mt == "" then null else (($mt | tonumber) - 5) end), temp_c: (if $t == "" then null else ($t | tonumber) end), strikes: ($s | tonumber)}'
}

# Provenance + tune + power + health, namespaced under one `rigforge` key. Runs in the refresh
# timer, never on a request path, so it can afford the full probe pass every time.
# #253/#254: the effective WRITABLE config in CANONICAL form — exactly the control-path allowlist,
# read the same way parse_config does (canonical strings perf->performance, on/true->enabled), keys
# sorted. Single source of truth for the masked feed view (#253) AND the revision hash (#254), so what
# a consumer reads, hashes, and can POST back all agree. UNMASKED here (pool pass included): the hash
# is one-way so it never leaks, and the revision must bump on ANY writable change incl. a pool password.
_writable_config_canonical() {
    local pools
    pools=$(jq -c '.pools // []' "$CONFIG_JSON" 2>/dev/null || echo '[]')
    [ -n "$pools" ] || pools='[]'
    jq -Sn --argjson pools "$pools" --argjson don "${DONATION:-0}" --arg at "${AUTOTUNE_MODE:-disabled}" --arg wd "${WATCHDOG_MODE:-disabled}" --argjson wi "${WATCHDOG_INTERVAL_MIN:-5}" --arg mt "${MAX_TEMP_C:-}" '{pools: $pools, DONATION: $don, autotune: $at, watchdog: $wd, watchdog_interval_min: $wi, max_temp_c: (if $mt == "" then null else ($mt | tonumber) end)}'
}

# #254: a short content hash of the canonical writable config — the load-bearing "did it change"
# signal a polling consumer compares against. Changes iff the effective writable config changes.
_writable_config_hash() { _sha256 <(_writable_config_canonical) | cut -c1-16; }

# #253: the MASKED view for the open feed — no pool credential is ever served on the token-optional
# read. #415: a SET secret is masked to the {"__secret__": true} sentinel rather than deleted
# outright. Deleting the value was right; deleting the *fact* that one is set was not. A consumer
# building an editor over this feed could not tell a pool with a password from one without, so it
# could not offer "leave blank to keep it" — its only choices were to re-send `pools` with no `pass`
# (which _control_commit then wiped, silently, to the throwaway "x") or to refuse every pools edit.
# The sentinel is the one Pithead's Configuration view already uses, and _control_commit resolves it
# back to the stored value. A key that is unset — or holds anything but a non-empty string — stays
# ABSENT, so "no marker" means "there is nothing here to keep", and the value itself never leaves.
_api_config_json() {
    _writable_config_canonical | jq -c 'def mask($k): if (.[$k] | type) == "string" and .[$k] != "" then .[$k] = {"__secret__": true} else del(.[$k]) end; .pools = [.pools[]? | if type == "object" then mask("pass") | mask("tls-fingerprint") else . end]'
}

# #254: config-change provenance marker. Stamped by every path that rewrites the writable config
# (local apply, control-apply, restore) via _stamp_config_meta; updated ONLY when the writable hash
# actually changes, so a no-op apply never false-bumps it. (autotune tunes runtime params — threads,
# MSR — not the writable config, so it is never a source here.)
_stamp_config_meta() { # <source> [change_id] — record provenance IFF the writable config changed
    local src="$1" cid="${2:-}" newrev oldrev
    # Self-sufficient + error-isolated: parse the current config.json in a subshell, so this is safe to
    # call from restore/apply/control regardless of whether the caller has parsed (and a bad config
    # can't abort the caller).
    newrev=$( (parse_config >/dev/null 2>&1 && _writable_config_hash) 2>/dev/null) || newrev=""
    [ -n "$newrev" ] || return 0
    oldrev=$(jq -r '.revision // ""' "$CONFIG_META_FILE" 2>/dev/null || echo "")
    [ "$newrev" = "$oldrev" ] && return 0
    jq -n --arg r "$newrev" --arg s "$src" --arg c "$cid" --arg w "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '{revision: $r, source: $s, last_change_id: (if $c == "" then null else $c end), changed_at: $w}' >"$CONFIG_META_FILE.tmp.$$" 2>/dev/null && mv -f "$CONFIG_META_FILE.tmp.$$" "$CONFIG_META_FILE" && chmod 644 "$CONFIG_META_FILE" 2>/dev/null || true
}

# #254: the config_meta block for the feed. revision is recomputed here (authoritative — catches even
# a raw hand-edit that never ran apply); source/changed_at/last_change_id come from the marker
# (best-effort attribution, null on a fresh rig that hasn't changed its config yet).
_api_config_meta_json() {
    local rev
    rev=$(_writable_config_hash)
    if [ -f "$CONFIG_META_FILE" ]; then
        jq --arg rev "$rev" '{revision: $rev, changed_at: .changed_at, source: .source, last_change_id: .last_change_id}' "$CONFIG_META_FILE" 2>/dev/null || jq -n --arg rev "$rev" '{revision: $rev, changed_at: null, source: null, last_change_id: null}'
    else
        jq -n --arg rev "$rev" '{revision: $rev, changed_at: null, source: null, last_change_id: null}'
    fi
}
# #346: mirror the last control outcome; missing, unreadable or malformed status.json -> null, never a broken feed.
_api_control_json() {
    jq -c '{change_id, status, reason}' "${RIGFORGE_CONTROL_STATE:-/var/lib/rigforge-control}/status.json" 2>/dev/null || echo null
}
_api_control_history_json() { for f in "${RIGFORGE_CONTROL_STATE:-/var/lib/rigforge-control}/changes"/*.json; do [ -f "$f" ] && jq -c '{change_id, status, reason}' "$f" 2>/dev/null; done | jq -cs '.' || true; } # #519: per-file so one malformed entry drops only itself; || true as the loop's rc leaks through pipefail
_api_rigforge_block() {                                                                                                                                                                                            # <hashrate|"">
    jq -n --arg v "$(cat "$SCRIPT_DIR/VERSION" 2>/dev/null || echo unknown)" --arg xv "$XMRIG_VERSION" --arg xc "$XMRIG_COMMIT" --argjson tune "$(_api_tune_json)" --argjson power "$(_api_power_json "$1")" --argjson health "$(_health_json)" --argjson watchdog "$(_watchdog_json)" --argjson config "$(_api_config_json)" --argjson config_meta "$(_api_config_meta_json)" --argjson control "$(_api_control_json)" --argjson control_history "$(_api_control_history_json)" '{version: $v, xmrig_version: $xv, xmrig_commit: $xc, tune: $tune, power: $power, health: $health, watchdog: $watchdog, config: $config, config_meta: $config_meta, control: $control, control_history: $control_history}'
}
# Produce response bodies atomically; the idle timer keeps probes off the request path (#164).
api_refresh() {
    [ "$OS_TYPE" = Linux ] || error "api-refresh is driven by the rigforge-api-refresh systemd timer and is Linux-only."
    parse_config >/dev/null
    local dir="${RIGFORGE_API_DATA:-/run/rigforge-api}" sum hr rf body generated_at
    mkdir -p "$dir"
    generated_at=$(date -u +%Y-%m-%dT%H:%M:%SZ)
    sum=$(_read_api_summary || true)
    printf '%s' "$sum" | jq -e . >/dev/null 2>&1 || sum=""
    hr=$(printf '%s' "$sum" | jq -r '.hashrate.total[0] // empty' 2>/dev/null || true)
    rf=$(_api_rigforge_block "$hr")
    # Preserve every XMRig field and add one namespaced key; health still serves if XMRig is down.
    if [ -n "$sum" ]; then body=$(jq -n --arg g "$generated_at" --argjson x "$sum" --argjson r "$rf" '$x + {generated_at: $g, rigforge: $r}'); else body=$(jq -n --arg g "$generated_at" --argjson r "$rf" '{generated_at: $g, rigforge: ($r + {xmrig_api: "unreachable"})}'); fi
    printf '%s' "$body" >"$dir/summary.json.tmp.$$" && mv -f "$dir/summary.json.tmp.$$" "$dir/summary.json"
    printf '%s' "$rf" | jq -c --arg g "$generated_at" '.health + {watchdog: .watchdog, generated_at: $g}' >"$dir/health.json.tmp.$$" && mv -f "$dir/health.json.tmp.$$" "$dir/health.json"
    printf '%s' "$rf" | jq -c '.tune' >"$dir/tune.json.tmp.$$" && mv -f "$dir/tune.json.tmp.$$" "$dir/tune.json"
}
_api_refresh_status() {
    local file="${RIGFORGE_API_DATA:-/run/rigforge-api}/summary.json" next last refresh_state stamp mtime now age i
    for i in 1 2 3 4 5; do
        next=$(systemctl show rigforge-api-refresh.timer -p NextElapseUSecRealtime --value 2>/dev/null || true)
        { [ -n "$next" ] && [ "$next" != n/a ]; } && break
        sleep 1
    done
    last=$(systemctl show rigforge-api-refresh.timer -p LastTriggerUSec --value 2>/dev/null || true)
    if [ ! -f "$file" ]; then
        printf 'sister feed is stale since never (next: %s; last: %s; payload missing)' "${next:-none}" "${last:-never}"
        return 1
    fi
    stamp=$(jq -r '.generated_at // empty' "$file" 2>/dev/null || true)
    mtime=$(date -d "$stamp" +%s 2>/dev/null || stat -c %Y "$file" 2>/dev/null || echo 0)
    now=$(date +%s)
    age=$((now - mtime))
    [ "$age" -lt 0 ] && age=0
    if [ -z "$next" ] || [ "$next" = n/a ]; then
        refresh_state=$(systemctl show rigforge-api-refresh.service -p ActiveState --value 2>/dev/null || true)
        if [ "$refresh_state" = active ] || [ "$refresh_state" = activating ]; then
            [ "$age" -le 300 ] || {
                printf 'sister feed refresh appears stuck (last: %s; payload age: %ss)' "${last:-never}" "$age"
                return 1
            }
            printf 'sister feed refresh in progress (last: %s; payload age: %ss)' "${last:-never}" "$age"
            return 0
        fi
        next=$(systemctl show rigforge-api-refresh.timer -p NextElapseUSecRealtime --value 2>/dev/null || true)
        if [ -z "$next" ] || [ "$next" = n/a ]; then
            printf 'sister feed has no next refresh (last: %s; payload age: %ss)' "${last:-never}" "$age"
            return 1
        fi
    fi
    if [ "$age" -gt 60 ]; then
        printf 'sister feed is stale since %s (next: %s; last: %s; payload age: %ss)' "${stamp:-unknown}" "${next:-none}" "${last:-never}" "$age"
        return 1
    fi
    printf 'sister feed refresh scheduled (next: %s; last: %s; payload age: %ss)' "$next" "${last:-never}" "$age"
}
# --- Doctor: one-stop health check ---
# Pool-connection probe (#343), shared by doctor and apply.
# The miner's own pool verdict from local /2/summary (API_CMD hook + _read_api_summary auth). One TSV line:
#   connected <pool> <conn_uptime_s> <accepted>   — a stratum connection is live
#   disconnected <pool> <failures>                — miner answers, but no live connection
#   api-down                                      — no parseable summary (API unreachable)
# connection.uptime is XMRig's seconds-since-connect: positive exactly while a pool connection is
# live, 0 while it retries (DNS failure, refused, pool down) — the signal #343 found missing. We
# read the miner's view rather than dialing the pool ourselves: a second dial from this script can
# disagree with the miner's (proxied, TLS) one, and the miner is the party that has to be connected.
_pool_conn_status() {
    local body pool cup fails acc
    body=$(_read_api_summary)
    if ! printf '%s' "$body" | jq -e '.connection' >/dev/null 2>&1; then
        echo api-down
        return 0
    fi
    # The "?" placeholder is jq-side, not bash-side: a disconnected xmrig reports pool "", and an
    # empty FIRST tsv field would be swallowed by read (tab is IFS *whitespace*, so leading tabs
    # strip) — every later field would shift one left and "failures: 2" would parse as a live
    # connection. Emitting a non-empty field for every column keeps the read aligned.
    IFS="$(printf '\t')" read -r pool cup fails acc <<EOF
$(printf '%s' "$body" | jq -r '[(.connection.pool | if . == null or . == "" then "?" else . end), (.connection.uptime // 0), (.connection.failures // 0), (.connection.accepted // 0)] | @tsv' 2>/dev/null)
EOF
    [ -n "${pool:-}" ] || pool="?" # belt (jq guarantees non-empty) and braces (an unparseable body)
    if [ "${cup:-0}" -gt 0 ] 2>/dev/null; then
        printf 'connected\t%s\t%s\t%s\n' "$pool" "$cup" "${acc:-0}"
    else
        printf 'disconnected\t%s\t%s\n' "$pool" "${fails:-0}"
    fi
}

# One guarded TCP dial, rc-only — doctor's fallback when the miner isn't running to testify itself.
# Host and port ride in as positional args (never interpolated into the -c string, so a hostile
# config.json can't inject shell), and `timeout` bounds the hang a filtered port would cause.
_tcp_probe() { # <host> <port>
    if command -v timeout >/dev/null 2>&1; then
        timeout 5 bash -c 'exec 3<>"/dev/tcp/$0/$1"' "$1" "$2" 2>/dev/null
    else
        bash -c 'exec 3<>"/dev/tcp/$0/$1"' "$1" "$2" 2>/dev/null
    fi
}

_check_donation() {
    local want got
    want=$(jq -r '.DONATION // 0' "$CONFIG_JSON" 2>/dev/null) || return 0
    _uint_in_range "$want" 0 100 || return 0
    got=$(_read_api_summary | jq -er '.donate_level | select(type == "number" and . >= 0 and . <= 100 and floor == .)' 2>/dev/null) || got=""
    if [ -z "$got" ]; then
        _ck_info "XMRig donation level unavailable — cannot verify DONATION"
    elif [ "$got" != "$want" ]; then
        _ck_warn "XMRig donate_level $got differs from DONATION $want — upgrade an older build, then apply and restart"
        return 1
    else
        _ck_ok "XMRig donate_level matches DONATION ($want%)"
    fi
}

doctor() {
    cmd_version
    if [ "$OS_TYPE" != "Linux" ]; then
        warn "doctor's health checks are Linux-only (this host is $OS_TYPE)."
        return 0
    fi
    log "Checking the worker (read-only)..."
    local issues=0

    case "$(jq -r 'if (.control | tostring) | test("^(enabled|true|on)$") then "enabled" else (.api // "disabled") end' "$CONFIG_JSON" 2>/dev/null || true)" in # #507: doctor has no parse_config, so it re-derives control's api implication here
    enabled | true | on)
        local refresh_state
        if refresh_state=$(_api_refresh_status); then _ck_ok "$refresh_state"; else
            _ck_warn "$refresh_state"
            issues=$((issues + 1))
        fi
        ;;
    esac

    # Service active?
    local svc_up=n
    if systemctl is-active --quiet "$SERVICE_NAME" 2>/dev/null; then
        svc_up=y
        _ck_ok "service '$SERVICE_NAME' is active"
    else
        _ck_warn "service '$SERVICE_NAME' is not active — start it with: sudo $0 start"
        issues=$((issues + 1))
    fi

    # Use the live miner verdict when running; a stopped miner can only support a TCP probe.
    if [ -f "$CONFIG_JSON" ]; then
        local pc_st="" pc_pool="" pc_n1="" pc_n2="" pool0 ph pp proxy
        pool0=$(jq -r '.pools[0].url // empty' "$CONFIG_JSON" 2>/dev/null || true)
        # Advisory only: a listening TCP socket does not prove SOCKS/Tor or mining works.
        while IFS= read -r proxy; do
            (_validate_host_port "$proxy" "Pool socks5" 9050) >/dev/null 2>&1 || {
                _ck_warn "configured SOCKS proxy has an invalid host:port — check pools[].socks5"
                continue
            }
            ph=${proxy%:*}
            pp=${proxy##*:}
            ph=${ph#\[}
            ph=${ph%\]}
            _tcp_probe "$ph" "$pp" || _ck_warn "configured SOCKS proxy is unreachable (TCP connect failed) — check pools[].socks5 and install/start Tor if needed"
        done < <(jq -r '[.pools[]? | select(.enabled != false) | .socks5 | select(. != null and . != "")] | unique[] | if type == "string" and (test("[[:cntrl:]]") | not) then . else "invalid proxy" end' "$CONFIG_JSON" 2>/dev/null)
        if [ "$svc_up" = y ]; then
            if ! ACCESS_TOKEN="$(jq -r '.ACCESS_TOKEN // empty' "$CONFIG_JSON" 2>/dev/null || true)" _check_donation; then
                issues=$((issues + 1))
            fi
            IFS="$(printf '\t')" read -r pc_st pc_pool pc_n1 pc_n2 <<EOF
$(ACCESS_TOKEN="$(jq -r '.ACCESS_TOKEN // empty' "$CONFIG_JSON" 2>/dev/null || true)" _pool_conn_status)
EOF
            case "$pc_st" in
            connected)
                _ck_ok "pool connection live: $pc_pool (up $(_render_duration "${pc_n1:-0}"), ${pc_n2:-0} share(s) accepted)"
                ;;
            disconnected)
                { [ -n "$pc_pool" ] && [ "$pc_pool" != "?" ]; } || pc_pool="${pool0:-?}"
                _ck_warn "miner is running but has NO live pool connection (pool: $pc_pool, ${pc_n1:-0} failed attempt(s)) — the rig is not mining; check pools[0].url in config.json and '$0 logs'"
                issues=$((issues + 1))
                ;;
            *)
                _ck_info "worker API not reachable at 127.0.0.1:8080 — can't verify the pool connection (the miner may still be starting; re-run doctor shortly)"
                ;;
            esac
        elif [ -n "$(jq -r '.pools[0].socks5 // empty' "$CONFIG_JSON" 2>/dev/null)" ]; then
            _ck_info "miner stopped — can't verify the pool connection through SOCKS until it starts"
        elif [ -n "$pool0" ]; then
            ph=${pool0#*://}
            pp=${ph##*:}
            ph=${ph%:*}
            if [[ "$pp" =~ ^[0-9]+$ ]]; then
                if _tcp_probe "$ph" "$pp"; then
                    _ck_info "pool $ph:$pp accepts TCP connections (miner stopped — the live check runs once it's started)"
                else
                    _ck_warn "pool $ph:$pp is unreachable (TCP connect failed) — the rig cannot mine until pools[0].url points at a reachable pool"
                    issues=$((issues + 1))
                fi
            fi
        fi
    fi

    # HugePages reserved? (the single biggest lever; needs a reboot after setup)
    local hp
    hp=$(awk '/^HugePages_Total:/ {print $2; exit}' "$MEMINFO" 2>/dev/null)
    if [ -n "$hp" ] && [ "$hp" -gt 0 ] 2>/dev/null; then
        _ck_ok "HugePages reserved (HugePages_Total=$hp)"
    else
        _ck_warn "HugePages not reserved — reboot after setup (the GRUB change needs a reboot)"
        issues=$((issues + 1))
    fi

    # 1GB HugePages (optional bonus)
    local g=0
    [ -f "$HUGEPAGES_1G_NR" ] && g=$(cat "$HUGEPAGES_1G_NR" 2>/dev/null || echo 0)
    if [ "${g:-0}" -gt 0 ] 2>/dev/null; then
        _ck_ok "1GB HugePages reserved ($g)"
    else
        _ck_warn "1GB HugePages not reserved (optional; needs a pdpe1gb CPU + reboot)"
    fi

    # CPU ISA support (#338): a rig without AES-NI mines at soft-AES speed (~4x slower) with no
    # error anywhere — exactly the "silently failing" #1's acceptance criterion forbids, so it's a
    # counted issue. Missing AVX2 only slows dataset init: advisory. Quiet when there's no x86
    # flags line to judge (unknown, not unsupported).
    local miss_isa
    miss_isa=$(_cpu_missing_isa)
    if [[ " $miss_isa " == *" aes "* ]]; then
        _ck_warn "CPU has no AES-NI — RandomX runs soft AES, roughly 4x slower; this hardware cannot mine at a competitive rate"
        issues=$((issues + 1))
    else
        # The ok line only when there IS a flags line to have judged; no flags line = unknown, say nothing.
        grep -q '^flags' "$CPUINFO" 2>/dev/null && _ck_ok "CPU supports AES-NI (hardware RandomX path)" || true
    fi
    [[ " $miss_isa " == *" avx2 "* ]] && _ck_info "CPU has no AVX2 — dataset init is slower (steady-state hashrate unaffected)"
    # Resolve the configured log once — appliance mode intentionally has no persistent file log (#477).
    local wr="" log_file="" live_log_cfg=""
    if [ -f "$CONFIG_JSON" ]; then
        wr=$(_worker_root_from_config)
        log_file="$wr/xmrig.log"
        live_log_cfg="$wr/xmrig/build/config.json"
        [ -f "$live_log_cfg" ] && log_file=$(jq -r '."log-file" // empty' "$live_log_cfg" 2>/dev/null || true)
    fi
    # Privilege separation (#140): when the config asks for an unprivileged miner, the unit must
    # actually say so (a stale unit from before the change would still run root). Quiet when
    # systemctl can't answer (non-systemd test envs).
    local cfg_mu=""
    [ -f "$CONFIG_JSON" ] && cfg_mu=$(jq -r '.miner_user // empty' "$CONFIG_JSON" 2>/dev/null || true)
    if [ -n "$cfg_mu" ]; then
        local svc_user
        svc_user=$(systemctl show -p User --value "$SERVICE_NAME" 2>/dev/null || true)
        if [ "$svc_user" = "$cfg_mu" ]; then
            _ck_ok "miner runs unprivileged as '$cfg_mu' (miner_user)"
        elif [ -n "$svc_user" ]; then
            _ck_warn "config sets miner_user='$cfg_mu' but the unit runs as '$svc_user' — re-run 'sudo $0 apply'"
            issues=$((issues + 1))
        fi
        if [ -n "$wr" ] && [ -f "$wr/.rigforge-msr-preset" ]; then
            local _mp
            _mp=$(cat "$wr/.rigforge-msr-preset" 2>/dev/null || true)
            _msr_rdmsr_verify "$_mp"
            if [ "$_MSR_TOTAL" -gt 0 ] && [ "$_MSR_OK" = "$_MSR_TOTAL" ]; then
                _ck_ok "root-side MSR preset '$_mp' verified by register read-back ($_MSR_OK/$_MSR_TOTAL)"
            elif [ "$_MSR_UNREAD" = "$_MSR_TOTAL" ]; then
                _ck_info "root-side MSR preset '$_mp' recorded — run doctor as root for the register read-back"
            else
                _ck_warn "root-side MSR preset '$_mp': only $_MSR_OK/$_MSR_TOTAL registers match (bad:$_MSR_BAD)"
                issues=$((issues + 1))
            fi
        fi
    fi
    # Binary tamper evidence (#141): the artifact that runs 24/7 as root should still be the one we
    # built. Recompute and compare against the build-time record; a missing record (older build) is
    # advisory only — the next rebuild writes one.
    local bin="$wr/xmrig/build/xmrig" sums="$wr/xmrig/.rigforge-sha256"
    if [ -n "$wr" ] && [ -f "$bin" ]; then
        if [ ! -f "$sums" ]; then
            _ck_info "no build-time checksum recorded (older build) — the next setup/upgrade rebuild records one"
        elif [ "$(cat "$sums" 2>/dev/null)" = "$(_sha256 "$bin")" ]; then
            _ck_ok "xmrig binary matches its build-time SHA-256 (unchanged since compile)"
        else
            _ck_warn "xmrig binary CHANGED since it was built — re-run 'sudo $0 setup' to rebuild, or investigate how it changed"
            issues=$((issues + 1))
        fi
    fi
    # Read-only API posture (#135): exposing the HTTP API on 0.0.0.0:8080 is safe ONLY because the
    # generated config pins http.restricted=true — assert the live file still does, so a hand-edit
    # or a bad merge can't silently turn the read-only API into a control plane. Quiet when there is
    # no built config yet (setup hasn't run); the service check above already covers that state.
    local live_cfg="" restricted=""
    [ -n "$wr" ] && live_cfg="$wr/xmrig/build/config.json"
    if [ -n "$live_cfg" ] && [ -f "$live_cfg" ]; then
        restricted=$(jq -r '.http.restricted' "$live_cfg" 2>/dev/null || true)
        if [ "$restricted" = "true" ]; then
            _ck_ok "HTTP API is read-only (http.restricted=true in the live config)"
        else
            _ck_warn "HTTP API is NOT read-only (http.restricted=${restricted:-unreadable}) — regenerate it with: sudo $0 apply"
            issues=$((issues + 1))
        fi
    fi

    # Combined exposure posture: open (tokenless) AND unscoped is the designed LAN default, but it
    # deserves one loud advisory line. Advisory, not a counted issue.
    if [ -f "$CONFIG_JSON" ]; then
        local cfg_tok cfg_scope cfg_extra_n
        cfg_tok=$(jq -r '.ACCESS_TOKEN // empty' "$CONFIG_JSON" 2>/dev/null || true)
        cfg_scope=$(jq -r '.api_allow_from // empty' "$CONFIG_JSON" 2>/dev/null || true)
        cfg_extra_n=$(jq -r '(.ACCESS_TOKENS // {}) | length' "$CONFIG_JSON" 2>/dev/null || echo 0)
        if [ -z "$cfg_tok" ] && [ -z "$cfg_scope" ]; then
            _ck_info "API is open (no ACCESS_TOKEN) and unscoped (no api_allow_from) — fine on a trusted LAN; set one of them before this rig faces anything else"
        else
            _ck_ok "API exposure is limited (${cfg_tok:+token}${cfg_tok:+${cfg_scope:+ + }}${cfg_scope:+firewall scope})"
        fi
        # #516: xmrig's :8080 is master-only; :8081/:8082 take any configured token. Never interpolate
        # cfg_tok itself here — this line is a NAME/COUNT report, not a value one.
        _ck_info "$(($([ -n "$cfg_tok" ] && echo 1 || echo 0) + cfg_extra_n)) access token(s) configured ($([ -n "$cfg_tok" ] && echo 1 || echo 0) master + $cfg_extra_n named in ACCESS_TOKENS); xmrig's own :8080 API carries $([ -n "$cfg_tok" ] && echo "ACCESS_TOKEN (the master)" || echo "no token (open)")"
    fi

    # Control receiver health (#278): probe the writable service when enabled; retry briefly because
    # systemd marks the Python service active before it binds its socket on a busy miner.
    if [ -f "$CONFIG_JSON" ]; then
        local cfg_control
        cfg_control=$(jq -r '.control // "disabled"' "$CONFIG_JSON" 2>/dev/null || true)
        case "$cfg_control" in
        enabled | true | on)
            if systemctl is-active --quiet rigforge-control 2>/dev/null; then
                local ctl_port ctl_tok ctl_code i
                ctl_port=$(jq -r '.control_port // 8082' "$CONFIG_JSON" 2>/dev/null || true)
                ctl_tok=$(jq -r '.ACCESS_TOKEN // empty' "$CONFIG_JSON" 2>/dev/null || true)
                # 200/503 both mean answering; 503 only means no change has been applied yet.
                for i in 1 2 3 4 5; do
                    ctl_code=$(_bearer_curl "$ctl_tok" -sS --max-time 2 -o /dev/null -w '%{http_code}' "http://127.0.0.1:${ctl_port:-8082}/status" 2>/dev/null || true)
                    case "$ctl_code" in 200 | 503) break ;; esac
                    [ "$i" = 5 ] || sleep 1
                done
                case "$ctl_code" in
                200 | 503) _ck_ok "control receiver is active and responding (rigforge-control, :${ctl_port:-8082})" ;;
                *)
                    _ck_warn "control: enabled and rigforge-control is active, but :${ctl_port:-8082}/status isn't responding — check journalctl -u rigforge-control"
                    issues=$((issues + 1))
                    ;;
                esac
            else
                _ck_warn "control: enabled but rigforge-control is inactive — run 'sudo $0 apply' or check journalctl -u rigforge-control"
                issues=$((issues + 1))
            fi
            ;;
        esac
    fi

    # MSR mod applied? (#66) The ~10-15% RandomX gain needs three things, checked in order: the msr
    # module loadable, XMRig's own log line confirming it WROTE the prefetcher preset, and — when rdmsr
    # (msr-tools) is present — a register read-back that catches a write a hypervisor/lockdown dropped.
    # Kernel lockdown (#333) — checked BEFORE the MSR probes below, because it is the CAUSE and they are
    # the symptom. Under lockdown, msr_write()/msr_ioctl() call security_locked_down(LOCKDOWN_MSR) and
    # return -EPERM *before* consulting the allow_writes filter (arch/x86/kernel/msr.c), so the
    # msr.allow_writes=on we put on the cmdline cannot override it. Reading the state beats inferring it
    # from Secure Boot: whether Secure Boot implies lockdown is a distro patch, not upstream behaviour.
    local ld
    ld=$(_lockdown_state)
    if [ -z "$ld" ]; then
        _ck_info "kernel lockdown state unknown ($LOCKDOWN_FILE unreadable) — run 'doctor' as root, or the lockdown LSM isn't built in"
    elif _lockdown_blocks_msr "$ld"; then
        _ck_warn "kernel lockdown is ACTIVE ('$ld') — it denies every /dev/cpu/*/msr write, so the MSR mod cannot apply (worth ~5-15% RandomX). msr.allow_writes=on does NOT override it: disable Secure Boot in BIOS ($(_bios_menu "$(_dmi board_vendor)" secure_boot "${TUNE_TARGET:-perf}")), then re-run 'sudo $0 doctor'."
        issues=$((issues + 1))
    else
        _ck_ok "kernel lockdown: none — MSR writes are permitted"
    fi

    if [ -d "$MSR_MODULE_DIR" ]; then
        _ck_ok "msr kernel module loaded"
    else
        # Secure Boot does NOT stop the in-tree, distro-signed `msr` module from loading, so the old
        # "disable Secure Boot" hint pointed the wrong way here (#333). A missing module is a modprobe /
        # packaging problem; lockdown is reported separately above.
        _ck_warn "msr module not loaded — the MSR mod won't apply; check 'sudo modprobe msr' and $MODULES_LOAD_DIR/msr.conf"
        issues=$((issues + 1))
    fi
    if [ -n "$wr" ]; then
        local msrstat="" preset=""
        IFS="$(printf '\t')" read -r msrstat preset <<EOF
$(_msr_log_status "$log_file")
EOF
        case "$msrstat" in
        ok)
            _ck_ok "MSR mod applied — XMRig set the '${preset:-?}' preset (per its log)"
            # Register-level read-back (rdmsr) needs root + the msr device; it's the strong check that
            # catches a write a hypervisor/lockdown silently dropped. Degrade gracefully otherwise — the
            # log line above already confirms XMRig wrote the preset, so missing rdmsr is advisory, never
            # an issue. Mirrors the #67 RAM check, which also asks for root rather than crying wolf.
            if [ "$(id -u)" -ne 0 ]; then
                _ck_warn "run 'doctor' as root (sudo) to verify the MSRs at the register level (advisory; XMRig's log already confirms the write)"
            elif ! command -v "$RDMSR_BIN" >/dev/null 2>&1; then
                _ck_warn "rdmsr not found — install msr-tools to verify the MSRs at the register level (advisory; XMRig's log already confirms the write)"
            elif [ -n "$(_msr_preset_regs "$preset")" ]; then
                _msr_rdmsr_verify "$preset"
                if [ "${_MSR_OK:-0}" -gt 0 ] && [ "${_MSR_OK:-0}" -eq "${_MSR_TOTAL:-0}" ]; then
                    _ck_ok "MSR registers verified via rdmsr ($_MSR_OK/$_MSR_TOTAL match the $preset preset)"
                elif [ -n "$_MSR_BAD" ]; then
                    # A genuine value mismatch — the write didn't take. This is the real failure (#66).
                    # #333: when lockdown is active we already know which of the three causes it was —
                    # say so instead of listing all of them.
                    if _lockdown_blocks_msr "$ld"; then
                        _ck_warn "MSR registers don't match the $preset preset ($_MSR_OK/$_MSR_TOTAL ok;${_MSR_BAD}) — kernel lockdown ('$ld') dropped the write; see the lockdown item above"
                    else
                        _ck_warn "MSR registers don't match the $preset preset ($_MSR_OK/$_MSR_TOTAL ok;${_MSR_BAD}) — a hypervisor may have dropped the write, or XMRig changed its preset"
                    fi
                    issues=$((issues + 1))
                else
                    # No mismatch, but some/all registers were unreadable (e.g. msr module not loaded). Advisory.
                    _ck_warn "couldn't read $_MSR_UNREAD/$_MSR_TOTAL MSR(s) via rdmsr (is the 'msr' module loaded?) — relying on XMRig's log confirmation"
                fi
            fi
            ;;
        fail)
            # #333: msr.allow_writes=on is only the answer when lockdown is NOT the blocker — under
            # lockdown the kernel rejects the write before the filter ever runs.
            if _lockdown_blocks_msr "$ld"; then
                _ck_warn "XMRig reports the MSR preset FAILED to set — kernel lockdown ('$ld') is denying the write; see the lockdown item above"
            else
                _ck_warn "XMRig reports the MSR preset FAILED to set — check msr.allow_writes=on and that no hypervisor is masking MSR access"
            fi
            issues=$((issues + 1))
            ;;
            # not-found is not proof of not-applied (miner hasn't started a RandomX job yet, or a
        # copytruncate rotation just cleared the live log) — stay quiet.
        *) : ;;
        esac
        if [ "$msrstat" = none ]; then
            [ -z "$log_file" ] && _ck_info "MSR file-log confirmation is disabled; the bounded systemd journal has no confirmation yet"
            [ -n "$log_file" ] && [ ! -f "$log_file" ] && _ck_info "MSR unverifiable — no xmrig.log at $log_file and no journal confirmation"
        fi
    elif [ -z "$wr" ]; then
        # #367: no config.json, so the worker root above never resolved. Distinct wording from the
        # "resolved but no log" case below — an absent block must not read as a failed check.
        _ck_info "MSR unverifiable — no config.json, so the worker root couldn't be resolved"
    fi

    # CPU governor
    local gov
    gov=$(cat "$GOVERNOR_FILE" 2>/dev/null || echo "")
    if [ "$gov" = "performance" ]; then
        _ck_ok "CPU governor = performance"
    else
        _ck_warn "CPU governor is '${gov:-unknown}' (expected 'performance')"
    fi

    # Hashrate-capping HARDWARE (advisory; #67). RandomX fast-mode is dataset-latency bound, so a
    # single memory channel, slow RAM, or a power/boost cap silently leaves performance on the table.
    # doctor can't change these — it only flags them. Best-effort, gated on tool/data availability.
    if command -v "$DMIDECODE" >/dev/null 2>&1; then
        local mem pop nch spd rated
        mem=$(_mem_summary)
        read -r pop nch spd rated <<<"${mem:-0 0 0 0}" # rated (4th field) feeds the #78 XMP/EXPO check
        if [ "${pop:-0}" -eq 0 ] 2>/dev/null; then
            _ck_warn "RAM layout not readable — run 'doctor' as root so dmidecode can check channels/speed"
        else
            if [ "${nch:-0}" -le 1 ]; then
                _ck_warn "RAM is single-channel ($pop module(s), 1 channel) — RandomX wants ≥2 channels; move a stick to the other channel for a large gain"
            else
                _ck_ok "RAM: $pop modules across $nch channels (dual+ channel)"
            fi
            if [ "${spd:-0}" -gt 0 ] 2>/dev/null && [ "$spd" -lt "$MIN_RAM_MTS" ]; then
                _ck_warn "RAM speed ${spd} MT/s is low — enable XMP/EXPO or fit faster RAM (RandomX is memory-latency bound)"
            elif [ "${spd:-0}" -gt 0 ] 2>/dev/null; then
                _ck_ok "RAM speed: ${spd} MT/s"
            fi
        fi
    else
        _ck_warn "dmidecode not found — install it for the RAM channels/speed check (advisory only)"
    fi

    # Effective CPU clock under load — only meaningful while the miner is running (else the cores idle).
    if systemctl is-active --quiet "$SERVICE_NAME" 2>/dev/null; then
        local maxk effk pct
        maxk=$(cat "$CPUFREQ_MAX" 2>/dev/null || true) # guard INSIDE $(): missing cpufreq sysfs (a VM) mustn't trip the ERR trap
        effk=$(_cpu_eff_khz)
        if [ -n "$effk" ] && [ "${maxk:-0}" -gt 0 ] 2>/dev/null; then
            pct=$((effk * 100 / maxk))
            if [ "$pct" -lt "$MIN_CLOCK_PCT" ]; then
                _ck_warn "CPU at $((effk / 1000)) MHz — only ${pct}% of the $((maxk / 1000)) MHz max boost; check PBO/cTDP power limits + cooling (likely throttling)"
            else
                _ck_ok "CPU clock under load: $((effk / 1000)) MHz (${pct}% of max boost)"
            fi
        fi
    fi

    # BIOS / firmware advisory (#78). RigForge can't read or change BIOS setup variables from a booted OS,
    # so this is detect-and-recommend only: it reads what the OS DOES expose (board/BIOS identity, the
    # memory profile, SMT) and turns it into concrete manual recommendations. Advisory — never an issue.
    local bvendor board bios bdate cpu smt xmp_rec="" smt_rec=""
    bvendor=$(_dmi board_vendor)
    board=$(_dmi board_name)
    bios=$(_dmi bios_version)
    bdate=$(_dmi bios_date)
    cpu=$(lscpu 2>/dev/null | awk -F: '/^Model name:/ {gsub(/^[ \t]+/, "", $2); print $2; exit}' || true) # ^anchored: skip "BIOS Model name:"; guard INSIDE $()
    # Work out the recommendations FIRST, so the context line only points "below" when there ARE any
    # (otherwise it'd promise items that never come — e.g. RAM already at its rated speed and SMT on).
    # XMP/EXPO/DOCP: RAM running below its rated SPD speed means the memory profile isn't enabled. Sharper
    # than the #67 fixed-threshold check (it compares rated vs configured for THIS kit).
    if [ "${rated:-0}" -gt 0 ] 2>/dev/null && [ "${spd:-0}" -gt 0 ] 2>/dev/null && [ "$spd" -lt "$rated" ] 2>/dev/null; then
        xmp_rec="RAM is running at ${spd} MT/s but the modules are rated for ${rated} MT/s — enable the memory profile (XMP / EXPO / DOCP) in BIOS for a sizable RandomX gain."
    fi
    # SMT / Hyper-Threading off on a capable CPU leaves logical cores unused for RandomX.
    smt=$(cat "$SMT_CONTROL" 2>/dev/null || true) # guard INSIDE $(): missing SMT sysfs mustn't trip the ERR trap
    case "$smt" in
    off | forceoff) smt_rec="SMT/Hyper-Threading is disabled — enable it in BIOS (SMT / Hyper-Threading) so RandomX can use every logical core." ;;
    esac
    # NPS on EPYC (#201): a BIOS update or CMOS reset silently drops NPS4 to NPS1 and costs
    # RandomX its per-node datasets — detectable, so say so. Advisory only; NPS1 mines, just slower.
    local nps_rec=""
    if [ -n "$(_nps_suspect "$cpu")" ]; then
        nps_rec="EPYC reports a single NUMA node (NPS1) — set NUMA nodes per socket to NPS4 in BIOS ($(_bios_menu "$bvendor" numa_nps perf)) so RandomX gets quadrant-local memory."
    fi
    if [ -n "$bvendor$board$bios" ]; then
        if [ -n "$xmp_rec$smt_rec$nps_rec" ]; then
            _ck_info "Firmware: ${bvendor:-?} ${board:-?}, BIOS ${bios:-?} (${bdate:-?})${cpu:+, $cpu} — apply the BIOS/UEFI item(s) below (RigForge can't change them from the OS)."
        else
            _ck_info "Firmware: ${bvendor:-?} ${board:-?}, BIOS ${bios:-?} (${bdate:-?})${cpu:+, $cpu} — no BIOS changes recommended."
        fi
    fi
    if [ -n "$xmp_rec" ]; then _ck_warn "$xmp_rec"; fi
    if [ -n "$smt_rec" ]; then _ck_warn "$smt_rec"; fi
    if [ -n "$nps_rec" ]; then _ck_warn "$nps_rec"; fi

    # XMRig's own startup report (HUGE PAGES 100% means the dataset is fully backed). Reuses the
    # log_file resolved above for the MSR-applied check.
    if [ -n "$log_file" ] && [ -f "$log_file" ]; then
        if grep -qiE 'huge pages.*100%' "$log_file"; then
            _ck_ok "XMRig log reports HUGE PAGES 100%"
        elif grep -qi 'huge pages' "$log_file"; then
            _ck_warn "XMRig log shows HUGE PAGES below 100% — not all threads are backed"
        fi
    fi

    echo ""
    if [ "$issues" -eq 0 ]; then
        log "doctor: all critical checks passed."
        log "Check for a newer RigForge any time: '$0 upgrade --check'."
    else
        warn "doctor: $issues issue(s) found — see the hints above."
        # Non-zero on unhealthy (#149): doctor is the verb operators cron/gate on, and Pithead's
        # health verb already exits non-zero — one stack's habits must transfer to the other.
        return 1
    fi
}

# --- Usage & command dispatch ---

# --- Guided BIOS tuning (#80): detect -> guide -> reboot -> re-verify ---

# One probe pass; results in globals (the S_* style tune uses). Detection expressions are byte-for-
# byte doctor's (#78: memory 2998-form, SMT, boost) so `bios` and `doctor` can never disagree about
# the same rig. Each item: B_<X>_STATUS = ok|pending|unknown, B_<X>_BEFORE = short human value.
# NPS regression detection (#201): a multi-CCD EPYC at NPS1 (one NUMA node) leaves quadrant-local
# memory on the table — XMRig allocates one RandomX dataset per NUMA node. Echoes "1" when the
# topology looks wrong (EPYC model + exactly one node dir), else nothing. Desktop parts correctly
# report one node and are never flagged; missing sysfs (n=0) is unverifiable, not suspect.
# Shared by doctor's #78 advisory and _bios_detect (the #80 rule: they can never disagree).
_nps_suspect() { # <cpu_model> -> echoes the node count when suspect, else nothing
    case "$1" in *EPYC*) ;; *) return 0 ;; esac
    local n=0 d
    for d in "${NODE_SYSFS:-/sys/devices/system/node}"/node[0-9]*; do
        [ -d "$d" ] && n=$((n + 1))
    done
    [ "$n" -eq 1 ] && echo "$n"
    return 0
}

_bios_detect() {
    local mem pop nch spd rated smt effk maxk pct cpu_m
    B_MEM_STATUS=unknown B_MEM_BEFORE="" B_SMT_STATUS=unknown B_SMT_BEFORE="" B_BOOST_STATUS=unknown B_BOOST_BEFORE=""
    B_NPS_STATUS=unknown B_NPS_BEFORE=""
    B_SB_STATUS=unknown B_SB_BEFORE=""
    # Secure Boot / lockdown (#333). Same probe doctor uses (the #80 rule: they can never disagree).
    # `unknown` when securityfs isn't readable — never guessed from Secure Boot state, which only
    # implies lockdown on distro kernels, not upstream.
    local ld_state
    ld_state=$(_lockdown_state)
    if [ -n "$ld_state" ]; then
        if _lockdown_blocks_msr "$ld_state"; then
            B_SB_STATUS=pending
            B_SB_BEFORE="lockdown=$ld_state (MSR writes denied)"
        else
            B_SB_STATUS=ok
            B_SB_BEFORE="lockdown=none"
        fi
    fi
    cpu_m=$(lscpu 2>/dev/null | awk -F: '/^Model name:/ {gsub(/^[ \t]+/, "", $2); print $2; exit}' || true)
    case "$cpu_m" in
    *EPYC*)
        if [ -n "$(_nps_suspect "$cpu_m")" ]; then
            B_NPS_STATUS=pending
            B_NPS_BEFORE="1 NUMA node (NPS1)"
        else
            B_NPS_STATUS=ok
            B_NPS_BEFORE="multiple NUMA nodes"
        fi
        ;;
    esac
    mem=$(_mem_summary)
    read -r pop nch spd rated <<<"${mem:-0 0 0 0}"
    if [ "${rated:-0}" -gt 0 ] 2>/dev/null && [ "${spd:-0}" -gt 0 ] 2>/dev/null; then
        if [ "$spd" -lt "$rated" ]; then B_MEM_STATUS=pending; else B_MEM_STATUS=ok; fi
        B_MEM_BEFORE="${spd} of ${rated} MT/s"
    fi
    smt=$(cat "$SMT_CONTROL" 2>/dev/null || true)
    case "$smt" in
    off | forceoff)
        B_SMT_STATUS=pending
        B_SMT_BEFORE="$smt"
        ;;
    "") : ;; # no SMT sysfs -> unknown (can't verify)
    *)
        B_SMT_STATUS=ok
        B_SMT_BEFORE="$smt"
        ;;
    esac
    # Boost is only measurable under load (idle cores read low) — same gate as doctor's check.
    if systemctl is-active --quiet "$SERVICE_NAME" 2>/dev/null; then
        maxk=$(cat "$CPUFREQ_MAX" 2>/dev/null || true)
        effk=$(_cpu_eff_khz)
        if [ -n "$effk" ] && [ "${maxk:-0}" -gt 0 ] 2>/dev/null; then
            pct=$((effk * 100 / maxk))
            if [ "$pct" -lt "$MIN_CLOCK_PCT" ]; then B_BOOST_STATUS=pending; else B_BOOST_STATUS=ok; fi
            B_BOOST_BEFORE="${pct}% of max boost"
        fi
    fi
}

# The exact BIOS menu path(s) for an item on a detected board vendor. A case statement is the
# smallest thing that holds four vendors + a generic fallback — no data file. (#80)
_bios_menu() { # <board_vendor> <item_id> <target> -> menu-path line(s) on stdout
    local v
    v=$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')
    case "$v" in
    asus*) v=asus ;; # asustek matches too
    asrock*) v=asrock ;;
    giga*) v=gigabyte ;;
    micro-star* | msi*) v=msi ;;
    *) v=generic ;;
    esac
    case "$2:$v" in
    memory_profile:asus) echo "Ai Tweaker ▸ Ai Overclock Tuner ▸ EXPO I (Intel boards: XMP I)" ;;
    memory_profile:asrock) echo "OC Tweaker ▸ DRAM Profile ▸ EXPO/XMP Profile 1" ;;
    memory_profile:gigabyte) echo "Tweaker ▸ Extreme Memory Profile (X.M.P.) / EXPO ▸ Profile 1" ;;
    memory_profile:msi) echo "OC ▸ A-XMP / EXPO ▸ Profile 1" ;;
    memory_profile:*) echo "look for the memory profile setting (XMP / EXPO / DOCP) and enable profile 1" ;;
    smt:*) echo "Advanced ▸ CPU Configuration ▸ SMT / Hyper-Threading ▸ Enabled" ;;
    # #333: Secure Boot itself is the lever — distro kernels enable lockdown from it, and lockdown is
    # what denies the MSR writes. On most boards the toggle only appears once the OS type is "Other OS".
    secure_boot:asus) echo "Boot ▸ Secure Boot ▸ OS Type ▸ Other OS (then Secure Boot state reads 'Disabled')" ;;
    secure_boot:asrock) echo "Security ▸ Secure Boot ▸ Disabled" ;;
    secure_boot:gigabyte) echo "Boot ▸ Secure Boot ▸ Secure Boot Enable ▸ Disabled" ;;
    secure_boot:msi) echo "Settings ▸ Advanced ▸ Windows OS Configuration ▸ Secure Boot ▸ Disabled" ;;
    secure_boot:*) echo "find the Secure Boot setting (usually under Boot or Security) and disable it" ;;
    numa_nps:*) echo "Advanced ▸ AMD CBS ▸ DF Common Options ▸ Memory Addressing ▸ NUMA nodes per socket ▸ NPS4" ;;
    power_boost:*)
        if [ "$3" = efficiency ]; then
            printf '%s\n' "PBO ▸ Eco Mode (65 W TDP)" "Curve Optimizer ▸ All Cores ▸ Negative ▸ 20" "Server boards (EPYC): AMD CBS ▸ NBIO ▸ cTDP — set the lower cTDP the SKU supports"
        else
            printf '%s\n' "Advanced ▸ AMD Overclocking ▸ Precision Boost Overdrive ▸ Enabled (Advanced) (Intel: lift the PL1/PL2 power limits)" "Server boards (EPYC): AMD CBS ▸ NBIO ▸ cTDP / Package Power Limit at the SKU maximum, Determinism Control ▸ Performance"
        fi
        ;;
    esac
}

# Persist ONLY the still-pending items — done items are not state. jq -n --arg for every value:
# DMI strings carry spaces/quotes, and the menu strings carry UTF-8 markers.
_bios_state_write() { # <state_file>; reads the B_* globals + TUNE_TARGET
    local f="$1" items="[]" vendor
    vendor=$(_dmi board_vendor)
    if [ "$B_MEM_STATUS" = pending ]; then items=$(jq -c --argjson a "$items" --arg b "$B_MEM_BEFORE" --arg m "$(_bios_menu "$vendor" memory_profile "$TUNE_TARGET")" -n '$a + [{id: "memory_profile", status: "pending", before: $b, menu: $m}]'); fi
    if [ "$B_SMT_STATUS" = pending ]; then items=$(jq -c --argjson a "$items" --arg b "$B_SMT_BEFORE" --arg m "$(_bios_menu "$vendor" smt "$TUNE_TARGET")" -n '$a + [{id: "smt", status: "pending", before: $b, menu: $m}]'); fi
    if [ "$B_BOOST_STATUS" = pending ]; then items=$(jq -c --argjson a "$items" --arg b "$B_BOOST_BEFORE" --arg m "$(_bios_menu "$vendor" power_boost "$TUNE_TARGET")" -n '$a + [{id: "power_boost", status: "pending", before: $b, menu: $m}]'); fi
    if [ "$B_NPS_STATUS" = pending ]; then items=$(jq -c --argjson a "$items" --arg b "$B_NPS_BEFORE" --arg m "$(_bios_menu "$vendor" numa_nps "$TUNE_TARGET")" -n '$a + [{id: "numa_nps", status: "pending", before: $b, menu: $m}]'); fi
    if [ "$B_SB_STATUS" = pending ]; then items=$(jq -c --argjson a "$items" --arg b "$B_SB_BEFORE" --arg m "$(_bios_menu "$vendor" secure_boot "$TUNE_TARGET")" -n '$a + [{id: "secure_boot", status: "pending", before: $b, menu: $m}]'); fi
    jq -n --arg t "$TUNE_TARGET" --arg when "$(date '+%Y-%m-%d %H:%M')" --argjson items "$items" '{target: $t, saved: $when, items: $items}' >"$f"
    log "Saved $(jq -r '.items | length' "$f") pending item(s) to $f."
}

_bios_item_label() { # <id> -> human label
    case "$1" in
    memory_profile) printf 'Memory profile' ;;
    smt) printf 'SMT / Hyper-Threading' ;;
    power_boost) printf 'CPU boost / power' ;;
    numa_nps) printf 'NUMA per socket (NPS)' ;;
    secure_boot) printf 'Secure Boot (kernel lockdown)' ;;
    esac
}

# Run 1: detect, print the firmware context, walk the pending items one at a time with the exact
# BIOS menu path for this board, save the resumable state, and hand the operator the checklist.
# RigForge never writes BIOS (#78 feasibility) — this is detect-and-recommend with a verify loop.
_bios_guide() { # <state_file>
    local state="$1" pending="" id
    _bios_detect
    echo ""
    log "Reading current firmware state (RigForge can't change these from the OS — it only reads them):"
    _ck_info "Firmware: $(_dmi board_vendor) $(_dmi board_name), BIOS $(_dmi bios_version) ($(_dmi bios_date))"
    if [ "$B_SMT_STATUS" = ok ]; then _ck_ok "SMT / Hyper-Threading: enabled"; fi
    if [ "$B_SMT_STATUS" = pending ]; then _ck_warn "SMT / Hyper-Threading: $B_SMT_BEFORE"; fi
    if [ "$B_MEM_STATUS" = ok ]; then _ck_ok "Memory profile: running at rated speed ($B_MEM_BEFORE)"; fi
    if [ "$B_MEM_STATUS" = pending ]; then _ck_warn "Memory profile: running at $B_MEM_BEFORE — EXPO/XMP not enabled"; fi
    if [ "$B_MEM_STATUS" = unknown ]; then _ck_info "Memory profile: can't verify — run as root so dmidecode can read the RAM state"; fi
    if [ "$B_BOOST_STATUS" = ok ]; then _ck_ok "CPU boost under load: $B_BOOST_BEFORE"; fi
    if [ "$B_BOOST_STATUS" = pending ]; then _ck_warn "CPU boost under load: $B_BOOST_BEFORE — likely power-capped"; fi
    if [ "$B_BOOST_STATUS" = unknown ]; then _ck_info "CPU boost not checked — the miner isn't running (start it and re-run bios to include the power/boost item)"; fi
    if [ "$B_NPS_STATUS" = ok ]; then _ck_ok "NUMA per socket (NPS): $B_NPS_BEFORE"; fi
    if [ "$B_NPS_STATUS" = pending ]; then _ck_warn "NUMA per socket (NPS): $B_NPS_BEFORE — set NUMA nodes per socket to NPS4 in BIOS so RandomX gets quadrant-local memory."; fi
    if [ "$B_SB_STATUS" = ok ]; then _ck_ok "Secure Boot / kernel lockdown: $B_SB_BEFORE — the MSR mod can apply"; fi
    if [ "$B_SB_STATUS" = pending ]; then _ck_warn "Secure Boot / kernel lockdown: $B_SB_BEFORE — the MSR mod (~5-15% RandomX) cannot apply until Secure Boot is off."; fi
    if [ "$B_SB_STATUS" = unknown ]; then _ck_info "Secure Boot / kernel lockdown: can't verify — $LOCKDOWN_FILE isn't readable (run as root, or the lockdown LSM isn't built in)"; fi
    # Secure Boot leads: it's the cheapest change and it gates the MSR mod outright.
    for id in secure_boot memory_profile smt power_boost numa_nps; do
        case "$id" in
        memory_profile) if [ "$B_MEM_STATUS" = pending ]; then pending="$pending $id"; fi ;;
        smt) if [ "$B_SMT_STATUS" = pending ]; then pending="$pending $id"; fi ;;
        power_boost) if [ "$B_BOOST_STATUS" = pending ]; then pending="$pending $id"; fi ;;
        numa_nps) if [ "$B_NPS_STATUS" = pending ]; then pending="$pending $id"; fi ;;
        secure_boot) if [ "$B_SB_STATUS" = pending ]; then pending="$pending $id"; fi ;;
        esac
    done
    if [ -z "$pending" ]; then
        echo ""
        _ck_ok "Everything's already set for $(_autotune_desc "$TUNE_TARGET") — no BIOS changes needed."
        return 0
    fi
    echo ""
    log "BIOS/UEFI changes for this board, one at a time (highest RandomX impact first):"
    local n=0 vendor
    vendor=$(_dmi board_vendor)
    for id in $pending; do
        n=$((n + 1))
        echo ""
        printf '  %d. %s\n' "$n" "$(_bios_item_label "$id")"
        _bios_menu "$vendor" "$id" "$TUNE_TARGET" | sed 's/^/     -> /'
        read -r -p "  Press Enter when you've noted it (nothing is applied now) ... " _ || true
    done
    _bios_state_write "$state"
    echo ""
    log "Next: reboot into BIOS/UEFI (usually Del/F2 at power-on), apply the item(s) above, Save & Exit."
    log "Back in Linux, run 'sudo $0 bios' again — it re-reads the same probes and reports what took."
    _reown_worker
}

# Run 2+: re-read the saved pending items against fresh probes. An item flips to done only when its
# OS-visible fingerprint says so — `unknown` NEVER passes (honesty rule from the issue spec).
_bios_verify() { # <state_file>
    local state="$1" target saved id before menu fresh_status fresh_before kept="" applied=0 total=0
    target=$(jq -r '.target // "perf"' "$state")
    saved=$(jq -r '.saved // "?"' "$state")
    TUNE_TARGET="$target" # the checklist was built for the saved target; it governs the re-verify wording
    total=$(jq -r '.items | length' "$state")
    log "Resuming — $total item(s) were pending from $saved."
    local rows
    rows=$(jq -r '.items[] | [.id, .before, .menu] | @tsv' "$state")
    _bios_detect
    echo ""
    log "Re-checking the items you went in to change:"
    while IFS=$'\t' read -r id before menu; do
        case "$id" in
        memory_profile)
            fresh_status="$B_MEM_STATUS"
            fresh_before="$B_MEM_BEFORE"
            ;;
        smt)
            fresh_status="$B_SMT_STATUS"
            fresh_before="$B_SMT_BEFORE"
            ;;
        power_boost)
            fresh_status="$B_BOOST_STATUS"
            fresh_before="$B_BOOST_BEFORE"
            ;;
        numa_nps)
            fresh_status="$B_NPS_STATUS"
            fresh_before="$B_NPS_BEFORE"
            ;;
        secure_boot)
            fresh_status="$B_SB_STATUS"
            fresh_before="$B_SB_BEFORE"
            ;;
        *) continue ;;
        esac
        if [ "$fresh_status" = ok ]; then
            _ck_ok "$(_bios_item_label "$id") — now $fresh_before (was $before). Took."
            applied=$((applied + 1))
        elif [ "$fresh_status" = pending ]; then
            _ck_warn "$(_bios_item_label "$id") — still $fresh_before. Didn't take; re-check: $menu"
            kept="$kept $id"
        elif [ "$id" = power_boost ]; then
            _ck_warn "CPU boost — can't verify with the miner stopped; run 'sudo $0 start', let it warm up, then re-run bios."
            kept="$kept $id"
        else
            case "$id" in
            memory_profile) _ck_warn "$(_bios_item_label "$id") — can't verify (run as root so dmidecode can read the RAM state)." ;;
            smt) _ck_warn "$(_bios_item_label "$id") — can't verify (no SMT control exposed in sysfs on this system)." ;;
            numa_nps) _ck_warn "$(_bios_item_label "$id") — can't verify (lscpu didn't report an EPYC CPU model, so the NUMA-node count can't be checked)." ;;
            secure_boot) _ck_warn "$(_bios_item_label "$id") — can't verify ($LOCKDOWN_FILE isn't readable; re-run as root)." ;;
            esac
            kept="$kept $id"
        fi
    done <<<"$rows"
    echo ""
    if [ -z "$kept" ]; then
        rm -f "$state"
        log "All BIOS items applied. Firmware is tuned for: $(_autotune_desc "$target")."
        log "Next: 'sudo $0 tune --live' — the hardware envelope changed, so re-tune XMRig against it."
    else
        # Rewrite the state with only the still-pending items: re-detect filled the B_* globals, so
        # neutralize the ones that took and let the writer keep the rest.
        case " $kept " in *" memory_profile "*) : ;; *) B_MEM_STATUS="done" ;; esac
        case " $kept " in *" smt "*) : ;; *) B_SMT_STATUS="done" ;; esac
        case " $kept " in *" power_boost "*) : ;; *) B_BOOST_STATUS="done" ;; esac
        case " $kept " in *" numa_nps "*) : ;; *) B_NPS_STATUS="done" ;; esac
        case " $kept " in *" secure_boot "*) : ;; *) B_SB_STATUS="done" ;; esac
        if [ "$B_BOOST_STATUS" = unknown ]; then B_BOOST_STATUS=pending; fi # keep it resumable
        if [ "$B_MEM_STATUS" = unknown ]; then B_MEM_STATUS=pending; fi
        if [ "$B_SMT_STATUS" = unknown ]; then B_SMT_STATUS=pending; fi
        if [ "$B_NPS_STATUS" = unknown ]; then B_NPS_STATUS=pending; fi
        if [ "$B_SB_STATUS" = unknown ]; then B_SB_STATUS=pending; fi
        _bios_state_write "$state"
        log "$applied of $total applied, $(jq -r '.items | length' "$state") still pending. Reboot into BIOS to finish, then run 'sudo $0 bios' again."
    fi
    _reown_worker
}

# The guided, resumable BIOS walk-through (#80): a sibling of tune/doctor. Interactive by design —
# this is the one flow that needs console access for the reboot-into-BIOS step.
bios() {
    [ "$OS_TYPE" = Linux ] || error "bios reads Linux firmware interfaces (dmidecode, /sys/class/dmi) and is only supported on Linux."
    # dmidecode (the memory-profile probe) needs root — auto-elevate exactly like tune.
    if _tune_should_elevate; then
        log "bios needs root for the firmware probes — re-running with sudo..."
        exec sudo "$0" bios "$@"
    fi
    local target_set=0
    if [ -n "${TUNE_TARGET:-}" ]; then target_set=1; fi
    while [ $# -gt 0 ]; do
        case "$1" in
        --efficiency)
            TUNE_TARGET=efficiency
            target_set=1
            ;;
        --perf)
            TUNE_TARGET=perf
            target_set=1
            ;;
        *) error "Unknown option for bios: '$1' (use --perf or --efficiency). Run '$0 help'." ;;
        esac
        shift
    done
    parse_config
    if [ "$target_set" != 1 ]; then TUNE_TARGET="${AUTOTUNE_TARGET:-perf}"; fi
    local state="$WORKER_ROOT/rigforge-bios.json"
    log "RigForge guided BIOS tuning — target: $(_autotune_desc "$TUNE_TARGET")"
    if [ -s "$state" ] && jq -e '.items | length > 0' "$state" >/dev/null 2>&1; then
        _bios_verify "$state"
        return 0
    fi
    _bios_guide "$state"
}

usage() {
    cat <<USAGE
RigForge — provision and maintain an XMRig mining worker.

Usage: $0 [command]

Most days you only need the first group; the rest are grouped below. Full guide: docs/operations.md

Day to day:
  apply      re-read config.json, regenerate the XMRig config, and restart (no rebuild; --dry-run: preview)
  upgrade    redeploy after checking out a new release: rebuild + restart if the pinned XMRig changed ('--check' just reports whether a newer RigForge release exists)
  doctor     check that HugePages, the MSR mod, the governor and the service are all healthy
  logs       follow the live miner logs
  status     live summary (hashrate, pool, uptime, shares) + whether the miner is running
  start      start the miner (systemd on Linux, a background process on macOS) [alias: up]
  stop       stop the miner [alias: down]
  restart    restart the miner

Tuning:
  tune       measure the fastest XMRig knobs and keep them. Live re-tunes against the running miner:
             '--now' (= '--short') a quick pass that keeps the best prefetch mode, '--now --long' a full
             all-knob live sweep (= '--live'). Offline: plain 'tune' (or '--bench') sweeps every knob on
             the whole machine — fastest/cleanest, but rx/0 only. '--confirm' A/B-checks the winner live
             before keeping it. '--efficiency' optimizes hashrate-per-watt (default '--perf' = raw H/s),
             '--history' shows the current tuning + recent runs, '--clear' resets
  bench      run a one-off 'xmrig --bench' and report the hashrate
  autotune   alias of 'tune --now' (and the verb the scheduled timer runs); turn on the schedule with
             autotune:"performance"|"efficiency" in config.json
  watchdog   one health check: restart a wedged miner (alive but 0 H/s, two strikes), enforce
             max_temp_c (stop above it, start 5°C below). Schedule it with watchdog:"enabled"
             in config.json — the timer runs it every watchdog_interval_min minutes
  bios       guided, resumable walk-through of the BIOS/UEFI changes for your hardware (XMP/EXPO,
             SMT, PBO/Eco-Mode; '--efficiency' picks the low-power set). Detects state, hands you a
             board-specific checklist, and re-verifies what took after the reboot. RigForge never
             writes BIOS itself

Provision & lifecycle:
  setup      (default) provision the worker: dependencies, build, kernel tuning, service (--dry-run: preview the plan, no sudo)
  uninstall  remove the service and revert all system changes (add -y|--yes to skip the prompt)
  enable     start the miner automatically (boot on Linux, login on macOS)
  disable    don't start the miner automatically

Backup:
  backup     save config.json + tuning to a timestamped archive in ./backups
  restore    restore config.json + tuning from a backup archive: restore [-y|--yes] <archive>

Info:
  msr-apply  (internal) apply the CPU's MSR preset as root — run by the miner unit's
             ExecStartPre when miner_user is set (the unprivileged miner can't write MSRs)
  api-refresh (internal) recompute the sister API's response files — driven every 15s by the
             rigforge-api-refresh systemd timer ("api": "enabled" in config.json)
  control-apply (internal) persist + apply a config change staged by the control server — run by
             the rigforge-control-apply.path unit ("control": "enabled" in config.json)
  control-upgrade (internal) fetch + redeploy a newer RigForge release staged by the control server —
             run by the rigforge-control-upgrade.path unit ("control_upgrade": "enabled" in config.json)
  support-bundle  collect doctor/version/configs/log-tail into a redacted tarball for bug reports
  completion print a bash/zsh tab-completion script: completion bash|zsh
  version    print the RigForge version  (-v, --version)
  help       show this help              (-h, --help)

Re-running 'setup' is idempotent: it skips the recompile when the pinned XMRig is already built.
USAGE
}

if [ "$_RIGFORGE_SOURCED" = "0" ]; then
    # Honesty check: these verbs take no arguments, so reject extras (Pithead's `setup --skip-deps`
    # muscle memory, a typo'd `apply --now`) instead of silently running as if nothing was passed.
    # Verbs with their own flags (setup/upgrade/tune/apply/backup/restore/...) validate in their loops.
    case "${1:-setup}" in
    autotune | watchdog | doctor | api-refresh | msr-apply | control-apply | control-upgrade | status | logs | start | up | stop | down | restart | enable | disable | bench | version | --version | -v | help | -h | --help)
        [ -z "${2:-}" ] || error "Unexpected argument for $1: '$2'. Run '$0 help'."
        ;;
    esac
    # #353 (1): name the verb before dispatch so an UNEXPECTED failure in any of them reports where it
    # actually happened, not the stale "starting up" default — setup's own main() overwrites this a
    # moment later with its fine-grained per-phase steps, so this is a no-op there.
    CURRENT_STEP="running '${1:-setup}'"
    case "${1:-setup}" in
    setup)
        # if-form, not `[ $# -gt 0 ] && shift`: a false && list at top level trips set -e on the
        # zero-arg default path (bare ./rigforge.sh dispatches here with $# = 0).
        if [ $# -gt 0 ]; then shift; fi
        main "$@"
        ;;
    upgrade)
        shift
        upgrade "$@"
        ;;
    uninstall)
        shift
        uninstall "$@"
        ;;
    tune)
        shift
        tune "$@"
        ;;
    autotune) autotune ;;
    watchdog) watchdog ;;
    doctor) doctor || exit 1 ;; # `||`: a mere unhealthy report must not fire the ERR trap's "aborted while" line
    bios)
        shift
        bios "$@"
        ;;
    api-refresh) api_refresh ;;
    msr-apply) msr_apply ;;
    control-apply) _with_control_lock control_apply ;;
    control-upgrade) _with_control_lock control_upgrade ;;
    status) svc_status ;;
    logs) svc_logs ;;
    start | up) svc_start ;;
    stop | down) svc_stop ;;
    restart) svc_restart ;;
    enable) svc_enable ;;
    disable) svc_disable ;;
    apply)
        shift
        apply "$@"
        ;;
    bench) bench ;;
    backup)
        shift
        backup "$@"
        ;;
    restore)
        shift
        restore "$@"
        ;;
    support-bundle)
        shift
        support_bundle "$@"
        ;;
    completion)
        shift
        cmd_completion "$@"
        ;;
    version | --version | -v) cmd_version ;;
    help | -h | --help) usage ;;
    *) error "Unknown command: $1. Run '$0 help' for the command list." ;;
    esac
fi