backend.func

#!/usr/bin/env bash
# Copyright (c) 2021-2026 community-scripts ORG
# License: MIT | https://github.com/community-scripts/DevScripts/raw/main/LICENSE

# ==============================================================================
# PVE-BACKEND.FUNC - PROXMOX VE LXC CREATE / DEPLOY BACKEND
# ==============================================================================
# build_container, create_lxc_container, storage helpers, description, traps.
# Loaded by core/build.func after ui/build-ui.func on Proxmox hosts only.
# ==============================================================================

[[ -n "${_PVE_BACKEND_FUNC_LOADED:-}" ]] && return
_PVE_BACKEND_FUNC_LOADED=1

# ==============================================================================
# SECTION 8: CONTAINER CREATION & DEPLOYMENT
# ==============================================================================

# ------------------------------------------------------------------------------
# _apply_http_proxy_in_container()
# ------------------------------------------------------------------------------
_apply_http_proxy_in_container() {
  local proxy="${HTTP_PROXY:-}"
  local noproxy="${HTTP_NO_PROXY:-}"
  [[ -z "$proxy" || -z "${CTID:-}" ]] && return 0
  [[ -z "$noproxy" ]] && noproxy="localhost,127.0.0.1,.local"

  msg_info "Applying HTTP proxy in container"
  if ! pct exec "$CTID" -- sh -c 'proxy="$1"; noproxy="$2"; cat > /etc/profile.d/90-http-proxy.sh <<EOF
export http_proxy="$proxy"
export https_proxy="$proxy"
export HTTP_PROXY="$proxy"
export HTTPS_PROXY="$proxy"
export no_proxy="$noproxy"
export NO_PROXY="$noproxy"
EOF
chmod 644 /etc/profile.d/90-http-proxy.sh' sh "$proxy" "$noproxy" >/dev/null 2>&1; then
    msg_warn "Failed to write HTTP proxy profile into container"
    return 0
  fi

  if [[ "$var_os" != "alpine" && "${APT_CACHER:-}" != "yes" ]]; then
    pct exec "$CTID" -- sh -c 'proxy="$1"; cat > /etc/apt/apt.conf.d/95http-proxy <<EOF
Acquire::http::Proxy "$proxy";
Acquire::https::Proxy "$proxy";
EOF' sh "$proxy" >/dev/null 2>&1 || true
  fi
  msg_ok "Applied HTTP proxy in container"
}
_apply_host_ca_certs_in_container() {
  local host_ca_dir="/usr/local/share/ca-certificates"
  [[ -z "${CTID:-}" ]] && return 0
  local inherit_host_ca="${INHERIT_HOST_CA:-${var_inherit_host_ca:-no}}"

  local -a host_certs=()
  local cert
  shopt -s nullglob
  for cert in "$host_ca_dir"/*.crt; do
    host_certs+=("$cert")
  done
  shopt -u nullglob

  [[ ${#host_certs[@]} -eq 0 ]] && return 0

  case "${inherit_host_ca,,}" in
  yes | true | 1 | on) ;;
  *)
    return 0
    ;;
  esac

  msg_info "Inheriting host CA certificates into container"

  local found=${#host_certs[@]}
  local copied=0
  local skipped=0
  local cert_name

  pct exec "$CTID" -- mkdir -p /usr/local/share/ca-certificates >/dev/null 2>&1 || {
    msg_warn "Failed to create CA certificate directory in container"
    return 0
  }

  for cert in "${host_certs[@]}"; do
    cert_name="$(basename "$cert")"
    if [[ ! -r "$cert" || "$cert_name" != *.crt ]]; then
      msg_warn "Skipping invalid or unreadable host CA certificate: ${cert_name}"
      skipped=$((skipped + 1))
      continue
    fi

    if pct push "$CTID" "$cert" "/usr/local/share/ca-certificates/${cert_name}" >/dev/null 2>&1; then
      pct exec "$CTID" -- chmod 644 "/usr/local/share/ca-certificates/${cert_name}" >/dev/null 2>&1 || true
      copied=$((copied + 1))
    else
      msg_warn "Failed to push host CA certificate: ${cert_name}"
      skipped=$((skipped + 1))
    fi
  done

  if [[ $copied -eq 0 ]]; then
    msg_warn "No host CA certificates were copied (${found} found, ${skipped} skipped)"
    return 0
  fi

  local refresh_shell="bash"
  [[ "$var_os" == "alpine" ]] && refresh_shell="ash"

  if pct exec "$CTID" -- "$refresh_shell" -c 'command -v update-ca-certificates >/dev/null 2>&1 && update-ca-certificates' >/dev/null 2>&1; then
    msg_ok "Inherited ${copied} host CA certificate(s) and updated trust store (${skipped} skipped)"
  else
    msg_warn "Copied ${copied} host CA certificate(s), but trust store update failed or update-ca-certificates is unavailable (${skipped} skipped)"
  fi
}
reclaim_tty() {
  command -v perl >/dev/null 2>&1 || return 0
  [[ -e /dev/tty ]] || return 0

  local pgid
  pgid=$(ps -o pgid= -p $$ 2>/dev/null | tr -d ' ') || true

  perl -e '
    use POSIX;
    $SIG{TTOU} = "IGNORE";
    my $pgid = $ARGV[0] || POSIX::getpgrp();
    open(my $t, "+<", "/dev/tty") or exit 1;
    POSIX::tcsetpgrp(fileno($t), $pgid) or exit 1;
  ' "${pgid:-0}" 2>/dev/null || true
}

# pct create extracts the template under the caller's umask. The GUI calls it
# from pvedaemon, which systemd starts with 022; we run from the operator's
# shell, so a hardened 027 there gave containers /etc at 750 -- and apt cannot
# resolve then, because it fetches as _apt. Same template, same pct, different
# umask. Scoped to the call, so the operator's umask still governs everything
# else we write on the host.
_pct_create() {
  local prev rc
  prev="$(umask)"
  umask 022
  pct create "$@"
  rc=$?
  umask "$prev"
  return $rc
}

# ------------------------------------------------------------------------------
# _pct_start_failed <ctid> [pct start output]
#
# pct says only that the startup failed; lxc writes why to the container's
# journal. Shows those lines and appends them to the build log, whose tail is
# what the telemetry reports: 80 failed starts a week arrived there as nothing
# more than "failed to start".
# ------------------------------------------------------------------------------
_pct_start_failed() {
  local ctid="$1" out="${2:-}" reason line
  # The last start attempt only, without systemd's own bookkeeping.
  reason="$(journalctl -u "pve-container@${ctid}" -n 80 --no-pager -o cat 2>/dev/null |
    awk '/^Starting pve-container@/ { n = 0; next } { l[++n] = $0 } END { for (i = 1; i <= n; i++) print l[i] }' |
    grep -vE '^pve-container@[0-9]+\.service: |^Failed to start pve-container@|To get more details, run the container in foreground mode' |
    tail -n 10 || true)"
  {
    echo "--- pct start ${ctid} ---"
    [[ -n "$out" ]] && echo "$out"
    [[ -n "$reason" ]] && echo "$reason"
  } >>"${BUILD_LOG:-/dev/null}" 2>/dev/null
  while IFS= read -r line; do
    [[ -n "$line" ]] && echo -e "${TAB}${line}"
  done <<<"${reason:-$out}"
  msg_custom "🔧" "${YW}" "More: journalctl -u pve-container@${ctid}, or in the foreground: lxc-start -n ${ctid} -F -l DEBUG -o /tmp/lxc-${ctid}.log"
}

# Restart after a config change, and say something useful when it fails. The
# two call sites used to be `pct start "$CTID" >/dev/null 2>&1`, so a failure
# aborted the run under errexit with a bare 255 and the output discarded - six
# runs across four apps in the telemetry, none of them diagnosable. pct can
# also return 0 and leave the container stopped, so ask for the real state.
_pct_restart() {
  local ctid="$1" what="$2" err
  err="$(pct start "$ctid" 2>&1)" || true
  [[ "$(pct status "$ctid" 2>/dev/null)" == "status: running" ]] && return 0
  msg_error "Container ${ctid} did not start after ${what}"
  _pct_start_failed "$ctid" "$err"
  return 1
}

# Where a template lands in $TEMPLATE_STORAGE, or the default dir layout when
# pvesm cannot say.
_template_path() {
  local p
  p="$(pvesm path "${TEMPLATE_STORAGE}:vztmpl/$1" 2>/dev/null)" || p=""
  echo "${p:-/var/lib/vz/template/cache/$1}"
}

# ------------------------------------------------------------------------------
# _template_download_failed <pveam output>
#
# Says why the template download failed, as far as the host can tell, and
# files a network or storage problem as such for the telemetry instead of as
# a Proxmox one.
# ------------------------------------------------------------------------------
_template_download_failed() {
  local out="$1" host="download.proxmox.com" last
  last="$(grep -iE 'failed|error|no such|denied|no space' <<<"$out" | tail -n1)"
  msg_error "Template download failed after 3 attempts: ${TEMPLATE}"
  [[ -n "$last" ]] && msg_custom "ℹ️" "${YW}" "pveam: ${last}"
  if grep -qi 'no space left' <<<"$out"; then
    msg_custom "🔧" "${YW}" "Free up space on storage '${TEMPLATE_STORAGE}', then retry."
    export ERROR_CATEGORY_OVERRIDE="storage"
  elif grep -q '^http_proxy:' /etc/pve/datacenter.cfg 2>/dev/null; then
    msg_custom "🔧" "${YW}" "Downloads go through the HTTP proxy set in Datacenter → Options; check that it is reachable."
    export ERROR_CATEGORY_OVERRIDE="network"
  elif ! getent hosts "$host" &>/dev/null; then
    msg_custom "🔧" "${YW}" "This host cannot resolve ${host}: check its DNS servers (node → System → DNS)."
    export ERROR_CATEGORY_OVERRIDE="network"
  elif grep -qiE 'unreachable|timed out|connection refused|name resolution|unable to resolve|interrupted by signal' <<<"$out" ||
    ! curl -fsI --connect-timeout 10 --max-time 20 -o /dev/null "http://${host}/images/system/"; then
    msg_custom "🔧" "${YW}" "This host cannot reliably reach ${host}: check its gateway, firewall and connection."
    export ERROR_CATEGORY_OVERRIDE="network"
  else
    msg_custom "🔧" "${YW}" "Try it by hand: pveam download ${TEMPLATE_STORAGE} ${TEMPLATE}"
  fi
}

# ------------------------------------------------------------------------------
# lxc_os_supported <os> <version>
#
# Asks this host's pve-container whether it can set up an OS release, through
# the same constructor pct create runs, so old and new pve-container answer
# exactly as they would later. Returns 0 supported, 1 not supported, 2 unknown
# (other OS types, or the check itself could not run).
# ------------------------------------------------------------------------------
lxc_os_supported() {
  local os="$1" ver="$2" module dir rc
  case "$os" in
  debian) module="Debian" ;;
  ubuntu) module="Ubuntu" ;;
  *) return 2 ;;
  esac
  # Debian templates always carry a point release, and older pve-container
  # compared it as a number: 13.6 fails "<= 13" where a bare 13 passes.
  [[ "$os" == "debian" && "$ver" != *.* ]] && ver="${ver}.1"
  dir="$(mktemp -d 2>/dev/null)" || return 2
  mkdir -p "$dir/etc"
  if [[ "$os" == "debian" ]]; then
    echo "$ver" >"$dir/etc/debian_version"
  else
    printf 'DISTRIB_ID=Ubuntu\nDISTRIB_RELEASE=%s\n' "$ver" >"$dir/etc/lsb-release"
  fi
  rc=0
  perl -e '
    my ($module, $root) = @ARGV;
    eval "require PVE::LXC::Setup::$module; 1" or exit 2;
    exit 0 if eval { "PVE::LXC::Setup::$module"->new({}, $root, undef, sub {}); 1 };
    exit($@ =~ /unsupported|too old/i ? 1 : 2);
  ' "$module" "$dir" 2>/dev/null || rc=$?
  rm -rf "$dir"
  return "$rc"
}

# ------------------------------------------------------------------------------
# lxc_os_support_check()
#
# Runs as soon as the OS release is settled, before storage selection and the
# template download. A pve-container too old for the release used to surface
# only after both, as a failed pct create.
# Offers what can actually help on this host: updating the LXC stack when a
# newer pve-container is available, or the newest older release it supports.
# ------------------------------------------------------------------------------
lxc_os_support_check() {
  local os="${var_os:-}" ver="${var_version:-}" rc=0
  [[ -n "$os" && -n "$ver" ]] || return 0
  lxc_os_supported "$os" "$ver" || rc=$?
  [[ $rc -eq 1 ]] || return 0

  local installed candidate="" older="" v
  installed="$(dpkg-query -W -f='${Version}' pve-container 2>/dev/null)"
  v="$(apt-cache policy pve-container 2>/dev/null | awk '/Candidate:/ {print $2}')"
  if [[ -n "$v" && "$v" != "(none)" ]] && dpkg --compare-versions "$v" gt "${installed:-0}"; then
    candidate="$v"
  fi
  while read -r v; do
    dpkg --compare-versions "$v" lt "$ver" || continue
    if lxc_os_supported "$os" "$v"; then
      older="$v"
      break
    fi
  done < <(_pveam_available | awk '{print $2}' | sed -nE "s/^${os}-([0-9]+(\.[0-9]+)?)-standard_.*/\1/p" | sort -u -rV)

  msg_error "pve-container ${installed:-?} on this host cannot create ${os^} ${ver} containers."
  local interactive=0
  [[ "${PHS_SILENT:-0}" != "1" && -t 0 ]] && command -v whiptail &>/dev/null && interactive=1

  if [[ $interactive -eq 0 || (-z "$candidate" && -z "$older") ]]; then
    if [[ -n "$candidate" ]]; then
      msg_custom "🔧" "${YW}" "pve-container ${candidate} is available: run 'apt update && apt dist-upgrade' on the host, then retry."
    else
      msg_custom "🔧" "${YW}" "No newer pve-container in the configured repositories. Enable a Proxmox VE repository"
      msg_custom "  " "${YW}" "(the post-pve-install tool can set one up), run 'apt update && apt dist-upgrade', then retry."
    fi
    [[ -n "$older" ]] && msg_custom "💡" "${YW}" "Or install with ${os^} ${older}: var_version=${older}"
    exit 231
  fi

  local -a menu=()
  [[ -n "$candidate" ]] && menu+=("upgrade" "Update the LXC stack to pve-container ${candidate} (apt dist-upgrade)")
  [[ -n "$older" ]] && menu+=("older" "Use ${os^} ${older} instead (not every app supports it)")
  menu+=("cancel" "Cancel")
  local choice
  choice=$(whiptail --backtitle "Proxmox VE Helper Scripts" --title "${os^} ${ver} not supported" --menu \
    "\npve-container ${installed:-?} on this host cannot create ${os^} ${ver} containers.\n\nHow do you want to continue?" \
    16 78 3 "${menu[@]}" 3>&1 1>&2 2>&3) || choice="cancel"

  case "$choice" in
  upgrade)
    msg_info "Updating the Proxmox LXC stack"
    apt_update_safe
    if ! DEBIAN_FRONTEND=noninteractive $STD apt-get -o Dpkg::Options::=--force-confdef -o Dpkg::Options::=--force-confold dist-upgrade -y; then
      msg_error "The upgrade failed. Check the APT output above, then retry."
      exit 231
    fi
    if ! pct list &>/dev/null; then
      msg_error "The upgrade left the Proxmox tools unusable. Run 'apt update && apt dist-upgrade' and reboot, then retry."
      exit 231
    fi
    msg_ok "Updated the Proxmox LXC stack"
    rc=0
    lxc_os_supported "$os" "$ver" || rc=$?
    if [[ $rc -eq 1 ]]; then
      msg_error "pve-container $(dpkg-query -W -f='${Version}' pve-container 2>/dev/null) still cannot create ${os^} ${ver} containers."
      exit 231
    fi
    ;;
  older)
    var_version="$older"
    msg_ok "Using ${os^} ${older}"
    ;;
  *)
    msg_error "Cancelled by user."
    exit 231
    ;;
  esac
}

# ------------------------------------------------------------------------------
# build_container()
#
# - Main function for creating and configuring LXC container
# - Builds network configuration string (IP, gateway, VLAN, MTU, MAC, IPv6)
# - Creates container via pct create with all specified settings
# - Applies features: FUSE, TUN, keyctl, VAAPI passthrough
# - Starts container and waits for network connectivity
# - Installs base packages (curl, sudo, etc.)
# - Injects SSH keys if configured
# - Executes <app>-install.sh inside container
# - Posts installation telemetry to API if diagnostics enabled
# ------------------------------------------------------------------------------
build_container() {
  #  if [ "$VERBOSE" == "yes" ]; then set -x; fi

  lxc_os_support_check

  NET_STRING="-net0 name=eth0,bridge=${BRG:-vmbr0}"
  if [[ -n "${var_sdn_vnet:-${SDN_VNET:-}}" ]]; then
    NET_STRING="-net0 name=eth0,bridge=${var_sdn_vnet:-$SDN_VNET}"
  fi

  # MAC
  if [[ -n "$MAC" ]]; then
    case "$MAC" in
    ,hwaddr=*) NET_STRING+="$MAC" ;;
    *) NET_STRING+=",hwaddr=$MAC" ;;
    esac
  fi

  # IP (always required, default dhcp)
  NET_STRING+=",ip=${NET:-dhcp}"

  # Gateway
  if [[ -n "$GATE" ]]; then
    case "$GATE" in
    ,gw=) ;;
    ,gw=*) NET_STRING+="$GATE" ;;
    *) NET_STRING+=",gw=$GATE" ;;
    esac
  fi

  # VLAN
  if [[ -n "$VLAN" ]]; then
    case "$VLAN" in
    ,tag=*) NET_STRING+="$VLAN" ;;
    *) NET_STRING+=",tag=$VLAN" ;;
    esac
  fi

  # MTU
  if [[ -n "$MTU" ]]; then
    case "$MTU" in
    ,mtu=*) NET_STRING+="$MTU" ;;
    *) NET_STRING+=",mtu=$MTU" ;;
    esac
  fi

  # IPv6 Handling
  case "$IPV6_METHOD" in
  auto) NET_STRING="$NET_STRING,ip6=auto" ;;
  dhcp) NET_STRING="$NET_STRING,ip6=dhcp" ;;
  static)
    if [[ -n "$IPV6_ADDR" ]]; then
      NET_STRING="$NET_STRING,ip6=$IPV6_ADDR"
      [ -n "$IPV6_GATE" ] && NET_STRING="$NET_STRING,gw6=$IPV6_GATE"
    fi
    ;;
  none) ;;
  esac

  # Build FEATURES string based on container type and user choices
  FEATURES=""

  # Nesting support (user configurable, default enabled)
  if [ "${ENABLE_NESTING:-1}" == "1" ]; then
    FEATURES="nesting=1"
  fi

  # Keyctl for unprivileged containers (needed for Docker)
  if [ "$CT_TYPE" == "1" ]; then
    [ -n "$FEATURES" ] && FEATURES="$FEATURES,"
    FEATURES="${FEATURES}keyctl=1"
  fi

  if [ "$ENABLE_FUSE" == "yes" ]; then
    [ -n "$FEATURES" ] && FEATURES="$FEATURES,"
    FEATURES="${FEATURES}fuse=1"
  fi

  if [ "${ENABLE_MKNOD:-0}" == "1" ]; then
    [ -n "$FEATURES" ] && FEATURES="$FEATURES,"
    FEATURES="${FEATURES}mknod=1"
  fi

  if [ -n "${ALLOW_MOUNT_FS:-}" ]; then
    local _mount_clean="${ALLOW_MOUNT_FS// /}"
    _mount_clean="${_mount_clean%%,}"
    _mount_clean="${_mount_clean##,}"
    _mount_clean="${_mount_clean%%;}"
    _mount_clean="${_mount_clean//,/;}"
    if [ -n "$_mount_clean" ]; then
      [ -n "$FEATURES" ] && FEATURES="$FEATURES,"
      FEATURES="${FEATURES}mount=${_mount_clean}"
    fi
  fi

  # Build PCT_OPTIONS as string for export
  TEMP_DIR=$(mktemp -d)
  pushd "$TEMP_DIR" >/dev/null
  # One bootstrap for every OS. install.func detects Alpine itself and has
  # carried apk, OpenRC and BusyBox branches all along; the split only meant
  # those branches never ran and Alpine got a second, thinner copy of the same
  # eight functions that had to be fixed separately every time.
  export FUNCTIONS_FILE_PATH="$(_cs_fetch_text "lxc/install.func")"

  # Core exports for install.func
  export DIAGNOSTICS="$DIAGNOSTICS"
  export RANDOM_UUID="$RANDOM_UUID"
  export EXECUTION_ID="$EXECUTION_ID"
  export SESSION_ID="$SESSION_ID"
  # Repo attribution for container-side progress pings (container inherits the
  # host's detection instead of re-detecting from its own cmdline)
  export REPO_SOURCE="${REPO_SOURCE:-}"
  export REPO_SLUG="${REPO_SLUG:-}"
  # Virtualization platform for telemetry (container has no pveversion)
  export TELEMETRY_PLATFORM="pve"
  export CACHER="$APT_CACHER"
  export CACHER_IP="$APT_CACHER_IP"
  if [[ -n "${HTTP_PROXY:-}" ]]; then
    export HTTP_PROXY HTTPS_PROXY="$HTTP_PROXY" http_proxy="$HTTP_PROXY" https_proxy="$HTTP_PROXY"
    export NO_PROXY="${HTTP_NO_PROXY:-}" no_proxy="${HTTP_NO_PROXY:-}"
    export var_http_proxy="$HTTP_PROXY"
    export var_http_no_proxy="${HTTP_NO_PROXY:-}"
  fi
  export tz="$timezone"
  export APPLICATION="$APP"
  export app="$NSAPP"
  export PASSWORD="$PW"
  export VERBOSE="$VERBOSE"
  export SSH_ROOT="${SSH}"
  export SSH_AUTHORIZED_KEY
  export CTID="$CT_ID"
  export CTTYPE="$CT_TYPE"
  export ENABLE_FUSE="$ENABLE_FUSE"
  export ENABLE_TUN="$ENABLE_TUN"
  export PCT_OSTYPE="$var_os"
  export PCT_OSVERSION="$var_version"
  export PCT_ARCH="$(dpkg --print-architecture 2>/dev/null || uname -m)"
  export PCT_DISK_SIZE="$DISK_SIZE"
  # load_vars_file exports var_ram from default.vars; hand over what the container really got.
  export var_ram="$RAM_SIZE"
  export IPV6_METHOD="$IPV6_METHOD"
  export ENABLE_GPU="$ENABLE_GPU"
  export APPLICATION_VERSION="${var_appversion:-}"

  # The container writes its own MOTD, so it has to know whether this is a
  # testing build. lxc-attach carries this across.
  declare -f cs_testing_state >/dev/null 2>&1 && cs_testing_state

  # DEV_MODE exports (optional, for debugging)
  export BUILD_LOG="$BUILD_LOG"
  export INSTALL_LOG="/root/.install-${SESSION_ID}.log"
  export COMMUNITY_SCRIPTS_URL="$COMMUNITY_SCRIPTS_URL"
  # The engine lives in its own repo — the container needs that base too,
  # otherwise its misc/*.func loads fall back to the hardcoded default.
  export COMMUNITY_SCRIPTS_CORE_URL="$COMMUNITY_SCRIPTS_CORE_URL"
  # Keep host-side logging on BUILD_LOG (not exported — invisible to container)
  # Without this, get_active_logfile() would return INSTALL_LOG (a container path)
  # and all host msg_info/msg_ok/msg_error would write to /root/.install-SESSION.log
  # on the HOST instead of BUILD_LOG, causing incomplete telemetry logs.
  _HOST_LOGFILE="$BUILD_LOG"
  export dev_mode="${dev_mode:-}"
  export DEV_MODE_MOTD="${DEV_MODE_MOTD:-false}"
  export DEV_MODE_KEEP="${DEV_MODE_KEEP:-false}"
  export DEV_MODE_TRACE="${DEV_MODE_TRACE:-false}"
  export DEV_MODE_PAUSE="${DEV_MODE_PAUSE:-false}"
  export DEV_MODE_BREAKPOINT="${DEV_MODE_BREAKPOINT:-false}"
  export DEV_MODE_LOGS="${DEV_MODE_LOGS:-false}"
  export DEV_MODE_NET="${DEV_MODE_NET:-false}"
  export DEV_MODE_TIMING="${DEV_MODE_TIMING:-false}"

  # MODE export for unattended detection in install scripts
  # This tells install scripts whether to prompt for input or use defaults
  export MODE="${METHOD:-default}"

  validate_ct_settings

  # Build PCT_OPTIONS as multi-line string
  PCT_OPTIONS_STRING="  -hostname $HN"

  # Only add -tags if TAGS is not empty
  if [ -n "$TAGS" ]; then
    PCT_OPTIONS_STRING="$PCT_OPTIONS_STRING
  -tags $TAGS"
  fi

  # Only add -features if FEATURES is not empty
  if [ -n "$FEATURES" ]; then
    PCT_OPTIONS_STRING="  -features $FEATURES
