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
}

# shellcheck source=util/config-apply-state.sh
source "$(_script_dir)/util/config-apply-state.sh"
SCRIPT_DIR="${RIGFORGE_HOME:-$(_script_dir)}"
# shellcheck source=util/daemon-pools.sh
source "$(_script_dir)/util/daemon-pools.sh"
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

# shellcheck source=util/shared-host.sh
source "$(_script_dir)/util/shared-host.sh"
# shellcheck source=util/randomx.sh
source "$(_script_dir)/util/randomx.sh"

# --- 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
    [ "${SHARED_HOST:-false}" != true ] || mem_kb=$((SHARED_MEMORY_MAX_MB * 1024))
    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 (Pithead dashboard: Connect a miner; 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
    CONFIG_INPUT_HASH=$(_sha256 "$CONFIG_JSON" 2>/dev/null) || CONFIG_INPUT_HASH=""
    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."

    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."
    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."
    POOLS_JSON=$(jq -c --argjson base "$POOLS_JSON" '[$base, [.pools[] | {"rig-id": .["rig-id"], nicehash, algo, coin, sni} | with_entries(select(.value != null))]] | transpose | map(.[0] + .[1])' "$CONFIG_JSON") || error "Could not parse 'pools' in $CONFIG_JSON."

    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."

    POOLS_JSON=$(jq -c --argjson base "$POOLS_JSON" '[$base, [.pools[] | with_entries(select(.key == "daemon" or .key == "daemon-poll-interval" or .key == "daemon-job-timeout" or .key == "daemon-zmq-port") | if (.key != "daemon") and (.value | type == "number") and (.value == (.value | floor)) then .value |= floor else . end)]] | transpose | map((.[0] + .[1]) | if (.url | type == "string" and (startswith("daemon+http://") or startswith("daemon+https://"))) and (has("daemon") | not) then .daemon = true else . end)' "$CONFIG_JSON") || error "Could not parse daemon pool fields."
    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_pool_url "$_pool" 3333 "$_u"
        # 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
        if ! jq -e 'has("rig-id") == false or (."rig-id" | type == "string" and (test("[^A-Za-z0-9._:@+-]") | not))' <<<"$_pool" >/dev/null 2>&1; then
            error "Pool rig-id must be a string using only these characters: letters, digits, . _ - : @ + (or empty)."
        fi
        for _f in nicehash sni; do
            if ! jq -e --arg f "$_f" 'has($f) == false or (.[$f] | type == "boolean")' <<<"$_pool" >/dev/null 2>&1; then
                error "Pool $_f must be true or false."
            fi
        done
        if ! jq -e '.algo == null or (.algo | IN("rx/0", "rx/2", "rx/wow", "rx/arq", "rx/graft", "rx/sfx", "rx/yada"))' <<<"$_pool" >/dev/null 2>&1; then
            error "Pool algo must be a supported RandomX algorithm (rx/0, rx/2, rx/wow, rx/arq, rx/graft, rx/sfx, rx/yada): HugePages reservation and tune --bench assume a RandomX scratchpad."
        fi
        if ! jq -e '.coin == null or (.coin | ascii_downcase | IN("monero", "xmr", "arqma", "arq", "graft", "grft", "wownero", "wow", "zephyr", "zeph", "townforge", "yadacoin", "yda"))' <<<"$_pool" >/dev/null 2>&1; then
            error "Pool coin must be a supported RandomX coin (monero/XMR, arqma/ARQ, graft/GRFT, wownero/WOW, zephyr/ZEPH, townforge, yadacoin/YDA): HugePages reservation and tune --bench assume a RandomX scratchpad."
        fi
        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
    RANDOMX_JSON=$(_read_randomx_config) || error "xmrig.randomx accepts mode (auto/fast/light), init (-1 or a positive integer), and init-avx2 (-1/0/1) only."
    RX_MODE=$(jq -r '.mode' <<<"$RANDOMX_JSON")
    export RX_MODE

    _shared_host_parse
    _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 shared_host xmrig"
    local known_pool="url user pass keepalive tls enabled tls-fingerprint socks5 rig-id nicehash algo coin sni daemon daemon-poll-interval daemon-job-timeout daemon-zmq-port"
    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"
}

_recover_xmrig_swap() {
    [ -f "$WORKER_ROOT/xmrig.swap" ] || return 0
    [ -d "$WORKER_ROOT/xmrig" ] || {
        mv "$WORKER_ROOT/xmrig.new" "$WORKER_ROOT/xmrig" 2>/dev/null || mv "$WORKER_ROOT/$(cat "$WORKER_ROOT/xmrig.swap")" "$WORKER_ROOT/xmrig" 2>/dev/null || warn "Could not recover the interrupted XMRig swap; rebuilding."
    }
    rm -f "$WORKER_ROOT/xmrig.swap"
    decide_rebuild
}

