#!/bin/bash
# daemons - observe and control the homegrown launchd daemons: activity logs + lifecycle
#
# Usage:
#   daemons append <name> <event> [detail|--detail-stdin]   Append one activity record
#   daemons status [--since T]               Summarize all daemons over a rolling window
#   daemons check                            Health+activity gate (returns nonzero on problem)
#   daemons log [name|--all] [--follow]      Render the log (human-readable)
#   daemons query [name|--all] [--event E] [--since T] [--jq EXPR]   Filter/extract JSONL records
#   daemons load <name> [--plist PATH] [--dry-run]   Bootstrap (reload) a daemon into launchd; logs a load record
#   daemons unload <name> [--dry-run]        Bootout a daemon from launchd; logs an unload record
#   daemons registry [--edit|--open]         Print the registry path, or open it (--edit: $VISUAL/$EDITOR, --open: macOS open)
#   daemons -h | --help
#
# Environment:
#   DAEMONS_LOG_DIR   Directory of <name>.log files (default: $XDG_STATE_HOME/daemons or ~/.local/state/daemons)
#   DAEMONS_REGISTRY  Registry TSV (default: $XDG_CONFIG_HOME/daemons/daemons.tsv or ~/.config/daemons/daemons.tsv)

PATH="/opt/homebrew/bin:/usr/local/bin:$PATH" # LaunchDaemons get a minimal PATH; need jq