$PCT_OPTIONS_STRING"
  fi

  # Add storage if specified
  if [ -n "$SD" ]; then
    PCT_OPTIONS_STRING="$PCT_OPTIONS_STRING
  $SD"
  fi

  # Add nameserver if specified
  if [ -n "$NS" ]; then
    PCT_OPTIONS_STRING="$PCT_OPTIONS_STRING
  $NS"
  fi

  # Network configuration
  PCT_OPTIONS_STRING="$PCT_OPTIONS_STRING
  $NET_STRING
  -onboot 1
  -cores $CORE_COUNT
  -memory $RAM_SIZE
  -unprivileged $CT_TYPE"

  # Protection flag (if var_protection was set)
  if [ "${PROTECT_CT:-}" == "1" ] || [ "${PROTECT_CT:-}" == "yes" ]; then
    PCT_OPTIONS_STRING="$PCT_OPTIONS_STRING
  -protection 1"
  fi

  # pct takes UTC or a zone.tab name only; aliases resolve, "host" is read here
  if [ -n "${CT_TIMEZONE:-}" ]; then
    local _pct_timezone
    _pct_timezone="$(pct_timezone "$CT_TIMEZONE")"
    if [[ -n "$_pct_timezone" ]]; then
      PCT_OPTIONS_STRING="$PCT_OPTIONS_STRING
  -timezone $_pct_timezone"
    else
      msg_warn "Timezone '${CT_TIMEZONE}' cannot be set by pct; the container keeps the template's (UTC)."
    fi
  fi

  # PVE derives ostype from the template name, then rejects its own value when
  # reading the config back - which breaks every later pct call.
  case "${var_os:-}" in
  openeuler | rockylinux | almalinux)
    PCT_OPTIONS_STRING="$PCT_OPTIONS_STRING
  -ostype centos"
    ;;
  esac

  # The password stays out of PCT_OPTIONS: that string is expanded unquoted, so
  # word splitting and globbing would reach it -- a space made two arguments, a
  # * matched a filename. It goes in as its own quoted argument.
  _PW_ARGS=()
  [[ -n "${PW:-}" ]] && _PW_ARGS=(--password "$PW")

  # Export as string (this works, unlike arrays!)
  export PCT_OPTIONS="$PCT_OPTIONS_STRING"
  export TEMPLATE_STORAGE="${var_template_storage:-}"
  export CONTAINER_STORAGE="${var_container_storage:-}"
  [[ -n "${HTTP_PROXY:-}" ]] && export HTTP_PROXY HTTPS_PROXY="$HTTP_PROXY" http_proxy="$HTTP_PROXY" https_proxy="$HTTP_PROXY"
  [[ -n "${HTTP_NO_PROXY:-}" ]] && export NO_PROXY="$HTTP_NO_PROXY" no_proxy="$HTTP_NO_PROXY"

  # Every storage path below shells out to pvesm. Where that binary is missing
  # this is not a Proxmox host at all, and the `pvesm ... 2>/dev/null | awk`
  # pipelines just returned a bare 127 with the diagnostic thrown away - the
  # single largest group in our telemetry. Say what actually happened instead.
  if ! command -v pvesm >/dev/null 2>&1; then
    msg_error "pvesm is not available - this backend expects a Proxmox VE host"
    if declare -f detect_lxc_platform >/dev/null 2>&1; then
      msg_custom "ℹ️" "${YW}" "Detected platform: $(detect_lxc_platform). Override with LXC_PLATFORM=pve|incus if that is wrong"
    fi
    exit 1
  fi

  # Validate storage space only if CONTAINER_STORAGE is already set
  # (Storage selection happens in create_lxc_container for some modes)
  if [[ -n "$CONTAINER_STORAGE" ]]; then
    msg_info "Validating storage space"
    if ! validate_storage_space "$CONTAINER_STORAGE" "$DISK_SIZE" "no"; then
      local free_space
      free_space=$(pvesm status 2>/dev/null | awk -v s="$CONTAINER_STORAGE" '$1 == s { print $6 }')
      local free_fmt
      free_fmt=$(numfmt --to=iec --from-unit=1024 --suffix=B --format %.1f "$free_space" 2>/dev/null || echo "${free_space}KB")
      msg_error "Not enough space on '$CONTAINER_STORAGE'. Required: ${DISK_SIZE}GB, Available: ${free_fmt}"
      exit 214
    fi
    msg_ok "Storage space validated"
    check_storage_health "$CONTAINER_STORAGE" "$DISK_SIZE"
  fi

  create_lxc_container || exit $?
  # Transition to 'configuring' — container created, now setting up OS/userland
  post_progress_to_api "configuring"
  LXC_CONFIG="/etc/pve/lxc/${CTID}.conf"

  # ============================================================================
  # GPU/USB PASSTHROUGH CONFIGURATION
  # ============================================================================

  # Check if GPU passthrough is enabled
  # Returns true only if var_gpu is explicitly set to "yes"
  # Can be set via:
  #   - Environment variable: var_gpu=yes bash -c "..."
  #   - CT script default: var_gpu="${var_gpu:-no}"
  #   - Advanced settings wizard
  #   - App defaults file: /usr/local/community-scripts/defaults/<app>.vars
  is_gpu_app() {
    [[ "${var_gpu:-no}" == "yes" ]] && return 0
    return 1
  }

  # Detect all available GPU devices
  detect_gpu_devices() {
    INTEL_DEVICES=()
    AMD_DEVICES=()
    NVIDIA_DEVICES=()

    # Store PCI info to avoid multiple calls
    local pci_vga_info
    pci_vga_info=$(lspci -nn 2>/dev/null | grep -E "VGA|Display|3D" || true)

    if [[ -z "$pci_vga_info" ]]; then
      msg_debug "No VGA/Display/3D PCI devices found"
      return 0
    fi

    if [[ -d /dev/dri ]]; then
      for d in /dev/dri/renderD* /dev/dri/card*; do
        [[ -e "$d" ]] || continue
        local node vendor
        node=$(basename "$d")
        vendor=$(cat "/sys/class/drm/${node}/device/vendor" 2>/dev/null || true)
        case "$vendor" in
        0x8086) INTEL_DEVICES+=("$d") ;;
        0x1002 | 0x1022) AMD_DEVICES+=("$d") ;;
        0x10de) ;;
        *) msg_debug "Unmapped GPU vendor '${vendor:-unknown}' for $d" ;;
        esac
      done
    fi

    [[ ${#INTEL_DEVICES[@]} -gt 0 ]] && msg_custom "🎮" "${BL}" "Detected Intel GPU"
    [[ ${#AMD_DEVICES[@]} -gt 0 ]] && msg_custom "🎮" "${RD}" "Detected AMD GPU"

    if [[ ${#AMD_DEVICES[@]} -gt 0 && -e /dev/kfd ]]; then
      AMD_DEVICES+=("/dev/kfd")
    fi

    if grep -q "\[10de:" <<<"$pci_vga_info"; then
      msg_custom "🎮" "${GN}" "Detected NVIDIA GPU"

      for d in /dev/nvidia*; do
        [[ -c "$d" ]] && NVIDIA_DEVICES+=("$d")
      done
      if [[ -d /dev/nvidia-caps ]]; then
        for d in /dev/nvidia-caps/*; do
          [[ -c "$d" ]] && NVIDIA_DEVICES+=("$d")
        done
      fi

      if [[ ${#NVIDIA_DEVICES[@]} -gt 0 ]]; then
        msg_custom "🎮" "${GN}" "Found ${#NVIDIA_DEVICES[@]} NVIDIA device(s) for passthrough"
      else
        msg_warn "NVIDIA GPU detected via PCI but no /dev/nvidia* devices found"
        msg_custom "ℹ️" "${YW}" "Skipping NVIDIA passthrough (host drivers may not be loaded)"
      fi
    fi

    # Debug output
    msg_debug "Intel devices: ${INTEL_DEVICES[*]}"
    msg_debug "AMD devices: ${AMD_DEVICES[*]}"
    msg_debug "NVIDIA devices: ${NVIDIA_DEVICES[*]}"
  }

  # Configure USB passthrough for privileged containers
  configure_usb_passthrough() {
    if [[ "$CT_TYPE" != "0" ]]; then
      return 0
    fi

    msg_info "Configuring automatic USB passthrough (privileged container)"
    cat <<EOF >>"$LXC_CONFIG"
# Automatic USB passthrough (privileged container)
lxc.cgroup2.devices.allow: a
lxc.cap.drop:
lxc.cgroup2.devices.allow: c 188:* rwm
lxc.cgroup2.devices.allow: c 189:* rwm
lxc.mount.entry: /dev/serial/by-id  dev/serial/by-id  none bind,optional,create=dir
lxc.mount.entry: /dev/ttyUSB0       dev/ttyUSB0       none bind,optional,create=file
lxc.mount.entry: /dev/ttyUSB1       dev/ttyUSB1       none bind,optional,create=file
lxc.mount.entry: /dev/ttyACM0       dev/ttyACM0       none bind,optional,create=file
lxc.mount.entry: /dev/ttyACM1       dev/ttyACM1       none bind,optional,create=file
EOF
    msg_ok "USB passthrough configured"
  }

  # Configure GPU passthrough
  configure_gpu_passthrough() {
    # Skip if:
    # GPU passthrough is enabled when var_gpu="yes":
    # - Set via environment variable: var_gpu=yes bash -c "..."
    # - Set in CT script: var_gpu="${var_gpu:-no}"
    # - Enabled in advanced_settings wizard
    # - Configured in app defaults file
    if ! is_gpu_app "$APP"; then
      return 0
    fi

    detect_gpu_devices

    # Count available GPU types
    local gpu_count=0
    local available_gpus=()

    if [[ ${#INTEL_DEVICES[@]} -gt 0 ]]; then
      available_gpus+=("INTEL")
      gpu_count=$((gpu_count + 1))
    fi

    if [[ ${#AMD_DEVICES[@]} -gt 0 ]]; then
      available_gpus+=("AMD")
      gpu_count=$((gpu_count + 1))
    fi

    if [[ ${#NVIDIA_DEVICES[@]} -gt 0 ]]; then
      available_gpus+=("NVIDIA")
      gpu_count=$((gpu_count + 1))
    fi

    if [[ $gpu_count -eq 0 ]]; then
      msg_custom "ℹ️" "${YW}" "No GPU devices found for passthrough"
      return 0
    fi

    # Several types can be passed through at once: the device nodes are disjoint,
    # and an iGPU next to a discrete card is the normal case rather than an
    # either/or. This used to pick exactly one, defaulting to the first entry --
    # always INTEL, since that is the order they are collected in. On a host with
    # an Intel iGPU and an NVIDIA card that silently passed through the iGPU and
    # left /dev/nvidia* out, so CUDA never saw a device.
    local -a selected_types=()

    if [[ $gpu_count -eq 1 ]]; then
      selected_types=("${available_gpus[0]}")
      msg_ok "Automatically configuring ${selected_types[0]} GPU passthrough"
    else
      echo -e "\n${INFO} Multiple GPU types detected:"
      local i
      for i in "${!available_gpus[@]}"; do
        echo "  $((i + 1))) ${available_gpus[$i]}"
      done
      echo "  A) Pass through ALL of them"

      local type_selection=""
      read -r -t 60 -p "Select GPU type(s) (1-${gpu_count}, comma-separated, A=all) [timeout 60s, default=all]: " type_selection </dev/tty || type_selection=""
      type_selection="${type_selection^^}"

      if [[ -z "$type_selection" || "$type_selection" == "A" ]]; then
        selected_types=("${available_gpus[@]}")
      else
        local -a nums=()
        local num
        IFS=',' read -ra nums <<<"$type_selection"
        for num in "${nums[@]}"; do
          num="${num// /}"
          if [[ "$num" =~ ^[0-9]+$ ]] && ((num >= 1 && num <= gpu_count)); then
            selected_types+=("${available_gpus[$((num - 1))]}")
          fi
        done
        # Nothing usable typed. Passing everything through beats passing nothing:
        # a spare device node is harmless, a missing one is the bug being fixed.
        if [[ ${#selected_types[@]} -eq 0 ]]; then
          msg_warn "No valid selection - passing through all detected GPUs"
          selected_types=("${available_gpus[@]}")
        fi
      fi
    fi

    # One counter across every selected type: each branch used to start at dev0,
    # which was harmless while only one branch could run and would overwrite
    # entries now that several can.
    local dev_index=0
    local -a configured_types=()

    local selected_gpu
    for selected_gpu in "${selected_types[@]}"; do
      case "$selected_gpu" in
      INTEL | AMD)
        local devices=()
        [[ "$selected_gpu" == "INTEL" ]] && devices=("${INTEL_DEVICES[@]}")
        [[ "$selected_gpu" == "AMD" ]] && devices=("${AMD_DEVICES[@]}")

        # dev0/dev1 format so the entries show up in the GUI.
        # GIDs are detected and corrected once the container has started.
        for dev in "${devices[@]}"; do
          echo "dev${dev_index}: ${dev},gid=44" >>"$LXC_CONFIG"
          dev_index=$((dev_index + 1))
        done

        configured_types+=("$selected_gpu")
        msg_ok "${selected_gpu} GPU passthrough configured (${#devices[@]} devices)"
        ;;

      NVIDIA)
        if [[ ${#NVIDIA_DEVICES[@]} -eq 0 ]]; then
          msg_warn "No NVIDIA devices available for passthrough"
          continue
        fi

        # Separate per-card device nodes (/dev/nvidia0, /dev/nvidia1, ...) from
        # the shared control nodes (nvidiactl, nvidia-uvm*, nvidia-caps/*,
        # nvidia-modeset), so a host with several NVIDIA cards can pass through
        # only some of them instead of always all-or-nothing.
        local -a nvidia_cards=() nvidia_shared=()
        for dev in "${NVIDIA_DEVICES[@]}"; do
          if [[ "$dev" =~ ^/dev/nvidia[0-9]+$ ]]; then
            nvidia_cards+=("$dev")
          else
            nvidia_shared+=("$dev")
          fi
        done

        local -a selected_cards=("${nvidia_cards[@]}")
        if [[ ${#nvidia_cards[@]} -gt 1 ]]; then
          echo -e "\n${INFO} Multiple NVIDIA GPUs detected:"
          local i
          for i in "${!nvidia_cards[@]}"; do
            echo "  $((i + 1))) ${nvidia_cards[$i]}"
          done
          echo "  A) Configure ALL GPUs"
          local gpu_selection=""
          read -r -t 60 -p "Select GPU(s) to pass through (1-${#nvidia_cards[@]}, A=all) [timeout 60s, default=all]: " gpu_selection </dev/tty || gpu_selection=""
          gpu_selection="${gpu_selection^^}"

          if [[ -n "$gpu_selection" && "$gpu_selection" != "A" ]]; then
            selected_cards=()
            local -a nums
            IFS=',' read -ra nums <<<"$gpu_selection"
            local num
            for num in "${nums[@]}"; do
              num=$(echo "$num" | tr -d ' ')
              if [[ "$num" =~ ^[0-9]+$ ]] && ((num >= 1 && num <= ${#nvidia_cards[@]})); then
                selected_cards+=("${nvidia_cards[$((num - 1))]}")
              fi
            done
            [[ ${#selected_cards[@]} -eq 0 ]] && selected_cards=("${nvidia_cards[@]}")
          fi
        fi

        local -a devices_to_add=("${selected_cards[@]}" "${nvidia_shared[@]}")
        for dev in "${devices_to_add[@]}"; do
          echo "dev${dev_index}: ${dev},gid=44" >>"$LXC_CONFIG"
          dev_index=$((dev_index + 1))
        done

        configured_types+=("NVIDIA")
        msg_ok "NVIDIA GPU passthrough configured (${#selected_cards[@]}/${#nvidia_cards[@]} GPU(s), ${#devices_to_add[@]} devices) - install drivers in container if needed"
        ;;
      esac
    done

    # Space separated, so the readers below can test for one type without
    # caring how many others came with it.
    export GPU_TYPE="${configured_types[*]}"
  }

  # Additional device passthrough
  configure_additional_devices() {
    # TUN device passthrough
    if [ "$ENABLE_TUN" == "yes" ]; then
      cat <<EOF >>"$LXC_CONFIG"
lxc.cgroup2.devices.allow: c 10:200 rwm
lxc.mount.entry: /dev/net/tun dev/net/tun none bind,create=file
EOF
    fi

    # Coral TPU passthrough
    if [[ -e /dev/apex_0 ]]; then
      msg_custom "🔌" "${BL}" "Detected Coral TPU - configuring passthrough"
      echo "lxc.mount.entry: /dev/apex_0 dev/apex_0 none bind,optional,create=file" >>"$LXC_CONFIG"
    fi
  }

  # Execute pre-start configurations
  configure_usb_passthrough
  configure_gpu_passthrough
  configure_additional_devices

  # GPU_TYPE can now name several types at once, so this asks whether AMD is
  # among them rather than whether it is the only one.
  if [[ " ${GPU_TYPE:-} " == *" AMD "* ]]; then
    local rocm_extra=4
    local new_disk_size=$((PCT_DISK_SIZE + rocm_extra))
    if pct resize "$CTID" rootfs "${new_disk_size}G" >/dev/null 2>&1; then
      msg_ok "Disk resized ${PCT_DISK_SIZE}GB → ${new_disk_size}GB for ROCm"
    else
      msg_warn "Failed to resize disk for ROCm — installation may fail if space is insufficient"
    fi
  fi

  # ============================================================================
  # START CONTAINER AND INSTALL USERLAND
  # ============================================================================

  msg_info "Starting LXC Container"
  # Checked, and with its own code. Unchecked, a failure here surfaced as pct's
  # generic 255 -- which the exit table reads as DPKG's fatal error, so 197 runs
  # across 70 apps in a fortnight were filed as a package manager problem when
  # the container simply would not start.
  local _start_out
  if ! _start_out="$(pct start "$CTID" 2>&1)"; then
    msg_error "Container ${CTID} was created but would not start"
    _pct_start_failed "$CTID" "$_start_out"
    exit 227
  fi

  # Wait for container to be running
  for i in {1..10}; do
    if pct status "$CTID" | grep -q "status: running"; then
      msg_ok "Started LXC Container"
      break
    fi
    sleep 1
    if [ "$i" -eq 10 ]; then
      local ct_status
      ct_status=$(pct status "$CTID" 2>/dev/null || echo "unknown")
      msg_error "LXC Container did not reach running state (status: ${ct_status})"
      _pct_start_failed "$CTID" "$_start_out"
      exit 117
    fi
  done

  # Wait for network (skip for Alpine initially)
  if [ "$var_os" != "alpine" ]; then
    msg_info "Waiting for network in LXC container"

    # Wait for IP assignment (IPv4 or IPv6)
    local ip_in_lxc=""
    for i in {1..60}; do
      # Try IPv4 first
      ip_in_lxc=$(pct exec "$CTID" -- ip -4 addr show dev eth0 2>/dev/null | awk '/inet / {print $2}' | cut -d/ -f1)
      # Fallback to IPv6 if IPv4 not available
      if [ -z "$ip_in_lxc" ]; then
        ip_in_lxc=$(pct exec "$CTID" -- ip -6 addr show dev eth0 scope global 2>/dev/null | awk '/inet6 / {print $2}' | cut -d/ -f1 | head -n1)
      fi
      [ -n "$ip_in_lxc" ] && break
      if [ "$i" -le 20 ]; then
        sleep 1
      elif [ "$i" -le 40 ]; then
        sleep 2
      else
        sleep 3
      fi
    done

    if [ -z "$ip_in_lxc" ]; then
      msg_error "No IP assigned to CT $CTID after 60 attempts"
      msg_custom "🔧" "${YW}" "Troubleshooting:"
      echo "  • Verify bridge ${BRG} exists and has connectivity"
      echo "  • Check if DHCP server is reachable (if using DHCP)"
      echo "  • Verify static IP configuration (if using static IP)"
      echo "  • Check Proxmox firewall rules"
      echo "  • If using Tailscale: Disable MagicDNS temporarily"
      exit 118
    fi

    # Verify basic connectivity (ping test)
    local ping_success=false
    for retry in {1..3}; do
      if pct exec "$CTID" -- ping -c 1 -W 2 1.1.1.1 &>/dev/null ||
        pct exec "$CTID" -- ping -c 1 -W 2 8.8.8.8 &>/dev/null ||
        pct exec "$CTID" -- ping6 -c 1 -W 2 2606:4700:4700::1111 &>/dev/null; then
        ping_success=true
        break
      fi
      sleep 2
    done

    if [ "$ping_success" = false ]; then
      msg_warn "Network configured (IP: $ip_in_lxc) but connectivity test failed - installation will continue"
    else
      msg_ok "Network in LXC is reachable (ping)"
    fi
  fi
  # Function to get correct GID inside container
  get_container_gid() {
    local group="$1"
    local gid=$(pct exec "$CTID" -- getent group "$group" 2>/dev/null | cut -d: -f3)
    echo "${gid:-44}" # Default to 44 if not found
  }

  fix_gpu_gids

  local rootfs
  rootfs=$(pct config "$CTID" 2>/dev/null | grep -E '^rootfs:' | sed 's/rootfs: //' | cut -d',' -f1 || true)
  if [[ -n "$rootfs" ]]; then
    local mount_point="/var/lib/lxc/${CTID}/rootfs"
    if [[ -d "$mount_point" ]] && [[ "$(stat -c '%U' "$mount_point")" != "root" ]]; then
      chown root:root "$mount_point" 2>/dev/null || true
    fi
  fi

  # Fix Debian 13 LXC template bug where / is owned by nobody:nogroup
  # This causes systemd-tmpfiles to fail with "unsafe path transition" errors
  # We need to fix this from the host before any package installation
  if [[ "$var_os" == "debian" && "$var_version" == "13" ]]; then
    # Stop container, fix ownership, restart
    pct stop "$CTID" >/dev/null 2>&1 || true
    sleep 1
    # Get the actual rootfs path from pct mount
    local rootfs_path
    rootfs_path=$(pct mount "$CTID" 2>/dev/null | grep -oP 'mounted at \K.*' || echo "")
    if [[ -n "$rootfs_path" && -d "$rootfs_path" ]]; then
      chown root:root "$rootfs_path" 2>/dev/null || true
    fi
    pct unmount "$CTID" >/dev/null 2>&1 || true
    _pct_restart "$CTID" "the rootfs ownership fix" || exit 227
    sleep 3
  fi

  msg_info "Customizing LXC Container"

 set +Eeuo pipefail
 trap - ERR

 local install_exit_code=0

 _apply_http_proxy_in_container
 _apply_host_ca_certs_in_container

 # Continue with standard container setup
 if [ "$var_os" == "alpine" ]; then
   sleep 3
   pct exec "$CTID" -- /bin/sh -c 'cat <<EOF >/etc/apk/repositories
https://dl-cdn.alpinelinux.org/alpine/latest-stable/main
https://dl-cdn.alpinelinux.org/alpine/latest-stable/community
EOF'
   pct exec "$CTID" -- ash -c 'set -a; [ -f /etc/profile.d/90-http-proxy.sh ] && . /etc/profile.d/90-http-proxy.sh; set +a; apk add bash newt curl openssh nano mc ncurses jq' >>"$BUILD_LOG" 2>&1 || {
     msg_warn "apk install failed (dl-cdn.alpinelinux.org), trying alternate mirrors..."
     local alpine_exit=0
     pct exec "$CTID" -- ash -c '
       set -a
       [ -f /etc/profile.d/90-http-proxy.sh ] && . /etc/profile.d/90-http-proxy.sh
       set +a
       ALPINE_MIRRORS="mirror.init7.net ftp.halifax.rwth-aachen.de mirrors.edge.kernel.org alpine.mirror.wearetriple.com mirror.leaseweb.com uk.alpinelinux.org dl-2.alpinelinux.org dl-4.alpinelinux.org"
       for m in $(printf "%s\n" $ALPINE_MIRRORS | shuf); do
         if wget -q --spider --timeout=2 "http://$m/alpine/latest-stable/main/" 2>/dev/null; then
            echo "  Attempting mirror: $m"
            cat <<EOF >/etc/apk/repositories
http://$m/alpine/latest-stable/main
http://$m/alpine/latest-stable/community
EOF
            if apk update >/dev/null 2>&1 && apk add bash newt curl openssh nano mc ncurses jq >/dev/null 2>&1; then
              echo "  CDN set to $m: tests passed"
              exit 0
            else
              echo "  Mirror $m failed"
            fi
          fi
        done
        exit 2
      ' && alpine_exit=0 || alpine_exit=$?
      if [[ $alpine_exit -ne 0 ]]; then
        msg_error "Failed to install base packages in Alpine container"
        install_exit_code=1
      fi
    }
  elif [[ "$var_os" =~ ^(debian|ubuntu|devuan)$ ]]; then
    sleep 3
    LANG=${LANG:-en_US.UTF-8}

    # Force C locale inside the container until proper locales are generated.
    # Otherwise perl/apt spam "Setting locale failed" because pct exec inherits
    # the host's LANG (e.g. en_US.UTF-8) which isn't generated in fresh templates.
    local _ct_env='export LC_ALL=C.UTF-8 LANG=C.UTF-8 DEBIAN_FRONTEND=noninteractive;'

    # Devuan templates don't include locales package by default - install it first
    if [ "$var_os" == "devuan" ]; then
      pct exec "$CTID" -- bash -c "set -a; [ -f /etc/profile.d/90-http-proxy.sh ] && . /etc/profile.d/90-http-proxy.sh; set +a; ${_ct_env} apt-get update >/dev/null && apt-get install -y locales >/dev/null" || true
    fi

    # Only configure locale if locale.gen exists (some minimal templates don't have it)
    if pct exec "$CTID" -- test -f /etc/locale.gen 2>/dev/null; then
      pct exec "$CTID" -- bash -c "${_ct_env} sed -i \"/$LANG/ s/^# //\" /etc/locale.gen"
      pct exec "$CTID" -- bash -c "${_ct_env} locale_line=\$(grep -v '^#' /etc/locale.gen | grep -E '^[a-zA-Z]' | awk '{print \$1}' | head -n 1) && \
      echo LANG=\$locale_line >/etc/default/locale && \
      locale-gen >/dev/null && \
      export LANG=\$locale_line"
    fi

    if [[ -z "${tz:-}" ]]; then
      tz=$(timedatectl show --property=Timezone --value 2>/dev/null || echo "UTC")
    fi
    [[ "${tz:-}" == Etc/* ]] && tz="UTC" # Normalize Etc/* to UTC for container setup

    if pct exec "$CTID" -- test -e "/usr/share/zoneinfo/$tz"; then
      # Set timezone using symlink (Debian 13+ compatible)
      # Create /etc/timezone for backwards compatibility with older scripts
      pct exec "$CTID" -- bash -c "${_ct_env} tz='$tz'; ln -sf \"/usr/share/zoneinfo/\$tz\" /etc/localtime && echo \"\$tz\" >/etc/timezone || true"
    else
      msg_warn "Skipping timezone setup – zone '$tz' not found in container"
    fi

    local _base_pkgs="sudo curl mc gnupg2 jq"
    if [[ "${ARCH:-amd64}" == "arm64" ]]; then
      _base_pkgs+=" openssh-server wget gcc"
    fi

    # Detect broken DNS resolver (e.g. Tailscale MagicDNS) and inject public DNS
    if ! pct exec "$CTID" -- bash -c "${_ct_env} getent hosts deb.debian.org >/dev/null 2>&1 && getent hosts archive.ubuntu.com >/dev/null 2>&1"; then
      msg_warn "APT repository DNS resolution failed in container, injecting public DNS servers"
      pct exec "$CTID" -- bash -c "echo -e 'nameserver 8.8.8.8\nnameserver 1.1.1.1' >/etc/resolv.conf"
    fi

    pct exec "$CTID" -- bash -c "set -a; [ -f /etc/profile.d/90-http-proxy.sh ] && . /etc/profile.d/90-http-proxy.sh; set +a; ${_ct_env} apt-get update 2>&1 && apt-get install -y ${_base_pkgs} 2>&1" >>"$BUILD_LOG" 2>&1 || {
      local failed_mirror
      failed_mirror=$(pct exec "$CTID" -- bash -c "grep -m1 -oP '(?<=URIs: https?://)[^/]+' /etc/apt/sources.list.d/debian.sources 2>/dev/null || grep -m1 -oP '(?<=deb https?://)[^/]+' /etc/apt/sources.list 2>/dev/null" 2>/dev/null || echo "unknown")
      msg_warn "apt-get update failed (${failed_mirror})."
      msg_custom "ℹ️" "${YW}" "Probing alternate mirrors (this can take 1-2 minutes on network issues)"
      local mirror_exit=0
      pct exec "$CTID" -- env APT_BASE="$_base_pkgs" bash -c '
        set -a
        [ -f /etc/profile.d/90-http-proxy.sh ] && . /etc/profile.d/90-http-proxy.sh
        set +a
        DISTRO=$(. /etc/os-release 2>/dev/null && echo "$ID" || echo "debian")
        echo "  Mirror fallback for distro: $DISTRO"

        if [ "$DISTRO" = "ubuntu" ]; then
          EU_MIRRORS="de.archive.ubuntu.com fr.archive.ubuntu.com se.archive.ubuntu.com nl.archive.ubuntu.com it.archive.ubuntu.com ch.archive.ubuntu.com mirrors.xtom.de"
          US_MIRRORS="us.archive.ubuntu.com archive.ubuntu.com mirrors.edge.kernel.org mirror.csclub.uwaterloo.ca mirrors.ocf.berkeley.edu mirror.math.princeton.edu"
          AP_MIRRORS="au.archive.ubuntu.com jp.archive.ubuntu.com kr.archive.ubuntu.com tw.archive.ubuntu.com mirror.aarnet.edu.au"
        else
          EU_MIRRORS="ftp.de.debian.org ftp.fr.debian.org ftp.nl.debian.org ftp.uk.debian.org ftp.ch.debian.org ftp.se.debian.org ftp.it.debian.org ftp.fau.de ftp.halifax.rwth-aachen.de debian.mirror.lrz.de mirror.init7.net debian.ethz.ch mirrors.dotsrc.org debian.mirrors.ovh.net"
          US_MIRRORS="ftp.us.debian.org ftp.ca.debian.org debian.csail.mit.edu mirrors.ocf.berkeley.edu mirrors.wikimedia.org debian.osuosl.org mirror.cogentco.com"
          AP_MIRRORS="ftp.au.debian.org ftp.jp.debian.org ftp.tw.debian.org ftp.kr.debian.org ftp.hk.debian.org ftp.sg.debian.org mirror.aarnet.edu.au mirror.nitc.ac.in"
        fi

        TZ=$(cat /etc/timezone 2>/dev/null || echo "UTC")
        case "$TZ" in
          Europe/*|Arctic/*) REGIONAL="$EU_MIRRORS"; OTHERS="$US_MIRRORS $AP_MIRRORS" ;;
          America/*) REGIONAL="$US_MIRRORS"; OTHERS="$EU_MIRRORS $AP_MIRRORS" ;;
          Asia/*|Australia/*|Pacific/*) REGIONAL="$AP_MIRRORS"; OTHERS="$EU_MIRRORS $US_MIRRORS" ;;
          *) REGIONAL=""; OTHERS="$EU_MIRRORS $US_MIRRORS $AP_MIRRORS" ;;
        esac

        echo "Acquire::By-Hash \"no\";" >/etc/apt/apt.conf.d/99no-by-hash

        try_mirrors() {
          for src in /etc/apt/sources.list.d/debian.sources /etc/apt/sources.list; do
            [ -f "$src" ] && sed -i "s|URIs: http[s]*://[^/]*/|URIs: http://${1}/|g; s|deb http[s]*://[^/]*/|deb http://${1}/|g" "$src"
          done
          rm -rf /var/lib/apt/lists/*
          APT_OUT=$(apt-get update 2>&1)
          APT_RC=$?
          if echo "$APT_OUT" | grep -qi "hashsum\|hash sum"; then
            echo "  Mirror $1 failed (hash mismatch)"
            return 1
          elif echo "$APT_OUT" | grep -qi "SSL\|certificate"; then
            echo "  Mirror $1 failed (SSL/certificate error)"
            return 1
          elif [ $APT_RC -ne 0 ]; then
            echo "  Mirror $1 failed (apt-get update error)"
            return 1
          elif apt-get install -y $APT_BASE >/dev/null 2>&1; then
            echo "  CDN set to $1: tests passed"
            return 0
          else
            echo "  Mirror $1 failed (package install error)"
            return 1
          fi
        }

        scan_reachable() {
          local result=""
          for m in $1; do
            if timeout 2 bash -c "echo >/dev/tcp/$m/80" 2>/dev/null; then
              result="$result $m"
            fi
          done
          echo "$result" | xargs
        }

        # Phase 1: Scan global mirrors first (independent of local CDN issues)
        echo "  Phase 1/3: Scanning global mirrors for reachability..."
        OTHERS_OK=$(scan_reachable "$OTHERS")
        OTHERS_PICK=$(printf "%s\n" $OTHERS_OK | shuf | head -3 | xargs)

        if [ -z "$OTHERS_PICK" ]; then
          echo "  No reachable global mirrors found"
        fi

        for mirror in $OTHERS_PICK; do
          echo "  Attempting mirror: $mirror"
          try_mirrors "$mirror" && exit 0
        done

        # Phase 2: Try primary mirror
        echo "  Phase 2/3: Trying primary mirror..."
        if [ "$DISTRO" = "ubuntu" ]; then
          PRIMARY="archive.ubuntu.com"
        else
          PRIMARY="ftp.debian.org"
        fi
        if timeout 2 bash -c "echo >/dev/tcp/$PRIMARY/80" 2>/dev/null; then
          echo "  Attempting mirror: $PRIMARY"
          try_mirrors "$PRIMARY" && exit 0
        fi

        # Phase 3: Fall back to regional mirrors
        echo "  Phase 3/3: Scanning regional mirrors..."
        REGIONAL_OK=$(scan_reachable "$REGIONAL")
        REGIONAL_PICK=$(printf "%s\n" $REGIONAL_OK | shuf | head -3 | xargs)

        if [ -z "$REGIONAL_PICK" ]; then
          echo "  No reachable regional mirrors found"
        fi

        for mirror in $REGIONAL_PICK; do
          echo "  Attempting mirror: $mirror"
          try_mirrors "$mirror" && exit 0
        done

        exit 2
      ' && mirror_exit=0 || mirror_exit=$?
      if [[ $mirror_exit -eq 2 ]]; then
        msg_warn "Multiple mirrors failed (possible CDN synchronization issue)."
        if [[ "$var_os" == "ubuntu" ]]; then
          msg_warn "Find Ubuntu mirrors at: https://launchpad.net/ubuntu/+archivemirrors"
        else
          msg_warn "Find Debian mirrors at: https://www.debian.org/mirror/list"
        fi
        local custom_mirror=""
        while true; do
          read -rp "  Enter a mirror hostname (or 'skip' to abort): " custom_mirror </dev/tty
          [[ -z "$custom_mirror" ]] && continue
          [[ "$custom_mirror" == "skip" ]] && break
          [[ ! "$custom_mirror" =~ ^[a-zA-Z0-9._-]+$ ]] && {
            msg_warn "Invalid hostname format."
            continue
          }
          pct exec "$CTID" -- bash -c "
            for src in /etc/apt/sources.list.d/debian.sources /etc/apt/sources.list; do
              [ -f \"\$src\" ] && sed -i \"s|URIs: http[s]*://[^/]*/|URIs: http://${custom_mirror}/|g; s|deb http[s]*://[^/]*/|deb http://${custom_mirror}/|g\" \"\$src\"
            done
            rm -rf /var/lib/apt/lists/*
            apt-get update >/dev/null 2>&1 && apt-get install -y ${_base_pkgs} >/dev/null 2>&1
          " && break
          msg_warn "Mirror '${custom_mirror}' also failed. Try another or type 'skip'."
        done
        if [[ "$custom_mirror" == "skip" ]]; then
          msg_warn "Mirror selection aborted by user ('skip')"
          msg_warn "Aborting installation before base package bootstrap"
          post_update_to_api "aborted" "130" "force"
          install_exit_code=130
        fi
      elif [[ $mirror_exit -ne 0 ]]; then
        msg_error "apt-get base packages installation failed"
        install_exit_code=100
      fi
    }
  else
    # Non-apt, non-apk systems: Fedora/Rocky/Alma/CentOS/openEuler/openSUSE/Arch/Gentoo
    sleep 3

    # Set timezone (host's timezone, falling back to UTC)
    if [[ -z "${tz:-}" ]]; then
      tz=$(timedatectl show --property=Timezone --value 2>/dev/null || echo "UTC")
    fi
    [[ "${tz:-}" == Etc/* ]] && tz="UTC"
    if pct exec "$CTID" -- test -e "/usr/share/zoneinfo/$tz"; then
      pct exec "$CTID" -- bash -c "ln -sf \"/usr/share/zoneinfo/$tz\" /etc/localtime && echo \"$tz\" >/etc/timezone || true"
    fi

    # Fix blank PVE noVNC console on distros with util-linux >= 2.40.3 and
    # bash/readline 8.2+ (Fedora 43, Arch rolling): agetty and readline both send
    # ESC[6n (cursor position query); the VNC terminal responds with ESC[row;colR
    # which gets read as keyboard input (shows as "R;80R;" garbage at the prompt).
    # Three-layer fix:
    #  1. console-getty drop-in: TERM=linux stops agetty from querying (fixes MOTD blank)
    #  2. /etc/environment: PAM passes TERM before /etc/profile runs (fixes openSUSE tset)
    #  3. /etc/profile.d/99-pve-console-term.sh: re-asserts TERM=linux AFTER all other
    #     profile.d scripts, so readline never thinks CPR is supported (fixes R;80R garbage)
    case "$var_os" in
    fedora | rocky | rockylinux | alma | almalinux | centos | openeuler | opensuse | archlinux | arch)
      pct exec "$CTID" -- bash -c '
        mkdir -p /etc/systemd/system/console-getty.service.d
        printf "[Service]\nEnvironment=TERM=linux\n" >/etc/systemd/system/console-getty.service.d/pve-console-term.conf
        systemctl daemon-reload 2>/dev/null || true
        systemctl restart console-getty.service 2>/dev/null || true

        # Layer 2: PAM environment (read before /etc/profile)
        grep -q "^TERM=" /etc/environment 2>/dev/null || echo "TERM=linux" >>/etc/environment

        # Layer 3: profile.d script that runs last (99-) to override any earlier TERM changes
        mkdir -p /etc/profile.d
        cat >/etc/profile.d/99-pve-console-term.sh <<'"'"'PROFILE'"'"'
# Ensure TERM=linux on PVE noVNC console to prevent ESC[6n CPR responses
# being read as keyboard input by bash/readline 8.2+ (shows as R;80R garbage).
_pve_t=$(tty 2>/dev/null)
case "$_pve_t" in
  /dev/console|/dev/tty[0-9]*)
    export TERM=linux ;;
esac
unset _pve_t
PROFILE
        chmod 644 /etc/profile.d/99-pve-console-term.sh
      ' 2>/dev/null || true
      ;;
    esac

    # Ensure curl is present for install.func bootstrap (most templates have it, but be safe)
    case "$var_os" in
    fedora | rocky | rockylinux | alma | almalinux | centos | openeuler)
      pct exec "$CTID" -- bash -c "command -v curl >/dev/null 2>&1 || (command -v dnf >/dev/null 2>&1 && dnf install -y curl >/dev/null 2>&1) || (command -v yum >/dev/null 2>&1 && yum install -y curl >/dev/null 2>&1)" || true
      ;;
    opensuse)
      pct exec "$CTID" -- bash -c "command -v curl >/dev/null 2>&1 || zypper -n install curl >/dev/null 2>&1" || true
      ;;
    archlinux | arch)
      pct exec "$CTID" -- bash -c "command -v curl >/dev/null 2>&1 || pacman -Sy --noconfirm curl >/dev/null 2>&1" || true
      ;;
    gentoo)
      pct exec "$CTID" -- bash -c "command -v curl >/dev/null 2>&1 || emerge --quiet net-misc/curl >/dev/null 2>&1" || true
      ;;
    esac
  fi

  if [[ $install_exit_code -eq 0 ]]; then
    msg_ok "Customized LXC Container"

    if [[ "${DNS_RETRY_OVERRIDE:-false}" == "true" ]]; then
      msg_info "Applying DNS retry override in LXC (8.8.8.8, 1.1.1.1)"
      pct exec "$CTID" -- bash -c "printf 'nameserver 8.8.8.8\nnameserver 1.1.1.1\n' >/etc/resolv.conf" >/dev/null 2>&1 || true
      msg_ok "DNS override applied in LXC"
    fi

    install_ssh_keys_into_ct
    start_install_timer

    export CONTAINER_INSTALLING=true

    local _install_script
    # Fetched explicitly rather than letting the ERR trap report it.
    #
    # A missing install script is almost always one thing: the ct/ script came
    # from a fork but COMMUNITY_SCRIPTS_URL was not set, so the engine looked
    # here -- upstream -- and found nothing. The trap reported that as
    # "exit code 22 (Command failed with exit status 22)", which says neither
    # what was missing nor where it was looked for.
    if ! _install_script="$(_cs_fetch_text "install/${var_install}.sh")" ||
      [[ -z "$_install_script" ]]; then
      msg_error "Could not fetch install/${var_install}.sh"
      msg_custom "📁" "${YW}" "Looked in: ${COMMUNITY_SCRIPTS_ROOT:-${COMMUNITY_SCRIPTS_URL}}"
      if [[ -z "${COMMUNITY_SCRIPTS_ROOT:-}" ]]; then
        msg_custom "💡" "${YW}" "Running a fork? A ct/ script fetched with curl cannot tell the engine"
        msg_custom "   " "${YW}" "where it came from, so set the scripts base explicitly:"
        msg_custom "   " "${YW}" "COMMUNITY_SCRIPTS_URL=https://raw.githubusercontent.com/<you>/<repo>/<branch>"
      fi
      exit 115
    fi
    lxc-attach -n "$CTID" -- bash -c "$_install_script"
    local lxc_exit=$?

    unset CONTAINER_INSTALLING

    if [[ -n "${SESSION_ID:-}" ]]; then
      local error_flag="/root/.install-${SESSION_ID}.failed"
      if pct exec "$CTID" -- test -f "$error_flag" 2>/dev/null; then
        # The flag holds the container's own code. When it cannot be read, or
        # comes back as something that is not a number, fall back to what
        # lxc-attach returned rather than to 1: that is a code we actually
        # observed, and it is already in hand a few lines up.

        install_exit_code=$(pct exec "$CTID" -- cat "$error_flag" 2>/dev/null | tr -d '[:space:]') || true
        [[ "$install_exit_code" =~ ^[0-9]+$ ]] || install_exit_code="${lxc_exit:-199}"
        pct exec "$CTID" -- rm -f "$error_flag" 2>/dev/null || true
      fi
    fi

    if [[ $install_exit_code -eq 0 && ${lxc_exit:-0} -ne 0 ]]; then
      install_exit_code=${lxc_exit:-0}
    fi
  fi

  if [[ $install_exit_code -ne 0 ]]; then
    trap '' TSTP TTIN TTOU
    reclaim_tty

    msg_error "Installation failed in container ${CTID} (exit code: ${install_exit_code})"

    local build_log_copied=false
    local install_log_copied=false
    local combined_log="/tmp/${NSAPP:-lxc}-${CTID}-${SESSION_ID}.log"

    if [[ -n "$CTID" && -n "${SESSION_ID:-}" ]]; then
      {
        echo "================================================================================"
        echo "COMBINED INSTALLATION LOG - ${APP:-LXC}"
        echo "Container ID: ${CTID}"
        echo "Session ID: ${SESSION_ID}"
        echo "Timestamp: $(date '+%Y-%m-%d %H:%M:%S')"
        echo "================================================================================"
        echo ""
      } >"$combined_log"

      if [[ -f "${BUILD_LOG}" ]]; then
        {
          echo "================================================================================"
          echo "PHASE 1: CONTAINER CREATION (Host)"
          echo "================================================================================"
          cat "${BUILD_LOG}"
          echo ""
        } >>"$combined_log"
        build_log_copied=true
      fi

      local temp_install_log="/tmp/.install-temp-${SESSION_ID}.log"
      if pct pull "$CTID" "/root/.install-${SESSION_ID}.log" "$temp_install_log" 2>/dev/null; then
        {
          echo "================================================================================"
          echo "PHASE 2: APPLICATION INSTALLATION (Container)"
          echo "================================================================================"
          cat "$temp_install_log"
          echo ""
        } >>"$combined_log"
        rm -f "$temp_install_log"
        install_log_copied=true
        INSTALL_LOG="$combined_log"
      fi

      local host_errinfo="/tmp/.errinfo-${SESSION_ID}"
      if timeout 8 pct pull "$CTID" "/root/.install-${SESSION_ID}.log.errinfo" "$host_errinfo" 2>/dev/null && [[ -s "$host_errinfo" ]]; then
        TELEMETRY_ERRINFO="$host_errinfo"
        export TELEMETRY_ERRINFO
      fi
    fi

    set +Eeuo pipefail
    trap - ERR

    local is_oom=false
    local is_network_issue=false
    local is_apt_issue=false
    local is_cmd_not_found=false
    local is_disk_full=false

    if [[ $install_exit_code -eq 1 && -f "$combined_log" ]]; then
      if grep -qiE 'E: Unable to|E: Package|E: Failed to fetch|dpkg.*error|broken packages|unmet dependencies|dpkg --configure -a' "$combined_log"; then
        is_apt_issue=true
      fi
      if grep -qiE 'Cannot allocate memory|Out of memory|oom-killer|Killed process|JavaScript heap' "$combined_log"; then
        is_oom=true
      fi
      if grep -qiE 'Could not resolve|DNS resolution failed|Connection refused|Network is unreachable|No route to host|Temporary failure resolving|Failed to fetch' "$combined_log"; then
        is_network_issue=true
      fi
      if grep -qiE ': command not found|No such file or directory.*/s?bin/' "$combined_log"; then
        is_cmd_not_found=true
      fi
      if grep -qiE 'ENOSPC|no space left on device|Disk quota exceeded|errno -28' "$combined_log"; then
        is_disk_full=true
      fi
    fi

    if [[ "$is_apt_issue" == true ]]; then
      export ERROR_CATEGORY_OVERRIDE="dependency"
    elif [[ "$is_oom" == true ]]; then
      export ERROR_CATEGORY_OVERRIDE="resource"
    elif [[ "$is_network_issue" == true ]]; then
      export ERROR_CATEGORY_OVERRIDE="network"
    elif [[ "$is_disk_full" == true ]]; then
      export ERROR_CATEGORY_OVERRIDE="storage"
    elif [[ "$is_cmd_not_found" == true ]]; then
      export ERROR_CATEGORY_OVERRIDE="dependency"
    fi

    $STD echo -e "${TAB}⏳ Reporting failure to telemetry..."
    post_update_to_api "failed" "$install_exit_code"
    $STD echo -e "${TAB}${CM:-✔} Failure reported"

    if [[ -n "$CTID" && -n "${SESSION_ID:-}" ]]; then
      msg_custom "📋" "${YW}" "Installation log: ${combined_log}"
    fi

    if [[ "${DEV_MODE_KEEP:-false}" == "true" ]]; then
      msg_dev "Keep mode active - container ${CTID} preserved"
      return 0
    elif [[ "${DEV_MODE_BREAKPOINT:-false}" == "true" ]]; then
      msg_dev "Breakpoint mode - opening shell in container ${CTID}"
      echo -e "${YW}Type 'exit' to return to host${CL}"
      pct enter "$CTID"
      echo ""
      echo -en "${YW}Container ${CTID} still running. Remove now? (y/N): ${CL}"
      reclaim_tty
      if read -r response </dev/tty && [[ "$response" =~ ^[Yy]$ ]]; then
        pct stop "$CTID" &>/dev/null || true
        pct destroy "$CTID" &>/dev/null || true
        msg_ok "Container ${CTID} removed"
      else
        msg_dev "Container ${CTID} kept for debugging"
      fi
      exit $install_exit_code
    fi

    echo ""

    local error_explanation="" failed_cmd=""
    [[ -s "${TELEMETRY_ERRINFO:-}" ]] && failed_cmd="$(sed -n 's/^COMMAND=//p' "$TELEMETRY_ERRINFO" | head -n1)"
    if declare -f _eh_explanation >/dev/null 2>&1; then
      error_explanation="$(_eh_explanation "$install_exit_code" "$failed_cmd")"
    elif declare -f explain_exit_code >/dev/null 2>&1; then
      error_explanation="$(explain_exit_code "$install_exit_code")"
    fi

    if [[ $install_exit_code -eq 134 || $install_exit_code -eq 137 || $install_exit_code -eq 243 ]]; then
      is_oom=true
    fi

    case "$install_exit_code" in
    100 | 101 | 102)
      # cargo exits 101 on a panic; only an apt/dpkg command makes this an APT problem
      if [[ -z "$failed_cmd" ]] || ! declare -f _eh_command_is >/dev/null 2>&1 || _eh_command_is "$failed_cmd" "$(_eh_tools_for APT)"; then
        is_apt_issue=true
      fi
      ;;
    255)
      if [[ -f "$combined_log" ]] && grep -qiE 'dpkg|apt-get|apt\.conf|broken packages|unmet dependencies|E: Sub-process|E: Failed' "$combined_log"; then
        is_apt_issue=true
      fi
      ;;
    esac

    if [[ $install_exit_code -eq 228 || $install_exit_code -eq 23 ]]; then
      is_disk_full=true
    fi
    if [[ -f "$combined_log" ]] && grep -qiE 'ENOSPC|no space left on device|No space left on device|Disk quota exceeded|errno -28' "$combined_log"; then
      is_disk_full=true
    fi

    if [[ $install_exit_code -eq 127 ]]; then
      is_cmd_not_found=true
    fi

    case "$install_exit_code" in
    6 | 7 | 22 | 28 | 35 | 52 | 56 | 57 | 75 | 78) is_network_issue=true ;;
    100)
      if [[ -f "$combined_log" ]] && grep -qiE 'Failed to fetch|Could not resolve|Connection failed|Network is unreachable|Temporary failure resolving' "$combined_log"; then
        is_network_issue=true
      fi
      ;;
    128)
      if [[ -f "$combined_log" ]] && grep -qiE 'RPC failed|early EOF|fetch-pack|HTTP/2 stream|Could not resolve host|Temporary failure resolving|Failed to fetch|Connection reset|Network is unreachable' "$combined_log"; then
        is_network_issue=true
      fi
      ;;
    esac

    if [[ -n "$error_explanation" ]]; then
      echo -e "${TAB}${RD}Error: ${error_explanation}${CL}"
      echo ""
    fi

    if [[ $install_exit_code -eq 10 ]]; then
      echo -e "${TAB}${INFO} This error usually means the container needs ${GN}privileged${CL} mode or Docker/nesting support."
      echo -e "${TAB}${INFO} Recreate with: Advanced Install → Container Type: ${GN}Privileged${CL}"
      echo ""
    fi

    if [[ $install_exit_code -eq 125 || $install_exit_code -eq 126 ]]; then
      echo -e "${TAB}${INFO} The command exists but cannot be executed. This may be a ${GN}permission${CL} issue."
      echo -e "${TAB}${INFO} If using Docker, ensure the container is ${GN}privileged${CL} or has correct permissions."
      echo ""
    fi

    if [[ "$is_disk_full" == true ]]; then
      echo -e "${TAB}${INFO} The container ran out of disk space during installation (${GN}ENOSPC${CL})."
      echo -e "${TAB}${INFO} Current disk size: ${GN}${DISK_SIZE} GB${CL}. A rebuild with doubled disk may resolve this."
      echo ""
    fi

    if [[ "$is_cmd_not_found" == true ]]; then
      local missing_cmd=""
      if [[ -f "$combined_log" ]]; then
        missing_cmd=$(grep -oiE '[a-zA-Z0-9_.-]+: command not found' "$combined_log" 2>/dev/null | tail -1 | sed 's/: command not found//') || true
      fi
      if [[ -n "$missing_cmd" ]]; then
        echo -e "${TAB}${INFO} Missing command: ${GN}${missing_cmd}${CL}"
      fi
      echo ""
    fi

    echo -e "${YW}What would you like to do?${CL}"
    echo ""
    echo -e "  ${GN}1)${CL} Remove container and exit"
    echo -e "  ${GN}2)${CL} Keep container for debugging"
    echo -e "  ${GN}3)${CL} Retry with verbose mode (full rebuild)"

    local next_option=4
    local APT_OPTION="" OOM_OPTION="" DNS_OPTION="" DISK_OPTION=""

    if [[ "$is_apt_issue" == true ]]; then
      if [[ "$var_os" == "alpine" ]]; then
        echo -e "  ${GN}${next_option})${CL} Repair APK state and re-run install (in-place)"
      else
        echo -e "  ${GN}${next_option})${CL} Repair APT/DPKG state and re-run install (in-place)"
      fi
      APT_OPTION=$next_option
      next_option=$((next_option + 1))
    fi

    if [[ "$is_oom" == true ]]; then
      local recovery_attempt="${RECOVERY_ATTEMPT:-0}"
      if [[ $recovery_attempt -lt 2 ]]; then
        local new_ram=$((RAM_SIZE * 2))
        local new_cpu=$((CORE_COUNT * 2))
        echo -e "  ${GN}${next_option})${CL} Retry with more resources (RAM: ${RAM_SIZE}→${new_ram} MiB, CPU: ${CORE_COUNT}→${new_cpu} cores)"
        OOM_OPTION=$next_option
        next_option=$((next_option + 1))
      else
        echo -e "  ${DGN}-)${CL} ${DGN}OOM retry exhausted (already retried ${recovery_attempt}x)${CL}"
      fi
    fi

    if [[ "$is_disk_full" == true ]]; then
      local disk_recovery_attempt="${DISK_RECOVERY_ATTEMPT:-0}"
      if [[ $disk_recovery_attempt -lt 2 ]]; then
        local new_disk=$((DISK_SIZE * 2))
        echo -e "  ${GN}${next_option})${CL} Retry with more disk space (Disk: ${DISK_SIZE}→${new_disk} GB)"
        DISK_OPTION=$next_option
        next_option=$((next_option + 1))
      else
        echo -e "  ${DGN}-)${CL} ${DGN}Disk resize retry exhausted (already retried ${disk_recovery_attempt}x)${CL}"
      fi
    fi

    if [[ "$is_network_issue" == true ]]; then
      echo -e "  ${GN}${next_option})${CL} Retry with DNS override in LXC (8.8.8.8 / 1.1.1.1)"
      DNS_OPTION=$next_option
      next_option=$((next_option + 1))
    fi

    local max_option=$((next_option - 1))

    echo ""
    echo -en "${YW}Select option [1-${max_option}] (default: 1, auto-remove in 60s): ${CL}"

    local response=""
    local read_rc
    reclaim_tty
    read -t 60 -r response </dev/tty
    read_rc=$?
    if [[ $read_rc -eq 0 ]]; then
      case "${response:-1}" in
      1)
        echo -e "\n${TAB}${HOLD}${YW}Removing container ${CTID}${CL}"
        pct stop "$CTID" &>/dev/null || true
        pct destroy "$CTID" &>/dev/null || true
        echo -e "${BFR}${CM}${GN}Container ${CTID} removed${CL}"
        ;;
      2)
        echo -e "\n${TAB}${YW}Container ${CTID} kept for debugging${CL}"
        if [[ "${DEV_MODE_MOTD:-false}" == "true" ]]; then
          echo -e "${TAB}${HOLD}${DGN}Setting up MOTD and SSH for debugging...${CL}"
          if pct exec "$CTID" -- bash -c "
              source <(curl -fsSL --retry 3 --retry-delay 1 --retry-connrefused --connect-timeout 10 \"${COMMUNITY_SCRIPTS_CORE_URL}/lxc/install.func\")
              declare -f motd_ssh >/dev/null 2>&1 && motd_ssh || true
            " >/dev/null 2>&1; then
            local ct_ip=$(pct exec "$CTID" ip a s dev eth0 2>/dev/null | awk '/inet / {print $2}' | cut -d/ -f1)
            echo -e "${BFR}${CM}${GN}MOTD/SSH ready - SSH into container: ssh root@${ct_ip}${CL}"
          fi
        fi
        exit $install_exit_code
        ;;
      3)
        echo -e "\n${TAB}${HOLD}${YW}Removing container ${CTID} for rebuild...${CL}"
        pct stop "$CTID" &>/dev/null || true
        pct destroy "$CTID" &>/dev/null || true
        echo -e "${BFR}${CM}${GN}Container ${CTID} removed${CL}"
        echo ""
        local old_ctid="$CTID"
        export CTID=$(get_valid_container_id "$CTID")
        export VERBOSE="yes"
        export var_verbose="yes"

        echo -e "${YW}Rebuilding with preserved settings:${CL}"
        echo -e "  Container ID: ${old_ctid} → ${CTID}"
        echo -e "  RAM: ${RAM_SIZE} MiB | CPU: ${CORE_COUNT} cores | Disk: ${DISK_SIZE} GB"
        echo -e "  Network: ${NET:-dhcp} | Bridge: ${BRG:-vmbr0}"
        echo -e "  Verbose: ${GN}enabled${CL}"
        echo ""
        msg_custom "ℹ️" "${YW}" "Restarting installation..."
        declare -f telemetry_new_attempt &>/dev/null && telemetry_new_attempt
        build_container
        return $?
        ;;
      *)
        local handled=false

        if [[ -n "${APT_OPTION}" && "${response}" == "${APT_OPTION}" ]]; then
          handled=true
          if [[ "$var_os" == "alpine" ]]; then
            echo -e "\n${TAB}${HOLD}${YW}Repairing APK state in container ${CTID}...${CL}"
            pct exec "$CTID" -- ash -c "
              apk fix 2>/dev/null || true
              apk cache clean 2>/dev/null || true
              apk update 2>/dev/null || true
            " >/dev/null 2>&1 || true
            echo -e "${BFR}${CM}${GN}APK state repaired in container ${CTID}${CL}"
          else
            echo -e "\n${TAB}${HOLD}${YW}Repairing APT/DPKG state in container ${CTID}...${CL}"
            pct exec "$CTID" -- bash -c "
              DEBIAN_FRONTEND=noninteractive dpkg --configure -a 2>/dev/null || true
              apt-get -f install -y 2>/dev/null || true
              apt-get clean 2>/dev/null
              apt-get update 2>/dev/null || true
            " >/dev/null 2>&1 || true
            echo -e "${BFR}${CM}${GN}APT/DPKG state repaired in container ${CTID}${CL}"
          fi
          echo ""
          export VERBOSE="yes"
          export var_verbose="yes"

          echo -e "${YW}Re-running installation in existing container ${CTID}:${CL}"
          echo -e "  RAM: ${RAM_SIZE} MiB | CPU: ${CORE_COUNT} cores | Disk: ${DISK_SIZE} GB"
          echo -e "  Verbose: ${GN}enabled${CL}"
          echo ""
          msg_info "Re-running installation script..."

          declare -f telemetry_new_attempt &>/dev/null && telemetry_new_attempt
          declare -f post_to_api &>/dev/null && post_to_api 2>/dev/null || true

          set +Eeuo pipefail
          trap - ERR
          local _install_script
          # The ERR trap is off here on purpose, so a failed fetch would hand
          # lxc-attach an empty script, run nothing, and record success.
          _install_script="$(_cs_fetch_text "install/${var_install}.sh")" || true
          if [[ -z "$_install_script" ]]; then
            set -Eeuo pipefail
            trap 'error_handler' ERR
            msg_error "Could not fetch install/${var_install}.sh for the retry"
            exit 115
          fi
          lxc-attach -n "$CTID" -- bash -c "$_install_script"
          local apt_retry_exit=$?
          set -Eeuo pipefail
          trap 'error_handler' ERR

          local apt_retry_code=0
          if [[ -n "${SESSION_ID:-}" ]]; then
            local retry_error_flag="/root/.install-${SESSION_ID}.failed"
            if pct exec "$CTID" -- test -f "$retry_error_flag" 2>/dev/null; then
              apt_retry_code=$(pct exec "$CTID" -- cat "$retry_error_flag" 2>/dev/null || echo "1")
              pct exec "$CTID" -- rm -f "$retry_error_flag" 2>/dev/null || true
            fi
          fi

          if [[ $apt_retry_code -eq 0 && $apt_retry_exit -ne 0 ]]; then
            apt_retry_code=$apt_retry_exit
          fi

          if [[ $apt_retry_code -eq 0 ]]; then
            msg_ok "Installation completed successfully after APT repair!"
            INSTALL_COMPLETE=true
            post_update_to_api "done" "0" "force"
            return 0
          else
            msg_error "Installation still failed after APT repair (exit code: ${apt_retry_code})"
            install_exit_code=$apt_retry_code
          fi
        fi

        if [[ -n "${OOM_OPTION}" && "${response}" == "${OOM_OPTION}" ]]; then
          handled=true
          echo -e "\n${TAB}${HOLD}${YW}Removing container ${CTID} for rebuild with more resources...${CL}"
          pct stop "$CTID" &>/dev/null || true
          pct destroy "$CTID" &>/dev/null || true
          echo -e "${BFR}${CM}${GN}Container ${CTID} removed${CL}"
          echo ""
          local old_ctid="$CTID"
          local old_ram="$RAM_SIZE"
          local old_cpu="$CORE_COUNT"
          export CTID=$(get_valid_container_id "$CTID")
          export RAM_SIZE=$((RAM_SIZE * 2))
          export CORE_COUNT=$((CORE_COUNT * 2))
          export var_ram="$RAM_SIZE"
          export var_cpu="$CORE_COUNT"
          export VERBOSE="yes"
          export var_verbose="yes"
          export RECOVERY_ATTEMPT=$((${RECOVERY_ATTEMPT:-0} + 1))

          echo -e "${YW}Rebuilding with increased resources (attempt ${RECOVERY_ATTEMPT}/2):${CL}"
          echo -e "  Container ID: ${old_ctid} → ${CTID}"
          echo -e "  RAM: ${old_ram} → ${GN}${RAM_SIZE}${CL} MiB (x2)"
          echo -e "  CPU: ${old_cpu} → ${GN}${CORE_COUNT}${CL} cores (x2)"
          echo -e "  Disk: ${DISK_SIZE} GB | Network: ${NET:-dhcp} | Bridge: ${BRG:-vmbr0}"
          echo -e "  Verbose: ${GN}enabled${CL}"
          echo ""
          msg_custom "ℹ️" "${YW}" "Restarting installation..."
          declare -f telemetry_new_attempt &>/dev/null && telemetry_new_attempt
          build_container
          return $?
        fi

        if [[ -n "${DISK_OPTION}" && "${response}" == "${DISK_OPTION}" ]]; then
          handled=true
          echo -e "\n${TAB}${HOLD}${YW}Removing container ${CTID} for rebuild with more disk space...${CL}"
          pct stop "$CTID" &>/dev/null || true
          pct destroy "$CTID" &>/dev/null || true
          echo -e "${BFR}${CM}${GN}Container ${CTID} removed${CL}"
          echo ""
          local old_ctid="$CTID"
          local old_disk="$DISK_SIZE"
          export CTID=$(get_valid_container_id "$CTID")
          export DISK_SIZE=$((DISK_SIZE * 2))
          export var_disk="$DISK_SIZE"
          export VERBOSE="yes"
          export var_verbose="yes"
          export DISK_RECOVERY_ATTEMPT=$((${DISK_RECOVERY_ATTEMPT:-0} + 1))

          echo -e "${YW}Rebuilding with increased disk space (attempt ${DISK_RECOVERY_ATTEMPT}/2):${CL}"
          echo -e "  Container ID: ${old_ctid} → ${CTID}"
          echo -e "  Disk: ${old_disk} → ${GN}${DISK_SIZE}${CL} GB (x2)"
          echo -e "  RAM: ${RAM_SIZE} MiB | CPU: ${CORE_COUNT} cores"
          echo -e "  Network: ${NET:-dhcp} | Bridge: ${BRG:-vmbr0}"
          echo -e "  Verbose: ${GN}enabled${CL}"
          echo ""
          msg_custom "ℹ️" "${YW}" "Restarting installation..."
          declare -f telemetry_new_attempt &>/dev/null && telemetry_new_attempt
          build_container
          return $?
        fi

        if [[ -n "${DNS_OPTION}" && "${response}" == "${DNS_OPTION}" ]]; then
          handled=true
          echo -e "\n${TAB}${HOLD}${YW}Removing container ${CTID} for rebuild with DNS override...${CL}"
          pct stop "$CTID" &>/dev/null || true
          pct destroy "$CTID" &>/dev/null || true
          echo -e "${BFR}${CM}${GN}Container ${CTID} removed${CL}"
          echo ""
          local old_ctid="$CTID"
          export CTID=$(get_valid_container_id "$CTID")
          export DNS_RETRY_OVERRIDE="true"
          export VERBOSE="yes"
          export var_verbose="yes"

          echo -e "${YW}Rebuilding with DNS override in LXC:${CL}"
          echo -e "  Container ID: ${old_ctid} → ${CTID}"
          echo -e "  DNS: ${GN}8.8.8.8, 1.1.1.1${CL} (inside LXC only)"
          echo -e "  Verbose: ${GN}enabled${CL}"
          echo ""
          msg_custom "ℹ️" "${YW}" "Restarting installation..."
          declare -f telemetry_new_attempt &>/dev/null && telemetry_new_attempt
          build_container
          return $?
        fi

        if [[ "$handled" == false ]]; then
          echo -e "\n${TAB}${YW}Invalid option. Container ${CTID} kept.${CL}"
          exit $install_exit_code
        fi
        ;;
      esac
    elif [[ $read_rc -gt 128 ]]; then
      echo ""
      msg_info "No response - removing container ${CTID}"
      pct stop "$CTID" &>/dev/null || true
      pct destroy "$CTID" &>/dev/null || true
      msg_ok "Container ${CTID} removed"
    else
      while read -r -t 0.1 -n 1 _ </dev/tty 2>/dev/null; do :; done
      echo ""
      msg_error "Could not read your response (stdin error) - keeping container ${CTID} for safety."
      msg_error "Remove it manually if not needed: pct destroy ${CTID}"
    fi

    # No "force" here. The same failure was already reported further up in this
    # very path, and force exists to bypass the POST_UPDATE_DONE guard -- so this
    # sent every failed install's terminal event a second time, identical to the
    # first. The guard makes it a no-op once the report has gone out, and still
    # reports if some path reached here without one.
    #
    # force stays where the outcome genuinely changed since the first report, as
    # after a successful rebuild.
    $STD echo -e "${TAB}⏳ Finalizing telemetry report..."
    post_update_to_api "failed" "$install_exit_code"
    $STD echo -e "${TAB}${CM:-✔} Telemetry finalized"

    trap - TSTP TTIN TTOU
    exit $install_exit_code
  fi

  set -Eeuo pipefail
  trap 'error_handler' ERR
}