_activate_xmrig_build() {
    cd "$WORKER_ROOT"
    local archived=""
    if [ -d xmrig ]; then
        log "Archiving existing worker installation..."
        archived="xmrig-$(date +%Y%m%d_%H%M%S)"
        printf '%s\n' "$archived" >xmrig.swap.tmp && mv xmrig.swap.tmp xmrig.swap || error "Could not record the XMRig swap."
        mv xmrig "$archived"
    fi
    mv xmrig.new xmrig || {
        [ -z "$archived" ] || mv "$archived" xmrig
        error "Could not swap in the new XMRig build."
    }
    rm -f xmrig.swap
    local keep="${KEEP_ARCHIVES:-3}" archives
    # shellcheck disable=SC2012  # archive names are controlled (xmrig-YYYYmmdd_HHMMSS); ls -t orders by recency
    archives="$(ls -dt xmrig-* 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
    cd "$WORKER_ROOT/xmrig/build"
}

# 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() {
    _recover_xmrig_swap
    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)..."
    cd "$WORKER_ROOT"
    rm -rf xmrig.new
    git clone --quiet --branch "$XMRIG_VERSION" --depth 1 https://github.com/xmrig/xmrig.git xmrig.new

    local actual
    actual="$(git -C xmrig.new rev-parse HEAD)"
    [ "$actual" = "$XMRIG_COMMIT" ] || {
        rm -rf xmrig.new
        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.new/src/donate.h >xmrig.new/src/donate.h.new
    mv xmrig.new/src/donate.h.new xmrig.new/src/donate.h
    grep -Fxq "constexpr const int kDefaultDonateLevel = $DONATION;" xmrig.new/src/donate.h &&
        grep -Fxq 'constexpr const int kMinimumDonateLevel = 0;' xmrig.new/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.new/build && cd xmrig.new/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)..."
        if [ "${SHARED_HOST:-false}" = true ] && systemctl is-active --quiet "$SERVICE_NAME" 2>/dev/null; then
            log "Shared host: stopping the miner so the build gets the whole memory ceiling."
            sudo systemctl stop "$SERVICE_NAME.service" || error "Could not stop the miner before the shared-host build."
        fi
        mkdir -p xmrig.new/build && cd xmrig.new/build
        _shared_host_run cmake .. -DWITH_HWLOC=ON >>"$BUILD_LOG" 2>&1
    fi

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

    echo "$XMRIG_COMMIT" >"$WORKER_ROOT/xmrig.new/.rigforge-commit"
    printf '0\n' >"$WORKER_ROOT/xmrig.new/.rigforge-donate-min"
    [ ! -f "$WORKER_ROOT/xmrig.new/build/xmrig" ] || _sha256 "$WORKER_ROOT/xmrig.new/build/xmrig" >"$WORKER_ROOT/xmrig.new/.rigforge-sha256"
    (cd "$WORKER_ROOT/xmrig.new/build" && generate_xmrig_config stage)
    _activate_xmrig_build
}

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

_config_render_fail() {
    rm -f "$1"
    [ -n "${3:-}" ] || [ -z "$1" ] || rm -f "$1.bak"
    warn "$2${3:-; the previous config.json is unchanged.}"
    return 1
}

_config_install() {
    jq -e . "$1" >/dev/null && chmod 600 "$1" && { [ ! -f config.json ] || (umask 077 && cat config.json >"$1.bak"); } || _config_render_fail "$1" "Validating or backing up the XMRig config failed" || return 1
    if [ "${2:-}" = stage ]; then mv -f "$1" config.json; else cat "$1" >config.json && cmp -s "$1" config.json && chmod 600 config.json; fi && { rm -f "$1" "$1.bak" || true; } && return 0
    if { [ -f "$1.bak" ] && cat "$1.bak" >config.json && cmp -s "$1.bak" config.json; } || { [ ! -f "$1.bak" ] && rm -f config.json; }; then
        _config_render_fail "$1" "Installing the XMRig config failed"
    else
        _config_render_fail "$1" "Installing the XMRig config failed" "; restoring it failed too, so config.json may be incomplete (the previous copy is $PWD/$1.bak)."
    fi
}