_daemons() (
    local SCRIPT_NAME="${BASH_SOURCE[0]##*/}"
    case "${BASH_SOURCE[0]}" in /dev/*|/proc/*) SCRIPT_NAME="" ;; esac
    case "$SCRIPT_NAME" in ""|bash|sh|zsh|dash) SCRIPT_NAME="daemons" ;; esac

    local LOG_DIR="${DAEMONS_LOG_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/daemons}"
    local REGISTRY="${DAEMONS_REGISTRY:-${XDG_CONFIG_HOME:-$HOME/.config}/daemons/daemons.tsv}"
    local DEFAULT_STATUS_WINDOW="24h"
    local REGISTRY_NONE="-"
    local SECONDS_PER_MINUTE=60
    local SECONDS_PER_HOUR=3600
    local SECONDS_PER_DAY=86400

    _error() { echo "[ERR][$SCRIPT_NAME] $*" >&2; }
    _dry() { printf '[DRY][%s] %s\n' "$SCRIPT_NAME" "$*"; }

    _shell_join() {
        local out=""
        local arg
        local quoted
        for arg in "$@"; do
            printf -v quoted '%q' "$arg"
            if [ -n "$out" ]; then out="$out "; fi
            out="$out$quoted"
        done
        printf '%s' "$out"
    }

    _dry_command() {
        local command; command="$(_shell_join "$@")"
        _dry "Would run: $command"
    }

    _expand_short_opts() {
        # $1 = string of short-opt letters that take a value (e.g. "nXHd"); "" for flag-only scripts
        # $2..$N = "$@"
        # Populates _EXPANDED; caller does: set -- "${_EXPANDED[@]}"; unset _EXPANDED
        local value_opts="$1"; shift
        _EXPANDED=()
        local passthru=""
        local arg
        local rest
        local c
        for arg in "$@"; do
            if [ -n "$passthru" ]; then _EXPANDED+=("$arg"); continue; fi
            case "$arg" in
                --)       passthru=1; _EXPANDED+=("$arg") ;;
                --*|-|"") _EXPANDED+=("$arg") ;;
                -[a-zA-Z]?*)
                    rest="${arg#-}"
                    while [ -n "$rest" ]; do
                        c="${rest%"${rest#?}"}"; rest="${rest#?}"
                        _EXPANDED+=("-$c")
                        case "$value_opts" in *"$c"*)
                            [ -n "$rest" ] && _EXPANDED+=("$rest")
                            rest="" ;;
                        esac
                    done ;;
                *)        _EXPANDED+=("$arg") ;;
            esac
        done
    }

    _show_help() {
        local s=""
        local r=""
        if { [ -t 1 ] || [ -n "${CLICOLOR_FORCE:-}" ]; } && [ -z "${NO_COLOR:-}" ]; then
            s=$'\033[4m'
            r=$'\033[24m'
        fi
        cat <<EOF
NAME
  $SCRIPT_NAME - observe and control the homegrown launchd daemons
SYNOPSIS
  $SCRIPT_NAME append <${s}name${r}> <${s}event${r}> [${s}detail${r}|--detail-stdin]
  $SCRIPT_NAME status [--since ${s}T${r}]
  $SCRIPT_NAME check
  $SCRIPT_NAME log [${s}name${r}|--all] [--follow]
  $SCRIPT_NAME query [${s}name${r}|--all] [--event ${s}E${r}] [--since ${s}T${r}] [--jq ${s}EXPR${r}]
  $SCRIPT_NAME load <${s}name${r}> [--plist ${s}PATH${r}] [--dry-run]
  $SCRIPT_NAME unload <${s}name${r}> [--dry-run]
  $SCRIPT_NAME registry [--edit|--open]
DESCRIPTION
  Writes and reads per-daemon activity logs (JSONL) under \$DAEMONS_LOG_DIR.
  Each record is {ts, daemon, event, detail}; event is trigger|noop|change|error|load|unload.
  'append' is the write path daemons call; 'status'/'check'/'log'/'query' read;
  'load'/'unload' control launchd and log their own record; 'registry' reveals the registry.
SUBCOMMANDS
  append   Append one activity record (creates the log dir on first write). Pass --detail-stdin in place of [detail] to read the detail from stdin
  status   Per-daemon summary: loaded state, last activity, rolling event counts, and expected-silence health
  check    Health+activity gate; nonzero + loud alerts on any problem
  log      Render one log human-readably, or merge all logs; optionally follow new records
  query    Filter structured JSONL records by daemon, event, or time, then optionally reshape them with jq
  load     Bootstrap a daemon into launchd (bootout-then-bootstrap, so it also reloads). Resolves the plist by --plist > registry column > convention, then verifies it exists. A system/ target elevates via sudo when not root. Logs a 'load' record
  unload   Bootout a daemon from launchd (idempotent; "already unloaded" is not an error). Logs an 'unload' record
  registry Print the resolved \$DAEMONS_REGISTRY path; --edit opens it in \$VISUAL/\$EDITOR (default vi), --open uses macOS open. --edit and --open are mutually exclusive
STATUS OPTIONS
  -s, --since T  Count activity since T (default: $DEFAULT_STATUS_WINDOW)
LOG OPTIONS
  -a, --all       Merge every daemon log instead of selecting one
  -f, --follow    Follow new records like tail -f
QUERY OPTIONS
  -a, --all       Query every daemon log instead of selecting one
  -e, --event E   Keep only event E
  -s, --since T   Keep records at or after T; no time filter by default
  -j, --jq EXPR   Apply EXPR to each matching JSON record
  T accepts NNN[smhd] (e.g. 1h, 30m, 7d), YYYY-MM-DD (midnight UTC), or YYYY-MM-DDTHH:MM:SSZ
LOAD AND UNLOAD OPTIONS
  -n, --dry-run   Print the launchctl commands without running them
  --plist PATH    Use PATH instead of the registry or conventional plist path (load only)
REGISTRY OPTIONS
  --edit           Open the registry in \$VISUAL or \$EDITOR
  --open           Open the registry with macOS open
ENVIRONMENT
  DAEMONS_LOG_DIR   Directory of <name>.log files (default: \$XDG_STATE_HOME/daemons or ~/.local/state/daemons)
  DAEMONS_REGISTRY  Registry TSV (default: \$XDG_CONFIG_HOME/daemons/daemons.tsv or ~/.config/daemons/daemons.tsv)
FILES
  \$DAEMONS_REGISTRY  Whitespace-separated table that 'status', 'check', 'load',
                     and 'unload' read, and 'registry' prints (append/log/query
                     don't need it). A header row, then one
                     row per daemon with four required columns and two optional columns:
                       name    log name; matches the <name> passed to append
                       domain  launchd domain: gui/\$UID/ (per-user agent; \$UID
                               is replaced with your numeric uid) or system/
                       label   launchd label; state read via launchctl print <domain><label>
                       script  path to the daemon's script; check flags it if missing
                       plist   (optional) path to the daemon's plist for 'load'; when
                               absent, load derives it: gui/\$UID/ -> ~/Library/LaunchAgents/<label>.plist,
                               system/ -> /Library/LaunchDaemons/<label>.plist
                       max_silence  (optional) maximum time between trigger records as
                                    NNN[smhd]; status marks a loaded daemon overdue and
                                    check fails when the limit is exceeded. Use - for no
                                    limit, or as a plist placeholder when setting this field
                     Example:
                       name      domain     label                 script                   plist  max_silence
                       periodic  gui/\$UID/  com.example.periodic  /usr/local/bin/periodic  -      15m
DEPENDENCIES
  jq, launchctl
  sudo (required only for load/unload of a system/ daemon when not root)
EXIT STATUS
  0  Success
  1  Runtime failure (missing plist, launchctl bootstrap/bootout failed, registry file absent, editor or open exited nonzero)
  2  Usage error (unknown/missing subcommand or option)
  3  jq not installed
EOF
    }

    case "${1:-}" in
        -h|--help) _show_help; return 0 ;;
    esac
    if ! command -v jq >/dev/null 2>&1; then _error "jq is required"; return 3; fi

    # Convert an NNN[smhd] relative duration to seconds
    _duration_to_seconds() {
        local duration="$1"
        local amount="${duration%?}"
        local unit="${duration#"$amount"}"
        local multiplier
        case "$amount" in
            ''|*[!0-9]*) return 1 ;;
        esac
        case "$unit" in
            s) multiplier=1 ;;
            m) multiplier=$SECONDS_PER_MINUTE ;;
            h) multiplier=$SECONDS_PER_HOUR ;;
            d) multiplier=$SECONDS_PER_DAY ;;
            *) return 1 ;;
        esac
        amount=$((10#$amount))
        printf '%s\n' "$((amount * multiplier))"
    }

    # Echo registry rows as six tab-separated fields, using - for absent optionals
    # Skips the header row and blank lines
    # Errors (return 1) if the registry file is absent
    _read_registry() {
        if [ ! -f "$REGISTRY" ]; then
            _error "registry not found: $REGISTRY"
            return 1
        fi
        # Skip the first row and blanks; split each daemon row on whitespace runs
        local uid="$UID"
        local first_row=true
        local row
        while IFS= read -r row || [ -n "$row" ]; do
            if [ "$first_row" = true ]; then
                first_row=false
                continue
            fi
            [ -n "$row" ] || continue
            # Split on whitespace runs; script and plist paths are space-free
            local name
            local domain
            local label
            local script
            local plist
            local max_silence
            local max_silence_seconds
            read -r name domain label script plist max_silence <<< "$row"
            [ -n "$name" ] || continue
            [ -n "$plist" ] || plist="$REGISTRY_NONE"
            [ -n "$max_silence" ] || max_silence="$REGISTRY_NONE"
            if [ "$max_silence" != "$REGISTRY_NONE" ]; then
                if ! max_silence_seconds="$(_duration_to_seconds "$max_silence")" || [ "$max_silence_seconds" -le 0 ]; then
                    _error "Invalid max_silence '$max_silence' for '$name' (valid: positive NNN[smhd] or -)"
                    return 1
                fi
            fi
            # Substitute $UID token in the domain
            domain="${domain//\$UID/$uid}"
            printf '%s\t%s\t%s\t%s\t%s\t%s\n' "$name" "$domain" "$label" "$script" "$plist" "$max_silence"
        done < "$REGISTRY"
    }

    # Echo `launchctl print <domain><label>` text; return nonzero if not loaded
    _launchd_state() {
        launchctl print "$1$2" 2>/dev/null
    }

    # Loud alert line (bold + red), to stdout so the login shell shows it inline
    _alert() {
        local b
        local red
        local rst
        if [ -t 1 ]; then b=$'\033[1m'; red=$'\033[31m'; rst=$'\033[0m'; fi
        printf '%s%s[daemons] %s%s\n' "$b" "$red" "$*" "$rst"
    }

    # Print the newest trigger's timestamp and epoch as tab-separated fields
    # BSD tail makes the healthy path independent of the append-only log size
    _latest_trigger() {
        local logf="$1"
        local trigger
        if trigger="$(
            tail -r "$logf" 2>/dev/null \
                | jq -Rnr 'first(inputs | fromjson | select(.event == "trigger") | [.ts, (.ts | fromdateiso8601)] | @tsv)' 2>/dev/null
            pipeline_status=("${PIPESTATUS[@]}")
            [ "${pipeline_status[1]}" -eq 0 ] || exit 1
            # tail receives SIGPIPE after jq finds the trigger and stops reading
            [ "${pipeline_status[0]}" -eq 0 ] || [ "${pipeline_status[0]}" -eq 141 ] || exit 1
        )"; then
            printf '%s\n' "$trigger"
            return 0
        fi
        # Portable fallback also distinguishes an unreadable log from no trigger
        jq -nr '
            reduce inputs as $record (null;
                if $record.event == "trigger" then $record else . end)
            | select(. != null)
            | [.ts, (.ts | fromdateiso8601)]
            | @tsv
        ' "$logf" 2>/dev/null
    }

    _do_check() {
        local rows; rows="$(_read_registry)" || return 1
        local problems=0
        local now_epoch=""
        while IFS=$'\t' read -r name domain label script _ max_silence; do
            [ -n "$name" ] || continue
            local state
            if ! state="$(_launchd_state "$domain" "$label")"; then
                _alert "$label not loaded in launchd!"
                problems=1
                continue
            fi
            if [ -n "$script" ] && [ ! -f "$script" ]; then
                _alert "$label points at a missing script ($script) -- re-run its install"
                problems=1
                continue
            fi
            # launchd reports a non-numeric marker before a service first exits
            local last_exit=""
            local state_line
            while IFS= read -r state_line; do
                case "$state_line" in
                    *'last exit code = '*)
                        last_exit="${state_line#*last exit code = }"
                        break
                        ;;
                esac
            done <<< "$state"
            case "$last_exit" in
                ''|0) ;;
                *[!0-9]*) ;;
                *) _alert "$label last run failed (exit $last_exit)"; problems=1 ;;
            esac
            if [ "$max_silence" != "$REGISTRY_NONE" ]; then
                local last_trigger=""
                local last_trigger_epoch=""
                local trigger
                local logf="$LOG_DIR/$name.log"
                if [ -e "$logf" ]; then
                    if ! trigger="$(_latest_trigger "$logf")"; then
                        _alert "$label activity log is unreadable ($logf)"
                        problems=1
                        continue
                    fi
                    IFS=$'\t' read -r last_trigger last_trigger_epoch <<< "$trigger"
                fi
                if [ -z "$last_trigger" ]; then
                    _alert "$label has never fired (silence limit $max_silence)"
                    problems=1
                    continue
                fi
                local max_silence_seconds; max_silence_seconds="$(_duration_to_seconds "$max_silence")" || return 1
                if [ -z "$now_epoch" ]; then
                    now_epoch="$(date '+%s')" || return 1
                fi
                if [ "$last_trigger_epoch" -lt "$((now_epoch - max_silence_seconds))" ]; then
                    _alert "$label has not fired within its $max_silence silence limit (last trigger $last_trigger)"
                    problems=1
                fi
            fi
        done <<< "$rows"
        [ "$problems" = 0 ]
    }

    if [ "${1:-}" = check ]; then
        shift
        _do_check "$@"
        return $?
    fi

    _do_append() {
        local name="${1:-}"
        local event="${2:-}"
        if [ -z "$name" ] || [ -z "$event" ]; then
            _error "append requires <name> and <event>. Run \`$SCRIPT_NAME -h\` for usage"
            return 2
        fi
        case "$event" in
            trigger|noop|change|error|load|unload) ;;
            *) _error "Invalid event '$event' (valid: trigger|noop|change|error|load|unload). Run \`$SCRIPT_NAME -h\` for usage"; return 2 ;;
        esac
        local detail
        if [ "${3:-}" = "--detail-stdin" ]; then
            detail="$(cat)"
        else
            detail="${3:-}"
        fi
        mkdir -p "$LOG_DIR" || { _error "cannot create $LOG_DIR"; return 1; }
        _compose_record "$name" "$event" "$detail" >> "$LOG_DIR/$name.log" \
            || { _error "failed to write log record"; return 1; }
    }

    # Echo the log file path(s) for a name, or all logs for --all. No error if absent
    _log_files_for() {
        local target="${1:-}"
        if [ "$target" = "--all" ] || [ -z "$target" ]; then
            # All *.log in LOG_DIR (may be none)
            local f
            for f in "$LOG_DIR"/*.log; do [ -e "$f" ] && printf '%s\n' "$f"; done
        else
            [ -e "$LOG_DIR/$target.log" ] && printf '%s\n' "$LOG_DIR/$target.log"
        fi
    }

    # Normalize --since into an ISO-8601 UTC timestamp
    _since_to_ts() {
        local t="$1"
        local secs
        case "$t" in
            [0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]) printf '%sT00:00:00Z\n' "$t" ;;
            [0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]T[0-9][0-9]:[0-9][0-9]:[0-9][0-9]Z) printf '%s\n' "$t" ;;
            *)
                secs="$(_duration_to_seconds "$t")" || return 1
                TZ=Etc/UTC date -v-"${secs}"S '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null \
                    || TZ=Etc/UTC date -u -d "-${secs} seconds" '+%Y-%m-%dT%H:%M:%SZ' ;;
        esac
    }

    _since_label() {
        if _duration_to_seconds "$1" >/dev/null 2>&1; then
            printf '%s\n' "$1"
        else
            printf 'since %s\n' "$1"
        fi
    }

    _trigger_is_overdue() {
        local last_trigger="$1"
        local max_silence="$2"
        local cutoff
        cutoff="$(_since_to_ts "$max_silence")" || return 2
        [ -z "$last_trigger" ] && return 0
        [ "$last_trigger" \< "$cutoff" ]
    }

    _do_query() {
        local target=""
        local event=""
        local since=""
        local jqexpr="."
        # -e/-s/-j take values; -a is a flag (kept out of the value-opts string)
        _expand_short_opts "esj" "$@"
        set -- "${_EXPANDED[@]}"; unset _EXPANDED
        while [ $# -gt 0 ]; do
            case "$1" in
                -a|--all) target="--all"; shift ;;
                -e|--event) [ $# -ge 2 ] || { _error "--event requires a value. Run \`$SCRIPT_NAME -h\` for usage"; return 2; }; event="$2"; shift 2 ;;
                --event=*) event="${1#*=}"; shift ;;
                -s|--since) [ $# -ge 2 ] || { _error "--since requires a value. Run \`$SCRIPT_NAME -h\` for usage"; return 2; }; since="$2"; shift 2 ;;
                --since=*) since="${1#*=}"; shift ;;
                -j|--jq) [ $# -ge 2 ] || { _error "--jq requires a value. Run \`$SCRIPT_NAME -h\` for usage"; return 2; }; jqexpr="$2"; shift 2 ;;
                --jq=*) jqexpr="${1#*=}"; [ -n "$jqexpr" ] || { _error "--jq requires a value. Run \`$SCRIPT_NAME -h\` for usage"; return 2; }; shift ;;
                -*) _error "Unknown argument '$1'. Run \`$SCRIPT_NAME -h\` for usage"; return 2 ;;
                *) target="$1"; shift ;;
            esac
        done
        local since_ts=""
        if [ -n "$since" ] && ! since_ts="$(_since_to_ts "$since")"; then
            _error "Invalid --since '$since' (valid: NNN[smhd], YYYY-MM-DD, or YYYY-MM-DDTHH:MM:SSZ). Run \`$SCRIPT_NAME -h\` for usage"
            return 2
        fi
        local files; files="$(_log_files_for "$target")"
        [ -z "$files" ] && return 0
        # Filter each record: event match (if set), ts >= since (if set), then apply jqexpr
        printf '%s\n' "$files" | while IFS= read -r f; do
            [ -n "$f" ] || continue
            jq -c \
                --arg event "$event" --arg since "$since_ts" \
                'select(($event=="" or .event==$event) and ($since=="" or .ts>=$since))' "$f"
        done | { [ "$jqexpr" = "." ] && cat || jq "$jqexpr"; }
    }

    # Render JSONL from stdin: one header line per record + indented extra detail lines
    _render_records() {
        jq -r '
            "\(.ts) \(.daemon) \(.event|ascii_upcase) \(.detail | split("\n")[0] // "")",
            (.detail | split("\n")[1:][] | "  " + .)
        '
    }

    # Compose one JSONL activity record on stdout (does NOT write it). Timestamps
    # at call time. detail is read raw so embedded newlines/quotes/tabs survive.
    # Returns jq's status so a caller can detect a compose failure
    # $1=name $2=event $3=detail
    _compose_record() {
        local ts; ts="$(TZ=Etc/UTC date '+%Y-%m-%dT%H:%M:%SZ')"
        jq -cn --arg ts "$ts" --arg daemon "$1" --arg event "$2" \
            --rawfile detail <(printf '%s' "$3") \
            '{ts:$ts, daemon:$daemon, event:$event, detail:($detail)}'
    }

    # Echo the matching registry row's six normalized fields
    # for a daemon name. Propagates _read_registry's status: registry file absent
    # is a runtime error (1, matching status/check); a present file with no matching
    # row is a usage error (2). Shared by load and unload
    _registry_row_for() {
        local want="$1"
        local rows
        local rc
        rows="$(_read_registry)"; rc=$?
        [ "$rc" -eq 0 ] || return "$rc"
        local match
        match="$(printf '%s\n' "$rows" | while IFS=$'\t' read -r name domain label script plist max_silence; do
            [ "$name" = "$want" ] && printf '%s\t%s\t%s\t%s\t%s\t%s\n' "$name" "$domain" "$label" "$script" "$plist" "$max_silence"
        done)"
        if [ -z "$match" ]; then
            _error "no daemon named '$want' in the registry. Run \`$SCRIPT_NAME -h\` for usage"
            return 2
        fi
        printf '%s\n' "$match"
    }

    # Echo the two launchctl target forms for a daemon, one per line:
    #   line 1: domain-target  (for bootstrap)  e.g. gui/501  or  system
    #   line 2: service-target (for bootout)    e.g. gui/501/usr.foo
    # $1 = domain (trailing slash, $UID already substituted), $2 = label
    _launchd_targets() {
        printf '%s\n' "${1%/}"
        printf '%s\n' "$1$2"
    }

    # Resolve a daemon's plist path by precedence: --plist flag > TSV column >
    # derive-by-convention (domain picks the dir, label picks the filename).
    # Tilde-expands a leading ~/ (registry values are literal text). Prints the
    # path; does not check existence (caller verifies and owns the error)
    # $1=domain $2=label $3=tsv_plist(may be empty) $4=flag_plist(may be empty)
    _resolve_plist() {
        local domain="$1"
        local label="$2"
        local tsv_plist="$3"
        local flag_plist="$4"
        local p=""
        [ "$tsv_plist" = "$REGISTRY_NONE" ] && tsv_plist=""
        if [ -n "$flag_plist" ]; then
            p="$flag_plist"
        elif [ -n "$tsv_plist" ]; then
            p="$tsv_plist"
        else
            case "$domain" in
                system*) p="/Library/LaunchDaemons/$label.plist" ;;
                *)       p="$HOME/Library/LaunchAgents/$label.plist" ;;
            esac
        fi
        case "$p" in
            "~/"*) p="$HOME/${p#\~/}" ;;
        esac
        printf '%s\n' "$p"
    }

    # Best-effort lifecycle-record append. Composes the JSON as the invoking user
    # (so $LOG_DIR is resolved before any elevation), then appends -- via `sudo
    # tee` when needs_root=1 (the elevated system/ case, where the log is
    # root-owned), else a plain append. Never returns nonzero: a logging failure
    # must not change load/unload's exit status
    # $1=name $2=event $3=detail $4=needs_root(1|"")
    _append_lifecycle() {
        local name="$1"
        local event="$2"
        local detail="$3"
        local needs_root="$4"
        local record
        record="$(_compose_record "$name" "$event" "$detail" 2>/dev/null)" || return 0
        mkdir -p "$LOG_DIR" 2>/dev/null || :
        if [ "$needs_root" = 1 ]; then
            printf '%s\n' "$record" | sudo tee -a "$LOG_DIR/$name.log" >/dev/null 2>&1 || :
        else
            # Wrap so stderr suppression covers the redirect open itself: a bare
            # `>> file 2>/dev/null` still lets the shell report an open failure
            # (e.g. unwritable LOG_DIR) before 2>/dev/null applies
            { printf '%s\n' "$record" >> "$LOG_DIR/$name.log"; } 2>/dev/null || :
        fi
        return 0
    }

    _do_status() {
        local since="$DEFAULT_STATUS_WINDOW"
        _expand_short_opts "s" "$@"
        set -- "${_EXPANDED[@]}"; unset _EXPANDED
        while [ $# -gt 0 ]; do
            case "$1" in
                -s|--since) [ $# -ge 2 ] || { _error "--since requires a value. Run \`$SCRIPT_NAME -h\` for usage"; return 2; }; since="$2"; shift 2 ;;
                --since=*) since="${1#*=}"; [ -n "$since" ] || { _error "--since requires a value. Run \`$SCRIPT_NAME -h\` for usage"; return 2; }; shift ;;
                *) _error "Unknown argument '$1'. Run \`$SCRIPT_NAME -h\` for usage"; return 2 ;;
            esac
        done
        local since_ts
        if ! since_ts="$(_since_to_ts "$since")"; then
            _error "Invalid --since '$since' (valid: NNN[smhd], YYYY-MM-DD, or YYYY-MM-DDTHH:MM:SSZ). Run \`$SCRIPT_NAME -h\` for usage"
            return 2
        fi
        local since_label
        since_label="$(_since_label "$since")"
        local rows
        rows="$(_read_registry)" || return 1
        printf '%s\n' "$rows" | while IFS=$'\t' read -r name domain label script plist max_silence; do
            [ -n "$name" ] || continue
            local loaded="loaded"
            _launchd_state "$domain" "$label" >/dev/null || loaded="NOT LOADED"
            local logf="$LOG_DIR/$name.log"
            local last_ts=""
            local last_ev=""
            local n_runs=0
            local n_change=0
            local n_err=0
            local last_trigger=""
            if [ -e "$logf" ]; then
                local summary
                if ! summary="$(jq -rs --arg since "$since_ts" '
                    [
                        (last | .ts // ""),
                        (last | .event // ""),
                        ([.[] | select((.ts // "") >= $since and .event == "trigger")] | length),
                        ([.[] | select((.ts // "") >= $since and .event == "change")] | length),
                        ([.[] | select((.ts // "") >= $since and .event == "error")] | length),
                        ([.[] | select(.event == "trigger")] | last | .ts // "")
                    ] | @tsv
                ' "$logf" 2>/dev/null)"; then
                    _error "Failed to read activity log: $logf"
                    return 1
                fi
                IFS=$'\t' read -r last_ts last_ev n_runs n_change n_err last_trigger <<< "$summary"
            fi
            local run_word="runs"
            local change_word="changes"
            local error_word="errors"
            [ "$n_runs" = 1 ] && run_word="run"
            [ "$n_change" = 1 ] && change_word="change"
            [ "$n_err" = 1 ] && error_word="error"
            local activity="never fired"
            [ -n "$last_ts" ] && activity="last $last_ev @ $last_ts"
            activity="$activity | $since_label: $n_runs $run_word, $n_change $change_word, $n_err $error_word"
            if [ "$loaded" = "loaded" ] && [ "$max_silence" != "$REGISTRY_NONE" ]; then
                if [ -z "$last_trigger" ]; then
                    activity="$activity | silence: NEVER OBSERVED (limit $max_silence)"
                elif _trigger_is_overdue "$last_trigger" "$max_silence"; then
                    activity="$activity | silence: OVERDUE (limit $max_silence)"
                else
                    activity="$activity | silence: OK (limit $max_silence)"
                fi
            fi
            printf '%-24s %-11s %s\n' "$name" "$loaded" "$activity"
        done
    }

    _do_load() {
        local target=""
        local flag_plist=""
        local dry=""
        _expand_short_opts "" "$@"
        set -- "${_EXPANDED[@]}"; unset _EXPANDED
        while [ $# -gt 0 ]; do
            case "$1" in
                -n|--dry-run) dry=1; shift ;;
                --plist) [ -n "${2-}" ] || { _error "--plist requires a value. Run \`$SCRIPT_NAME -h\` for usage"; return 2; }; flag_plist="$2"; shift 2 ;;
                --plist=*) flag_plist="${1#*=}"; [ -n "$flag_plist" ] || { _error "--plist requires a value. Run \`$SCRIPT_NAME -h\` for usage"; return 2; }; shift ;;
                -*) _error "Unknown argument '$1'. Run \`$SCRIPT_NAME -h\` for usage"; return 2 ;;
                *)
                    if [ -n "$target" ]; then
                        _error "Multiple daemon names not allowed (already set to '$target'). Run \`$SCRIPT_NAME -h\` for usage"
                        return 2
                    fi
                    target="$1"; shift ;;
            esac
        done
        [ -n "$target" ] || { _error "Must provide a daemon name. Run \`$SCRIPT_NAME -h\` for usage"; return 2; }

        local row
        local rc
        row="$(_registry_row_for "$target")"; rc=$?
        [ "$rc" -eq 0 ] || return "$rc"
        local name
        local domain
        local label
        local script
        local tsv_plist
        local max_silence
        IFS=$'\t' read -r name domain label script tsv_plist max_silence <<< "$row"

        local plist; plist="$(_resolve_plist "$domain" "$label" "$tsv_plist" "$flag_plist")"
        if [ ! -f "$plist" ]; then
            _error "no plist at $plist -- pass --plist <path> if it lives elsewhere"
            return 1
        fi

        local dtgt
        local stgt
        { read -r dtgt; read -r stgt; } <<< "$(_launchd_targets "$domain" "$label")"

        # system/ target needs root: elevate just the launchctl (and the record append)
        local needs_root=""
        local sudo_pfx=""
        case "$domain" in
            system*) [ "$(id -u)" -ne 0 ] && { needs_root=1; sudo_pfx="sudo "; } ;;
        esac

        if [ -n "$dry" ]; then
            _dry "Would use plist: '$plist'"
            if [ -n "$needs_root" ]; then
                _dry_command sudo launchctl bootout "$stgt"
                _dry_command sudo launchctl bootstrap "$dtgt" "$plist"
            else
                _dry_command launchctl bootout "$stgt"
                _dry_command launchctl bootstrap "$dtgt" "$plist"
            fi
            return 0
        fi

        # Reload: bootout first (ignore "not loaded"), then bootstrap
        # shellcheck disable=SC2086 # "Double quote to prevent globbing and word splitting." -- $sudo_pfx is "sudo " or empty; the split into a separate argv word is intentional
        ${sudo_pfx}launchctl bootout "$stgt" 2>/dev/null || :
        # shellcheck disable=SC2086 # "Double quote to prevent globbing and word splitting." -- $sudo_pfx is "sudo " or empty; the split into a separate argv word is intentional
        if ! ${sudo_pfx}launchctl bootstrap "$dtgt" "$plist"; then
            _error "launchctl bootstrap failed for $stgt"
            return 1
        fi
        _append_lifecycle "$name" load "bootstrapped $stgt" "$needs_root"
    }

    _do_unload() {
        local target=""
        local dry=""
        _expand_short_opts "" "$@"
        set -- "${_EXPANDED[@]}"; unset _EXPANDED
        while [ $# -gt 0 ]; do
            case "$1" in
                -n|--dry-run) dry=1; shift ;;
                -*) _error "Unknown argument '$1'. Run \`$SCRIPT_NAME -h\` for usage"; return 2 ;;
                *)
                    if [ -n "$target" ]; then
                        _error "Multiple daemon names not allowed (already set to '$target'). Run \`$SCRIPT_NAME -h\` for usage"
                        return 2
                    fi
                    target="$1"; shift ;;
            esac
        done
        [ -n "$target" ] || { _error "Must provide a daemon name. Run \`$SCRIPT_NAME -h\` for usage"; return 2; }

        local row
        local rc
        row="$(_registry_row_for "$target")"; rc=$?
        [ "$rc" -eq 0 ] || return "$rc"
        local name
        local domain
        local label
        local script
        local tsv_plist
        local max_silence
        IFS=$'\t' read -r name domain label script tsv_plist max_silence <<< "$row"

        # bootout needs only the service-target (2nd line); discard the domain-target
        local stgt
        { read -r _; read -r stgt; } <<< "$(_launchd_targets "$domain" "$label")"

        local needs_root=""
        local sudo_pfx=""
        case "$domain" in
            system*) [ "$(id -u)" -ne 0 ] && { needs_root=1; sudo_pfx="sudo "; } ;;
        esac

        # Idempotent: if not loaded, report and stop (no state change, no record)
        if ! _launchd_state "$domain" "$label" >/dev/null; then
            printf '%s already unloaded\n' "$stgt"
            return 0
        fi

        if [ -n "$dry" ]; then
            if [ -n "$needs_root" ]; then
                _dry_command sudo launchctl bootout "$stgt"
            else
                _dry_command launchctl bootout "$stgt"
            fi
            return 0
        fi

        # shellcheck disable=SC2086 # "Double quote to prevent globbing and word splitting." -- $sudo_pfx is "sudo " or empty; the split into a separate argv word is intentional
        if ! ${sudo_pfx}launchctl bootout "$stgt"; then
            _error "launchctl bootout failed for $stgt"
            return 1
        fi
        _append_lifecycle "$name" unload "booted out $stgt" "$needs_root"
    }

    _do_registry() {
        local action=""
        while [ $# -gt 0 ]; do
            case "$1" in
                --edit) # long-only: no natural short (-e is --event in query)
                    [ -z "$action" ] || { _error "Multiple actions not allowed (already set to --$action). Run \`$SCRIPT_NAME -h\` for usage"; return 2; }
                    action=edit; shift ;;
                --open) # long-only: no natural short (-o avoided for a rare action)
                    [ -z "$action" ] || { _error "Multiple actions not allowed (already set to --$action). Run \`$SCRIPT_NAME -h\` for usage"; return 2; }
                    action=open; shift ;;
                *) _error "Unknown argument '$1'. Run \`$SCRIPT_NAME -h\` for usage"; return 2 ;;
            esac
        done
        case "$action" in
            edit)
                # Editor resolves $VISUAL, then $EDITOR, then vi. The editor string may
                # carry args (e.g. VISUAL="code --wait"), so it is invoked THROUGH a
                # shell that word-splits the command while $REGISTRY passes via "$@"
                # (space-safe) -- the same model git uses for GIT_EDITOR
                local editor; editor="${VISUAL:-${EDITOR:-vi}}"
                sh -c "$editor \"\$@\"" "$editor" "$REGISTRY" || { _error "editor '$editor' exited nonzero"; return 1; }
                ;;
            open) open "$REGISTRY" || { _error "open '$REGISTRY' failed"; return 1; } ;;
            *)    printf '%s\n' "$REGISTRY" ;;
        esac
    }

    _do_log() {
        local follow=""
        local target=""
        # log's shorts (-f, -a) are all flags, so value-opts is empty
        _expand_short_opts "" "$@"
        set -- "${_EXPANDED[@]}"; unset _EXPANDED
        while [ $# -gt 0 ]; do
            case "$1" in
                -f|--follow) follow=1; shift ;;
                -a|--all) target="--all"; shift ;;
                -*) _error "Unknown argument '$1'. Run \`$SCRIPT_NAME -h\` for usage"; return 2 ;;
                *) target="$1"; shift ;;
            esac
        done
        local files; files="$(_log_files_for "$target")"
        [ -z "$files" ] && return 0
        if [ -n "$follow" ]; then
            # Follow: tail -f the file(s); render each incoming JSONL line
            # -q suppresses the "==> path <==" banners tail prints with 2+ files, which are not JSON and would abort the jq parse
            # shellcheck disable=SC2086 # "Double quote to prevent globbing and word splitting." -- $files is a newline list of paths we intentionally word-split into tail's args
            tail -f -q $files | _render_records
        else
            # Merge-sort all records by ts (line-sortable ISO-UTC), then render
            # shellcheck disable=SC2086 # "Double quote to prevent globbing and word splitting." -- $files is a newline list of paths we intentionally word-split into cat's args
            cat $files | jq -c . | sort | _render_records
        fi
    }

    local subcmd="${1:-}"
    [ $# -gt 0 ] && shift
    case "$subcmd" in
        -h|--help) _show_help; return 0 ;;
        "") _error "Must provide a subcommand. Run \`$SCRIPT_NAME -h\` for usage"; return 2 ;;
        append)  _do_append "$@"; return $? ;;
        load)    _do_load "$@"; return $? ;;
        unload)  _do_unload "$@"; return $? ;;
        registry) _do_registry "$@"; return $? ;;
        status)  _do_status "$@"; return $? ;;
        check)   _do_check "$@"; return $? ;;
        log)     _do_log "$@"; return $? ;;
        query)   _do_query "$@"; return $? ;;
        *) _error "Unknown argument '$subcmd'. Run \`$SCRIPT_NAME -h\` for usage"; return 2 ;;
    esac
)

_daemons "$@"
__daemons_rc=$?
unset -f _daemons
if [ -n "${BASH_SOURCE[0]}" ] && [ "${BASH_SOURCE[0]}" != "$0" ]; then
    eval "unset __daemons_rc; return $__daemons_rc"
fi
eval "unset __daemons_rc; exit $__daemons_rc"