update-checker

#!/usr/bin/env bash

# NixOS Update Checker for Waybar
# This script checks for NixOS updates and outputs JSON for Waybar integration

    # ===== Configuration =====
    UPDATE_INTERVAL="${UPDATE_INTERVAL:-3599}"  # Check interval in seconds (1 hour)
    NIXOS_CONFIG_PATH="${NIXOS_CONFIG_PATH:-$HOME/.config/nixos}"  # Path to NixOS configuration
    CACHE_DIR="${CACHE_DIR:-$HOME/.cache}"
    NOTIFICATIONS_ENABLED="${NOTIFICATIONS_ENABLED:-true}"  # Set to "false" to disable desktop notifications
    # Clock format for tooltip timestamps: "24h" (14:23) or "12h" (2:23 PM)
    CLOCK_FORMAT="${CLOCK_FORMAT:-24h}"
    # Input checker: "disabled" | "show" | "count"
    INPUT_CHECKER_MODE="${INPUT_CHECKER_MODE:-disabled}"
    INPUT_CHECKER_PINNED="${INPUT_CHECKER_PINNED:-disabled}"
    # Explicit upstream policies for sources the package and input checks cannot
    # interpret on their own. An empty list means the source checker never runs.
    # Deliberately ${VAR-default}, not ${VAR:-default}: only an *unset* value
    # means "no checks configured". An empty value is a broken one, and must
    # reach source-checker to be reported rather than passing as a clean result.
    SOURCE_CHECKS_JSON="${SOURCE_CHECKS_JSON-[]}"
    # On-demand update-cost preview, bound to middle-click when enabled. Off by
    # default: a preview is a full system evaluation costing minutes, so it
    # never runs on a timer.
    DRY_RUN_PREVIEW="${DRY_RUN_PREVIEW:-false}"
    # Recompute that preview by itself once it goes stale. Also off by default,
    # and it only ever refreshes a preview that already exists - see
    # maybe_auto_preview.
    PREVIEW_AUTO="${PREVIEW_AUTO:-false}"
    # What a detected rebuild does to the package count.
    #
    # "recheck" discards the old result and checks, so a rebuild that applied
    # only some of the pending updates is reported correctly - at the cost of a
    # full check, which in this mode builds the new closure. "reconcile"
    # subtracts the packages the rebuild demonstrably changed, read from the nvd
    # diff already being run to detect it, and keeps the rest; no extra work, but
    # it cannot see the channel moving on, so it can undercount until the next
    # scheduled check. "assume-updated" reports zero packages without checking.
    #
    # None of them affect the input, pinned or source sections: a rebuild does
    # not resolve those.
    AFTER_REBUILD="${AFTER_REBUILD:-recheck}"
    case "$AFTER_REBUILD" in
        assume-updated|reconcile) ;;
        *) AFTER_REBUILD="recheck" ;;
    esac
    STATE_FILE="$CACHE_DIR/nix-update-state"
    LAST_RUN_FILE="$CACHE_DIR/nix-update-last-run"
    LAST_RUN_TOOLTIP="$CACHE_DIR/nix-update-tooltip"
    BOOT_MARKER_FILE="$CACHE_DIR/nix-update-boot-marker"  # Marker file to detect boot/resume
    TOGGLE_FILE="$CACHE_DIR/nix-update-toggle"  # Toggle file to enable/disable update checking
    INPUT_STATE_FILE="$CACHE_DIR/nix-update-input-state"  # Input checker state
    INPUT_TOOLTIP_FILE="$CACHE_DIR/nix-update-input-tooltip"  # Input checker tooltip
    PINNED_STATE_FILE="$CACHE_DIR/nix-update-pinned-state"  # Pinned input checker state
    PINNED_TOOLTIP_FILE="$CACHE_DIR/nix-update-pinned-tooltip"  # Pinned input checker tooltip
    # Source check results. Cached for the same reason the input and pinned
    # results are: a rebuild handled as "assume-updated" has to rebuild the
    # tooltip without re-running the checks, and source-checker reaches the
    # network.
    SOURCE_COUNT_FILE="$CACHE_DIR/nix-update-source-count"
    SOURCE_SHOWN_FILE="$CACHE_DIR/nix-update-source-shown"
    SOURCE_TOOLTIP_FILE="$CACHE_DIR/nix-update-source-tooltip"
    # The reported packages as structured data, not just the rendered line.
    # Written by every check so "reconcile" can drop entries by package name
    # after a rebuild instead of parsing them back out of display text.
    PACKAGES_JSON_FILE="$CACHE_DIR/nix-update-packages.json"
    # Set while the link is down, so the "not connected" notification is raised
    # once per outage rather than once per poll. notify-send is called without a
    # replace id, so an unthrottled notification does not update in place - it
    # stacks a new one every few seconds for as long as the link stays down.
    NETWORK_DOWN_FLAG="$CACHE_DIR/nix-update-network-down"
    # Held for the duration of a check. This mode's check realises the closure
    # rather than evaluating it, so its duration is however long the pending
    # update takes to fetch and build - which can exceed updateInterval, putting
    # a second poll inside the first check. Two of those would fetch and build
    # the same paths concurrently and race to write the same result files.
    CHECK_LOCK_FILE="$CACHE_DIR/nix-update-check.lock"

    # The grace period prevents the update checker from running immediately after:
    # 1. First boot - when the system has just started up
    # 2. Resume from hibernation/suspension - when the system has just woken up
    # This avoids unnecessary resource usage and notifications during these transition periods.
    # Read from the environment like every other setting: these were plain
    # assignments, which overwrote what the module exports, so skipAfterBoot and
    # gracePeriod had no effect in this mode whatever they were set to.
    SKIP_AFTER_BOOT="${SKIP_AFTER_BOOT:-true}"  # false runs the checker even after boot/resume
    GRACE_PERIOD="${GRACE_PERIOD:-60}"  # Grace period in seconds after boot/resume

    # If true, update the lock file in the config folder.
    # If false, resolve a speculative lock beside it and leave yours untouched.
    #
    # Deliberately still a plain assignment, so the module's updateLockFile is
    # inert and every check takes the false branch. The true branch runs `nix
    # flake update` in the real configuration directory and builds there,
    # rewriting your flake.lock and leaving a ./result behind. It has been dead
    # code for long enough that honouring the option would newly enable that on
    # configurations already setting it, which is not a change to make quietly.
    UPDATE_LOCK_FILE="false"

    # If you have a separate script to update your lock file (i.e. "nix flake update" script)
    # and you have UPDATE_LOCK_FILE set to "false",
    # the UPDATE_FLAG will signal that your lock file has been updated.
    # Auto-detection cache files - no flag files or alias modifications needed.
    # Stores the last seen /run/current-system path to auto-detect rebuilds.
    SYSTEM_PATH_FILE="$CACHE_DIR/nix-update-system-path"
    # Stores the flake.lock hash to auto-detect input updates.
    FLAKE_LOCK_INPUT_HASH_FILE="$CACHE_DIR/nix-update-flake-lock-input-hash"

    # The UPDATING_FLAG signals if upgrade process is currently performing
    # This is required to force waybar module to render while we wait for nixos rebuild.
    UPDATING_FLAG="$CACHE_DIR/nix-update-updating-flag"
    # Set by `refresh` to request a check before the interval is up. A flag
    # rather than deleting LAST_RUN_FILE, because that file is also where the
    # tooltip's "Last checked" time comes from - removing it to force a check
    # would erase the very timestamp the header needs to display.
    FORCE_CHECK_FLAG="$CACHE_DIR/nix-update-force-check"
    # Fingerprint of the last check's findings, used to expire a preview when
    # upstream moves. Written by the checker, read by the preview script.
    RESULT_HASH_FILE="$CACHE_DIR/nix-update-result-hash"
    # Fingerprint of the packages the configuration declares, used to expire a
    # preview when that set changes. Written by the checker, read by the preview
    # script.
    APP_LIST_HASH_FILE="$CACHE_DIR/nix-update-app-list-hash"
    # Result of the last update-cost preview, written by the preview script.
    PREVIEW_FILE="$CACHE_DIR/nix-update-preview"


    # ===== Initialize Files =====
    function init_files() {
        # Ensure cache directory exists
        mkdir -p "$CACHE_DIR"
        
        # Create the state file if it doesn't exist
        if [ ! -f "$STATE_FILE" ]; then
            echo "0" > "$STATE_FILE"
        fi

        # Create the last run file if it doesn't exist
        if [ ! -f "$LAST_RUN_FILE" ]; then
            echo "0" > "$LAST_RUN_FILE"
        fi

        # Create the tooltip file if it doesn't exist
        if [ ! -f "$LAST_RUN_TOOLTIP" ]; then
            updates=$(cat "$STATE_FILE" 2>/dev/null || echo "0")
            if [ "$updates" = "0" ] || [ -z "$updates" ]; then
                echo "System updated" > "$LAST_RUN_TOOLTIP"
            else
                # Will be populated during update check
                echo "Checking for updates..." > "$LAST_RUN_TOOLTIP"
            fi
        fi
        
        # Create the toggle file if it doesn't exist (default: enabled)
        if [ ! -f "$TOGGLE_FILE" ]; then
            echo "enabled" > "$TOGGLE_FILE"
        fi
    }

    # ===== Helper Functions =====
    function send_notification() {
        # Skip if notifications are disabled
        if [ "$NOTIFICATIONS_ENABLED" != "true" ]; then
            return 0
        fi
        
        # Check if notify-send is available
        if ! command -v notify-send >/dev/null 2>&1; then
            return 0
        fi
        
        local icon="$1"
        local title="$2"
        local message="$3"
        local expire_flag="${4:-}" # Optional fourth parameter for -e flag
        
        local args=("$title" "$message")
        if [ -f "$HOME/.icons/$icon.png" ]; then
            args=(-i "$HOME/.icons/$icon.png" "${args[@]}")
        fi
        if [ -n "$expire_flag" ]; then
            args+=("$expire_flag")
        fi
        
        notify-send "${args[@]}" >/dev/null 2>&1 || true
    }

    function refresh_waybar() {
        pkill -x -RTMIN+12 .waybar-wrapped >/dev/null 2>&1 || true
    }

    function check_boot_resume() {
            # Detects if system recently booted OR resumed from suspend/hibernate
            # Returns 0 (true) if we're in grace period, 1 (false) otherwise

            local current_time=$(date +%s)
            local uptime_seconds=$(awk '{print int($1)}' /proc/uptime)
            local last_boot_time=$((current_time - uptime_seconds))

            # Check if this is a recent boot
            if [ $((current_time - last_boot_time)) -lt "$GRACE_PERIOD" ]; then
                echo "$current_time" > "$BOOT_MARKER_FILE"
                return 0
            fi

            # Check for recent suspend/hibernate resume using journalctl
            if command -v journalctl >/dev/null 2>&1; then
                local last_resume=0
                
                # Method 1: Check sleep.target (most reliable - "Stopped target Sleep" = resume)
                local resume_timestamp
                resume_timestamp=$(journalctl -b -u sleep.target --output=short-unix 2>/dev/null \
                    | grep "Stopped target Sleep" | tail -1 | awk '{print int($1)}')
                
                if [[ "$resume_timestamp" =~ ^[0-9]+$ ]] && [ "$resume_timestamp" -gt 0 ]; then
                    last_resume=$resume_timestamp
                fi
                
                # Method 2: Check systemd suspend/hibernate service timestamps
                if [ "$last_resume" -eq 0 ]; then
                    resume_timestamp=$(journalctl -b -u systemd-suspend.service -u systemd-hibernate.service \
                        -u systemd-hybrid-sleep.service -u systemd-suspend-then-hibernate.service \
                        --output=short-unix -n 1 2>/dev/null | tail -1 | awk '{print int($1)}')
                    
                    if [[ "$resume_timestamp" =~ ^[0-9]+$ ]] && [ "$resume_timestamp" -gt 0 ]; then
                        last_resume=$resume_timestamp
                    fi
                fi
                
                # Method 3: Check kernel PM messages as fallback
                if [ "$last_resume" -eq 0 ]; then
                    resume_timestamp=$(journalctl -b -k --grep="PM: suspend exit\|PM: hibernation exit\|PM: restore" \
                        --output=short-unix -n 1 2>/dev/null | tail -1 | awk '{print int($1)}')
                    
                    if [[ "$resume_timestamp" =~ ^[0-9]+$ ]] && [ "$resume_timestamp" -gt 0 ]; then
                        last_resume=$resume_timestamp
                    fi
                fi
                
                # If we found a recent resume event within grace period, trigger it
                if [ "$last_resume" -gt 0 ] && [ $((current_time - last_resume)) -lt "$GRACE_PERIOD" ]; then
                    echo "$current_time" > "$BOOT_MARKER_FILE"
                    return 0
                fi
            fi

            # Fallback: Check boot marker for existing grace period
            if [ -f "$BOOT_MARKER_FILE" ]; then
                local marker_time
                marker_time=$(cat "$BOOT_MARKER_FILE")
                if [[ "$marker_time" =~ ^[0-9]+$ ]] && [ $((current_time - marker_time)) -lt "$GRACE_PERIOD" ]; then
                    return 0
                fi
            fi

            # Not in grace period
            return 1
        }

    function check_network_connectivity() {
        # Check if we have a default route and an IP on a non-loopback interface
        if ip route 2>/dev/null | grep -q "^default" && \
           ip -4 addr show 2>/dev/null | grep -E "inet .* scope global" > /dev/null 2>&1; then
            return 0  # Network is configured
        else
            return 1  # No network
        fi
    }

    # Assembles the tooltip body from whichever sections have something to show,
    # and prints it. Section labels appear only when more than one section is
    # present, so a tooltip with a single section stays as bare lines.
    #
    # Separate from the check because a rebuild handled as "assume-updated" has
    # to produce the same body from cached section state without re-running
    # anything. Inlining it there is what let the old early-exit path overwrite
    # the tooltip with a bare "System updated", discarding the input, pinned and
    # source sections a rebuild does not resolve.
    #
    # Args: pkg_count pkg_tooltip input_count input_tooltip
    #       pinned_count pinned_tooltip source_shown source_tooltip
    # Package names nvd reports as changed, lowercased, one per line.
    #
    # nvd's format is "[U.]  #02  brave  1.93.129 -> 1.93.138": a bracketed
    # marker, an index, the name, then versions. Every marker counts, not just
    # [U] - a downgrade, a mixed-version change and a removal all mean the same
    # thing here, that the entry being held no longer describes what is
    # installed.
    function nvd_changed_names() {
        sed -nE 's/^\[[A-Z][^]]*\][[:space:]]+#[0-9]+[[:space:]]+([^[:space:]]+)[[:space:]].*/\1/p' \
            <<<"$1" | tr '[:upper:]' '[:lower:]' | sort -u
    }

    # Drops the pending entries a rebuild resolved and prints what is left.
    #
    # The rule is "the rebuild changed this package at all", not "it reached the
    # version we were waiting for". A package whose installed version moved is
    # one the rebuild acted on, and the stored entry has stopped describing
    # reality either way. Entries nvd never mentions were untouched, so they
    # stay. What this cannot see is the channel moving forward since the last
    # check, so the surviving count can be an undercount; it never invents a
    # resolved entry, and the next scheduled check replaces it with a
    # measurement.
    function reconcile_packages() {
        local pending="$1" nvd_out="$2"
        local changed_json
        changed_json=$(nvd_changed_names "$nvd_out" \
            | jq -R -s 'split("\n") | map(select(length > 0))' 2>/dev/null)
        [ -n "$changed_json" ] || { printf '%s' "$pending"; return 0; }
        jq -c --argjson changed "$changed_json" \
            '[ .[] | select((.name | ascii_downcase) as $n | ($changed | index($n)) == null) ]' \
            <<<"$pending" 2>/dev/null
    }

    # Derives the count, the rendered tooltip and the structured package list
    # from a single nvd invocation. The diff used to be run twice per check for
    # the first two, at roughly four seconds each.
    function record_pending_from_nvd() {
        local diff_out="$1"
        local changed
        changed=$(grep -e '\[U' <<<"$diff_out")
        updates=$(grep -c . <<<"$changed")
        [[ "$updates" =~ ^[0-9]+$ ]] || updates=0
        tooltip=$(awk '{ for (i=3; i<NF; i++) printf $i " "; if (NF >= 3) print $NF; }' <<<"$changed" \
            | awk '{printf "%s%s", (NR>1 ? "\\n" : ""), $0}')
        # name plus the rendered line, so reconciling is a filter and a join and
        # never has to re-derive how an entry was displayed.
        awk 'NF >= 3 { line = ""; for (i = 3; i < NF; i++) line = line $i " "; line = line $NF;
                       printf "%s\t%s\n", tolower($3), line }' <<<"$changed" \
            | jq -R -s -c 'split("\n") | map(select(length > 0)) | map(split("\t"))
                           | map({name: .[0], line: .[1]})' > "$PACKAGES_JSON_FILE" 2>/dev/null
    }

    function compose_tooltip_body() {
        local pkg_count="$1" pkg_tooltip="$2"
        local input_count="$3" input_tooltip="$4"
        local pinned_count="$5" pinned_tooltip="$6"
        local source_shown="$7" source_tooltip="$8"

        local labels=() texts=()
        if [ "$pkg_count" -gt 0 ]; then
            labels+=("Packages"); texts+=("$pkg_tooltip")
        fi
        if [ "$INPUT_CHECKER_MODE" != "disabled" ] && [ "$input_count" -gt 0 ]; then
            labels+=("Inputs"); texts+=("$input_tooltip")
        fi
        if [ "$INPUT_CHECKER_PINNED" != "disabled" ] && [ "$pinned_count" -gt 0 ]; then
            labels+=("Pinned"); texts+=("$pinned_tooltip")
        fi
        if [ "$source_shown" -gt 0 ]; then
            labels+=("Sources"); texts+=("$source_tooltip")
        fi

        local n=${#labels[@]}
        if [ "$n" -eq 0 ]; then
            printf 'System updated'
            return 0
        fi

        local out="" i
        for ((i = 0; i < n; i++)); do
            [ -n "$out" ] && out="$out\\n\\n"
            [ "$n" -gt 1 ] && out="$out${labels[i]}:\\n"
            out="$out${texts[i]}"
        done
        printf '%s' "$out"
    }

    # Set by check_system_rebuilt when it had two closures to compare, so
    # "reconcile" can subtract from the pending list without diffing again.
    REBUILD_NVD_OUT=""

    function check_system_rebuilt() {
        # Auto-detect rebuild by comparing /run/current-system to cached path.
        # Uses nvd diff on existing store paths (fast, no build needed) to distinguish
        # package version updates from config-only rebuilds.
        # Returns 0 only if package versions actually changed.
        local current_system
        current_system=$(readlink /run/current-system 2>/dev/null)
        local cached_system
        cached_system=$(cat "$SYSTEM_PATH_FILE" 2>/dev/null || echo "")

        if [ -n "$current_system" ] && [ -z "$cached_system" ]; then
            # First run - initialize without treating as a rebuild
            echo "$current_system" > "$SYSTEM_PATH_FILE"
            return 1
        elif [ -n "$current_system" ] && [ "$current_system" != "$cached_system" ]; then
            # Rebuild detected - update cache then check if packages actually changed
            echo "$current_system" > "$SYSTEM_PATH_FILE"
            if [ -d "$cached_system" ]; then
                # Both paths exist - diff them to check if package versions
                # changed. No building is needed, since both closures are already
                # in the store, but it is not free either (~4.3s measured), so the
                # output is kept for "reconcile" rather than diffed again.
                REBUILD_NVD_OUT=$(nvd diff "$cached_system" "$current_system" 2>/dev/null)
                if grep -q '\[U' <<<"$REBUILD_NVD_OUT"; then
                    return 0  # Package versions changed
                fi
                return 1  # Config-only rebuild - preserve package state
            else
                # Previous path was GC'd - can't diff, assume packages may have changed
                return 0
            fi
        fi
        return 1
    }

    function check_inputs_updated() {
        # Auto-detect flake.lock changes to trigger an immediate input re-check.
        # Triggers whenever any input is updated via nix flake update, regardless
        # of which alias or command was used. No flag files needed.
        local flake_lock="$NIXOS_CONFIG_PATH/flake.lock"
        [ ! -f "$flake_lock" ] && return 1

        local current_hash
        current_hash=$(md5sum "$flake_lock" 2>/dev/null | cut -d' ' -f1)
        local cached_hash
        cached_hash=$(cat "$FLAKE_LOCK_INPUT_HASH_FILE" 2>/dev/null || echo "")

        if [ -z "$cached_hash" ]; then
            # First run - initialize without triggering re-check
            echo "$current_hash" > "$FLAKE_LOCK_INPUT_HASH_FILE"
            return 1
        elif [ "$current_hash" != "$cached_hash" ]; then
            # flake.lock changed - update cache and signal re-check needed
            echo "$current_hash" > "$FLAKE_LOCK_INPUT_HASH_FILE"
            return 0
        fi
        return 1
    }

    function calc_next_update() {
        local last_run=$(cat "$LAST_RUN_FILE")
        local current_time=$(date +%s)
        local next_update=$((UPDATE_INTERVAL - (current_time - last_run)))
        local next_update_min=$((next_update / 60))
        echo "$next_update_min"
    }

    # With no argument: "Last checked: X · Next check: Y".
    # With "checking":  "Last checked: X · Checking for updates..." - the layout
    # stays put while a check runs, so only the right-hand half changes.
    # Waybar renders a custom module's tooltip with set_tooltip_markup, so the
    # text is parsed as Pango markup. An unescaped & or < - from a nix error, a
    # package name, an input name - is a parse failure that discards the *whole*
    # tooltip rather than the offending line, and it happens precisely when
    # something has already gone wrong and the tooltip is what you need. Escaped
    # centrally here so that no caller can forget it.
    #
    # The only markup this module emits is the horizontal rule, so callers place
    # a token and it is substituted after escaping.
    TOOLTIP_HR=$'\002'

    function escape_markup() {
        local s="$1"
        # The ampersands are backslash-escaped because bash 5.2 made a bare & in a
        # substitution replacement expand to the matched text (patsub_replacement, on
        # by default), which turned every escape into <lt; rather than &lt;. Escaping
        # & first is also load-bearing: the & this introduces must not be re-escaped.
        s=${s//&/\&amp;}
        s=${s//</\&lt;}
        s=${s//>/\&gt;}
        printf '%s' "$s"
    }

    function output_json() {
        local text="$1" alt="$2" tooltip="$3"
        # Kept for the width measurement below, which has to run on what Pango
        # will draw rather than on what is handed to it: escaping turns one &
        # into the five characters of &amp;, and the rule was sized from the
        # escaped text, so it overhung its content by four characters for every
        # ampersand. Measured at 57 spaces under a 53-character line.
        local raw="$tooltip"
        tooltip=$(escape_markup "$tooltip")
        # The tooltip is interpolated into a JSON string, so a double quote in a
        # nix error or a package name ends that string early and waybar gets
        # malformed JSON. Only the quote is escaped: the body carries literal
        # backslash-n sequences meant to reach waybar as JSON line breaks, and
        # escaping backslashes too would turn them into the characters \ and n.
        tooltip=${tooltip//\"/\\\"}

        if [[ "$tooltip" == *"$TOOLTIP_HR"* ]]; then
            # Width of the widest line, the rule's own line excluded. Counted in
            # characters, which needs a UTF-8 locale to be exact; under a C
            # locale the multi-byte arrows inflate the count and the rule comes
            # out a little long, which is what a fixed width did anyway.
            local width=0 line
            while IFS= read -r line; do
                [[ "$line" == *"$TOOLTIP_HR"* ]] && continue
                [ "${#line}" -gt "$width" ] && width=${#line}
            done < <(printf '%s\n' "${raw//\\n/$'\n'}")
            [ "$width" -gt 0 ] || width=20

            # line_height shortens the rule's own line box and is the only thing
            # that reduces the space above it; rise lifts the stroke and adds
            # space below it only. Full size, not x-small: Pango scales
            # underline thickness with font size, and smaller spaces are
            # narrower than the body characters the width was measured from.
            # line_height needs Pango 1.50+, which rejects unknown attributes
            # rather than ignoring them.
            local spaces
            printf -v spaces '%*s' "$width" ''
            # Single-quoted attributes, which Pango accepts: a double quote would
            # be interpolated into the JSON string below and end it early.
            tooltip=${tooltip//$TOOLTIP_HR/<span line_height=\'0.15\' rise=\'8000\' underline=\'single\'>$spaces</span>}
        fi

        echo "{ \"text\":\"$text\", \"alt\":\"$alt\", \"tooltip\":\"$tooltip\" }"
    }

    function format_tooltip_header() {
        local state="${1:-idle}"
        local last_run
        last_run=$(cat "$LAST_RUN_FILE" 2>/dev/null || echo "0")
        local time_fmt
        if [ "$CLOCK_FORMAT" = "12h" ]; then
            time_fmt="+%I:%M %p"
        else
            time_fmt="+%H:%M"
        fi

        local last_checked next_check
        if [ "$last_run" = "0" ]; then
            last_checked="never"
            next_check="soon"
        else
            last_checked=$(date -d "@$last_run" "$time_fmt")
            next_check=$(date -d "@$((last_run + UPDATE_INTERVAL))" "$time_fmt")
        fi

        case "$state" in
            checking) echo "Last checked: $last_checked · Checking for updates..." ;;
            offline)  echo "Last checked: $last_checked · Offline" ;;
            *)        echo "Last checked: $last_checked · Next check: $next_check" ;;
        esac
    }

    # Renders the "Update cost" tooltip section and reports, via
    # PREVIEW_HAS_STATE, whether there is real state behind it. A bare
    # "middle-click to calculate" affordance must not by itself give a fully
    # updated system a tooltip, so only actual state counts towards showing one.
    # True while the process that recorded a "calculating" preview is still
    # alive. An empty owner means the launcher has written the record but the
    # evaluating process has not claimed it yet - a sub-second window, treated
    # as live.
    function preview_owner_alive() {
        local pid starttime bootid
        read -r pid starttime bootid <<<"$1"

        [ -z "$pid" ] && return 0
        [[ "$pid" =~ ^[0-9]+$ ]] || return 1

        # A record from an earlier boot cannot describe a running process, and
        # its pid/starttime pair can still match a live one: starttime is
        # counted from boot, so both halves repeat every time the machine starts.
        if [ -n "$bootid" ] && \
           [ "$bootid" != "$(cat /proc/sys/kernel/random/boot_id 2>/dev/null)" ]; then
            return 1
        fi

        [ -d "/proc/$pid" ] || return 1

        if [[ "$starttime" =~ ^[0-9]+$ ]]; then
            local live
            live=$(awk '{print $22}' "/proc/$pid/stat" 2>/dev/null)
            [ "$live" = "$starttime" ] || return 1
        fi
        return 0
    }

    PREVIEW_SECTION=""
    PREVIEW_HAS_STATE=false
    function build_preview_section() {
        PREVIEW_SECTION=""
        PREVIEW_HAS_STATE=false

        # Disabled: drop any result so turning the feature off also clears what
        # it left behind, rather than stranding a number with no way to dismiss.
        if [ "$DRY_RUN_PREVIEW" != "true" ]; then
            rm -f "$PREVIEW_FILE"
            return 0
        fi

        if [ ! -f "$PREVIEW_FILE" ]; then
            PREVIEW_SECTION="Update cost:\nmiddle-click to calculate"
            return 0
        fi

        local status="" timestamp="" lock_hash="" system_path="" result_hash="" owner="" reason="" cost=""
        local app_list_hash=""
        local key value
        while IFS='=' read -r key value; do
            case "$key" in
                status)      status="$value" ;;
                timestamp)   timestamp="$value" ;;
                lock_hash)   lock_hash="$value" ;;
                system_path) system_path="$value" ;;
                app_list_hash) app_list_hash="$value" ;;
                result_hash) result_hash="$value" ;;
                owner)       owner="$value" ;;
                reason)      reason="$value" ;;
                cost)        cost="$value" ;;
            esac
        done < "$PREVIEW_FILE"

        PREVIEW_HAS_STATE=true
        local body
        case "$status" in
            calculating)
                # An evaluation that died without recording anything would
                # otherwise leave this reading "calculating..." indefinitely,
                # since nothing else rewrites the record.
                if preview_owner_alive "$owner"; then
                    body="calculating... (~3 min)"
                else
                    body="interrupted — middle-click to retry"
                fi
                ;;
            declined)
                body="check in progress — try again shortly"
                # Cleared on read: the click has been answered, and the message
                # should not outlive the check it refers to.
                rm -f "$PREVIEW_FILE"
                ;;
            failed)
                body="unavailable${reason:+ — $reason}"
                ;;
            done)
                local live_lock live_system
                live_lock=$(sha256sum "$NIXOS_CONFIG_PATH/flake.lock" 2>/dev/null | cut -d' ' -f1)
                live_system=$(readlink -f /run/current-system 2>/dev/null)
                # Inputs first: when both moved, that is the change that governs
                # what a prospective update would cost.
                if [ "$lock_hash" != "$live_lock" ]; then
                    body="inputs changed — middle-click to recalculate"

                elif [ "$result_hash" != "$(cat "$RESULT_HASH_FILE" 2>/dev/null)" ]; then
                    # Upstream moved: the check now finds something different, so a cost
                    # priced against the old upstream no longer holds.
                    body="updates changed — middle-click to recalculate"
                elif [ -n "$app_list_hash" ] && \
                     [ -n "$(cat "$APP_LIST_HASH_FILE" 2>/dev/null)" ] && \
                     [ "$app_list_hash" != "$(cat "$APP_LIST_HASH_FILE" 2>/dev/null)" ]; then
                    # A package was added to or removed from the configuration,
                    # which adds or drops a whole closure from the plan. Both
                    # sides are required to be non-empty: a missing hash means
                    # the extraction has not run or found nothing, which is not
                    # evidence of a change.
                    body="packages changed — middle-click to recalculate"
                else
                    local when=""
                    if [ -n "$timestamp" ] && [ "$timestamp" != "0" ]; then
                        if [ "$CLOCK_FORMAT" = "12h" ]; then
                            when=$(date -d "@$timestamp" "+%I:%M %p" 2>/dev/null)
                        else
                            when=$(date -d "@$timestamp" "+%H:%M" 2>/dev/null)
                        fi
                    fi
                    # A rebuild marks the cost rather than discarding it. The
                    # number is stale by however much the rebuild changed the
                    # closure, which for a config-only rebuild is a few
                    # config-file derivations against a plan of hundreds of paths
                    # - well inside the accuracy already claimed for it. The one
                    # case that bites is a config change adding a package: the
                    # rebuild makes it resident, so the plan shrinks and the
                    # stored figure overestimates. That is the safe direction for
                    # a number already reported as a floor, and cheaper than
                    # throwing away a three-minute evaluation.
                    #
                    # Not a staleness reason, deliberately. recalculateOnChange
                    # ignores system_path, so treating it as one here would leave
                    # a config-only rebuild in a state nothing recovers from
                    # except a click - see maybe_auto_preview.
                    if [ "$system_path" != "$live_system" ]; then
                        when="${when:+$when, }pre-rebuild"
                    fi
                    PREVIEW_SECTION="Update cost${when:+ ($when)}:\n$cost"
                    return 0
                fi
                ;;
            *)
                body="unavailable"
                ;;
        esac

        PREVIEW_SECTION="Update cost:\n$body"
    }

    # Recompute a stale cost preview without being asked, when PREVIEW_AUTO is
    # set.
    #
    # Kept out of build_preview_section on purpose. That function renders, and
    # the tail below reaches it from the grace and no-network branches as well;
    # starting a multi-minute evaluation from a render is the wrong shape, and
    # it would fire from branches where a preview cannot succeed anyway.
    #
    # This only ever refreshes a preview that already exists. Enabling the
    # option never starts the first one - that stays a middle-click - so turning
    # it on cannot commit a machine to an evaluation it has not asked for once.
    function maybe_auto_preview() {
        [ "$PREVIEW_AUTO" = "true" ] || return 0
        [ "$DRY_RUN_PREVIEW" = "true" ] || return 0
        [ -f "$PREVIEW_FILE" ] || return 0

        local status="" lock_hash="" result_hash="" app_list_hash=""
        local key value
        while IFS='=' read -r key value; do
            case "$key" in
                status)        status="$value" ;;
                lock_hash)     lock_hash="$value" ;;
                result_hash)   result_hash="$value" ;;
                app_list_hash) app_list_hash="$value" ;;
            esac
        done < "$PREVIEW_FILE"
        # Anything but a completed preview is either already running or a
        # message about why one did not, and neither is a baseline to refresh.
        # It also stops this re-firing on the poll its own "calculating" record
        # provokes.
        [ "$status" = "done" ] || return 0

        # Every staleness key except system_path, deliberately: a rebuild moves
        # that one, and what to do after a rebuild is already the user's choice.
        # Every afterRebuild option settles into a check whose findings move
        # result_hash anyway, so the cost still refreshes when it genuinely
        # changed, without pricing each rebuild as an event in its own right -
        # which in this mode would mean building the closure again.
        local live_lock live_app_list
        live_lock=$(sha256sum "$NIXOS_CONFIG_PATH/flake.lock" 2>/dev/null | cut -d' ' -f1)
        live_app_list=$(cat "$APP_LIST_HASH_FILE" 2>/dev/null)
        if [ "$lock_hash" = "$live_lock" ] && \
           [ "$result_hash" = "$(cat "$RESULT_HASH_FILE" 2>/dev/null)" ] && \
           { [ -z "$app_list_hash" ] || [ -z "$live_app_list" ] || \
             [ "$app_list_hash" = "$live_app_list" ]; }; then
            return 0
        fi

        # The lock is tested here rather than left to "preview start", which
        # answers a busy lock by recording the "declined" state - and that
        # record is cleared on read, taking the stored preview with it. For a
        # click that is right: the click has been answered. Here it would delete
        # the very baseline this function requires, disabling the option until
        # the next manual click.
        #
        # A check in this mode runs inline and holds the lock on fd 9 until the
        # script exits, so a poll that checked skips here and the recompute
        # lands on a later one. That is the intended order: the check comes
        # first, and its findings are what the new cost is priced against.
        flock -n "$CHECK_LOCK_FILE" true 2>/dev/null || return 0

        preview start >/dev/null 2>&1 || true
    }

    function var_setter() {
        # Ensure updates is a number
        if [ -z "$updates" ]; then
            updates=0
        fi

        local header
        header=$(format_tooltip_header)

        if [ "$updates" -ne 0 ]; then
            alt="has-updates"
            local existing_tooltip
            existing_tooltip=$(cat "$LAST_RUN_TOOLTIP" 2>/dev/null || echo "$updates updates available")
            tooltip="$header\\n${TOOLTIP_HR}\\n$existing_tooltip"
        else
            alt="updated"
            tooltip="$header"
        fi
    }

    # ===== Flake Input Checking =====
    function check_flake_inputs() {
        local flake_lock="$NIXOS_CONFIG_PATH/flake.lock"
        [[ ! -f "$flake_lock" ]] && return 1

        local count=0
        local tooltip=""

        # Check GitHub inputs (unpinned)
        while IFS=$'\t' read -r name owner repo rev ref last_modified; do
            local remote_ref
            [[ "$ref" == "HEAD" ]] && remote_ref="HEAD" || remote_ref="refs/heads/$ref"

            local latest
            latest=$(GIT_TERMINAL_PROMPT=0 GIT_ASKPASS="" git ls-remote \
                "https://github.com/$owner/$repo" "$remote_ref" 2>/dev/null | cut -f1)

            if [[ -n "$latest" && "$latest" != "$rev" ]]; then
                count=$((count + 1))
                local locked_date
                locked_date=$(date -d "@$last_modified" +%Y-%m-%d 2>/dev/null || echo "?")
                [[ -n "$tooltip" ]] && tooltip+="\\n"
                tooltip+="$name (locked: $locked_date)"
            fi
        done < <(jq -r '
            . as $root |
            $root.nodes.root.inputs | to_entries[] |
            select(.value | type == "string") |
            {name: .key, node: $root.nodes[.value]} |
            select(.node.locked.type == "github") |
            select(.node.original.rev == null) |
            [.name, .node.original.owner, .node.original.repo, .node.locked.rev,
             (.node.original.ref // "HEAD"), (.node.locked.lastModified | tostring)] |
            @tsv
        ' "$flake_lock")

        # Check generic git inputs (Bitbucket, GitLab, self-hosted, etc.) - unpinned
        while IFS=$'\t' read -r name url rev ref last_modified; do
            local remote_ref="$ref"
            
            local latest
            latest=$(GIT_TERMINAL_PROMPT=0 GIT_ASKPASS="" git ls-remote \
                "$url" "$remote_ref" 2>/dev/null | cut -f1)

            if [[ -n "$latest" && "$latest" != "$rev" ]]; then
                count=$((count + 1))
                local locked_date
                locked_date=$(date -d "@$last_modified" +%Y-%m-%d 2>/dev/null || echo "?")
                [[ -n "$tooltip" ]] && tooltip+="\\n"
                tooltip+="$name (locked: $locked_date)"
            fi
        done < <(jq -r '
            . as $root |
            $root.nodes.root.inputs | to_entries[] |
            select(.value | type == "string") |
            {name: .key, node: $root.nodes[.value]} |
            select(.node.locked.type == "git") |
            select(.node.original.rev == null) |
            [.name, .node.locked.url, .node.locked.rev,
             (.node.locked.ref // "HEAD"), (.node.locked.lastModified | tostring)] |
            @tsv
        ' "$flake_lock")

        echo "$count" > "$INPUT_STATE_FILE"

        if [ "$count" -eq 0 ]; then
            echo "" > "$INPUT_TOOLTIP_FILE"
        else
            echo "$tooltip" > "$INPUT_TOOLTIP_FILE"
        fi
        
        return 0
    }

    # Check pinned flake inputs
    function check_pinned_inputs() {
        local flake_lock="$NIXOS_CONFIG_PATH/flake.lock"
        [[ ! -f "$flake_lock" ]] && return 1

        local count=0
        local tooltip=""

        # Check pinned GitHub inputs
        while IFS=$'\t' read -r name owner repo rev ref last_modified; do
            local remote_ref
            [[ "$ref" == "HEAD" ]] && remote_ref="HEAD" || remote_ref="refs/heads/$ref"

            local latest
            latest=$(GIT_TERMINAL_PROMPT=0 GIT_ASKPASS="" git ls-remote \
                "https://github.com/$owner/$repo" "$remote_ref" 2>/dev/null | cut -f1)

            if [[ -n "$latest" && "$latest" != "$rev" ]]; then
                count=$((count + 1))
                local locked_date
                locked_date=$(date -d "@$last_modified" +%Y-%m-%d 2>/dev/null || echo "?")
                [[ -n "$tooltip" ]] && tooltip+="\\n"
                tooltip+="$name (pinned: $locked_date)"
            fi
        done < <(jq -r '
            . as $root |
            $root.nodes.root.inputs | to_entries[] |
            select(.value | type == "string") |
            {name: .key, node: $root.nodes[.value]} |
            select(.node.locked.type == "github") |
            select(.node.original.rev != null) |
            [.name, .node.original.owner, .node.original.repo, .node.locked.rev,
             (.node.original.ref // "HEAD"), (.node.locked.lastModified | tostring)] |
            @tsv
        ' "$flake_lock")

        # Check pinned generic git inputs
        while IFS=$'\t' read -r name url rev ref last_modified; do
            local remote_ref="$ref"
            
            local latest
            latest=$(GIT_TERMINAL_PROMPT=0 GIT_ASKPASS="" git ls-remote \
                "$url" "$remote_ref" 2>/dev/null | cut -f1)

            if [[ -n "$latest" && "$latest" != "$rev" ]]; then
                count=$((count + 1))
                local locked_date
                locked_date=$(date -d "@$last_modified" +%Y-%m-%d 2>/dev/null || echo "?")
                [[ -n "$tooltip" ]] && tooltip+="\\n"
                tooltip+="$name (pinned: $locked_date)"
            fi
        done < <(jq -r '
            . as $root |
            $root.nodes.root.inputs | to_entries[] |
            select(.value | type == "string") |
            {name: .key, node: $root.nodes[.value]} |
            select(.node.locked.type == "git") |
            select(.node.original.rev != null) |
            [.name, .node.locked.url, .node.locked.rev,
             (.node.locked.ref // "HEAD"), (.node.locked.lastModified | tostring)] |
            @tsv
        ' "$flake_lock")

        echo "$count" > "$PINNED_STATE_FILE"

        if [ "$count" -eq 0 ]; then
            echo "" > "$PINNED_TOOLTIP_FILE"
        else
            echo "$tooltip" > "$PINNED_TOOLTIP_FILE"
        fi
        
        return 0
    }

    # Reduces nix's stderr to the tooltip line, or two lines when nix said what
    # it was doing. The cause and trace extraction is the same as
    # lightweight-checker's report_eval_failure, because both scripts write the
    # same tooltip and a failure should not read differently depending on which
    # checker happened to produce it. Only the last-resort fallback differs, and
    # the comment on it says why.
    #
    # Replaces three separate heuristics that used to live at the call sites:
    # two took the *first* line indented by exactly seven spaces, one took the
    # last line of stderr whatever it was. The first indented error is nix's
    # outermost frame - the least specific thing it knows - and the bare last
    # line is as often a "For full logs, run ..." hint as it is the cause.
    function nix_error_summary() {
        local raw="$1"
        local clean detail context

        clean=$(sed 's/\x1b\[[0-9;]*m//g' <<<"$raw")

        # nix opens with a bare "error:" and puts the actual cause on a later,
        # indented "error:" line, after the stack trace. Take the last one that
        # has content, which is the most specific; anything else is trace or
        # chatter. Any indent, not seven spaces: nix varies it with nesting
        # depth, and an unindented single-line error is the whole message.
        detail=$(grep -E '^[[:space:]]*error:[[:space:]]*[^[:space:]]' <<<"$clean" \
            | tail -1 \
            | sed 's/^[[:space:]]*error:[[:space:]]*//; s/[[:space:]]*$//' \
            | cut -c1-200)

        # The cause on its own does not say what nix was doing when it hit it.
        # "cannot read file from tarball" is libarchive reporting a truncated
        # channel download, and read alone it looks like a broken configuration
        # rather than a network hiccup worth simply retrying. nix already says
        # which fetch it was, one line up ("... while fetching the input
        # '<url>'"), so carry the nearest trace line preceding the cause.
        #
        # The marker is stripped in awk rather than matched around, because the
        # ellipsis is one thing in nix's output and three dots in a terminal
        # that could not render it - and only what follows is worth showing.
        context=$(awk '
            {
                trimmed = $0
                sub(/^[[:space:]]*/, "", trimmed)
                sub(/^…[[:space:]]*/, "", trimmed)
                sub(/^\.\.\.[[:space:]]*/, "", trimmed)
                sub(/[[:space:]]*$/, "", trimmed)
            }
            trimmed ~ /^while / { trace = trimmed }
            /^[[:space:]]*error:[[:space:]]*[^[:space:]]/ { found = trace }
            END { print found }
        ' <<<"$clean" | cut -c1-200)

        # The whole check is gated on the link being up, but that was minutes
        # and a full build ago. A drop since then explains the failure better
        # than whichever fetch nix happened to be inside when it noticed.
        if ! check_network_connectivity; then
            printf 'no network connection'
            return
        fi

        # Nothing matched, so fall back to the last non-empty line - which is
        # what the flake-update site used to do unconditionally. Kept as the
        # last resort rather than dropped: a nix that fails without ever
        # printing an "error:" line is exactly the case with nothing else left
        # to show, and a fixed label there would discard the only clue there is.
        if [ -z "$detail" ]; then
            detail=$(grep -v '^[[:space:]]*$' <<<"$clean" | tail -1 \
                | sed 's/^[[:space:]]*//; s/[[:space:]]*$//' | cut -c1-200)
        fi
        [ -z "$detail" ] && detail="nix gave no error output"

        # A literal backslash-n: this is read back a line at a time and the
        # tooltip renders the escape itself.
        if [ -n "$context" ]; then
            printf '%s\\n%s' "$context" "$detail"
        else
            printf '%s' "$detail"
        fi
    }

    # ===== Update Check Logic =====
    function check_for_updates() {
        local tempdir=$(mktemp -d)
        # Ensure cleanup happens when script exits
        trap "rm -rf '$tempdir'" EXIT
    
        send_notification "updates-checking" "Checking for Updates" "Please be patient" -e
    
        local updates=0
        local tooltip=""
        local error_output=""

        if [ "$UPDATE_LOCK_FILE" = "true" ]; then
            # Use the config directory directly
            cd "$NIXOS_CONFIG_PATH" || return 1
            nix flake update
            # Capture stderr and extract the error line
            error_output=$(nix build .#nixosConfigurations.$(hostname).config.system.build.toplevel 2>&1)
            if [ "$?" -eq 0 ]; then
                record_pending_from_nvd "$(nvd diff /run/current-system ./result)"
            else
                nix_error_summary "$error_output" > "$LAST_RUN_TOOLTIP"
                return 1
            fi
        else
            # Resolve the updated lock beside the real one rather than copying
            # the tree. --output-lock-file writes only the lock file - tens of
            # kilobytes - where copying the configuration directory meant
            # copying whatever else lives in it, on every check: for the
            # configuration this was measured against, 529MB, 356MB of it a .git
            # directory nix never reads. The configuration and its working tree
            # are untouched either way, which is what this branch is for.
            #
            # The build then evaluates the real flake against that lock via
            # --reference-lock-file, so nothing has to be relocated for it to
            # resolve its own relative paths. This is how `preview` has priced a
            # prospective update since 3.5; the check simply never adopted it.
            local update_err
            if ! update_err=$(nix flake update --flake "$NIXOS_CONFIG_PATH" \
                    --output-lock-file "$tempdir/flake.lock" 2>&1); then
                nix_error_summary "$update_err" > "$LAST_RUN_TOOLTIP"
                return 1
            fi
            # --out-link keeps the result symlink in the temp directory, so the
            # configuration directory does not gain a stray ./result.
            error_output=$(nix build --reference-lock-file "$tempdir/flake.lock" \
                --out-link "$tempdir/result" \
                "$NIXOS_CONFIG_PATH#nixosConfigurations.$(hostname).config.system.build.toplevel" 2>&1)
            if [ "$?" -eq 0 ]; then
                record_pending_from_nvd "$(nvd diff /run/current-system "$tempdir/result")"
            else
                nix_error_summary "$error_output" > "$LAST_RUN_TOOLTIP"
                return 1
            fi
        fi

        # Check flake inputs based on mode
        local pkg_count=$updates
        local input_count=0
        local input_tooltip=""
        local input_count_for_total=0
        if [ "$INPUT_CHECKER_MODE" != "disabled" ]; then
            check_flake_inputs
            input_count=$(cat "$INPUT_STATE_FILE" 2>/dev/null || echo "0")
            input_tooltip=$(cat "$INPUT_TOOLTIP_FILE" 2>/dev/null || echo "")
            if [ "$INPUT_CHECKER_MODE" = "count" ]; then
                input_count_for_total=$input_count
            fi
        fi
        
        # Check pinned inputs based on mode
        local pinned_count=0
        local pinned_tooltip=""
        local pinned_count_for_total=0
        if [ "$INPUT_CHECKER_PINNED" != "disabled" ]; then
            check_pinned_inputs
            pinned_count=$(cat "$PINNED_STATE_FILE" 2>/dev/null || echo "0")
            pinned_tooltip=$(cat "$PINNED_TOOLTIP_FILE" 2>/dev/null || echo "")
            if [ "$INPUT_CHECKER_PINNED" = "count" ]; then
                pinned_count_for_total=$pinned_count
            fi
        fi
        
        local source_count=0
        local source_shown=0
        local source_tooltip=""
        # -1 marks a value that is set but is not a JSON array. It still has to
        # reach source-checker so the problem gets reported - gating on length
        # alone let an empty or malformed value skip the check entirely and read
        # as "nothing configured", indistinguishable from a clean result.
        local source_checks_len
        source_checks_len=$(jq 'if type == "array" then length else -1 end' <<<"$SOURCE_CHECKS_JSON" 2>/dev/null)
        [[ "$source_checks_len" =~ ^-?[0-9]+$ ]] || source_checks_len=-1
        if [ "$source_checks_len" -ne 0 ]; then
            local source_result
            source_result=$(source-checker 2>/dev/null)
            # Fall back to zeroes rather than letting an empty or malformed
            # result propagate into arithmetic and numeric tests below.
            source_count=$(jq -r '.count // 0' <<<"$source_result" 2>/dev/null || echo 0)
            source_shown=$(jq -r '.shown // 0' <<<"$source_result" 2>/dev/null || echo 0)
            source_tooltip=$(jq -r '.tooltip // ""' <<<"$source_result" 2>/dev/null || echo "")
            [[ "$source_count" =~ ^[0-9]+$ ]] || source_count=0
            [[ "$source_shown" =~ ^[0-9]+$ ]] || source_shown=0
            source_tooltip=${source_tooltip//$'\n'/\\n}
        fi
        # Recorded so a rebuild can rebuild the tooltip without reaching the network.
        echo "$source_count" > "$SOURCE_COUNT_FILE"
        echo "$source_shown" > "$SOURCE_SHOWN_FILE"
        echo "$source_tooltip" > "$SOURCE_TOOLTIP_FILE"

        # Calculate total count (only items with mode="count")
        local total_count=$((pkg_count + input_count_for_total + pinned_count_for_total + source_count))

        # Save results
        echo "$total_count" > "$STATE_FILE"
        echo "$(date +%s)" > "$LAST_RUN_FILE"

        # Check if there's anything to show (including "show" mode items)
        local has_items_to_show=false
        [ "$pkg_count" -gt 0 ] && has_items_to_show=true
        [ "$INPUT_CHECKER_MODE" != "disabled" ] && [ "$input_count" -gt 0 ] && has_items_to_show=true
        [ "$INPUT_CHECKER_PINNED" != "disabled" ] && [ "$pinned_count" -gt 0 ] && has_items_to_show=true
        [ "$source_shown" -gt 0 ] && has_items_to_show=true

        if [ "$has_items_to_show" = false ]; then
            echo "System updated" > "$LAST_RUN_TOOLTIP"
            send_notification "updates-complete" "Update Check Complete" "No updates available" -e
        else
            compose_tooltip_body \
                "$pkg_count" "$tooltip" \
                "$input_count" "$input_tooltip" \
                "$pinned_count" "$pinned_tooltip" \
                "$source_shown" "$source_tooltip" > "$LAST_RUN_TOOLTIP"

            if [ "$total_count" -eq 0 ]; then
                send_notification "updates-complete" "Update Check Complete" "No countable updates" -e
            elif [ "$total_count" -eq 1 ]; then
                send_notification "updates-pending" "Update Check Complete" "Found 1 update" -e
            else
                send_notification "updates-pending" "Update Check Complete" "Found $total_count updates" -e
            fi
        fi
    
        write_result_hash
        write_app_list_hash
        return 0
    }

    # Fingerprint of what the last check found. The update-cost preview prices a
    # prospective `nix flake update`, so it goes stale when upstream moves -
    # which changes nothing about flake.lock or the current system, and so is
    # invisible to the preview's other two staleness keys. A change in what the
    # check reports is the observable signal that upstream moved.
    function write_result_hash() {
        sha256sum "$LAST_RUN_TOOLTIP" 2>/dev/null | cut -d' ' -f1 > "$RESULT_HASH_FILE"
    }

    # The packages the configuration declares, as a sorted list. Kept in step
    # with the lightweight checker's copy of the same function - full mode does
    # no config parsing of its own, so this exists here only to fingerprint the
    # declared set for the preview.
    function extract_explicit_packages() {
        local config_dir="$1"
        local filter_pattern='^(done|else|fi|echo|then|in|let|true|false|null|if|with|import|inherit|rec|self|super|builtins|lib|pkgs|config|options|args|inputs|outputs|system|name|value|enable|default|description|type|example|services|programs|environment|systemd|networking|users|boot|hardware|security|nixpkgs|home|fonts|xdg|prev|final|old|new|src|version|meta|license|homepage|maintainers|platforms|broken|sha256|hash|url|owner|repo|rev|fetchurl|fetchgit|fetchFromGitHub|mkDerivation|stdenv|buildInputs|nativeBuildInputs|propagatedBuildInputs|checkInputs|installPhase|buildPhase|configurePhase|postInstall|preInstall|postBuild|preBuild|makeWrapper|wrapProgram|substituteInPlace|patchShebangs|autoPatchelfHook|pkg|drv|result|override|overrideAttrs|callPackage|writeText|writeScript|writeShellScript|runCommand|symlinkJoin|makeDesktopItem|copyDesktopItems|wrapGAppsHook)$'

        {
            # Bare identifiers on their own lines, e.g. "  brave  # comment"
            find "$config_dir" -name "*.nix" -type f -print0 2>/dev/null | \
            xargs -0 grep -hE '^\s*[a-z][a-zA-Z0-9_-]*\s*(#.*)?$' 2>/dev/null | \
            sed 's/#.*//; s/^[[:space:]]*//; s/[[:space:]]*$//'

            # Overlay definitions, e.g. "brave = prev.brave.override"
            find "$config_dir" -name "*.nix" -type f -print0 2>/dev/null | \
            xargs -0 grep -hE '^\s*[a-z][a-zA-Z0-9_-]+\s*=\s*(prev|final|old)\.[a-z]' 2>/dev/null | \
            sed 's/^\s*//; s/\s*=.*//'

            # Package references, e.g. "pkgs.brave" or "pkgs-unstable.yt-dlp"
            find "$config_dir" -name "*.nix" -type f -print0 2>/dev/null | \
            xargs -0 grep -hoE '(pkgs|pkgs-unstable|pkgs-stable)\.[a-z][a-zA-Z0-9_-]+' 2>/dev/null | \
            sed 's/^[^.]*\.//'
        } | \
        grep -v '^\s*$' | \
        grep -vE "$filter_pattern" | \
        sort -u
    }

    # Fingerprint of the packages the configuration declares. This is the key
    # that tells a package being added or removed apart from a setting being
    # changed on one already there - a distinction /run/current-system cannot
    # make, since every rebuild moves it, and nvd cannot make either: it reports
    # added packages for config-generated systemd units and for transitive
    # dependencies pulled in by ordinary upgrades.
    #
    # The extraction is a heuristic and its absolute contents are noisy, which
    # does not matter here: only whether it changed does, and a stable false
    # positive cancels. Roughly half a second over a hundred files, so it runs
    # once per check rather than per render.
    function write_app_list_hash() {
        local list
        list=$(extract_explicit_packages "$NIXOS_CONFIG_PATH" 2>/dev/null)
        # An empty result means the extraction found nothing to look at rather
        # than that the configuration declares nothing. Writing it would read as
        # a change and retire a preview for no reason, so leave the last good
        # value in place.
        [ -n "$list" ] || return 0
        printf '%s\n' "$list" | sha256sum | cut -d' ' -f1 > "$APP_LIST_HASH_FILE"
    }

    # ===== Toggle Function =====
    function toggle_updates() {
        CACHE_DIR="$HOME/.cache"
        TOGGLE_FILE="$CACHE_DIR/nix-update-toggle"
        
        # Initialize toggle file if it doesn't exist (default: enabled)
        if [ ! -f "$TOGGLE_FILE" ]; then
            echo "enabled" > "$TOGGLE_FILE"
        fi
        
        # Get current state
        current_state=$(cat "$TOGGLE_FILE")
        
        # Toggle the state
        if [ "$current_state" = "enabled" ]; then
            echo "disabled" > "$TOGGLE_FILE"
        else
            echo "enabled" > "$TOGGLE_FILE"
        fi
        
        # Send signal to refresh waybar update module
        pkill -x -RTMIN+12 .waybar-wrapped
    }

    # Force a re-check on the next poll. Deliberately keeps the previous count
    # and tooltip so the widget shows the last known result while the check
    # runs, rather than blanking. Matches lightweight-checker's refresh.
    # UPDATING_FLAG is cleared so the two-phase check restarts from phase one.
    # True only while the process running the check is still alive. The check
    # runs inline, so UPDATING_FLAG names a real process: "pending" means phase
    # one has run but the checking poll has not started yet, which is a
    # sub-second window and counts as not running.
    function check_in_progress() {
        [ -f "$UPDATING_FLAG" ] || return 1

        local pid starttime
        read -r pid starttime < "$UPDATING_FLAG" 2>/dev/null || return 1
        [[ "$pid" =~ ^[0-9]+$ ]] || return 1

        # Process gone: the check is over, however it ended.
        [ -d "/proc/$pid" ] || return 1

        # Same pid, different process - only possible after pid wraparound, but
        # cheap to rule out.
        if [[ "$starttime" =~ ^[0-9]+$ ]]; then
            local live
            live=$(awk '{print $22}' "/proc/$pid/stat" 2>/dev/null)
            [ "$live" = "$starttime" ] || return 1
        fi
        return 0
    }

    function refresh_updates() {
        # refresh is dispatched without going through main, so init_files has
        # not run and the cache dir may not exist yet.
        mkdir -p "$CACHE_DIR"

        # A check is already under way. Say so rather than appearing to ignore
        # the click. This tests the checking process itself, so a check that
        # died without clearing the flag is detected at once instead of after
        # some assumed timeout.
        if check_in_progress; then
            send_notification "updates-wait" "Please Wait" \
                "An update check is already running. Wait for it to finish before checking again." -e
            return 0
        fi

        touch "$FORCE_CHECK_FLAG"
        rm -f "$UPDATING_FLAG"
        pkill -x -RTMIN+12 .waybar-wrapped
    }

    # ===== Main Function =====
    function main() {
        init_files

        # Establish the app-list fingerprint before anything can stamp a preview
        # with an empty one. Checks maintain it from here on; this only covers
        # the first poll on a new machine, and costs its half second once.
        [ -s "$APP_LIST_HASH_FILE" ] || write_app_list_hash

        # Check if update checking is disabled via toggle
        if [ -f "$TOGGLE_FILE" ] && [ "$(cat "$TOGGLE_FILE")" = "disabled" ]; then
            # Updates are disabled, show last known state without checking
            local updates=$(cat "$STATE_FILE" 2>/dev/null || echo "0")
            local alt=""
            local tooltip=""
            
            # Read the existing tooltip (which contains the actual update list)
            local existing_tooltip=$(cat "$LAST_RUN_TOOLTIP" 2>/dev/null || "")
            
            # Get last run timestamp and format it
            local last_run=$(cat "$LAST_RUN_FILE" 2>/dev/null || echo "0")
            local last_run_formatted=""
            if [ "$last_run" != "0" ]; then
                last_run_formatted=$(date -d "@$last_run" "+%Y-%m-%d %H:%M")
            else
                last_run_formatted="never"
            fi
            
            if [ "$updates" = "0" ] || [ -z "$updates" ]; then
                alt="disabled"
                tooltip="Updates disabled (Last checked: $last_run_formatted)"
            else
                alt="disabled"
                # Show the original tooltip content with disabled indicator and timestamp
                if [ -n "$existing_tooltip" ] && [ "$existing_tooltip" != "System updated" ]; then
                    # Preserve the original update list with timestamp
                    tooltip="Updates disabled (Last checked: $last_run_formatted)\n${TOOLTIP_HR}\n$existing_tooltip"
                else
                    # Fallback if no proper tooltip exists
                    tooltip="Updates disabled ($updates pending)\nLast checked: $last_run_formatted"
                fi
            fi
            # Output JSON without modifying the tooltip file
            output_json "$updates" "$alt" "$tooltip"
            exit 0
        fi

        # Check if we're in post-boot/resume grace period
        # Skip update check during grace period after boot or resume from hibernation
        # This prevents unnecessary resource usage during system startup or wakeup
        local in_grace=false
        if [ "$SKIP_AFTER_BOOT" = "true" ] && check_boot_resume; then
            in_grace=true
        fi

        local updates=""
        local alt=""
        local tooltip=""
        # Set only on the live-link branch. The tail below is shared with the
        # grace and no-network branches, and neither is a place to start an
        # evaluation that needs the network and has just been skipped for cost.
        local network_up=false

        # Rendering falls through to the shared tail rather than exiting inside
        # the grace branch: the early exit there skipped the update-cost section
        # below for the first minutes after every boot and every resume.
        if [ "$in_grace" = true ]; then
            updates=$(cat "$STATE_FILE" 2>/dev/null || echo "0")
            var_setter
        # Check for network connectivity before proceeding
        elif check_network_connectivity; then
          # The link is up, so clear the once-per-outage latch. Doing it here is
          # what makes the next outage notify again, rather than the first one
          # silencing every outage that follows it.
          rm -f "$NETWORK_DOWN_FLAG"
          network_up=true
          # Auto-detect rebuild via /run/current-system comparison
          local rebuild_handled=false
          if check_system_rebuilt; then
              # Update flake.lock hash now to avoid a spurious input re-check next run
              # (flake.lock may have changed as part of this rebuild e.g. via checkup).
              md5sum "$NIXOS_CONFIG_PATH/flake.lock" 2>/dev/null | cut -d' ' -f1 > "$FLAKE_LOCK_INPUT_HASH_FILE"

              # "reconcile" needs something to reconcile against: a GC'd previous
              # closure means no diff, and no stored package list means nothing
              # to subtract from. Either way it degrades to a real check rather
              # than reporting a number it cannot support.
              local rebuild_mode="$AFTER_REBUILD"
              if [ "$rebuild_mode" = "reconcile" ]; then
                  if [ -z "$REBUILD_NVD_OUT" ] || [ ! -s "$PACKAGES_JSON_FILE" ]; then
                      rebuild_mode="recheck"
                  fi
              fi

              if [ "$rebuild_mode" != "recheck" ]; then
                  # Neither fast path runs a check. "assume-updated" takes the
                  # rebuild as having applied every pending package update and
                  # reports zero; "reconcile" subtracts only the packages nvd
                  # says actually changed and keeps the rest.
                  #
                  # Either way only the package section is decided here. A
                  # rebuild does not resolve stale inputs, pinned inputs or
                  # source drift, so those keep both their counts and their
                  # tooltip sections - rebuilt from cached state, not dropped.
                  local r_input_count=0 r_input_tooltip=""
                  local r_pinned_count=0 r_pinned_tooltip=""
                  local r_source_count=0 r_source_shown=0 r_source_tooltip=""
                  local r_total=0

                  if [ "$INPUT_CHECKER_MODE" != "disabled" ]; then
                      r_input_count=$(cat "$INPUT_STATE_FILE" 2>/dev/null || echo "0")
                      r_input_tooltip=$(cat "$INPUT_TOOLTIP_FILE" 2>/dev/null || echo "")
                      [[ "$r_input_count" =~ ^[0-9]+$ ]] || r_input_count=0
                      [ "$INPUT_CHECKER_MODE" = "count" ] && r_total=$((r_total + r_input_count))
                  fi
                  if [ "$INPUT_CHECKER_PINNED" != "disabled" ]; then
                      r_pinned_count=$(cat "$PINNED_STATE_FILE" 2>/dev/null || echo "0")
                      r_pinned_tooltip=$(cat "$PINNED_TOOLTIP_FILE" 2>/dev/null || echo "")
                      [[ "$r_pinned_count" =~ ^[0-9]+$ ]] || r_pinned_count=0
                      [ "$INPUT_CHECKER_PINNED" = "count" ] && r_total=$((r_total + r_pinned_count))
                  fi
                  r_source_count=$(cat "$SOURCE_COUNT_FILE" 2>/dev/null || echo "0")
                  r_source_shown=$(cat "$SOURCE_SHOWN_FILE" 2>/dev/null || echo "0")
                  r_source_tooltip=$(cat "$SOURCE_TOOLTIP_FILE" 2>/dev/null || echo "")
                  [[ "$r_source_count" =~ ^[0-9]+$ ]] || r_source_count=0
                  [[ "$r_source_shown" =~ ^[0-9]+$ ]] || r_source_shown=0
                  r_total=$((r_total + r_source_count))

                  # The surviving packages, if any. "assume-updated" keeps none
                  # by construction; "reconcile" keeps whatever the rebuild left
                  # untouched, re-rendered from the line stored with each entry.
                  local r_pkg_count=0 r_pkg_tooltip=""
                  if [ "$rebuild_mode" = "reconcile" ]; then
                      local r_remaining
                      r_remaining=$(reconcile_packages \
                          "$(cat "$PACKAGES_JSON_FILE" 2>/dev/null)" "$REBUILD_NVD_OUT")
                      if [ -n "$r_remaining" ]; then
                          printf '%s' "$r_remaining" > "$PACKAGES_JSON_FILE"
                          r_pkg_count=$(jq 'length' <<<"$r_remaining" 2>/dev/null || echo 0)
                          [[ "$r_pkg_count" =~ ^[0-9]+$ ]] || r_pkg_count=0
                          r_pkg_tooltip=$(jq -r '.[] | .line' <<<"$r_remaining" 2>/dev/null \
                              | awk '{printf "%s%s", (NR>1 ? "\\n" : ""), $0}')
                      fi
                      r_total=$((r_total + r_pkg_count))
                  else
                      # Nothing is pending under this setting, so the stored list
                      # must not outlive it and be reconciled against next time.
                      printf '[]' > "$PACKAGES_JSON_FILE"
                  fi

                  local r_body
                  r_body=$(compose_tooltip_body \
                      "$r_pkg_count" "$r_pkg_tooltip" \
                      "$r_input_count" "$r_input_tooltip" \
                      "$r_pinned_count" "$r_pinned_tooltip" \
                      "$r_source_shown" "$r_source_tooltip")

                  echo "$r_total" > "$STATE_FILE"
                  echo "$r_body" > "$LAST_RUN_TOOLTIP"
                  # Stamp LAST_RUN_FILE with "now" so the interval throttle treats the
                  # rebuild as a completed check and skips an immediate (expensive) full
                  # re-check; the next check runs on the normal updateInterval schedule.
                  # This is what makes the setting cheap, and also what makes a wrong
                  # zero persist for an interval - the trade "recheck" exists to avoid.
                  echo "$(date +%s)" > "$LAST_RUN_FILE"

                  updates="$r_total"
                  alt="updated"
                  [ "$r_total" -gt 0 ] && alt="has-updates"
                  # Rendering falls through to the shared tail rather than exiting
                  # here, so the header and the update-cost section are included.
                  tooltip="$(format_tooltip_header)\n${TOOLTIP_HR}\n$r_body"
                  rebuild_handled=true
              else
                  # "recheck": the rebuild may have applied only some of the
                  # pending updates, so the previous result is discarded rather
                  # than replaced with an assumed zero, and the throttle is
                  # cleared so the check runs on this poll.
                  rm -f "$LAST_RUN_FILE"
              fi
          else
              # Auto-detect flake.lock changes for immediate input re-check.
              # Package state is intentionally preserved - system hasn't been rebuilt yet.
              if check_inputs_updated; then
                  rm -f "$LAST_RUN_FILE"
              fi
          fi

          if [ "$rebuild_handled" = false ]; then

              # Read state from files
              updates=$(cat "$STATE_FILE" 2>/dev/null || echo "0")
              local last_run=$(cat "$LAST_RUN_FILE" 2>/dev/null || echo "0")
              local current_time=$(date +%s)

             
              # Decide whether to show saved state or perform new check
              if [ -f "$FORCE_CHECK_FLAG" ] || [ $((current_time - last_run)) -gt "$UPDATE_INTERVAL" ]; then
                  # Separating updating and updated phase
                  if [ -f "$UPDATING_FLAG" ]; then
                      # The check is happening now, so the refresh request has
                      # been honoured. Cleared here rather than after the check
                      # so a failing check does not re-trigger on every poll.
                      rm -f "$FORCE_CHECK_FLAG"
                      # Serialise. UPDATING_FLAG alone does not do this: a poll
                      # landing inside a running check finds the flag present,
                      # takes it as its cue to check, and overwrites the pid with
                      # its own. The lock is what actually keeps one check at a
                      # time, as it does in lightweight mode.
                      #
                      # Held on a file descriptor in this shell rather than a
                      # subshell, because the check runs inline and sets the
                      # variables rendered below; it is released when the script
                      # exits. flock is treated as optional so a manual install
                      # without util-linux still runs, just unserialised - a
                      # missing binary must not mean no check ever runs.
                      local check_locked=true
                      if command -v flock >/dev/null 2>&1; then
                          exec 9>"$CHECK_LOCK_FILE"
                          flock -n 9 || check_locked=false
                      fi

                      if [ "$check_locked" = false ]; then
                          # Another check owns the lock. Report it as in progress
                          # rather than starting a second one, and leave its
                          # UPDATING_FLAG alone - it belongs to that process.
                          updates=$(cat "$STATE_FILE" 2>/dev/null || echo "0")
                          alt="updating"
                          local busy_tooltip=$(cat "$LAST_RUN_TOOLTIP" 2>/dev/null || echo "")
                          local busy_header=$(format_tooltip_header checking)
                          if [ -n "$busy_tooltip" ] && [ "$busy_tooltip" != "System updated" ]; then
                              tooltip="$busy_header\n${TOOLTIP_HR}\n$busy_tooltip"
                          else
                              tooltip="$busy_header"
                          fi
                      else
                      # Claim the flag for this process. The check runs inline,
                      # so this pid is alive for exactly as long as the check
                      # is, which lets refresh test liveness precisely rather
                      # than guessing from elapsed time. starttime pins the
                      # identity so a recycled pid cannot be mistaken for it.
                      echo "$$ $(awk '{print $22}' /proc/$$/stat 2>/dev/null)" > "$UPDATING_FLAG"
                      # Time to check for updates
                      if check_for_updates; then
                          updates=$(cat "$STATE_FILE" 2>/dev/null || echo "0")
                          var_setter
                      else
                          # Update check failed - read the full error from tooltip file.
                          #
                          # Stamped here rather than in check_for_updates, which
                          # writes the timestamp only on its success path and has
                          # four ways to fail. Without it the throttle still sees
                          # the interval as elapsed, and the next poll starts
                          # another doomed build - a retry loop for as long as the
                          # cause persists, which for an unreachable substituter
                          # can be the length of an outage.
                          echo "$(date +%s)" > "$LAST_RUN_FILE"
                          # The count is left alone. A check that failed has
                          # learned nothing about it, and zeroing here would now
                          # persist a wrong "0" for a whole interval rather than
                          # until the next retry.
                          updates=$(cat "$STATE_FILE" 2>/dev/null || echo "0")
                          [ -n "$updates" ] || updates="0"
                          alt="error"
                          tooltip=$(cat "$LAST_RUN_TOOLTIP" 2>/dev/null || echo "Check failed")
                          send_notification "updates-failed" "Update Check Failed" "Check tooltip for detailed error message"
                      fi

                      rm -f "$UPDATING_FLAG"
                      fi
                  else
                      updates=$(cat "$STATE_FILE" 2>/dev/null || echo "0")
                      alt="updating"
                      # Show previous updates while checking for new ones, under
                      # the same header layout as the idle state.
                      local existing_tooltip=$(cat "$LAST_RUN_TOOLTIP" 2>/dev/null || echo "")
                      local header=$(format_tooltip_header checking)
                      if [ -n "$existing_tooltip" ] && [ "$existing_tooltip" != "System updated" ]; then
                          tooltip="$header\n${TOOLTIP_HR}\n$existing_tooltip"
                      else
                          tooltip="$header"
                      fi
                      # The checking process is the next poll, not this one, so
                      # there is no pid to record yet.
                      echo "pending" > "$UPDATING_FLAG"
                      # Rerun same script just to show updating status and
                      # run update process in separate thread
                      refresh_waybar
                  fi
              else
                  # Use saved state
                  send_notification "updates-wait" "Please Wait" "Next update is in $(calc_next_update) min." -e
                  var_setter
              fi
          fi
        else
            updates=$(cat "$STATE_FILE" 2>/dev/null || echo "0")
            if [ -z "$updates" ]; then
                updates="0"
            fi
            alt="updated"
            # The header carries the state now, so the body does not repeat it
            # and keeps showing what is actually pending. The last result is not
            # invalidated by the link being down - the same reasoning the
            # "checking" state uses for holding its previous list. Any update
            # cost is appended by the shared tail below.
            local off_header=$(format_tooltip_header offline)
            local off_existing=$(cat "$LAST_RUN_TOOLTIP" 2>/dev/null || echo "")
            if [ -n "$off_existing" ] && [ "$off_existing" != "System updated" ]; then
                tooltip="$off_header\n${TOOLTIP_HR}\n$off_existing"
            else
                tooltip="$off_header"
            fi
            # Once per outage, not once per poll. This branch is reached on every
            # poll for as long as the link is down, and the notification carries
            # no replace id, so notifying unconditionally stacks a new one every
            # few seconds rather than updating one in place.
            if [ ! -f "$NETWORK_DOWN_FLAG" ]; then
                : > "$NETWORK_DOWN_FLAG"
                send_notification "updates-failed" "Update Check Failed" "Not connected to the internet"
            fi
        fi

        if [ "$network_up" = true ]; then
            maybe_auto_preview
        fi

        # Built here rather than during the check, so a preview requested
        # between checks shows up on the very next poll instead of waiting.
        build_preview_section
        if [ -n "$PREVIEW_SECTION" ]; then
            # The affordance hint alone must not conjure a tooltip for an
            # otherwise up-to-date system; only real preview state earns one.
            if [ -n "$tooltip" ]; then
                tooltip="$tooltip\n\n$PREVIEW_SECTION"
            elif [ "$PREVIEW_HAS_STATE" = true ]; then
                tooltip="$PREVIEW_SECTION"
            fi
        fi

        # Output JSON for Waybar
        output_json "$updates" "$alt" "$tooltip"
    }

    # Error handler to ensure we always output valid JSON
    trap 'echo "{ \"text\":\"?\", \"alt\":\"error\", \"tooltip\":\"Script error occurred\" }" >&2' ERR
    
    # Check for command-line arguments
    case "${1:-}" in
        toggle)  toggle_updates ;;
        refresh) refresh_updates ;;
        preview) shift; preview "${@:-start}" ;;
        *)       main ;;
    esac