generate_xmrig_config() {
    log "Generating hardware-optimized XMRig configuration..."
    _config_apply_begin "${1:-}"
    if [ "$OS_TYPE" == "Darwin" ]; then
        CPU_MODEL=$(sysctl -n machdep.cpu.brand_string)
    else
        CPU_MODEL=$(lscpu | grep -E '^Model name:' | cut -d':' -f2 | xargs)
    fi
    LOG_FILE_PATH=""
    if [ "$RIGFORGE_APPLIANCE" = 1 ]; then
        [ "${1:-}" = stage ] || sudo rm -f "$WORKER_ROOT/xmrig.log"
    else
        LOG_FILE_PATH="$WORKER_ROOT/xmrig.log"
    fi

    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"
    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

    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

    FULL_USER="$(hostname)"
    local _new _step
    _new=$(mktemp config.json.XXXXXX) || _config_render_fail "" "Creating a temp file for the XMRig config failed" || return 1
    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)' >"$_new" || _config_render_fail "$_new" "Rendering the XMRig config failed" || return 1

    if [ -f "$WORKER_ROOT/tune-overrides.json" ]; then
        _step=$(_shared_host_merge "$_new" "$WORKER_ROOT/tune-overrides.json") && printf '%s\n' "$_step" >"$_new" || _config_render_fail "$_new" "Applying $WORKER_ROOT/tune-overrides.json failed (fix or remove it)" || return 1
        log "Applied tuned overrides from tune-overrides.json."
    fi

    _apply_randomx_config "$_new" || _config_render_fail "$_new" "Applying the xmrig.randomx settings failed" || return 1
    if [ -n "${THREADS_CAP:-}" ]; then
        _step=$(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)' "$_new") && printf '%s\n' "$_step" >"$_new" || _config_render_fail "$_new" "Clamping cpu.rx to the thread cap failed" || return 1
    fi

    _shared_host_config "$_new"
    _config_install "$_new" "${1:-}" || return 1
    _config_apply_stamp "${CONFIG_INPUT_HASH:-}" "${1:-}"

    if [ "$OS_TYPE" == "Linux" ] && [ "${1:-}" != stage ]; then
        if [ "$RIGFORGE_APPLIANCE" = 1 ]; then
            log "Appliance mode: skipping the logrotate policy (image-owned logging)."
            return
        fi
        log "Configuring log rotation policy..."
        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 ---

_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=""
    [ "${SHARED_HOST:-false}" = true ] || _shared_host_remove
    if [ -n "${MINER_USER:-}" ] && [ "${SHARED_HOST:-false}" != true ]; 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" | _shared_host_unit | 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
        [ "${SHARED_HOST:-false}" != true ] || _reown_worker

        # 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 ] || [ "${SHARED_HOST:-false}" = true ]; then
            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
        [ "${SHARED_HOST:-false}" = true ] || _shared_host_remove
        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 } counter 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
}
_sister_api_failed() { ! warn "The configured sister API could NOT be started; check journalctl -u rigforge-api.service, then re-run 'sudo $0 $1'."; }
_control_failed() { warn "The writable control receiver could NOT be reconciled; check journalctl -u rigforge-control.service, then re-run 'sudo $0 $1'."; }
_stop_control_receiver() {
    sudo systemctl stop rigforge-control.service 2>/dev/null && return 0
    if [ "$(systemctl show -p LoadState --value rigforge-control.service 2>/dev/null)" = not-found ] && [ "$(systemctl show -p ActiveState --value rigforge-control.service 2>/dev/null)" = inactive ]; then return 0; fi
    sudo systemctl kill --kill-who=all --signal=KILL rigforge-control.service 2>/dev/null || true
    sudo systemctl stop rigforge-control.service 2>/dev/null && return 0
    ! warn "Could not stop the control receiver; revocation is NOT confirmed. Stop rigforge-control.service before retrying."
}
install_control() (
    [ "$OS_TYPE" == "Linux" ] || return 0
    trap 'rc=$?; if [ "$rc" -ne 0 ]; then _stop_control_receiver || true; fi; exit "$rc"' EXIT
    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"
    _stop_control_receiver || return 1
    if [ "${CONTROL_MODE:-disabled}" = "disabled" ]; then
        local u units=()
        for u in rigforge-control.service rigforge-control-apply.path rigforge-control-upgrade.path; do [ ! -f "$SYSTEMD_DIR/$u" ] || units+=("$u"); done
        if [ "${#units[@]}" -gt 0 ]; then
            sudo systemctl disable ${ENABLE_RUNTIME:+"$ENABLE_RUNTIME"} --now "${units[@]}" 2>/dev/null || return 1
            sudo rm -f "$svc" "$asvc" "$apath" "$usvc" "$upath" && sudo systemctl daemon-reload 2>/dev/null || return 1
            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}" WORKER_ROOT="${WORKER_ROOT:-}" NFT_PATH="$(command -v nft || echo /usr/sbin/nft)" \
        envsubst '$CONTROL_BIND $CONTROL_PORT $SCRIPT_DIR $API_PORT $WORKER_ROOT $NFT_PATH' \
        <"$SCRIPT_DIR/systemd/rigforge-control.service.template" | sudo tee "$svc" >/dev/null || return 1
    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 || return 1
    sudo tee "$apath" <"$SCRIPT_DIR/systemd/rigforge-control-apply.path.template" >/dev/null || return 1
    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 || return 1
        sudo tee "$upath" <"$SCRIPT_DIR/systemd/rigforge-control-upgrade.path.template" >/dev/null || return 1
        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
        { [ ! -f "$upath" ] || sudo systemctl disable ${ENABLE_RUNTIME:+"$ENABLE_RUNTIME"} --now rigforge-control-upgrade.path 2>/dev/null; } && sudo rm -f "$usvc" "$upath" || return 1
    fi
    install_api_firewall || return 1
    sudo systemctl daemon-reload || return 1
    sudo systemctl enable ${ENABLE_RUNTIME:+"$ENABLE_RUNTIME"} --now rigforge-control-apply.path 2>/dev/null || return 1
    if [ "${CONTROL_UPGRADE:-disabled}" = "enabled" ]; then
        sudo systemctl enable ${ENABLE_RUNTIME:+"$ENABLE_RUNTIME"} --now rigforge-control-upgrade.path 2>/dev/null || return 1
    fi
    sudo systemctl enable ${ENABLE_RUNTIME:+"$ENABLE_RUNTIME"} rigforge-control.service 2>/dev/null || return 1
    sudo systemctl restart rigforge-control.service || return 1
)