destroy_lxc() {
  if [[ -z "$CT_ID" ]]; then
    msg_error "No CT_ID found. Nothing to remove."
    return 1
  fi

  # Abort on Ctrl-C / Ctrl-D / ESC
  trap 'echo; msg_error "Aborted by user (SIGINT/SIGQUIT)"; return 130' INT QUIT

  local prompt
  reclaim_tty
  if ! read -rp "Remove this Container? <y/N> " prompt </dev/tty; then
    # read returns non-zero on Ctrl-D/ESC
    msg_error "Aborted input (Ctrl-D/ESC)"
    return 130
  fi

  case "${prompt,,}" in
  y | yes)
    if pct stop "$CT_ID" &>/dev/null && pct destroy "$CT_ID" &>/dev/null; then
      msg_ok "Removed Container $CT_ID"
    else
      msg_error "Failed to remove Container $CT_ID"
      return 1
    fi
    ;;
  "" | n | no)
    msg_custom "ℹ️" "${BL}" "Container was not removed."
    ;;
  *)
    msg_warn "Invalid response. Container was not removed."
    ;;
  esac
}

# ------------------------------------------------------------------------------
# Storage discovery / selection helpers
# ------------------------------------------------------------------------------

# A storage named in default.vars that no longer takes this content used to end
# the run in a loop that asked nothing and never exited. Ask instead, and offer
# to correct the file so the next run does not stop at the same place.
_storage_preselect_recover() {
  local class="$1" stale="$2" key vf

  case "$class" in
  template) key="var_template_storage" ;;
  container) key="var_container_storage" ;;
  *) return 1 ;;
  esac

  select_storage "$class" || return 1

  vf="${CS_DEFAULT_VARS_FILE:-}"
  [[ -n "$stale" && -n "$vf" && -f "$vf" ]] || return 0
  [[ "$stale" == "$STORAGE_RESULT" ]] && return 0
  grep -qE "^[#[:space:]]*${key}=" "$vf" 2>/dev/null || return 0
  declare -f _write_storage_to_vars >/dev/null 2>&1 || return 0

  if whiptail --backtitle "Proxmox VE Helper Scripts" --title "UPDATE DEFAULTS" \
    --yesno "${key} in default.vars still points at '${stale}', which cannot hold this content.\n\nReplace it with '${STORAGE_RESULT}'?" 12 72; then
    _write_storage_to_vars "$vf" "$key" "$STORAGE_RESULT"
    msg_ok "Set ${key}=${STORAGE_RESULT} in ${vf}"
  fi
  return 0
}