# #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() {
    if [ "${SHARED_HOST:-false}" = true ]; then
        RX_SETUP_THREADS="${THREADS_CAP:-}"
        return 0
    fi
    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")

    if [ "${HUGEPAGES_RESERVE_EXTRA_MB:-0}" -gt 0 ] 2>/dev/null; then
        if [ "${HUGEPAGES_POOL_CEILING_MB:-0}" -gt 0 ] &&
            [ "$(_cmdline_reserved_2mb "$CURRENT" 2M)" -gt "$((HUGEPAGES_POOL_CEILING_MB / 2))" ]; then
            return 0
        fi
        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
}

_cmdline_reserved_2mb() {
    awk -v size="${2:-}" '{ 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") { if (size!="2M") 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>
    [ "${SHARED_HOST:-false}" != true ] || return 0
    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() {
    [ "${SHARED_HOST:-false}" != true ] || {
        log "Shared host: skipping kernel, MSR and HugePages tuning."
        return 0
    }
    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.
        [ "${RX_MODE:-}" != light ] || error "RandomX light mode requires util/proposed-grub.sh for safe HugePages sizing."
        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() {
    [ "${SHARED_HOST:-false}" != true ] || {
        log "Shared host: preserving mounts and host memlock limits."
        return 0
    }
    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
    [ "$OS_TYPE" = Linux ] || return 0
    if [ "${SHARED_HOST:-false}" = true ] && [ "${RIGFORGE_APPLIANCE:-0}" != 1 ] && [ -d "$WORKER_ROOT" ]; then sudo touch "$WORKER_ROOT/xmrig.log" 2>/dev/null || true; fi
    if [ -n "${MINER_USER:-}" ]; then
        sudo chown "$MINER_USER:$MINER_USER" "$WORKER_ROOT/xmrig/build/config.json" "$WORKER_ROOT/xmrig.log" 2>/dev/null || true
    elif [ "${SHARED_HOST:-false}" = true ]; then
        sudo chown "root:$REAL_USER" "$WORKER_ROOT/xmrig/build/config.json" "$WORKER_ROOT/xmrig.log" 2>/dev/null || true
        sudo chmod 0640 "$WORKER_ROOT/xmrig/build/config.json" 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"
    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.new/build, record the binary SHA-256, then archive any prior install and swap the build in"
    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 [ "${SHARED_HOST:-false}" = true ]; then
        _p "shared host" "CPU quota ${SHARED_CPU_QUOTA}% of one CPU, memory ${SHARED_MEMORY_MAX_MB} MiB; verify cgroup v2, preserve host tuning"
    elif [ "$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
        elif [ "${RX_MODE:-}" = light ]; then
            _pages="FAIL: RandomX light mode requires util/proposed-grub.sh"
        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 _api_rc=0 _control_rc=0
    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
    _shared_host_prepare
    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 || _api_rc=1
    CURRENT_STEP="configuring the control path"
    install_control || _control_rc=1
    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
    [ "$_control_rc" -eq 0 ] || _control_failed setup
    [ "$_api_rc" -eq 0 ] || _sister_api_failed setup || true
    [ "$_api_rc:$_control_rc" = 0:0 ]
}

# --- 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 _api_rc=0 _control_rc=0
    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
    _shared_host_prepare
    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 || _api_rc=1
    install_control || _control_rc=1
    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"
    [ "$OS_TYPE" != Linux ] || [ "${SHARED_HOST:-false}" = true ] || _shared_host_remove
    _post_upgrade_retune
    _reown_worker
    [ "$_control_rc" -eq 0 ] || _control_failed upgrade
    [ "$_api_rc" -eq 0 ] || _sister_api_failed upgrade || true
    [ "$_api_rc:$_control_rc" = 0:0 ]
}

# 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)
    local preserve_host=no
    _shared_host_preserves_tuning "$worker_root" && preserve_host=yes

    # 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"

    _shared_host_remove
    if [ "$preserve_host" = no ]; then
        remove_line "$FSTAB" "hugetlbfs /dev/hugepages hugetlbfs defaults 0 0"
        remove_line "$FSTAB" "hugetlbfs_1g $HUGEPAGES_1G_DIR hugetlbfs pagesize=1G 0 0"

        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"

        sudo rm -f "$MODULES_LOAD_DIR/msr.conf"
        remove_line "$MODULES_FILE" "msr"

        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

        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

    else
        log "Shared-host history: preserving existing HugePages, mounts, MSR and boot settings."
    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" && _apply_randomx_config "$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|"">
    [ "${SHARED_HOST:-false}" != true ] || error "Offline benchmarks are unavailable in shared_host; use tune --now for a bounded live prefetch trial."
    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" || { warn "  tune: rendering the candidate config failed — skipping it." >&2 && printf 0 && return 0; }
        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() { if [ "${RX_MODE:-}" = light ]; then echo false; else jq -r '.randomx | if has("1gb-pages") then ."1gb-pages" else true end' "$TUNE_BASE"; fi; }
# 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
    [ "${SHARED_HOST:-false}" != true ] || error "Full tuning is unavailable in shared_host; use tune --now for a bounded live prefetch trial."

    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 && [ "${RX_MODE:-}" != light ]; then
        TUNE_ONEGB="${TUNE_ONEGB:-true false}"
    else
        TUNE_ONEGB="$(_seed_g)"
        [ "${RX_MODE:-}" = light ] || 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
    _shared_host_start_guard
    if [ "${SHARED_HOST:-false}" = true ] && ! _shared_host_in_slice; then
        AUTOTUNE_TARGET="${target_env:-${AUTOTUNE_TARGET:-perf}}" _shared_host_run "$SCRIPT_DIR/rigforge.sh" autotune
        return
    fi
    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
}

_pool_algorithm() {
    jq -r '.algo | select(type == "string" and . != "" and . != "rx/0")' 2>/dev/null || true
}
_status_api_summary() {
    local body hs pool up acc rej hp pa
    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"
    pa=$(printf '%s' "$body" | _pool_algorithm)
    [ -n "$pa" ] && printf '  Algorithm: %s\n' "$pa"
    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() {
    [ ! -f "$CONFIG_JSON" ] || (_shared_host_report) || true
    _config_apply_check
    [ "$OS_TYPE" = "Linux" ] || {
        mac_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() {
    _shared_host_start_guard
    [ "$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() {
    _shared_host_start_guard
    [ "$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")) ;;
    doctor) COMPREPLY=($(compgen -W "--json" -- "$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 ]
}

_apply_runtime() { # [preserve-run-state]
    parse_config
    _shared_host_start_guard
    local build="$WORKER_ROOT/xmrig/build"
    [ -d "$build" ] || error "No built worker at $build. Run 'setup' first."
    local held=no
    RIGFORGE_RESTART_FAILED=0
    [ "${1:-}" = preserve-run-state ] && _miner_deliberately_stopped && held=yes
    (cd "$build" && generate_xmrig_config) || return 1
    [ "${SHARED_HOST:-false}" != true ] || _reown_worker
    if [ "$OS_TYPE" != "Linux" ]; then
        log "Config regenerated. Restart the miner to apply."
    elif [ "$held" = yes ]; then
        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" || RIGFORGE_RESTART_FAILED=1
        [ "$RIGFORGE_RESTART_FAILED" -eq 0 ] && log "Applied config and restarted $SERVICE_NAME." || warn "Config regenerated, but restarting $SERVICE_NAME failed."
    fi
    _reown_worker
}

_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
        _shared_host_prepare
        _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
        _shared_host_reload
    fi
    local _wd_rc=0 _api_rc=0 _control_rc=0
    _apply_runtime preserve-run-state
    [ "$OS_TYPE" != Linux ] || [ "${SHARED_HOST:-false}" = true ] || _shared_host_remove
    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 || _control_rc=1
        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
    if [ "$_control_rc" -ne 0 ]; then
        RIGFORGE_APPLY_FAIL_REASON="could not reconcile the control receiver"
        _control_failed apply
    fi
    [ "${RIGFORGE_RESTART_FAILED:-0}" -eq 0 ] || : "${RIGFORGE_APPLY_FAIL_REASON:=could not restart the miner}"
    [ "$_wd_rc:$_api_rc:$_control_rc" = 0:0:0 ] && [ "${RIGFORGE_RESTART_FAILED:-0}" -eq 0 ]
}

_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="" detail=""
    for i in $(seq 1 "$tries"); do
        IFS="$(printf '\t')" read -r st pool n detail <<EOF
$(_pool_conn_status)
EOF
        case "$st" in connected | daemon | daemon-down) break ;; esac
        [ "$i" -lt "$tries" ] && sleep "$iv"
    done
    case "$st" in
    daemon) log "Node RPC reachable: height $n (${detail:-unknown})." ;;
    daemon-down) warn "Node get_info is unavailable, invalid or timed out — check the configured daemon and its RPC access." ;;
    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
}

_control_upgrade_throttle_ok() (
    local dir="$1" lock="$1/.upgrade-throttle.lock" stamp="$1/upgrade-last" now tmp min="${CONTROL_UPGRADE_MIN_INTERVAL:-21600}" last=0
    [ ! -L "$dir" ] && [ -d "$dir" ] && [ "$(stat -c '%u:%g:%a' "$dir" 2>/dev/null)" = "0:0:700" ] || return 2
    if [ -e "$lock" ] || [ -L "$lock" ]; then
        [ ! -L "$lock" ] && [ -f "$lock" ] && [ "$(stat -c '%u:%g:%a:%h' "$lock" 2>/dev/null)" = "0:0:600:1" ] || return 2
    fi
    umask 077
    exec 9>>"$lock" 2>/dev/null || return 2
    flock -x 9 2>/dev/null || return 2
    if [ -e "$stamp" ] || [ -L "$stamp" ]; then
        [ ! -L "$stamp" ] && [ -f "$stamp" ] && [ "$(stat -c '%u:%g:%a:%h' "$stamp" 2>/dev/null)" = "0:0:600:1" ] || return 2
        last=$(cat "$stamp" 2>/dev/null) || return 2
    fi
    case "$last" in '' | *[!0-9]*) return 2 ;; esac
    now=$(date +%s) || return 2
    if [ $((now - last)) -lt "$min" ] 2>/dev/null; then
        return 1
    fi
    tmp=$(mktemp "$dir/.upgrade-last.XXXXXX") || return 2
    if ! printf '%s\n' "$now" >"$tmp" || ! mv -f "$tmp" "$stamp"; then
        rm -f "$tmp"
        return 2
    fi
    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 throttle="${RIGFORGE_CONTROL_UPGRADE_STATE:-/var/lib/rigforge-control-upgrade}"
    _control_upgrade_throttle_ok "$throttle" || thr_rc=$?
    if [ "$thr_rc" -eq 2 ]; then
        _control_status "$status" failed "$cid" version "throttle state unavailable under $throttle — 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
}