resolve_storage_preselect() {
  local class="$1" preselect="$2" required_content=""
  case "$class" in
  template) required_content="vztmpl" ;;
  container) required_content="rootdir" ;;
  *) return 1 ;;
  esac
  [[ -z "$preselect" ]] && return 1
  if ! pvesm status -content "$required_content" | awk 'NR>1{print $1}' | grep -qx -- "$preselect"; then
    msg_warn "Preselected storage '${preselect}' does not support content '${required_content}' (or not found)"
    return 1
  fi

  local line total used free
  line="$(pvesm status | awk -v s="$preselect" 'NR>1 && $1==s {print $0}')"
  if [[ -z "$line" ]]; then
    STORAGE_INFO="n/a"
  else
    total="$(awk '{print $4}' <<<"$line")"
    used="$(awk '{print $5}' <<<"$line")"
    free="$(awk '{print $6}' <<<"$line")"
    local total_h used_h free_h
    if command -v numfmt >/dev/null 2>&1; then
      total_h="$(numfmt --to=iec --from-unit=1024 --suffix=B --format %.1f "$total" 2>/dev/null || echo "$total")"
      used_h="$(numfmt --to=iec --from-unit=1024 --suffix=B --format %.1f "$used" 2>/dev/null || echo "$used")"
      free_h="$(numfmt --to=iec --from-unit=1024 --suffix=B --format %.1f "$free" 2>/dev/null || echo "$free")"
      STORAGE_INFO="Free: ${free_h}  Used: ${used_h}"
    else
      STORAGE_INFO="Free: ${free}  Used: ${used}"
    fi
  fi
  STORAGE_RESULT="$preselect"
  return 0
}