watchdog() {
    if [ "$OS_TYPE" != "Linux" ]; then
        error "watchdog drives the live systemd service and is only supported on Linux."
    fi
    parse_config
    _shared_host_start_guard
    local fails_f="$WORKER_ROOT/watchdog.fails" hold_f="$WORKER_ROOT/watchdog.thermal-hold" t hr f
    t=$(_read_temp)
    if [ -f "$hold_f" ]; then
        if [ -z "$MAX_TEMP_C" ]; then
            if ! sudo systemctl start "$SERVICE_NAME" 2>/dev/null; then
                warn "watchdog: failed to start $SERVICE_NAME — thermal hold retained; will retry."
                return 0
            fi
            rm -f "$hold_f"
            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
            if ! sudo systemctl start "$SERVICE_NAME" 2>/dev/null; then
                warn "watchdog: failed to start $SERVICE_NAME — thermal hold retained; will retry."
                return 0
            fi
            rm -f "$hold_f"
            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
        if ! sudo systemctl stop "$SERVICE_NAME" 2>/dev/null; then
            warn "watchdog: failed to stop $SERVICE_NAME at ${t}°C — will retry while above max_temp_c=${MAX_TEMP_C}°C."
            return 0
        fi
        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"
}

# shellcheck source=util/doctor-report.sh
source "$(_script_dir)/util/doctor-report.sh"
# 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
    [ "${SHARED_HOST:-false}" != true ] || error "MSR tuning is disabled in shared_host."
    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)}'
}

_writable_config_hash() { _writable_config_canonical | RIGFORGE_KEY_OWNER="$REAL_USER" "$(_script_dir)/util/revision-key.sh" "${RIGFORGE_REVISION_KEY:-$SCRIPT_DIR/.rigforge-revision-key}" || :; }