fix_gpu_gids() {
  if [[ -z "${GPU_TYPE:-}" ]]; then
    return 0
  fi

  msg_info "Detecting and setting correct GPU group IDs"

  # Get actual GIDs from container
  local video_gid=$(pct exec "$CTID" -- sh -c "getent group video 2>/dev/null | cut -d: -f3")
  local render_gid=$(pct exec "$CTID" -- sh -c "getent group render 2>/dev/null | cut -d: -f3")

  # Create groups if they don't exist
  if [[ -z "$video_gid" ]]; then
    pct exec "$CTID" -- sh -c "groupadd -r video 2>/dev/null || true" >/dev/null 2>&1
    video_gid=$(pct exec "$CTID" -- sh -c "getent group video 2>/dev/null | cut -d: -f3")
    [[ -z "$video_gid" ]] && video_gid="44"
  fi

  if [[ -z "$render_gid" ]]; then
    pct exec "$CTID" -- sh -c "groupadd -r render 2>/dev/null || true" >/dev/null 2>&1
    render_gid=$(pct exec "$CTID" -- sh -c "getent group render 2>/dev/null | cut -d: -f3")
    [[ -z "$render_gid" ]] && render_gid="104"
  fi

  # Stop container to update config
  pct stop "$CTID" >/dev/null 2>&1
  sleep 1

  # Update dev entries with correct GIDs
  sed -i.bak -E "s|(dev[0-9]+: /dev/dri/renderD[0-9]+),gid=[0-9]+|\1,gid=${render_gid}|g" "$LXC_CONFIG"
  sed -i -E "s|(dev[0-9]+: /dev/dri/card[0-9]+),gid=[0-9]+|\1,gid=${video_gid}|g" "$LXC_CONFIG"
  sed -i -E "s|(dev[0-9]+: /dev/kfd),gid=[0-9]+|\1,gid=${render_gid}|g" "$LXC_CONFIG"

  # Restart container
  _pct_restart "$CTID" "GPU passthrough configuration" || exit 227
  sleep 2

  msg_ok "GPU passthrough configured (video:${video_gid}, render:${render_gid})"

  # For privileged containers: also fix permissions inside container
  if [[ "$CT_TYPE" == "0" ]]; then
    pct exec "$CTID" -- sh -c "
      if [ -d /dev/dri ]; then
        for dev in /dev/dri/*; do
          if [ -e \"\$dev\" ]; then
            case \"\$dev\" in
              *renderD*) chgrp ${render_gid} \"\$dev\" 2>/dev/null || true ;;
              *)         chgrp ${video_gid} \"\$dev\" 2>/dev/null || true ;;
            esac
            chmod 660 \"\$dev\" 2>/dev/null || true
          fi
        done
      fi
      if [ -e /dev/kfd ]; then
        chgrp ${render_gid} /dev/kfd 2>/dev/null || true
        chmod 660 /dev/kfd 2>/dev/null || true
      fi
    " >/dev/null 2>&1
  fi
}

check_storage_support() {
  local CONTENT="$1" VALID=0
  while IFS= read -r line; do
    local STORAGE_NAME
    STORAGE_NAME=$(awk '{print $1}' <<<"$line")
    [[ -n "$STORAGE_NAME" ]] && VALID=1
  done < <(pvesm status -content "$CONTENT" 2>/dev/null | awk 'NR>1')
  [[ $VALID -eq 1 ]]
}

_storage_content_of() {
  awk -v s="$1" '/^[a-z]+:/ { f = ($2 == s); next } f && $1 == "content" { print $2; exit }' /etc/pve/storage.cfg 2>/dev/null
}

# ------------------------------------------------------------------------------
# _offer_storage_content <vztmpl|rootdir>
#
# Lists the active storages that can hold the content and, when interactive,
# switches it on for the one picked, keeping what that storage already holds.
# ------------------------------------------------------------------------------
_offer_storage_content() {
  local content="$1" label types id type current choice
  case "$content" in
  vztmpl)
    label="container templates"
    types=" dir nfs cifs btrfs cephfs glusterfs "
    ;;
  rootdir)
    label="container disks"
    types=" dir nfs cifs btrfs lvm lvmthin zfspool rbd "
    ;;
  *) return 1 ;;
  esac

  msg_error "No storage on this host is enabled for ${label} (content '${content}')."
  local -a menu=()
  while read -r id type; do
    [[ "$types" == *" $type "* ]] && menu+=("$id" "${type}, holds: $(_storage_content_of "$id")")
  done < <(pvesm status 2>/dev/null | awk 'NR > 1 && $3 == "active" {print $1, $2}')

  if ((${#menu[@]} == 0)); then
    msg_custom "🔧" "${YW}" "Add a storage that can hold them (Datacenter → Storage) and enable content '${content}' on it."
    return 1
  fi
  if [[ "${PHS_SILENT:-0}" == "1" || ! -t 0 ]] || ! command -v whiptail &>/dev/null; then
    current="$(_storage_content_of "${menu[0]}")"
    msg_custom "🔧" "${YW}" "Enable it on a storage, e.g.: pvesm set ${menu[0]} --content ${current:+${current},}${content}"
    return 1
  fi

  choice=$(whiptail --backtitle "Proxmox VE Helper Scripts" --title "No storage for ${label}" --menu \
    "\nNo storage is enabled for ${label} ('${content}').\n\nEnable it on one of these, keeping what it already holds?" \
    18 78 6 "${menu[@]}" 3>&1 1>&2 2>&3) || return 1

  current="$(_storage_content_of "$choice")"
  [[ "$current" == "none" ]] && current=""
  if pvesm set "$choice" --content "${current:+${current},}${content}" >/dev/null 2>&1 && check_storage_support "$content"; then
    msg_ok "Enabled ${label} on storage '${choice}'"
    return 0
  fi
  msg_error "Could not enable '${content}' on storage '${choice}'."
  return 1
}

# ------------------------------------------------------------------------------
# storage_content_check()
#
# Runs before the settings menu. A host without a storage for container
# templates or container disks failed only once everything was chosen, with
# 120 or 119. The usual cause is the 'local' directory storage with that
# content switched off, which can be switched on in place.
# ------------------------------------------------------------------------------
storage_content_check() {
  check_storage_support "vztmpl" || _offer_storage_content "vztmpl" || exit 120
  check_storage_support "rootdir" || _offer_storage_content "rootdir" || exit 119
}

select_storage() {
  local CLASS=$1 CONTENT CONTENT_LABEL
  case $CLASS in
  container)
    CONTENT='rootdir'
    CONTENT_LABEL='Container'
    ;;
  template)
    CONTENT='vztmpl'
    CONTENT_LABEL='Container template'
    ;;
  iso)
    CONTENT='iso'
    CONTENT_LABEL='ISO image'
    ;;
  images)
    CONTENT='images'
    CONTENT_LABEL='VM Disk image'
    ;;
  backup)
    CONTENT='backup'
    CONTENT_LABEL='Backup'
    ;;
  snippets)
    CONTENT='snippets'
    CONTENT_LABEL='Snippets'
    ;;
  *)
    msg_error "Invalid storage class '$CLASS'"
    return 1
    ;;
  esac

  declare -A STORAGE_MAP
  local -a MENU=()
  local COL_WIDTH=0

  while read -r TAG TYPE _ TOTAL USED FREE _; do
    [[ -n "$TAG" && -n "$TYPE" ]] || continue
    local DISPLAY="${TAG} (${TYPE})"
    local USED_FMT=$(numfmt --to=iec --from-unit=1024 --format %.1f <<<"$USED")
    local FREE_FMT=$(numfmt --to=iec --from-unit=1024 --format %.1f <<<"$FREE")
    local INFO="Free: ${FREE_FMT}B  Used: ${USED_FMT}B"
    STORAGE_MAP["$DISPLAY"]="$TAG"
    MENU+=("$DISPLAY" "$INFO" "OFF")
    ((${#DISPLAY} > COL_WIDTH)) && COL_WIDTH=${#DISPLAY}
  done < <(pvesm status -content "$CONTENT" | awk 'NR>1')

  if [[ ${#MENU[@]} -eq 0 ]]; then
    msg_error "No storage found for content type '$CONTENT'."
    return 2
  fi

  if [[ $((${#MENU[@]} / 3)) -eq 1 ]]; then
    STORAGE_RESULT="${STORAGE_MAP[${MENU[0]}]}"
    STORAGE_INFO="${MENU[1]}"
    return 0
  fi

  local WIDTH=$((COL_WIDTH + 42))
  while true; do
    local DISPLAY_SELECTED
    DISPLAY_SELECTED=$(whiptail --backtitle "Proxmox VE Helper Scripts" \
      --title "Storage Pools" \
      --radiolist "Which storage pool for ${CONTENT_LABEL,,}?\n(Spacebar to select)" \
      16 "$WIDTH" 6 "${MENU[@]}" 3>&1 1>&2 2>&3) || { exit_script; }

    DISPLAY_SELECTED=$(sed 's/[[:space:]]*$//' <<<"$DISPLAY_SELECTED")
    if [[ -z "$DISPLAY_SELECTED" || -z "${STORAGE_MAP[$DISPLAY_SELECTED]+_}" ]]; then
      whiptail --msgbox "No valid storage selected. Please try again." 8 58
      continue
    fi
    STORAGE_RESULT="${STORAGE_MAP[$DISPLAY_SELECTED]}"
    for ((i = 0; i < ${#MENU[@]}; i += 3)); do
      if [[ "${MENU[$i]}" == "$DISPLAY_SELECTED" ]]; then
        STORAGE_INFO="${MENU[$i + 1]}"
        break
      fi
    done

    # Validate storage space for container storage
    if [[ "$CLASS" == "container" && -n "${DISK_SIZE:-}" ]]; then
      validate_storage_space "$STORAGE_RESULT" "$DISK_SIZE" "yes"
      check_storage_health "$STORAGE_RESULT" "$DISK_SIZE"
      # Continue even if validation fails - user was warned
    fi

    return 0
  done
}

# ------------------------------------------------------------------------------
# validate_ct_settings()
#
# Checks the settings pct create would reject, whichever way they were set:
# the wizard checks its own input, but default.vars, app defaults and var_*
# from the environment arrive unchecked, and pct reported them only after the
# storage selection and template download, as a generic creation failure.
# ------------------------------------------------------------------------------
validate_ct_settings() {
  local -a problems=()
  local ns="${NS#-nameserver=}" sd="${SD#-searchdomain=}"

  if ! validate_ram_size "${RAM_SIZE:-}"; then
    if [[ "${RAM_SIZE:-}" =~ ^[1-9][0-9]*$ ]]; then
      problems+=("RAM ${RAM_SIZE} MiB is too little (var_ram is in MiB; ${RAM_SIZE} GiB would be $((RAM_SIZE * 1024)))")
    else
      problems+=("RAM '${RAM_SIZE:-}' is not a number of MiB (var_ram)")
    fi
  fi
  if [[ -n "${PW:-}" && ${#PW} -lt 5 ]]; then
    problems+=("the root password needs at least 5 characters (var_pw)")
  fi
  if [[ -n "${NET:-}" && "$NET" != "dhcp" && "$NET" != "manual" ]] && ! validate_ip_address "$NET"; then
    problems+=("IPv4 '${NET}' is not dhcp or an address with prefix, e.g. 192.168.1.50/24 (var_net)")
  fi
  if [[ -n "${GATE:-}" ]] && ! validate_gateway_ip "${GATE#,gw=}"; then
    problems+=("gateway '${GATE#,gw=}' is not an IPv4 address (var_gateway)")
  fi
  if ! validate_nameservers "$ns"; then
    problems+=("DNS server '${ns}' must be IP addresses (var_ns)")
  fi
  if ! validate_searchdomain "$sd"; then
    problems+=("search domain '${sd}' is not a DNS name (var_searchdomain)")
  fi
  if ! validate_mount_fs "${ALLOW_MOUNT_FS:-}"; then
    problems+=("mount types '${ALLOW_MOUNT_FS}' must be filesystem types such as nfs or cifs, not paths (var_mount_fs)")
  fi

  [[ ${#problems[@]} -eq 0 ]] && return 0
  msg_error "These settings would be rejected by pct create:"
  local p
  for p in "${problems[@]}"; do
    echo -e "${TAB}- ${p}"
  done
  msg_custom "🔧" "${YW}" "Fix them in the advanced settings or in the defaults file they came from, then retry."
  exit 208
}

# ------------------------------------------------------------------------------
# _lvmthin_check <storage>
#
# LVM refuses a new thin volume once the pool's data or metadata use reaches
# 100% or passes activation/thin_pool_autoextend_threshold. pct reported that
# as "Cannot create new thin volume" after the template download; full
# metadata with free data space is the usual case on PVE.
# ------------------------------------------------------------------------------
_lvmthin_check() {
  local storage="$1" vg pool data meta threshold
  read -r vg pool < <(awk -v s="$storage" '
    $1 == "lvmthin:" { f = ($2 == s); next }
    /^[a-z]+:/ { f = 0 }
    f && $1 == "vgname" { vg = $2 }
    f && $1 == "thinpool" { tp = $2 }
    END { if (vg != "" && tp != "") print vg, tp }' /etc/pve/storage.cfg 2>/dev/null)
  [[ -n "$vg" && -n "$pool" ]] || return 0
  read -r data meta < <(LC_ALL=C lvs --noheadings --nosuffix -o data_percent,metadata_percent "${vg}/${pool}" 2>/dev/null) || return 0
  # A decimal comma ("33,09") turns awk's comparison below into a string one, and "33,09" >= "100".
  data="${data//,/.}" meta="${meta//,/.}"
  [[ -n "$data" && -n "$meta" ]] || return 0
  threshold="$(lvmconfig --type full activation/thin_pool_autoextend_threshold 2>/dev/null | cut -d= -f2)"
  [[ "$threshold" =~ ^[0-9]+$ ]] || threshold=100
  if awk -v d="$data" -v m="$meta" -v t="$threshold" 'BEGIN { exit !(d >= 100 || m >= 100 || d > t || m > t) }'; then
    msg_error "Thin pool ${vg}/${pool} of storage '${storage}' is full (data ${data}%, metadata ${meta}%): LVM will not create a new volume in it."
    if awk -v m="$meta" -v t="$threshold" 'BEGIN { exit !(m >= 100 || m > t) }'; then
      msg_custom "🔧" "${YW}" "Grow its metadata: lvextend --poolmetadatasize +1G ${vg}/${pool}"
    else
      msg_custom "🔧" "${YW}" "Free space in it (unused disks, old snapshots, fstrim on containers) or extend it with lvextend."
    fi
    return 1
  fi
  return 0
}

# ------------------------------------------------------------------------------
# validate_storage_space()
#
# - Validates if storage has enough free space for container
# - Takes storage name and required size in GB
# - Returns 0 if enough space, 1 if not enough, 2 if storage unavailable
# - Can optionally show whiptail warning
# - Handles all storage types: dir, lvm, lvmthin, zfs, nfs, cifs, etc.
# ------------------------------------------------------------------------------
validate_storage_space() {
  local storage="$1"
  local required_gb="${2:-8}"
  local show_dialog="${3:-no}"

  # Get full storage line from pvesm status
  local storage_line
  storage_line=$(pvesm status 2>/dev/null | awk -v s="$storage" '$1 == s {print $0}')

  if [[ -z "$storage_line" ]]; then
    [[ "$show_dialog" == "yes" ]] && whiptail --msgbox "⚠️  Warning: Storage '$storage' not found!

The storage may be unavailable or disabled." 10 60
    return 2
  fi

  local status
  status=$(awk '{print $3}' <<<"$storage_line")
  if [[ "$status" == "disabled" ]]; then
    [[ "$show_dialog" == "yes" ]] && whiptail --msgbox "⚠️  Warning: Storage '$storage' is disabled!

Please enable the storage first." 10 60
    return 2
  fi

  # Get storage type and free space (column 6)
  local storage_type storage_free
  storage_type=$(awk '{print $2}' <<<"$storage_line")
  storage_free=$(awk '{print $6}' <<<"$storage_line")

  # Some storage types (like PBS, iSCSI) don't report size info
  # In these cases, skip space validation
  if [[ -z "$storage_free" || "$storage_free" == "0" ]]; then
    # Silent pass for storages without size info
    return 0
  fi

  local required_kb=$((required_gb * 1024 * 1024))
  local free_gb_fmt
  free_gb_fmt=$(numfmt --to=iec --from-unit=1024 --suffix=B --format %.1f "$storage_free" 2>/dev/null || echo "${storage_free}KB")

  if [[ "$storage_free" -lt "$required_kb" ]]; then
    if [[ "$show_dialog" == "yes" ]]; then
      whiptail --msgbox "⚠️  Warning: Storage '$storage' may not have enough space!

Storage Type: ${storage_type}
Required: ${required_gb}GB
Available: ${free_gb_fmt}

You can continue, but creation might fail." 14 70
    fi
    return 1
  fi

  return 0
}

check_storage_health() {
  local storage="$1"
  local required_gb="${2:-8}"
  [[ -z "$storage" ]] && return 0

  local storage_line storage_type total_kb avail_kb used_pct free_gb_fmt
  storage_line=$(pvesm status 2>/dev/null | awk -v s="$storage" '$1 == s {print $0}')
  [[ -z "$storage_line" ]] && return 0

  storage_type=$(awk '{print $2}' <<<"$storage_line")
  total_kb=$(awk '{print $4}' <<<"$storage_line")
  avail_kb=$(awk '{print $6}' <<<"$storage_line")

  [[ -z "$total_kb" || "$total_kb" == "0" || -z "$avail_kb" ]] && return 0

  used_pct=$(((total_kb - avail_kb) * 100 / total_kb))
  free_gb_fmt=$(numfmt --to=iec --from-unit=1024 --suffix=B --format %.1f "$avail_kb" 2>/dev/null || echo "${avail_kb}KB")

  if ((used_pct >= 95)); then
    msg_warn "Storage '${storage}' (${storage_type}) is ${used_pct}% full (${free_gb_fmt} free)"
    if ! is_unattended && command -v whiptail >/dev/null 2>&1 && [[ -t 0 ]]; then
      if ! whiptail --backtitle "Proxmox VE Helper Scripts"         --title "STORAGE ALMOST FULL"         --yesno "Storage '${storage}' is ${used_pct}% full.

Type: ${storage_type}
Available: ${free_gb_fmt}
Required for CT: ${required_gb} GB

Continue anyway?" 14 70; then
        msg_error "Installation cancelled – storage nearly full"
        exit 214
      fi
    elif ((used_pct >= 98)); then
      msg_error "Storage '${storage}' is ${used_pct}% full – refusing install in unattended mode"
      exit 214
    fi
  elif ((used_pct >= 85)); then
    msg_warn "Storage '${storage}' (${storage_type}) is ${used_pct}% full (${free_gb_fmt} free)"
  fi

  return 0
}
create_lxc_container() {
  # ------------------------------------------------------------------------------
  # Optional verbose mode (debug tracing)
  # ------------------------------------------------------------------------------
  if [[ "${CREATE_LXC_VERBOSE:-no}" == "yes" ]]; then set -x; fi

  # ------------------------------------------------------------------------------
  # Helpers (dynamic versioning / template parsing)
  # ------------------------------------------------------------------------------
  pkg_ver() { dpkg-query -W -f='${Version}\n' "$1" 2>/dev/null || echo ""; }
  pkg_cand() { apt-cache policy "$1" 2>/dev/null | awk '/Candidate:/ {print $2}'; }

  ver_ge() { dpkg --compare-versions "$1" ge "$2"; }
  ver_gt() { dpkg --compare-versions "$1" gt "$2"; }
  ver_lt() { dpkg --compare-versions "$1" lt "$2"; }

  # Extract Debian OS minor from template name: debian-13-standard_13.1-1_amd64.tar.zst => "13.1"

  # Switch to the previous OS major version template and retry pct create
  fallback_to_previous_os_version() {
    local old_template="$TEMPLATE"
    local os_type="${PCT_OSTYPE:-}"
    local current_ver="${PCT_OSVERSION:-}"

    local tpl_pattern=""
    case "$os_type" in
    debian | ubuntu) tpl_pattern="-standard_" ;;
    alpine | fedora | rocky | centos) tpl_pattern="-default_" ;;
    *) tpl_pattern="" ;;
    esac

    msg_info "Searching for an older $os_type template (current: $os_type $current_ver)"

    local -a all_versions=()
    mapfile -t _local_vers < <(
      pveam list "$TEMPLATE_STORAGE" 2>/dev/null |
        awk -v os="$os_type" -v pat="$tpl_pattern" '$1 ~ ("^"os"|/"os) && $1 ~ pat {print $1}' |
        sed 's|.*/||' |
        sed -E "s/^${os_type}-([0-9]+(\.[0-9]+)?).*/\1/" |
        sort -u -V || true
    )
    all_versions+=("${_local_vers[@]}")

    _pveam_update || true
    mapfile -t _online_vers < <(
      _pveam_available |
        awk '{print $2}' |
        grep -E "^${os_type}-[0-9]" |
        { [[ -n "$tpl_pattern" ]] && grep "$tpl_pattern" || cat; } |
        sed -E "s/^${os_type}-([0-9]+(\.[0-9]+)?).*/\1/" |
        sort -u -V 2>/dev/null || true
    )
    all_versions+=("${_online_vers[@]}")

    local fallback_ver=""
    fallback_ver=$(printf '%s\n' "${all_versions[@]}" | sort -u -V | awk -v cur="$current_ver" '{
      split($0, a, ".")
      split(cur, b, ".")
      if (a[1]+0 < b[1]+0) ver=$0
    } END { if (ver) print ver }')

    if [[ -z "$fallback_ver" ]]; then
      msg_error "No older $os_type template version found."
      return 1
    fi

    msg_ok "Fallback version: $os_type $fallback_ver"

    local fallback_search="${os_type}-${fallback_ver}"
    local fallback_template=""
    mapfile -t _fb_local < <(
      pveam list "$TEMPLATE_STORAGE" 2>/dev/null |
        awk -v search="$fallback_search" -v pat="$tpl_pattern" '$1 ~ search && $1 ~ pat {print $1}' |
        sed 's|.*/||' | sort -t - -k 2 -V || true
    )
    if [[ ${#_fb_local[@]} -gt 0 ]]; then
      fallback_template="${_fb_local[-1]}"
    else
      mapfile -t _fb_online < <(
        _pveam_available |
          awk '{print $2}' |
          grep -E "^${fallback_search}.*${tpl_pattern}" |
          sort -t - -k 2 -V 2>/dev/null || true
      )
      [[ ${#_fb_online[@]} -gt 0 ]] && fallback_template="${_fb_online[-1]}"
    fi

    if [[ -z "$fallback_template" ]]; then
      msg_error "No template found for $os_type $fallback_ver."
      return 1
    fi

    msg_ok "Found template: $fallback_template"

    local fallback_path
    fallback_path="$(pvesm path "$TEMPLATE_STORAGE:vztmpl/$fallback_template" 2>/dev/null || true)"
    [[ -z "$fallback_path" ]] && fallback_path="/var/lib/vz/template/cache/$fallback_template"

    if [[ ! -f "$fallback_path" ]]; then
      msg_info "Downloading $os_type $fallback_ver template"
      if ! pveam download "$TEMPLATE_STORAGE" "$fallback_template" >>"${BUILD_LOG:-/dev/null}" 2>&1; then
        msg_error "Failed to download $os_type $fallback_ver template."
        return 1
      fi
      msg_ok "Template downloaded"
    fi

    TEMPLATE="$fallback_template"
    TEMPLATE_PATH="$fallback_path"
    PCT_OSVERSION="$fallback_ver"
    export PCT_OSVERSION

    msg_info "Retrying container creation with $os_type $fallback_ver"
    if _pct_create "$CTID" "${TEMPLATE_STORAGE}:vztmpl/${TEMPLATE}" $PCT_OPTIONS ${_PW_ARGS[@]+"${_PW_ARGS[@]}"} >>"$LOGFILE" 2>&1; then
      msg_ok "Container created successfully with $os_type $fallback_ver (fallback from $old_template)."
      return 0
    else
      msg_error "Container creation with $os_type $fallback_ver also failed. See $LOGFILE"
      return 1
    fi
  }

  # Offer upgrade for pve-container/lxc-pve if candidate > installed; optional auto-retry pct create
  # Returns:
  #   0 = no upgrade needed / container created after upgrade or explicit fallback
  #   1 = upgraded (and if do_retry=yes and retry succeeded, creation done)
  #   2 = user chose ignore
  #   3 = upgrade attempted but failed OR retry failed
  #   4 = user cancelled
  offer_lxc_stack_upgrade_and_maybe_retry() {
    local do_retry="${1:-no}" # yes|no
    local _pvec_i _pvec_c _lxcp_i _lxcp_c need=0
    local _ans

    has_previous_os_version_template() {
      local os_type="${PCT_OSTYPE:-}"
      local current_ver="${PCT_OSVERSION:-}"
      local tpl_pattern="${TEMPLATE_PATTERN:-${TEMPLATE:-}}"
      local -a all_versions=()

      [[ -n "$os_type" && -n "$current_ver" ]] || return 1

      mapfile -t _local_vers < <(
        pveam list "$TEMPLATE_STORAGE" 2>/dev/null |
          awk '{print $1}' |
          sed 's|.*/||' |
          grep -E "^${os_type}-[0-9]" |
          { [[ -n "$tpl_pattern" ]] && grep "$tpl_pattern" || cat; } |
          sed -E "s/^${os_type}-([0-9]+(\.[0-9]+)?).*/\1/" |
          sort -u -V || true
      )
      all_versions+=("${_local_vers[@]}")

      _pveam_update || true
      mapfile -t _online_vers < <(
        _pveam_available |
          awk '{print $2}' |
          grep -E "^${os_type}-[0-9]" |
          { [[ -n "$tpl_pattern" ]] && grep "$tpl_pattern" || cat; } |
          sed -E "s/^${os_type}-([0-9]+(\.[0-9]+)?).*/\1/" |
          sort -u -V 2>/dev/null || true
      )
      all_versions+=("${_online_vers[@]}")

      printf '%s\n' "${all_versions[@]}" | sort -u -V | awk -v cur="$current_ver" '
        {
          split($0, a, ".")
          split(cur, b, ".")
          if (a[1]+0 < b[1]+0) found=1
        }
        END { exit found ? 0 : 1 }
      '
    }

    _pvec_i="$(pkg_ver pve-container)"
    _lxcp_i="$(pkg_ver lxc-pve)"
    _pvec_c="$(pkg_cand pve-container)"
    _lxcp_c="$(pkg_cand lxc-pve)"

    if [[ -n "$_pvec_c" && "$_pvec_c" != "none" ]]; then
      ver_gt "$_pvec_c" "${_pvec_i:-0}" && need=1
    fi
    if [[ -n "$_lxcp_c" && "$_lxcp_c" != "none" ]]; then
      ver_gt "$_lxcp_c" "${_lxcp_i:-0}" && need=1
    fi
    if [[ $need -eq 0 ]]; then
      msg_debug "No newer candidate for pve-container/lxc-pve (installed=$_pvec_i/$_lxcp_i, cand=$_pvec_c/$_lxcp_c)"
      return 5
    fi

    local _disable_update="${DISABLE_UPDATE:-no}"
    if [[ "${PHS_SILENT:-0}" == "1" || "${_disable_update,,}" == "yes" ]]; then
      msg_info "Skipping host LXC stack upgrade prompt (unattended mode)"
      return 2
    fi

    msg_warn "An update for the Proxmox LXC stack is available"
    echo "  pve-container: installed=${_pvec_i:-n/a}  candidate=${_pvec_c:-n/a}"
    echo "  lxc-pve     : installed=${_lxcp_i:-n/a}  candidate=${_lxcp_c:-n/a}"
    echo "  note        : option 1 runs host apt update + apt dist-upgrade"
    echo

    local _has_fallback_option=false
    if [[ "$do_retry" == "yes" ]] && has_previous_os_version_template; then
      _has_fallback_option=true
      echo "  [1] Run host upgrade now (recommended). WARNING: this runs apt dist-upgrade and updates all packages on your host!"
      echo "  [2] Use an older ${PCT_OSTYPE} template instead (may not work with all scripts)"
      echo "  [3] Ignore (continue without upgrading)"
      echo "  [4] Cancel (abort the script)"
      echo
      read -rp "Select option [1/2/3/4]: " _ans </dev/tty
    else
      echo "  [1] Run host upgrade now (recommended). WARNING: this runs apt dist-upgrade and updates all packages on your host!"
      echo "  [2] Ignore (continue without upgrading)"
      echo "  [3] Cancel (abort the script)"
      echo
      read -rp "Select option [1/2/3]: " _ans </dev/tty
    fi

    if [[ "$_has_fallback_option" == true ]]; then
      case "$_ans" in
      1) _ans="y" ;;
      2)
        if fallback_to_previous_os_version; then
          return 0
        else
          return 3
        fi
        ;;
      3) return 2 ;;
      4) return 4 ;;
      *) return 2 ;;
      esac
    else
      case "$_ans" in
      1) _ans="y" ;;
      2) return 2 ;;
      3) return 4 ;;
      *) return 2 ;;
      esac
    fi

    case "${_ans,,}" in
    y | yes)
      msg_info "Running host upgrade for LXC stack compatibility"
      apt_update_safe
      if DEBIAN_FRONTEND=noninteractive $STD apt-get -o Dpkg::Options::=--force-confdef -o Dpkg::Options::=--force-confold dist-upgrade -y; then
        msg_ok "LXC stack upgraded."
        if ! pct list &>/dev/null; then
          msg_error "LXC stack upgrade caused PVE tool breakage (likely Perl module incompatibility)."
          msg_custom "⚠️" "${YW}" "A partial package upgrade has left the PVE stack in an inconsistent state."
          msg_custom "🔧" "${YW}" "Please run the following on the Proxmox host, then retry:"
          echo -e "${TAB}  apt update && apt dist-upgrade -y"
          echo -e "${TAB}  reboot"
          return 3
        fi
        if [[ "$do_retry" == "yes" ]]; then
          msg_info "Retrying container creation after upgrade"
          if _pct_create "$CTID" "${TEMPLATE_STORAGE}:vztmpl/${TEMPLATE}" $PCT_OPTIONS ${_PW_ARGS[@]+"${_PW_ARGS[@]}"} >>"$LOGFILE" 2>&1; then
            msg_ok "Container created successfully after upgrade."
            return 0
          else
            msg_error "pct create still failed after upgrade. See $LOGFILE"
            return 3
          fi
        fi
        return 1
      else
        msg_error "Upgrade failed. Please check APT output."
        return 3
      fi
      ;;
    *) return 2 ;;
    esac
  }

  ARCH="$(dpkg --print-architecture)"

  # Maps OS type + version to the release variant name used by ARM64 template sources.
  arm64_template_variant() {
    case "$1:$2" in
    debian:12) echo "bookworm" ;;
    debian:13) echo "trixie" ;;
    debian:) echo "$DEBIAN_DEFAULT_CODENAME" ;;

    ubuntu:24.04) echo "noble" ;;
    ubuntu:26.04) echo "questing" ;;
    ubuntu:) echo "$UBUNTU_DEFAULT_CODENAME" ;;

    alpine:*) echo "${2:-$ALPINE_DEFAULT_VERSION}" ;;

    *) return 1 ;;
    esac
  }

  # Downloads an ARM64 LXC rootfs template to $1.
  # Does Proxmox offer this OS/version/arch? Local first, then the catalog.
  _pveam_offers_template() {
    local search pattern
    search="${PCT_OSTYPE}-${PCT_OSVERSION:-}"
    case "$PCT_OSTYPE" in
    debian | ubuntu) pattern="-standard_" ;;
    alpine | fedora | rocky | centos) pattern="-default_" ;;
    *) pattern="" ;;
    esac

    if pveam list "$TEMPLATE_STORAGE" 2>/dev/null |
      awk -v s="$search" -v p="$pattern" -v a="$ARCH" \
        '$1 ~ s && $1 ~ p && $1 ~ ("_" a "\\.(tar\\.zst|tar\\.xz|tar\\.gz)$") {found=1}
         END {exit !found}'; then
      return 0
    fi

    _pveam_update >/dev/null 2>&1 || true
    _pveam_available |
      grep -E "_${ARCH}\.(tar\.zst|tar\.xz|tar\.gz)([[:space:]]|$)" |
      awk '{print $2}' |
      grep -qE "^${search}.*${pattern}"
  }

  # Only reached when pveam has nothing for this arch.
  download_arm64_template() {
    local dest="$1" url

    mkdir -p "$(dirname "$dest")" || {
      msg_error "Cannot create template dir."
      exit 217
    }

    url="https://jenkins.linuxcontainers.org/job/image-${PCT_OSTYPE}/architecture=arm64,release=${CUSTOM_TEMPLATE_VARIANT},variant=default/lastStableBuild/artifact/rootfs.tar.xz"

    msg_info "Downloading ${PCT_OSTYPE^} ${CUSTOM_TEMPLATE_VARIANT} ARM64 template"
    local patched="${dest%/*}/.${dest##*/}.patched"
    (
      flock -x 200
      if [[ -f "$patched" ]] && [[ -s "$dest" ]] && xz -t "$dest" 2>/dev/null; then
        exit 0
      fi
      if ! curl -fsSL -o "$dest" "$url"; then
        msg_error "Failed to download ARM64 template from: $url"
        exit 208
      fi
      if ! tar -tJf "$dest" 2>/dev/null | grep -q '/etc/network/$'; then
        fixdir=$(mktemp -d)
        tmptar="${dest%.xz}"
        mkdir -p "$fixdir/etc/network"
        : >"$fixdir/etc/network/interfaces"
        if xz -d -f "$dest" && tar -C "$fixdir" --append -f "$tmptar" ./etc/network && xz -1 -f "$tmptar"; then
          rm -rf "$fixdir"
        else
          rm -rf "$fixdir" "$tmptar"
          msg_error "Failed to patch ARM64 template (missing /etc/network)"
          exit 208
        fi
      fi
      touch "$patched"
    ) 200>"${dest}.lock"
    local dl_rc=$?
    if [[ $dl_rc -ne 0 ]]; then
      exit "$dl_rc"
    fi
    msg_ok "Downloaded ARM64 LXC template"
  }

  download_template() {
    local dest="${1:-$TEMPLATE_PATH}"
    if [[ "$ARCH" == "arm64" ]]; then
      download_arm64_template "$dest"
    else
      pveam download "$TEMPLATE_STORAGE" "$TEMPLATE" >>"${BUILD_LOG:-/dev/null}" 2>&1 || {
        msg_error "Failed to download template '$TEMPLATE' to storage '$TEMPLATE_STORAGE'"
        exit 222
      }
    fi
  }

  # ------------------------------------------------------------------------------
  # Required input variables
  # ------------------------------------------------------------------------------
  [[ "${CTID:-}" ]] || {
    msg_error "You need to set 'CTID' variable."
    exit 203
  }
  [[ "${PCT_OSTYPE:-}" ]] || {
    msg_error "You need to set 'PCT_OSTYPE' variable."
    exit 204
  }

  msg_debug "CTID=$CTID"
  msg_debug "PCT_OSTYPE=$PCT_OSTYPE"
  msg_debug "PCT_OSVERSION=${PCT_OSVERSION:-default}"

  # ID checks
  [[ "$CTID" -ge 100 ]] || {
    msg_error "ID cannot be less than 100."
    exit 205
  }
  if qm status "$CTID" &>/dev/null || pct status "$CTID" &>/dev/null; then
    msg_warn "Container/VM ID $CTID is already in use (detected late). Reassigning..."
    CTID=$(get_valid_container_id "$((CTID + 1))")
    export CTID
    msg_ok "Reassigned to container ID $CTID"
  fi

  # Report installation start to API early - captures failures in storage/template/create
  post_to_api

  # Transition to 'validation' — Proxmox-internal checks (storage, template, cluster)
  post_progress_to_api "validation"

  # Storage capability check
  check_storage_support "rootdir" || {
    msg_error "No valid storage found for 'rootdir' [Container]"
    exit 119
  }
  check_storage_support "vztmpl" || {
    msg_error "No valid storage found for 'vztmpl' [Template]"
    exit 120
  }

  # Template storage selection
  if resolve_storage_preselect template "${TEMPLATE_STORAGE:-}"; then
    TEMPLATE_STORAGE="$STORAGE_RESULT"
    TEMPLATE_STORAGE_INFO="$STORAGE_INFO"
    msg_ok "Storage ${BL}${TEMPLATE_STORAGE}${CL} (${TEMPLATE_STORAGE_INFO}) [Template]"
  else
    _storage_preselect_recover template "${TEMPLATE_STORAGE:-}" || exit 120
    TEMPLATE_STORAGE="$STORAGE_RESULT"
    TEMPLATE_STORAGE_INFO="$STORAGE_INFO"
    msg_ok "Storage ${BL}${TEMPLATE_STORAGE}${CL} (${TEMPLATE_STORAGE_INFO}) [Template]"
  fi

  # Container storage selection
  if resolve_storage_preselect container "${CONTAINER_STORAGE:-}"; then
    CONTAINER_STORAGE="$STORAGE_RESULT"
    CONTAINER_STORAGE_INFO="$STORAGE_INFO"
    msg_ok "Storage ${BL}${CONTAINER_STORAGE}${CL} (${CONTAINER_STORAGE_INFO}) [Container]"
  else
    _storage_preselect_recover container "${CONTAINER_STORAGE:-}" || exit 119
    CONTAINER_STORAGE="$STORAGE_RESULT"
    CONTAINER_STORAGE_INFO="$STORAGE_INFO"
    msg_ok "Storage ${BL}${CONTAINER_STORAGE}${CL} (${CONTAINER_STORAGE_INFO}) [Container]"
  fi

  msg_info "Validating storage '$CONTAINER_STORAGE'"
  if [[ ! -f /etc/pve/storage.cfg ]]; then
    if ! mountpoint -q /etc/pve 2>/dev/null; then
      msg_error "Proxmox cluster filesystem (pmxcfs) is not mounted at /etc/pve."
      msg_custom "🔧" "${YW}" "Try: systemctl restart pve-cluster"
    else
      msg_error "/etc/pve/storage.cfg does not exist."
      msg_custom "🔧" "${YW}" "Check Proxmox cluster filesystem integrity: pvecm status"
    fi
    exit 228
  fi

  STORAGE_TYPE=$(grep -E "^[^:]+:[[:space:]]*${CONTAINER_STORAGE}[[:space:]]*$" /etc/pve/storage.cfg | cut -d: -f1 | head -1 || true)
  if [[ -z "$STORAGE_TYPE" ]]; then
    STORAGE_TYPE=$(pvesm status -storage "$CONTAINER_STORAGE" 2>/dev/null | awk 'NR>1{print $2}')
  fi

  if [[ -z "$STORAGE_TYPE" ]]; then
    msg_error "Storage '$CONTAINER_STORAGE' not found in /etc/pve/storage.cfg"
    msg_custom "📋" "${YW}" "Available storages: $(pvesm status 2>/dev/null | awk 'NR>1{printf \"%s (%s) \", $1, $2}' || echo 'n/a')"
    if [[ -r /etc/pve/storage.cfg ]]; then
      msg_custom "📋" "${YW}" "Storage definitions found in config:"
      grep -E '^[a-z]+:' /etc/pve/storage.cfg 2>/dev/null | while IFS= read -r _line; do
        echo "${TAB}  $_line"
      done
    fi
    msg_custom "📖" "${YW}" "See https://pve.proxmox.com/wiki/Storage for storage configuration details."
    exit 213
  fi

  case "$STORAGE_TYPE" in
  iscsidirect)
    msg_error "Storage '$CONTAINER_STORAGE' uses iSCSI-direct which does not support container rootfs."
    exit 212
    ;;
  iscsi | zfs)
    msg_error "Storage '$CONTAINER_STORAGE' ($STORAGE_TYPE) does not support container rootdir content."
    exit 213
    ;;
  cephfs)
    msg_error "Storage '$CONTAINER_STORAGE' uses CephFS which is not supported for LXC rootfs."
    exit 219
    ;;
  pbs)
    msg_error "Storage '$CONTAINER_STORAGE' is a Proxmox Backup Server — cannot be used for containers."
    exit 224
    ;;
  linstor | rbd | nfs | cifs)
    if ! pvesm status -storage "$CONTAINER_STORAGE" &>/dev/null; then
      msg_error "Storage '$CONTAINER_STORAGE' ($STORAGE_TYPE) is not accessible or inactive."
      exit 217
    fi
    ;;
  esac

  if ! pvesm status -content rootdir 2>/dev/null | awk 'NR>1{print $1}' | grep -qx "$CONTAINER_STORAGE"; then
    msg_error "Storage '$CONTAINER_STORAGE' ($STORAGE_TYPE) does not support 'rootdir' content."
    msg_custom "💡" "${YW}" "Enable 'Disk image' (rootdir) for storage '${CONTAINER_STORAGE}' in:"
    msg_custom "   " "${YW}" "Datacenter → Storage → ${CONTAINER_STORAGE} → Edit → Content"
    msg_custom "📖" "${YW}" "See: https://pve.proxmox.com/wiki/Storage"
    msg_custom "🔗" "${YW}" "Help: https://github.com/community-scripts/ProxmoxVE/discussions"
    exit 213
  fi
  if [[ "$STORAGE_TYPE" == "lvmthin" ]] && ! _lvmthin_check "$CONTAINER_STORAGE"; then
    exit 214
  fi
  msg_ok "Storage '$CONTAINER_STORAGE' ($STORAGE_TYPE) validated"

  msg_info "Validating template storage '$TEMPLATE_STORAGE'"
  TEMPLATE_TYPE=$(grep -E "^[^:]+: $TEMPLATE_STORAGE$" /etc/pve/storage.cfg | cut -d: -f1 || true)

  if ! pvesm status -content vztmpl 2>/dev/null | awk 'NR>1{print $1}' | grep -qx "$TEMPLATE_STORAGE"; then
    msg_warn "Template storage '$TEMPLATE_STORAGE' may not support 'vztmpl'"
  fi
  msg_ok "Template storage '$TEMPLATE_STORAGE' validated"

  # Cluster quorum (if cluster)
  if [[ -f /etc/pve/corosync.conf ]]; then
    msg_info "Checking cluster quorum"
    if ! pvecm status | awk -F':' '/^Quorate/ { exit ($2 ~ /Yes/) ? 0 : 1 }'; then
      msg_error "Cluster is not quorate. Start all nodes or configure quorum device (QDevice)."
      exit 210
    fi
    msg_ok "Cluster is quorate"
  fi

  # ------------------------------------------------------------------------------
  # Template discovery & validation
  # ------------------------------------------------------------------------------
  CUSTOM_TEMPLATE_VARIANT=""

  if [[ "$ARCH" == "arm64" ]] && ! _pveam_offers_template; then
    msg_info "No Proxmox template for ${PCT_OSTYPE} on ${ARCH}, using linuxcontainers.org"

    CUSTOM_TEMPLATE_VARIANT=$(arm64_template_variant "$PCT_OSTYPE" "${PCT_OSVERSION:-}") || {
      msg_error "No ARM64 template mapping for ${PCT_OSTYPE} ${PCT_OSVERSION:-latest}"
      exit 225
    }

    TEMPLATE="${PCT_OSTYPE}-${CUSTOM_TEMPLATE_VARIANT}-rootfs.tar.xz"
    TEMPLATE_SOURCE="custom-arm64"

    # Resolve template path
    TEMPLATE_PATH="$(pvesm path "${TEMPLATE_STORAGE}:vztmpl/${TEMPLATE}" 2>/dev/null || true)"
    if [[ -z "$TEMPLATE_PATH" ]]; then
      local _tpl_base
      _tpl_base=$(awk -v s="$TEMPLATE_STORAGE" '
        $0 ~ "^[^:]+:[[:space:]]*" s "$" {f=1; next}
        f && /^[^[:space:]]/ {f=0}
        f && $1 == "path" {print $2; exit}
      ' /etc/pve/storage.cfg)
      TEMPLATE_PATH="${_tpl_base:-/var/lib/vz}/template/cache/$TEMPLATE"
    fi

    # Download if missing, too small, or corrupt
    if [[ ! -f "$TEMPLATE_PATH" ]]; then
      download_arm64_template "$TEMPLATE_PATH"
    elif [[ "$(stat -c%s "$TEMPLATE_PATH")" -lt 1000000 ]] || ! tar -tf "$TEMPLATE_PATH" &>/dev/null; then
      msg_warn "Local template invalid - re-downloading."
      rm -f "$TEMPLATE_PATH"
      download_arm64_template "$TEMPLATE_PATH"
    else
      msg_ok "Template ${BL}$TEMPLATE${CL} found locally."
    fi

  else
    TEMPLATE_SEARCH="${PCT_OSTYPE}-${PCT_OSVERSION:-}"
    case "$PCT_OSTYPE" in
    debian | ubuntu) TEMPLATE_PATTERN="-standard_" ;;
    alpine | fedora | rocky | centos) TEMPLATE_PATTERN="-default_" ;;
    *) TEMPLATE_PATTERN="" ;;
    esac

    msg_info "Searching for template '$TEMPLATE_SEARCH'"

    # Initialize variables
    ONLINE_TEMPLATE=""
    ONLINE_TEMPLATES=()

    # Step 1: Check local templates first (instant)
    mapfile -t LOCAL_TEMPLATES < <(
      pveam list "$TEMPLATE_STORAGE" 2>/dev/null |
        awk -v search="${TEMPLATE_SEARCH}" -v pattern="${TEMPLATE_PATTERN}" -v arch="${ARCH}" \
          '$1 ~ search && $1 ~ pattern && $1 ~ ("_" arch "\\.(tar\\.zst|tar\\.xz|tar\\.gz)$") {print $1}' |
        sed 's|.*/||' | sort -t - -k 2 -V || true
    )

    # Step 2: If local template found, use it immediately (skip pveam update)
    if [[ ${#LOCAL_TEMPLATES[@]} -gt 0 ]]; then
      TEMPLATE="${LOCAL_TEMPLATES[-1]}"
      TEMPLATE_SOURCE="local"
      msg_ok "Template search completed"
    else
      # Step 3: No local template - need to check online (this may be slow)
      msg_info "No local template found, checking online catalog..."

      # Update catalog with timeout to prevent long hangs
      if command -v timeout &>/dev/null; then
        if ! _pveam_update; then
          msg_warn "Template catalog update timed out (possible network/DNS issue). Run 'pveam update' manually to diagnose."
        fi
      else
        _pveam_update || msg_warn "Could not update template catalog (pveam update failed)"
      fi

      ONLINE_TEMPLATES=()
      mapfile -t ONLINE_TEMPLATES < <(_list_templates "$TEMPLATE_SEARCH" "$TEMPLATE_PATTERN")
      [[ ${#ONLINE_TEMPLATES[@]} -gt 0 ]] && ONLINE_TEMPLATE="${ONLINE_TEMPLATES[-1]}"

      TEMPLATE="$ONLINE_TEMPLATE"
      TEMPLATE_SOURCE="online"
      msg_ok "Template search completed"
    fi

    # resolve_os_version() already validated the version, so this means the
    # variant (TEMPLATE_PATTERN) is missing - a catalog issue in unattended mode.
    # Interactively, we still allow selecting another available version.
    if [[ -z "$TEMPLATE" ]]; then
      if is_unattended; then
        msg_error "No ${TEMPLATE_PATTERN#-} template found for ${PCT_OSTYPE} ${PCT_OSVERSION}"
        msg_custom "ℹ️" "${YW}" "Refresh the catalog and check what this host offers:"
        echo -e "${TAB}  pveam update && pveam available -section system | grep '${PCT_OSTYPE}-'"
        exit 225
      fi

      # Build the list before offering a choice: pveam carries no template at all
      # for some distros, and announcing "select a different version" first left
      # the user reading an offer that was never going to appear.
      AVAILABLE_VERSIONS=()
      mapfile -t AVAILABLE_VERSIONS < <(
        _pveam_available |
          grep -E '\.(tar\.zst|tar\.xz|tar\.gz)$' |
          awk -F'\t' '{print $1}' |
          grep "^${PCT_OSTYPE}-" |
          sed -E "s/.*${PCT_OSTYPE}-([0-9]+(\.[0-9]+)?).*/\1/" |
          sort -u -V 2>/dev/null || true
      )

      if [[ ${#AVAILABLE_VERSIONS[@]} -gt 0 ]]; then
        msg_warn "No ${TEMPLATE_PATTERN#-} template found for ${PCT_OSTYPE} ${PCT_OSVERSION}"
        msg_custom "ℹ️" "${YW}" "Select a different available version or press Enter to cancel."

        echo ""
        echo "${BL}Available ${PCT_OSTYPE} versions:${CL}"
        for i in "${!AVAILABLE_VERSIONS[@]}"; do
          echo "  [$((i + 1))] ${AVAILABLE_VERSIONS[$i]}"
        done
        echo ""

        choice=""
        read -r -p "Select version [1-${#AVAILABLE_VERSIONS[@]}] or press Enter to cancel: " choice </dev/tty || choice=""

        if [[ "$choice" =~ ^[0-9]+$ ]] && [[ "$choice" -ge 1 ]] && [[ "$choice" -le ${#AVAILABLE_VERSIONS[@]} ]]; then
          PCT_OSVERSION="${AVAILABLE_VERSIONS[$((choice - 1))]}"
          var_version="$PCT_OSVERSION"
          export PCT_OSVERSION var_version
          TEMPLATE_SEARCH="${PCT_OSTYPE}-${PCT_OSVERSION}"

          mapfile -t LOCAL_TEMPLATES < <(
            pveam list "$TEMPLATE_STORAGE" 2>/dev/null |
                awk -v search="${TEMPLATE_SEARCH}-" -v pattern="${TEMPLATE_PATTERN}" -v arch="${ARCH}" \
                  '$1 ~ search && $1 ~ pattern && $1 ~ ("_" arch "\\.(tar\\.zst|tar\\.xz|tar\\.gz)$") {print $1}' |
              sed 's|.*/||' | sort -t - -k 2 -V || true
          )
          mapfile -t ONLINE_TEMPLATES < <(
            _pveam_available |
              grep -E "_${ARCH}\.(tar\.zst|tar\.xz|tar\.gz)([[:space:]]|$)" |
              awk '{print $2}' |
              grep -E "^${TEMPLATE_SEARCH}-.*${TEMPLATE_PATTERN}" |
              sort -t - -k 2 -V 2>/dev/null || true
          )
          ONLINE_TEMPLATE=""
          [[ ${#ONLINE_TEMPLATES[@]} -gt 0 ]] && ONLINE_TEMPLATE="${ONLINE_TEMPLATES[-1]}"

          if [[ ${#LOCAL_TEMPLATES[@]} -gt 0 ]]; then
            TEMPLATE="${LOCAL_TEMPLATES[-1]}"
            TEMPLATE_SOURCE="local"
          else
            TEMPLATE="$ONLINE_TEMPLATE"
            TEMPLATE_SOURCE="online"
          fi

          if [[ -z "$TEMPLATE" ]]; then
            msg_error "No ${TEMPLATE_PATTERN#-} template found for ${PCT_OSTYPE} ${PCT_OSVERSION}"
            exit 225
          fi
        else
          msg_custom "🚫" "${YW}" "Installation cancelled"
          exit 0
        fi
      else
        msg_error "Proxmox offers no ${PCT_OSTYPE} template for ${ARCH}"
        msg_custom "ℹ️" "${YW}" "Check what this host offers:"
        echo -e "${TAB}  pveam update && pveam available -section system | grep '${PCT_OSTYPE}-'"
        exit 225
      fi
    fi

    TEMPLATE_PATH="$(pvesm path $TEMPLATE_STORAGE:vztmpl/$TEMPLATE 2>/dev/null || true)"
    if [[ -z "$TEMPLATE_PATH" ]]; then
      TEMPLATE_BASE=$(awk -v s="$TEMPLATE_STORAGE" '$1==s {f=1} f && /path/ {print $2; exit}' /etc/pve/storage.cfg)
      [[ -n "$TEMPLATE_BASE" ]] && TEMPLATE_PATH="$TEMPLATE_BASE/template/cache/$TEMPLATE"
    fi

    # If we still don't have a path but have a valid template name, construct it
    if [[ -z "$TEMPLATE_PATH" && -n "$TEMPLATE" ]]; then
      TEMPLATE_PATH="/var/lib/vz/template/cache/$TEMPLATE"
    fi

    [[ -n "$TEMPLATE_PATH" ]] || {
      msg_error "Could not resolve a storage path for template ${TEMPLATE}"
      exit 220
    }

    if [[ -z "$TEMPLATE" ]]; then
      msg_error "No ${TEMPLATE_PATTERN#-} template found for ${PCT_OSTYPE} ${PCT_OSVERSION}"
      msg_custom "ℹ️" "${YW}" "Refresh the catalog and check what this host offers:"
      echo -e "${TAB}  pveam update && pveam available -section system | grep '${PCT_OSTYPE}-'"
      exit 225
    fi

    msg_ok "Template ${BL}$TEMPLATE${CL} [$TEMPLATE_SOURCE]"
    msg_debug "Resolved TEMPLATE_PATH=$TEMPLATE_PATH"

    NEED_DOWNLOAD=0
    if [[ ! -f "$TEMPLATE_PATH" ]]; then
      msg_info "Template not present locally – will download."
      NEED_DOWNLOAD=1
    elif [[ ! -r "$TEMPLATE_PATH" ]]; then
      msg_error "Template file exists but is not readable – check permissions."
      exit 221
    elif [[ "$(stat -c%s "$TEMPLATE_PATH")" -lt 1000000 ]]; then
      if [[ -n "$ONLINE_TEMPLATE" ]]; then
        msg_warn "Template file too small (<1MB) – re-downloading."
        NEED_DOWNLOAD=1
      else
        msg_warn "Template looks too small, but no online version exists. Keeping local file."
      fi
    elif ! tar -tf "$TEMPLATE_PATH" &>/dev/null; then
      if [[ -n "$ONLINE_TEMPLATE" ]]; then
        msg_warn "Template appears corrupted – re-downloading."
        NEED_DOWNLOAD=1
      else
        msg_warn "Template appears corrupted, but no online version exists. Keeping local file."
      fi
    else
      $STD msg_ok "Template $TEMPLATE is present and valid."
    fi

    if [[ "$TEMPLATE_SOURCE" == "local" && -n "$ONLINE_TEMPLATE" && "$TEMPLATE" != "$ONLINE_TEMPLATE" ]]; then
      msg_warn "Local template is outdated: $TEMPLATE (latest available: $ONLINE_TEMPLATE)"
      if whiptail --yesno "A newer template is available:\n$ONLINE_TEMPLATE\n\nDo you want to download and use it instead?" 12 70; then
        TEMPLATE="$ONLINE_TEMPLATE"
        TEMPLATE_PATH="$(_template_path "$TEMPLATE")"
        NEED_DOWNLOAD=1
      else
        msg_custom "ℹ️" "${BL}" "Continuing with local template $TEMPLATE"
      fi
    fi

    if [[ "$NEED_DOWNLOAD" -eq 1 ]]; then
      # Belt and braces. Every path above that leaves TEMPLATE empty is supposed
      # to have exited already, but one of them did not, and `pveam download
      # local ""` was retried three times with backoff before reporting a
      # generic failure. An empty name is never worth a single attempt.
      if [[ -z "$TEMPLATE" ]]; then
        msg_error "No template name resolved for ${PCT_OSTYPE} ${PCT_OSVERSION} — refusing to download"
        msg_custom "ℹ️" "${YW}" "Check what this host offers:"
        echo -e "${TAB}  pveam update && pveam available -section system | grep '${PCT_OSTYPE}-'"
        exit 225
      fi
      [[ -f "$TEMPLATE_PATH" ]] && rm -f "$TEMPLATE_PATH"
      local _dl_out="" _fresh=""
      for attempt in {1..3}; do
        msg_info "Attempt $attempt: Downloading template $TEMPLATE to $TEMPLATE_STORAGE"
        _dl_out="$(pveam download "$TEMPLATE_STORAGE" "$TEMPLATE" 2>&1)" || true
        printf '%s\n' "$_dl_out" >>"${BUILD_LOG:-/dev/null}"
        # pveam can report a failed download and still exit 0, so only the
        # template in storage counts as success.
        if pveam list "$TEMPLATE_STORAGE" 2>/dev/null | grep -qF "$TEMPLATE"; then
          msg_ok "Template download successful."
          break
        fi
        # A catalog left over from a failed update can name a template the
        # server has replaced since. Refresh it and take the current one.
        if grep -q 'no such template' <<<"$_dl_out" && _pveam_update; then
          _fresh="$(_list_templates "$TEMPLATE_SEARCH" "$TEMPLATE_PATTERN" | tail -n1)"
          if [[ -n "$_fresh" && "$_fresh" != "$TEMPLATE" ]]; then
            msg_warn "$TEMPLATE is no longer offered, using $_fresh"
            TEMPLATE="$_fresh"
            TEMPLATE_PATH="$(_template_path "$TEMPLATE")"
          fi
        fi
        if [[ $attempt -eq 3 ]]; then
          _template_download_failed "$_dl_out"
          exit 222
        fi
        sleep $((attempt * 5))
      done
    fi

    if ! pveam list "$TEMPLATE_STORAGE" 2>/dev/null | grep -q "$TEMPLATE"; then
      msg_error "Template $TEMPLATE not available in storage $TEMPLATE_STORAGE after download."
      exit 223
    fi
  fi

  # ------------------------------------------------------------------------------
  # Create LXC Container
  # ------------------------------------------------------------------------------
  msg_info "Creating LXC container"

  # Ensure subuid/subgid entries exist
  grep -q "root:100000:65536" /etc/subuid || echo "root:100000:65536" >>/etc/subuid
  grep -q "root:100000:65536" /etc/subgid || echo "root:100000:65536" >>/etc/subgid

  # PCT_OPTIONS is now a string (exported from build_container)
  # Add rootfs if not already specified
  if [[ ! "$PCT_OPTIONS" =~ "-rootfs" ]]; then
    PCT_OPTIONS="$PCT_OPTIONS
  -rootfs $CONTAINER_STORAGE:${PCT_DISK_SIZE:-8}"
  fi

  # Lock by template file (avoid concurrent template downloads/validation)
  lockfile="/tmp/template.${TEMPLATE}.lock"

  # Cleanup stale lock files (older than 1 hour - likely from crashed processes)
  if [[ -f "$lockfile" ]]; then
    local lock_age=$(($(date +%s) - $(stat -c %Y "$lockfile" 2>/dev/null || echo 0)))
    if [[ $lock_age -gt 3600 ]]; then
      msg_warn "Removing stale template lock file (age: ${lock_age}s)"
      rm -f "$lockfile"
    fi
  fi

  exec 9>"$lockfile" || {
    msg_error "Failed to create lock file '$lockfile'."
    exit 200
  }

  # Retry logic for template lock (another container creation may be running)
  local lock_attempts=0
  local max_lock_attempts=10
  local lock_wait_time=30

  while ! flock -w "$lock_wait_time" 9; do
    lock_attempts=$((lock_attempts + 1))
    if [[ $lock_attempts -ge $max_lock_attempts ]]; then
      msg_error "Timeout while waiting for template lock after ${max_lock_attempts} attempts."
      msg_custom "💡" "${YW}" "Another container creation may be stuck. Check running processes or remove: $lockfile"
      exit 211
    fi
    msg_custom "⏳" "${YW}" "Another container is being created with this template. Waiting... (attempt ${lock_attempts}/${max_lock_attempts})"
  done

  LOGFILE="/tmp/pct_create_${CTID}_$(date +%Y%m%d_%H%M%S)_${SESSION_ID}.log"

  _flush_pct_log() {
    if [[ -s "${LOGFILE:-}" && -n "${BUILD_LOG:-}" ]]; then
      {
        echo ""
        echo "--- pct create output (${LOGFILE}) ---"
        cat "$LOGFILE"
        echo "--- end pct create output ---"
      } >>"$BUILD_LOG" 2>/dev/null || true
    fi
  }

  _lxc_stack_too_old() {
    msg_error "pve-container $(pkg_ver pve-container) does not support ${PCT_OSTYPE:-this} ${PCT_OSVERSION:-template}, and no newer version is available from the configured repositories."
    msg_custom "🔧" "${YW}" "Enable a Proxmox VE package repository, run 'apt update && apt dist-upgrade' on the host, then retry."
    msg_custom "💡" "${YW}" "Alternatively, choose an older ${PCT_OSTYPE:-OS} version in the advanced settings."
    _flush_pct_log
  }

  # Validate template before pct create (while holding lock)
  if [[ ! -s "$TEMPLATE_PATH" || "$(stat -c%s "$TEMPLATE_PATH" 2>/dev/null || echo 0)" -lt 1000000 ]]; then
    msg_info "Template file missing or too small – downloading"
    rm -f "$TEMPLATE_PATH"
    download_template
    msg_ok "Template downloaded"
  elif ! tar -tf "$TEMPLATE_PATH" &>/dev/null; then
    if [[ "$ARCH" == "arm64" || -n "$ONLINE_TEMPLATE" ]]; then
      msg_info "Template appears corrupted – re-downloading"
      rm -f "$TEMPLATE_PATH"
      download_template
      msg_ok "Template re-downloaded"
    else
      msg_warn "Template appears corrupted, but no online version exists. Skipping re-download."
    fi
  fi

  # openEuler templates are detected by PVE as ostype 'centos' but ship without
  # /etc/redhat-release, which makes PVE::LXC::Setup::post_create_hook abort with
  # "can't open '/etc/redhat-release' - No such file or directory".
  # Patch the cached template once to inject a CentOS-compatible release file.
  if [[ "${var_os:-}" == "openeuler" ]]; then
    if ! tar -tf "$TEMPLATE_PATH" 2>/dev/null | grep -qE '^\.?/?etc/redhat-release$'; then
      msg_info "Patching openEuler template (adding /etc/redhat-release)"
      local _oe_tmp
      _oe_tmp=$(mktemp -d) || _oe_tmp=""
      if [[ -n "$_oe_tmp" ]] && mkdir -p "$_oe_tmp/etc"; then
        # Content is parsed by PVE's CentOS setup plugin (expects "<name> release <ver>")
        local _oe_ver="${var_version:-25.03}"
        echo "CentOS Linux release ${_oe_ver} (openEuler)" >"$_oe_tmp/etc/redhat-release"
        if xz -dc "$TEMPLATE_PATH" >"$_oe_tmp/template.tar" 2>/dev/null &&
          tar -C "$_oe_tmp" --append -f "$_oe_tmp/template.tar" etc/redhat-release 2>/dev/null &&
          xz -f "$_oe_tmp/template.tar" 2>/dev/null &&
          mv -f "$_oe_tmp/template.tar.xz" "$TEMPLATE_PATH"; then
          msg_ok "Patched openEuler template"
        else
          msg_warn "Failed to patch openEuler template – pct create may fail in post_create_hook"
        fi
        rm -rf "$_oe_tmp"
      fi
    fi
  fi

  # Release lock after template validation - pct create has its own internal locking
  exec 9>&-

  # Without the password argument on purpose: this line goes to the log.
  msg_debug "pct create command (password omitted): pct create $CTID ${TEMPLATE_STORAGE}:vztmpl/${TEMPLATE} $PCT_OPTIONS"
  msg_debug "Logfile: $LOGFILE"

  # First attempt (PCT_OPTIONS is a multi-line string, use it directly)
  set -f
  if ! _pct_create "$CTID" "${TEMPLATE_STORAGE}:vztmpl/${TEMPLATE}" $PCT_OPTIONS ${_PW_ARGS[@]+"${_PW_ARGS[@]}"} >"$LOGFILE" 2>&1; then
    msg_debug "Container creation failed on ${TEMPLATE_STORAGE}. Checking error..."

    if grep -qiE 'Compilation failed|Bareword.*not allowed' "$LOGFILE"; then
      msg_error "Container creation failed due to broken Perl modules on the PVE host."
      msg_custom "⚠️" "${YW}" "This usually happens after a partial PVE package upgrade."
      msg_custom "🔧" "${YW}" "Please run the following on the Proxmox host, then retry:"
      echo -e "${TAB}  apt update && apt dist-upgrade -y"
      echo -e "${TAB}  reboot"
      _flush_pct_log
      exit 232
    fi

    # A rejected setting is not a broken template: re-downloading it and
    # retrying on local storage only ended in the same rejection.
    if grep -q 'Parameter verification failed' "$LOGFILE"; then
      msg_error "pct create rejected a setting:"
      grep -A6 'Parameter verification failed' "$LOGFILE" | grep -E '^[a-z0-9_]+: ' | while IFS= read -r _line; do
        echo -e "${TAB}- ${_line}"
      done
      msg_custom "🔧" "${YW}" "Fix it in the advanced settings or in the defaults file it came from, then retry."
      _flush_pct_log
      exit 208
    fi

    if grep -qiE 'already exists|already in use' "$LOGFILE"; then
      local old_ctid="$CTID"
      CTID=$(get_valid_container_id "$((CTID + 1))")
      export CTID
      msg_warn "Container ID $old_ctid was claimed by another process. Retrying with ID $CTID"
      LOGFILE="/tmp/pct_create_${CTID}_$(date +%Y%m%d_%H%M%S)_${SESSION_ID}.log"
      if _pct_create "$CTID" "${TEMPLATE_STORAGE}:vztmpl/${TEMPLATE}" $PCT_OPTIONS ${_PW_ARGS[@]+"${_PW_ARGS[@]}"} >"$LOGFILE" 2>&1; then
        msg_ok "Container successfully created with new ID $CTID"
      else
        msg_error "Container creation failed even with new ID $CTID. See $LOGFILE"
        _flush_pct_log
        exit 209
      fi
    else
      if grep -qiE 'unable to open|corrupt|invalid' "$LOGFILE"; then
        msg_info "Template may be corrupted – re-downloading"
        rm -f "$TEMPLATE_PATH"
        download_template
        msg_ok "Template re-downloaded"
      fi

      if ! _pct_create "$CTID" "${TEMPLATE_STORAGE}:vztmpl/${TEMPLATE}" $PCT_OPTIONS ${_PW_ARGS[@]+"${_PW_ARGS[@]}"} >>"$LOGFILE" 2>&1; then
        if [[ "$TEMPLATE_STORAGE" != "local" ]]; then
          msg_info "Retrying container creation with fallback to local storage"
          LOCAL_TEMPLATE_PATH="/var/lib/vz/template/cache/$TEMPLATE"
          if [[ ! -f "$LOCAL_TEMPLATE_PATH" ]]; then
            msg_ok "Trying local storage fallback"
            msg_info "Downloading template to local"
            if [[ "$ARCH" == "arm64" ]]; then
              download_arm64_template "$LOCAL_TEMPLATE_PATH"
            else
              pveam download local "$TEMPLATE" >>"${BUILD_LOG:-/dev/null}" 2>&1
            fi
            msg_ok "Template downloaded to local"
          else
            msg_ok "Trying local storage fallback"
          fi
          if ! _pct_create "$CTID" "local:vztmpl/${TEMPLATE}" $PCT_OPTIONS ${_PW_ARGS[@]+"${_PW_ARGS[@]}"} >>"$LOGFILE" 2>&1; then
            if grep -qiE 'unsupported .* version' "$LOGFILE"; then
              msg_warn "pct reported 'unsupported version' – LXC stack might be too old for this template"
              offer_lxc_stack_upgrade_and_maybe_retry "yes"
              rc=$?
              case $rc in
              0) : ;;
              2)
                msg_error "LXC stack upgrade ignored. Please inspect: $LOGFILE"
                _flush_pct_log
                exit 231
                ;;
              3)
                msg_error "LXC stack upgrade failed. Please inspect: $LOGFILE"
                _flush_pct_log
                exit 231
                ;;
              4)
                msg_error "Cancelled by user."
                _flush_pct_log
                exit 231
                ;;
              5)
                _lxc_stack_too_old
                exit 231
                ;;
              esac
            else
              msg_error "Container creation failed. See $LOGFILE"
              if whiptail --yesno "pct create failed.\nDo you want to enable verbose debug mode and view detailed logs?" 12 70; then
                set -x
                _pct_create "$CTID" "local:vztmpl/${TEMPLATE}" $PCT_OPTIONS ${_PW_ARGS[@]+"${_PW_ARGS[@]}"} 2>&1 | tee -a "$LOGFILE"
                set +x
              fi
              _flush_pct_log
              exit 209
            fi
          else
            msg_ok "Container successfully created using local fallback."
          fi
        else
          if grep -qiE 'unsupported .* version' "$LOGFILE"; then
            msg_warn "pct reported 'unsupported version' – LXC stack might be too old for this template"
            offer_lxc_stack_upgrade_and_maybe_retry "yes"
            rc=$?
            case $rc in
            0) : ;;
            2)
              msg_error "LXC stack upgrade ignored. Please inspect: $LOGFILE"
              _flush_pct_log
              exit 231
              ;;
            3)
              msg_error "LXC stack upgrade failed. Please inspect: $LOGFILE"
              _flush_pct_log
              exit 231
              ;;
            4)
              msg_error "Cancelled by user."
              _flush_pct_log
              exit 231
              ;;
            5)
              _lxc_stack_too_old
              exit 231
              ;;
            esac
          else
            msg_error "Container creation failed. See $LOGFILE"
            if whiptail --yesno "pct create failed.\nDo you want to enable verbose debug mode and view detailed logs?" 12 70; then
              set -x
              _pct_create "$CTID" "local:vztmpl/${TEMPLATE}" $PCT_OPTIONS ${_PW_ARGS[@]+"${_PW_ARGS[@]}"} 2>&1 | tee -a "$LOGFILE"
              set +x
            fi
            _flush_pct_log
            exit 209
          fi
        fi
      else
        msg_ok "Container successfully created after template repair."
      fi
    fi
  fi
  set +f

  # Verify container exists
  local _pct_visible=false
  for _pct_check in {1..10}; do
    if pct list | awk '{print $1}' | grep -qx "$CTID"; then
      _pct_visible=true
      break
    fi
    sleep 1
  done
  if [[ "$_pct_visible" != true ]]; then
    msg_error "Container ID $CTID not listed in 'pct list' after 10s. See $LOGFILE"
    msg_custom "🔧" "${YW}" "This can happen in clusters with pmxcfs sync delays."
    _flush_pct_log
    exit 215
  fi

  # Verify config rootfs
  grep -q '^rootfs:' "/etc/pve/lxc/$CTID.conf" || {
    msg_error "RootFS entry missing in container config. See $LOGFILE"
    _flush_pct_log
    exit 216
  }

  msg_ok "LXC Container ${BL}$CTID${CL} ${GN}was successfully created."

  if [[ -s "$LOGFILE" && -n "${BUILD_LOG:-}" ]]; then
    {
      echo ""
      echo "--- pct create output ---"
      cat "$LOGFILE"
      echo "--- end pct create output ---"
    } >>"$BUILD_LOG" 2>/dev/null || true
  fi
}

# ==============================================================================
# SECTION 9: POST-INSTALLATION & FINALIZATION
# ==============================================================================

# ------------------------------------------------------------------------------
# description()
#
# - Sets container description with formatted HTML content
# - Includes:
#   * Community-Scripts logo
#   * Application name
#   * Links to GitHub, Discussions, Issues
#   * Ko-fi donation badge
# - Restarts ping-instances.service if present (monitoring)
# - Posts final "done" status to API telemetry
# ------------------------------------------------------------------------------
description() {
  IP=$(pct exec "$CTID" -- ip -4 addr show dev eth0 2>/dev/null | awk '/inet / {print $2}' | cut -d/ -f1 | head -n1 || true)
  [[ -n "$IP" ]] || IP=$(pct exec "$CTID" -- ip -6 addr show dev eth0 scope global 2>/dev/null | awk '/inet6 / {print $2}' | cut -d/ -f1 | head -n1 || true)

  # Links follow the repository the script actually came from, which
  # detect_repo_source() has already established. Hardcoding DevScripts sent
  # every Incus container to a repository it has nothing to do with.
  local repo_slug="${REPO_SLUG:-community-scripts/ProxmoxVE}"
  local repo_url="https://github.com/${repo_slug}"
  # NSAPP is the slug the website serves, and what menu.func and the update
  # entrypoint already look the app up by. Dashing the spaces instead of
  # dropping them pointed "Arch Linux" at /scripts/arch-linux, which 404s.
  local script_slug
  script_slug="${SCRIPT_SLUG:-${NSAPP:-$APP}}"
  script_slug="$(printf '%s' "$script_slug" | tr '[:upper:]' '[:lower:]' | tr -d ' ')"

  # A script under test asks for feedback here too: the description shows in the
  # Proxmox UI without entering the container and outlives the install output.
  # Same elements as below, which are known to survive Proxmox's rendering.
  # cs_testing_state() has already rejected anything but a plain https URL, so
  # only an ampersand needs an entity.
  local _testing_block=""
  if [[ -n "${CS_TESTING_URL:-}" ]]; then
    local _url_html="${CS_TESTING_URL//&/&amp;}"
    # "Report feedback #2135" reads as a specific destination; a bare "Report
    # feedback" reads as a form to fill in. Only when the URL ends in an issue
    # or discussion number, which is the normal case.
    local _label="Report%20feedback"
    if [[ "$CS_TESTING_URL" =~ /(issues|discussions)/([0-9]+)$ ]]; then
      _label="Report%20feedback%20%23${BASH_REMATCH[2]}"
    fi
    _testing_block=$(
      cat <<EOF
<div align='center'>
  <p style='margin: 4px 0 12px 0;'>
    <a href='${_url_html}' target='_blank' rel='noopener noreferrer'>
      <img src='https://img.shields.io/badge/%E2%9A%A0%EF%B8%8F-TESTING%20BUILD-d97706' alt='Testing build' />
    </a>
  </p>

  <p style='margin: 8px 16px; font-size: 13px;'>This script is still being tested.<br/>Without feedback it cannot be finished.</p>

  <p style='margin: 12px 0;'>
    <a href='${_url_html}' target='_blank' rel='noopener noreferrer'>
      <img src='https://img.shields.io/badge/%F0%9F%92%AC-${_label}-2ea043' alt='Report feedback' />
    </a>
  </p>

  <p style='margin: 8px 16px 16px 16px; font-size: 12px;'>Works, broken, or anything odd &mdash; one line is enough.</p>
</div>
EOF
    )
  fi

  # Generate LXC Description
  DESCRIPTION=$(
    cat <<EOF
${_testing_block}
<div align='center'>
  <a href='https://community-scripts.org' target='_blank' rel='noopener noreferrer'>
    <img src='https://raw.githubusercontent.com/community-scripts/core/main/images/logo-description.png' alt='Community-Scripts' width='192' height='112' style='width:192px;height:112px;'/>
  </a>

  <h2 style='font-size: 24px; margin: 20px 0;'>${APP} LXC</h2>

  <p style='margin: 16px 0;'>
    <a href='https://community-scripts.org/donate' target='_blank' rel='noopener noreferrer'>
      <img src='https://img.shields.io/badge/%E2%9D%A4%EF%B8%8F-Sponsoring%20%26%20Donations-FF5E5B' alt='Sponsoring and donations' />
    </a>
  </p>

  <p style='margin: 12px 0;'>
    <a href='https://community-scripts.org/scripts/${script_slug}' target='_blank' rel='noopener noreferrer'>
      <img src='https://img.shields.io/badge/%F0%9F%93%A6-Open%20Script%20Page-00617f' alt='Open script page' />
    </a>
  </p>

  <span style='margin: 0 10px;'>
    <i class="fa fa-github fa-fw" style="color: #f5f5f5;"></i>
    <a href='${repo_url}' target='_blank' rel='noopener noreferrer' style='text-decoration: none; color: #00617f;'>GitHub</a>
  </span>
  <span style='margin: 0 10px;'>
    <i class="fa fa-comments fa-fw" style="color: #f5f5f5;"></i>
    <a href='${repo_url}/discussions' target='_blank' rel='noopener noreferrer' style='text-decoration: none; color: #00617f;'>Discussions</a>
  </span>
  <span style='margin: 0 10px;'>
    <i class="fa fa-exclamation-circle fa-fw" style="color: #f5f5f5;"></i>
    <a href='${repo_url}/issues' target='_blank' rel='noopener noreferrer' style='text-decoration: none; color: #00617f;'>Issues</a>
  </span>
</div>
EOF
  )
  pct set "$CTID" -description "$DESCRIPTION"

  # Last line of the run, where the user is still looking at the terminal.
  if [[ -n "${CS_TESTING_URL:-}" ]]; then
    msg_custom "🔗" "${YW}" "Testing build — please report back: ${CS_TESTING_URL}"
  fi

  if [[ -f /etc/systemd/system/ping-instances.service ]]; then
    systemctl start ping-instances.service
  fi

  # Optional host-side post-install hook
  # Path comes from var_post_install (default.vars / app.vars / advanced settings).
  # Runs ON THE PROXMOX HOST after the container is up and configured.
  # Exposed env vars: APP, NSAPP, CTID, IP, HN, STORAGE, BRG.
  # Output (stdout/stderr) is captured to /var/log/community-scripts/post-install-<CTID>.log
  if [[ -n "${var_post_install:-}" ]]; then
    local _hook_log_dir="/var/log/community-scripts"
    local _hook_log="${_hook_log_dir}/post-install-${CTID}.log"
    mkdir -p "$_hook_log_dir" 2>/dev/null || true

    if [[ ! -f "${var_post_install}" ]]; then
      msg_error "Post-install hook not found on host: ${var_post_install}"
      whiptail --backtitle "Proxmox VE Helper Scripts" \
        --title "POST-INSTALL HOOK FAILED" \
        --msgbox "The configured post-install hook was not found on the Proxmox host:\n\n${var_post_install}\n\nThe LXC was created successfully, but the hook did NOT run." 14 72 || true
    else
      msg_info "Running post-install hook: ${var_post_install}"
      local _hook_rc=0
      APP="$APP" NSAPP="${NSAPP:-}" CTID="$CTID" IP="$IP" HN="${HN:-}" \
        STORAGE="${STORAGE:-}" BRG="${BRG:-}" \
        bash "${var_post_install}" >"${_hook_log}" 2>&1 || _hook_rc=$?
      if [[ $_hook_rc -eq 0 ]]; then
        msg_ok "Post-install hook completed (log: ${_hook_log})"
      else
        msg_error "Post-install hook failed (rc=${_hook_rc}) – see ${_hook_log}"
        local _hook_tail=""
        _hook_tail="$(tail -n 15 "${_hook_log}" 2>/dev/null || true)"
        whiptail --backtitle "Proxmox VE Helper Scripts" \
          --title "POST-INSTALL HOOK FAILED" \
          --msgbox "Hook exited with code ${_hook_rc}.\n\nScript: ${var_post_install}\nLog:    ${_hook_log}\n\n--- Last log lines ---\n${_hook_tail}\n\nThe LXC itself was created successfully." 22 78 || true
      fi
    fi
  fi

  post_update_to_api "done" "none"
}

# ==============================================================================
# SECTION 10: ERROR HANDLING & EXIT TRAPS
# ==============================================================================

# ------------------------------------------------------------------------------
# ensure_log_on_host()
#
# - Ensures INSTALL_LOG points to a readable file on the host
# - If INSTALL_LOG points to a container path (e.g. /root/.install-*),
#   tries to pull it from the container and create a combined log
# - This allows get_error_text() to find actual error output for telemetry
# - Uses timeout on pct pull to prevent hangs on dead/unresponsive containers
# ------------------------------------------------------------------------------
ensure_log_on_host() {
  # Already readable on host? Nothing to do.
  [[ -n "${INSTALL_LOG:-}" && -s "${INSTALL_LOG}" ]] && return 0

  # Try pulling from container and creating combined log
  if [[ -n "${CTID:-}" && -n "${SESSION_ID:-}" ]] && command -v pct &>/dev/null; then
    local host_combined=""
    if [[ -n "${combined_log:-}" && -s "${combined_log}" ]]; then
      host_combined="$combined_log"
    elif [[ -s "/tmp/install-${SESSION_ID}-combined.log" ]]; then
      host_combined="/tmp/install-${SESSION_ID}-combined.log"
    else
      host_combined="/tmp/${NSAPP:-lxc}-${CTID}-${SESSION_ID}.log"
    fi
    if [[ ! -s "$host_combined" ]]; then
      # Create combined log
      {
        echo "================================================================================"
        echo "COMBINED INSTALLATION LOG - ${APP:-LXC}"
        echo "Container ID: ${CTID}"
        echo "Session ID: ${SESSION_ID}"
        echo "Timestamp: $(date '+%Y-%m-%d %H:%M:%S')"
        echo "================================================================================"
        echo ""
      } >"$host_combined" 2>/dev/null || return 0
      # Append BUILD_LOG if it exists
      if [[ -f "${BUILD_LOG:-}" ]]; then
        {
          echo "================================================================================"
          echo "PHASE 1: CONTAINER CREATION (Host)"
          echo "================================================================================"
          cat "${BUILD_LOG}"
          echo ""
        } >>"$host_combined"
      fi
      # Pull INSTALL_LOG from container (with timeout to prevent hangs on dead containers)
      local temp_log="/tmp/.install-temp-${SESSION_ID}.log"
      if timeout 8 pct pull "$CTID" "/root/.install-${SESSION_ID}.log" "$temp_log" 2>/dev/null; then
        {
          echo "================================================================================"
          echo "PHASE 2: APPLICATION INSTALLATION (Container)"
          echo "================================================================================"
          cat "$temp_log"
          echo ""
        } >>"$host_combined"
        rm -f "$temp_log"
      fi
    fi
    # Also pull the structured error capture for the telemetry error trace
    if [[ -z "${TELEMETRY_ERRINFO:-}" || ! -s "${TELEMETRY_ERRINFO:-}" ]]; then
      local host_errinfo="/tmp/.errinfo-${SESSION_ID}"
      if timeout 8 pct pull "$CTID" "/root/.install-${SESSION_ID}.log.errinfo" "$host_errinfo" 2>/dev/null && [[ -s "$host_errinfo" ]]; then
        TELEMETRY_ERRINFO="$host_errinfo"
        export TELEMETRY_ERRINFO
      fi
    fi
    if [[ -s "$host_combined" ]]; then
      INSTALL_LOG="$host_combined"
    fi
  fi
}

# ------------------------------------------------------------------------------
# api_exit_script()
#
# - Exit trap handler for reporting to API telemetry
# - Captures exit code and reports to the telemetry service using centralized error descriptions
# - Uses explain_exit_code() from api.func for consistent error messages
# - ALWAYS sends telemetry FIRST before log collection to prevent pct pull
#   hangs from blocking status updates (container may be dead/unresponsive)
# - For non-zero exit codes: posts "failed" status
# - For zero exit codes where post_update_to_api was never called:
#   catches orphaned "installing" records (e.g., script exited cleanly
#   but description() was never reached)
# ------------------------------------------------------------------------------
api_exit_script() {
  local exit_code=$?
  if [ $exit_code -ne 0 ]; then
    # ALWAYS send telemetry FIRST - ensure status is reported even if
    # ensure_log_on_host hangs (e.g. pct pull on dead container)
    post_update_to_api "failed" "$exit_code" 2>/dev/null || true
    # Best-effort log collection (non-critical after telemetry is sent)
    if declare -f ensure_log_on_host >/dev/null 2>&1; then
      ensure_log_on_host 2>/dev/null || true
    fi
    # Stop orphaned container if we're in the install phase
    if [[ "${CONTAINER_INSTALLING:-}" == "true" && -n "${CTID:-}" ]] && command -v pct &>/dev/null; then
      pct stop "$CTID" 2>/dev/null || true
    fi
  elif [[ "${POST_TO_API_DONE:-}" == "true" && "${POST_UPDATE_DONE:-}" != "true" ]]; then
    # Script exited with 0 but never sent a completion status: the user backed
    # out somewhere (whiptail cancel etc.). Report as aborted - NOT success
    # (the install never finished) and NOT failed (nothing actually broke).
    post_update_to_api "aborted" "0"
  fi
}

# All five traps report telemetry, so all five belong to the host. EXIT was
# already guarded; the other four were not, and core/build.func sources this
# file unconditionally -- including inside a container, where a ct script runs
# again for an update. A Ctrl-C or any ERR during an update therefore posted a
# failed record, typed lxc, indistinguishable from a failed install. Their pct
# calls were dead weight in a container anyway.
#
# NOTE: never use `local` inside trap strings — traps do not run in a function scope.
if command -v pveversion >/dev/null 2>&1; then
  trap 'api_exit_script' EXIT
  trap '_ec=$?; if [[ $_ec -ne 0 ]]; then post_update_to_api "failed" "$_ec" 2>/dev/null || true; if declare -f ensure_log_on_host &>/dev/null; then ensure_log_on_host 2>/dev/null || true; fi; fi' ERR
  trap 'post_update_to_api "failed" "129" 2>/dev/null || true; if [[ -n "${CTID:-}" ]] && command -v pct &>/dev/null; then pct stop "$CTID" 2>/dev/null || true; fi; exit 129' SIGHUP
  trap 'post_update_to_api "failed" "130" 2>/dev/null || true; if [[ -n "${CTID:-}" ]] && command -v pct &>/dev/null; then pct stop "$CTID" 2>/dev/null || true; fi; exit 130' SIGINT
  trap 'post_update_to_api "failed" "143" 2>/dev/null || true; if [[ -n "${CTID:-}" ]] && command -v pct &>/dev/null; then pct stop "$CTID" 2>/dev/null || true; fi; exit 143' SIGTERM
fi