# #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 appliance "$RIGFORGE_APPLIANCE" --arg stamp "$(cat "$SCRIPT_DIR/RIGFORGE_REF" 2>/dev/null || echo '')" --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, appliance: ($appliance == "1"), stamp: (if $stamp == "" then null else $stamp end), 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")
    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
    if _active_daemon_pool "${sum:-null}" >/dev/null; then body=$(jq '.connection.mode = "daemon"' <<<"$body"); 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_conn_status() {
    local body pool cup fails acc daemon_pool
    body=$(_read_api_summary)
    if daemon_pool=$(_active_daemon_pool "${body:-null}"); then
        _daemon_node_status "$daemon_pool"
        return 0
    fi
    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" donation
    elif [ "$got" != "$want" ]; then
        _ck_warn "XMRig donate_level $got differs from DONATION $want — upgrade an older build, then apply and restart" donation
        return 1
    else
        _ck_ok "XMRig donate_level matches DONATION ($want%)" donation
    fi
}

doctor() {
    cmd_version
    local issues=0
    if [ -f "$CONFIG_JSON" ]; then
        _shared_host_parse
        if [ "$SHARED_HOST" = true ]; then _shared_host_report || issues=$((issues + 1)); fi
    fi
    if [ "$OS_TYPE" != "Linux" ]; then
        warn "doctor's health checks are Linux-only (this host is $OS_TYPE)."
        return "$issues"
    fi
    log "Checking the worker (read-only)..."
    _config_apply_check
    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" api-refresh; else
            _ck_warn "$refresh_state" api-refresh
            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" service
    else
        _ck_warn "service '$SERVICE_NAME' is not active — start it with: sudo $0 start" service
        issues=$((issues + 1))
    fi

    if [ -f "$CONFIG_JSON" ]; then
        local pc_st="" pc_pool="" pc_n1="" pc_n2="" pool0 ph pp proxy daemon_pool pa
        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" socks-proxy
                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" socks-proxy
        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
            pa=$(ACCESS_TOKEN="$(jq -r '.ACCESS_TOKEN // empty' "$CONFIG_JSON" 2>/dev/null || true)" _read_api_summary | _pool_algorithm)
            [ -n "$pa" ] && _ck_info "Algorithm: $pa" pool-algorithm
            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
            daemon | daemon-down)
                _doctor_daemon_status "$(printf '%s\t%s\t%s\t%s' "$pc_st" "$pc_pool" "$pc_n1" "$pc_n2")" || issues=$((issues + 1))
                ;;
            connected)
                _ck_ok "pool connection live: $pc_pool (up $(_render_duration "${pc_n1:-0}"), ${pc_n2:-0} share(s) accepted)" pool-connection
                ;;
            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'" pool-connection
                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)" pool-connection
                ;;
            esac
        elif daemon_pool=$(_active_daemon_pool); then
            _doctor_daemon_status "$(_daemon_node_status "$daemon_pool")" || issues=$((issues + 1))
        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" pool-connection
        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)" pool-connection
                else
                    _ck_warn "pool $ph:$pp is unreachable (TCP connect failed) — the rig cannot mine until pools[0].url points at a reachable pool" pool-connection
                    issues=$((issues + 1))
                fi
            fi
        fi
    fi

    _check_randomx_memory "$svc_up" || issues=$((issues + 1))
    # HugePages reserved? (the single biggest lever; needs a reboot after setup)
    if [ "${SHARED_HOST:-false}" != true ]; then
        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)" hugepages
        else
            _ck_warn "HugePages not reserved — reboot after setup (the GRUB change needs a reboot)" hugepages
            issues=$((issues + 1))
        fi

        local g=0
        [ -f "$HUGEPAGES_1G_NR" ] && g=$(cat "$HUGEPAGES_1G_NR" 2>/dev/null || echo 0)
        if [ "${RX_MODE:-}" = light ]; then
            _ck_info "1GB HugePages disabled in RandomX light mode" hugepages-1gb
        elif [ "${g:-0}" -gt 0 ] 2>/dev/null; then
            _ck_ok "1GB HugePages reserved ($g)" hugepages-1gb
        else
            _ck_warn "1GB HugePages not reserved (optional; needs a pdpe1gb CPU + reboot)" hugepages-1gb
        fi

    fi
    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" cpu-aes
        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)" cpu-aes || true
    fi
    [[ " $miss_isa " == *" avx2 "* ]] && _ck_info "CPU has no AVX2 — dataset init is slower (steady-state hashrate unaffected)" cpu-avx2
    # 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)" 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'" miner-user
            issues=$((issues + 1))
        fi
        if [ "${SHARED_HOST:-false}" != true ] && [ -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)" msr-root-preset
            elif [ "$_MSR_UNREAD" = "$_MSR_TOTAL" ]; then
                _ck_info "root-side MSR preset '$_mp' recorded — run doctor as root for the register read-back" msr-root-preset
            else
                _ck_warn "root-side MSR preset '$_mp': only $_MSR_OK/$_MSR_TOTAL registers match (bad:$_MSR_BAD)" msr-root-preset
                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" binary-checksum
        elif [ "$(cat "$sums" 2>/dev/null)" = "$(_sha256 "$bin")" ]; then
            _ck_ok "xmrig binary matches its build-time SHA-256 (unchanged since compile)" binary-checksum
        else
            _ck_warn "xmrig binary CHANGED since it was built — re-run 'sudo $0 setup' to rebuild, or investigate how it changed" binary-checksum
            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)" api-read-only
        else
            _ck_warn "HTTP API is NOT read-only (http.restricted=${restricted:-unreadable}) — regenerate it with: sudo $0 apply" api-read-only
            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" api-exposure
        else
            _ck_ok "API exposure is limited (${cfg_tok:+token}${cfg_tok:+${cfg_scope:+ + }}${cfg_scope:+firewall scope})" api-exposure
        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)")" access-tokens
    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})" control ;;
                *)
                    _ck_warn "control: enabled and rigforge-control is active, but :${ctl_port:-8082}/status isn't responding — check journalctl -u rigforge-control" 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" control
                issues=$((issues + 1))
            fi
            ;;
        esac
    fi

    if [ "${SHARED_HOST:-false}" != true ]; then
        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" kernel-lockdown
        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'." kernel-lockdown
            issues=$((issues + 1))
        else
            _ck_ok "kernel lockdown: none — MSR writes are permitted" kernel-lockdown
        fi

        if [ -d "$MSR_MODULE_DIR" ]; then
            _ck_ok "msr kernel module loaded" msr-module
        else
            _ck_warn "msr module not loaded — the MSR mod won't apply; check 'sudo modprobe msr' and $MODULES_LOAD_DIR/msr.conf" msr-module
            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)" msr-log
                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)" msr-registers
                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)" msr-registers
                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)" msr-registers
                    elif [ -n "$_MSR_BAD" ]; then
                        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" msr-registers
                        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" msr-registers
                        fi
                        issues=$((issues + 1))
                    else
                        _ck_warn "couldn't read $_MSR_UNREAD/$_MSR_TOTAL MSR(s) via rdmsr (is the 'msr' module loaded?) — relying on XMRig's log confirmation" msr-registers
                    fi
                fi
                ;;
            fail)
                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" msr-log
                else
                    _ck_warn "XMRig reports the MSR preset FAILED to set — check msr.allow_writes=on and that no hypervisor is masking MSR access" msr-log
                fi
                issues=$((issues + 1))
                ;;
            *) : ;;
            esac
            if [ "$msrstat" = none ]; then
                [ -z "$log_file" ] && _ck_info "MSR file-log confirmation is disabled; the bounded systemd journal has no confirmation yet" msr-log
                [ -n "$log_file" ] && [ ! -f "$log_file" ] && _ck_info "MSR unverifiable — no xmrig.log at $log_file and no journal confirmation" msr-log
            fi
        elif [ -z "$wr" ]; then
            _ck_info "MSR unverifiable — no config.json, so the worker root couldn't be resolved" msr-log
        fi

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

    fi
    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" ram-layout
        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" ram-channels
            else
                _ck_ok "RAM: $pop modules across $nch channels (dual+ channel)" ram-channels
            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)" ram-speed
            elif [ "${spd:-0}" -gt 0 ] 2>/dev/null; then
                _ck_ok "RAM speed: ${spd} MT/s" ram-speed
            fi
        fi
    else
        _ck_warn "dmidecode not found — install it for the RAM channels/speed check (advisory only)" ram-layout
    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)" cpu-clock
            else
                _ck_ok "CPU clock under load: $((effk / 1000)) MHz (${pct}% of max boost)" cpu-clock
            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)." firmware
        else
            _ck_info "Firmware: ${bvendor:-?} ${board:-?}, BIOS ${bios:-?} (${bdate:-?})${cpu:+, $cpu} — no BIOS changes recommended." firmware
        fi
    fi
    if [ -n "$xmp_rec" ]; then _ck_warn "$xmp_rec" memory-profile; fi
    if [ -n "$smt_rec" ]; then _ck_warn "$smt_rec" smt; fi
    if [ -n "$nps_rec" ]; then _ck_warn "$nps_rec" numa-nps; 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 [ "${SHARED_HOST:-false}" != true ] && [ -n "$log_file" ] && [ -f "$log_file" ]; then
        if grep -qiE 'huge pages.*100%' "$log_file"; then
            _ck_ok "XMRig log reports HUGE PAGES 100%" hugepages-backing
        elif grep -qi 'huge pages' "$log_file"; then
            _ck_warn "XMRig log shows HUGE PAGES below 100% — not all threads are backed" hugepages-backing
        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 worker health (doctor --json: machine report on stdout, human report on stderr)
  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 | 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)
        shift
        doctor_command "$@" || exit 1
        ;;
    bios)
        shift
        bios "$@"
        ;;
    api-refresh) api_refresh ;;
    shared-host-check) _shared_host_check ;;
    shared-host-run)
        shift
        _shared_host_exec "$@"
        ;;
    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