backend.func

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

# ==============================================================================
# INCUS-BACKEND.FUNC - FULL PARITY BACKEND FOR INCUS CONTAINER CREATION
# ==============================================================================
# Mirrors core/build.func build_container / create_lxc_container flow for Incus.
# Requires incus/build.func hooks and UI functions to be loaded first.
# ==============================================================================

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

incus_ct_exec() {
  incus exec "${CT_NAME}" -- "$@"
}

_incus_device_set() {
  # usage: _incus_device_set <key> <value> [warn-msg]
  local key="$1" val="$2" warn="${3:-}"
  if ! incus config device set "${CT_NAME}" eth0 "${key}=${val}" >>"${LOGFILE:-$INCUS_BUILD_LOG}" 2>&1; then
    [[ -n "$warn" ]] && msg_warn "$warn"
    return 1
  fi
  return 0
}

# Soft-fail helper: never trips set -e / ERR traps from intentional best-effort cmds.
_incus_soft() {
  "$@" || return 0
}

_incus_nic_supports_ip() {
  # Takes the network name, not the type: managed-ness matters as much as the
  # type does. ipv4.address on a NIC is a reservation in the DHCP server Incus
  # itself runs, and that server only exists for managed networks. On a bridge
  # the operator built by hand there is nothing to reserve in, so the address
  # is quietly ignored and the container comes up on the LAN's own DHCP while
  # the summary claims a static address. Better to say so than to pretend.
  #
  # physical / sriov: skip either way (host NIC ownership; keys often rejected).
  local net="${1:-}" cfg type
  [[ -z "$net" ]] && return 1
  cfg=$(LC_ALL=C incus network show "$net" 2>/dev/null) || return 1
  grep -qE '^managed:[[:space:]]*true$' <<<"$cfg" || return 1
  type=$(awk '/^type:/ {print $2; exit}' <<<"$cfg")
  case "$type" in
  bridge | ovn | macvlan) return 0 ;;
  *) return 1 ;;
  esac
}

# A system container takes only a plain address (a DHCP reservation) and no
# gateway; CIDR and ipv4/ipv6.gateway are OCI-only and stop it from starting.
_incus_apply_addresses() {
  local changed=1 addr gw net_gw
  if [[ -n "${NET:-}" && "${NET}" != "dhcp" ]]; then
    addr="${NET%%/*}"
    _incus_device_set ipv4.address "$addr" "Could not reserve ${addr} on '${BRG}' (see the log); the container keeps a DHCP address" && changed=0 || true
  fi

  gw="${GATE:-}"
  gw="${gw#,gw=}"
  if [[ -n "$gw" ]]; then
    net_gw="$(incus network get "$BRG" ipv4.dhcp.gateway 2>/dev/null || true)"
    if [[ -z "$net_gw" ]]; then
      net_gw="$(incus network get "$BRG" ipv4.address 2>/dev/null || true)"
      net_gw="${net_gw%%/*}"
    fi
    if [[ "$gw" != "$net_gw" ]]; then
      msg_warn "Gateway ${gw} is not applied: Incus DHCP on '${BRG}' hands out ${net_gw:-its own}"
    fi
  fi

  if [[ "${IPV6_METHOD:-}" == "static" && -n "${IPV6_ADDR:-}" && "${IPV6_ADDR}" != "auto" ]]; then
    addr="${IPV6_ADDR%%/*}"
    _incus_device_set ipv6.address "$addr" "Could not reserve ${addr} on '${BRG}' (see the log); IPv6 stays as the network assigns it" && changed=0 || true
    if [[ -n "${IPV6_GATE:-}" ]]; then
      msg_warn "IPv6 gateway ${IPV6_GATE} is not applied: Incus sets a gateway only for OCI containers"
    fi
  fi
  return "$changed"
}

# Restart the container, tolerating optional boot-time configs (e.g.
# linux.sysctl.kernel.keys.maxkeys) that some hosts/kernels reject for the
# container's privilege level. Such configs pass 'config set' but abort the
# container at *start* time, so a plain restart would leave it stopped. On
# failure, roll those configs back and retry so the container is never left
# dead. Returns non-zero only if it still cannot start.
_incus_restart_ct() {
  local logf="${LOGFILE:-$INCUS_BUILD_LOG}"
  if incus restart "${CT_NAME}" >>"$logf" 2>&1; then
    return 0
  fi
  msg_warn "Container failed to start with current config — rolling back optional sysctls"
  _incus_soft incus config unset "${CT_NAME}" linux.sysctl.kernel.keys.maxkeys >>"$logf" 2>&1
  _incus_soft incus stop -f "${CT_NAME}" >>"$logf" 2>&1
  _incus_soft incus start "${CT_NAME}" >>"$logf" 2>&1
  # A failed restart leaves incus disagreeing with itself - the same recovery
  # logged "already stopped" from stop and "already running" from start - so
  # the exit code proves nothing here. Ask what the state actually is.
  [[ "$(incus_instance_field "${CT_NAME}" s)" == "RUNNING" ]]
}

# An alias resolves whether or not the image exists for this host's
# architecture; the launch then fails with "architecture isn't supported".
_incus_image_fits_host() {
  local arch
  arch=$(LC_ALL=C incus image info "$1" 2>/dev/null | awk '/^Architecture:/ {print $2; exit}' || true)
  [[ -n "$arch" ]] || return 2
  [[ "$arch" == "$(uname -m)" ]]
}

_incus_resolve_launch_image() {
  # Tries images:OS/VER (+ /cloud, codename alias, local cache). Sets INCUS_LAUNCH_IMAGE.
  # Returns 2 when the image exists, but not for this architecture.
  local os="${IMAGE_OS:-debian}" ver="${IMAGE_VERSION:-13}" alias=""
  os="${os,,}"
  alias="$(incus_get_image_alias "$os" "$ver" 2>/dev/null || true)"

  local candidates=()
  candidates+=("images:${os}/${ver}")
  candidates+=("images:${os}/${ver}/cloud")
  if [[ -n "$alias" && "$alias" != "$ver" ]]; then
    candidates+=("images:${os}/${alias}")
    candidates+=("images:${os}/${alias}/cloud")
  fi
  # Ubuntu often published as 24.04 even when UI stores "24"
  if [[ "$os" == "ubuntu" && "$ver" =~ ^[0-9]+$ ]]; then
    candidates+=("images:ubuntu/${ver}.04" "images:ubuntu/${ver}.04/cloud")
  fi

  local cand local_aliases

  # Local first: no round-trip, and works without internet.
  local_aliases=$(incus image list -f csv,noheader -c l 2>/dev/null || true)
  for cand in "${candidates[@]}"; do
    if [[ -n "$local_aliases" ]] &&
      grep -qxF "${cand#images:}" <<<"$local_aliases" &&
      _incus_image_fits_host "${cand#images:}"; then
      INCUS_LAUNCH_IMAGE="${cand#images:}"
      return 0
    fi
  done

  local fit other_arch=0
  for cand in "${candidates[@]}"; do
    fit=0
    _incus_image_fits_host "$cand" || fit=$?
    if ((fit == 0)); then
      INCUS_LAUNCH_IMAGE="$cand"
      return 0
    fi
    ((fit == 1)) && other_arch=1
  done

  # Not on the image server under any name we know: take its newest version.
  local newest
  for newest in $(incus image alias list images: "${os}/" -f csv 2>/dev/null | cut -d, -f1 |
    awk -F/ 'NF == 2 && $2 ~ /^[0-9][0-9.]*$/ {print $2}' | sort -urV || true); do
    if _incus_image_fits_host "images:${os}/${newest}"; then
      msg_warn "${os} ${ver} is not on the image server; using ${os} ${newest}"
      INCUS_LAUNCH_IMAGE="images:${os}/${newest}"
      return 0
    fi
  done
  ((other_arch)) && return 2

  # Last resort: try remote launch of primary (incus may pull on demand)
  INCUS_LAUNCH_IMAGE="images:${os}/${ver}"
  return 1
}

_incus_parse_size_to_bytes() {
  # Integer arithmetic only: BusyBox awk truncates printf "%d" to 32 bit.
  local raw="${1:-}" int frac unit mult scale=1 i
  raw="${raw// /}"
  [[ "$raw" =~ ^([0-9]+)(\.([0-9]+))?([A-Za-z]*)$ ]] || return 1
  int="${BASH_REMATCH[1]}"
  frac="${BASH_REMATCH[3]}"
  unit="${BASH_REMATCH[4]^^}"
  case "$unit" in
  B | "") mult=1 ;;
  KB | KIB | K) mult=1024 ;;
  MB | MIB | M) mult=$((1024 * 1024)) ;;
  GB | GIB | G) mult=$((1024 * 1024 * 1024)) ;;
  TB | TIB | T) mult=$((1024 * 1024 * 1024 * 1024)) ;;
  *) return 1 ;;
  esac
  for ((i = 0; i < ${#frac}; i++)); do scale=$((scale * 10)); done
  echo $((10#$int * mult + 10#${frac:-0} * mult / scale))
}

incus_storage_pool_free_gb() {
  local pool="${1:-}"
  local info free_bytes total_bytes used_bytes free_raw total_raw used_raw

  # Prefer machine-readable bytes when available (Incus --bytes).
  # LC_ALL=C: incus translates this output. A German host reports "Gesamter
  # Speicherplatz" and "Speicherplatz in Benutzung", so the awk below matched
  # nothing and a 357GB pool looked unmeasurable.
  # Incus reports total and used only; with --bytes they are plain integers, so
  # the subtraction stays in bash and never goes through awk floats (BusyBox awk
  # truncates those to 32 bit).
  info=$(LC_ALL=C incus storage info --bytes "$pool" 2>/dev/null || true)
  free_raw=$(echo "$info" | awk -F': *' '/space free:/ {gsub(/"/, "", $2); print $2; exit}')
  total_raw=$(echo "$info" | awk -F': *' '/total space:/ {gsub(/"/, "", $2); print $2; exit}')
  used_raw=$(echo "$info" | awk -F': *' '/space used:/ {gsub(/"/, "", $2); print $2; exit}')
  if [[ "$free_raw" =~ ^[0-9]+$ ]]; then
    free_bytes="$free_raw"
  elif [[ "$total_raw" =~ ^[0-9]+$ && "$used_raw" =~ ^[0-9]+$ && "$total_raw" -ge "$used_raw" ]]; then
    free_bytes=$((total_raw - used_raw))
  fi

  # Older/human output often has only "space used" + "total space" (no free line).
  if [[ -z "${free_bytes:-}" ]]; then
    info=$(LC_ALL=C incus storage info "$pool" 2>/dev/null || true)
    free_raw=$(echo "$info" | awk -F': *' '/space free:/ {gsub(/"/, "", $2); print $2; exit}')
    total_raw=$(echo "$info" | awk -F': *' '/total space:/ {gsub(/"/, "", $2); print $2; exit}')
    used_raw=$(echo "$info" | awk -F': *' '/space used:/ {gsub(/"/, "", $2); print $2; exit}')
    if [[ -n "$free_raw" ]]; then
      free_bytes="$(_incus_parse_size_to_bytes "$free_raw" 2>/dev/null || true)"
    elif [[ -n "$total_raw" && -n "$used_raw" ]]; then
      total_bytes="$(_incus_parse_size_to_bytes "$total_raw" 2>/dev/null || true)"
      used_bytes="$(_incus_parse_size_to_bytes "$used_raw" 2>/dev/null || true)"
      if [[ -n "${total_bytes:-}" && -n "${used_bytes:-}" && "$total_bytes" -ge "$used_bytes" ]]; then
        free_bytes=$((total_bytes - used_bytes))
      fi
    fi
  fi

  # A dir pool is just a path, so ask the filesystem when incus says nothing.
  # Does not help lvm or zfs, where source is not a path.
  if [[ -z "${free_bytes:-}" ]]; then
    local src
    src="$(LC_ALL=C incus storage get "$pool" source 2>/dev/null || true)"
    if [[ "${INCUS_REMOTE:-local}" == "local" && -n "$src" && -d "$src" ]]; then
      free_bytes="$(df -PB1 "$src" 2>/dev/null | awk 'NR==2 {print $4}')"
    fi
  fi

  [[ -z "${free_bytes:-}" || "$free_bytes" -le 0 ]] && return 1
  echo $((free_bytes / 1024 / 1024 / 1024))
}

incus_validate_storage_space() {
  local pool="${1:-$CONTAINER_STORAGE}"
  local need_gb="${2:-${DISK_SIZE:-4}}"
  local free_gb
  free_gb=$(incus_storage_pool_free_gb "$pool" 2>/dev/null || echo "")
  if [[ -z "$free_gb" ]]; then
    msg_warn "Could not determine free space on pool '${pool}' (continuing)"
    return 0
  fi
  if [[ "$free_gb" -lt "$need_gb" ]]; then
    # Match PVE behavior: warn, do not hard-abort (pool/dir drivers can still grow).
    msg_warn "Pool '${pool}' reports ~${free_gb}GB free, container wants ${need_gb}GB"
    msg_custom "ℹ️" "${YW}" "Source: incus storage info '${pool}' (pool free space, not full host disk)"
    msg_custom "ℹ️" "${YW}" "Grow: incus storage set ${pool} size=50GiB   |   Or pick another pool"
    return 0
  fi
}

resolve_storage_preselect() {
  local _class="${1:-container}"
  local preselect="${2:-}"
  [[ -z "$preselect" ]] && return 1
  incus storage info "$preselect" &>/dev/null || return 1
  STORAGE_RESULT="$preselect"
  local free_gb
  free_gb=$(incus_storage_pool_free_gb "$preselect" 2>/dev/null || true)
  # "Free: ~?GB" reads like a broken template. Say what is actually known.
  if [[ -n "$free_gb" ]]; then
    STORAGE_INFO="Free: ~${free_gb}GB"
  else
    STORAGE_INFO="Free: unknown"
  fi
  return 0
}

check_storage_support() {
  local _content="${1:-rootdir}"
  case "$_content" in
  vztmpl | template)
    getent hosts images.linuxcontainers.org &>/dev/null
    ;;
  *)
    [[ "$(incus storage list -f csv,noheader 2>/dev/null | wc -l)" -gt 0 ]]
    ;;
  esac
}

validate_storage_space() {
  local pool="${1:-$CONTAINER_STORAGE}"
  local need_gb="${2:-${DISK_SIZE:-4}}"
  local show_dialog="${3:-no}"
  local free_gb
  free_gb=$(incus_storage_pool_free_gb "$pool" 2>/dev/null || echo "")
  if [[ -z "$free_gb" ]]; then
    [[ "$show_dialog" == "yes" ]] && whiptail --msgbox "⚠️  Warning: Could not determine free space on pool '${pool}'.\n\n(Checked via: incus storage info ${pool})" 12 64 2>/dev/null || true
    return 0
  fi
  if [[ "$free_gb" -lt "$need_gb" ]]; then
    if [[ "$show_dialog" == "yes" ]]; then
      whiptail --msgbox "⚠️  Warning: Not enough space on Incus pool '${pool}'.\n\nRequired: ${need_gb}GB\nPool free: ~${free_gb}GB\n\nThis is pool free space (incus storage info),\nNOT your full host disk. Default/loop pools are often small.\n\nGrow pool:  incus storage set ${pool} size=50GiB\nOr pick another pool in Advanced settings." 16 72 2>/dev/null || true
    fi
    return 1
  fi
  return 0
}

_incus_prepare_install_exports() {
  # One bootstrap for every OS — see pve/backend.func for why the Alpine split
  # went away.
  export FUNCTIONS_FILE_PATH="$(_cs_fetch_text "lxc/install.func")"

  export DIAGNOSTICS="${DIAGNOSTICS:-yes}"
  export RANDOM_UUID="${RANDOM_UUID}"
  export EXECUTION_ID="${EXECUTION_ID}"
  export SESSION_ID="${SESSION_ID}"
  export CACHER="${APT_CACHER:-}"
  export CACHER_IP="${APT_CACHER_IP:-}"
  export tz="${timezone:-UTC}"
  export APPLICATION="$APP"
  export app="$NSAPP"
  export PASSWORD="$PW"
  export VERBOSE="${VERBOSE:-no}"
  export SSH_ROOT="${SSH:-no}"
  export SSH_AUTHORIZED_KEY="${SSH_AUTHORIZED_KEY:-}"
  export CTID="$CT_NAME"
  export CTTYPE="${CT_TYPE:-1}"
  export ENABLE_FUSE="${ENABLE_FUSE:-no}"
  export ENABLE_TUN="${ENABLE_TUN:-no}"
  export PCT_OSTYPE="${var_os:-debian}"
  export PCT_OSVERSION="${var_version:-13}"
  export PCT_DISK_SIZE="${DISK_SIZE}"
  export IPV6_METHOD="${IPV6_METHOD:-auto}"
  export ENABLE_GPU="${ENABLE_GPU:-no}"
  export APPLICATION_VERSION="${var_appversion:-}"

  # The container writes its own MOTD, so it has to know whether this is a
  # testing build. Incus is not the testing repository, so this is normally
  # empty here -- which is the point: it used to warn unconditionally.
  declare -f cs_testing_state >/dev/null 2>&1 && cs_testing_state

  export BUILD_LOG="${BUILD_LOG:-$INCUS_BUILD_LOG}"
  export INSTALL_LOG="/root/.install-${SESSION_ID}.log"
  export COMMUNITY_SCRIPTS_URL="${INCUS_COMMUNITY_SCRIPTS_URL}"
  export COMMUNITY_SCRIPTS_CORE_URL="${COMMUNITY_SCRIPTS_CORE_URL}"
  export MODE="${METHOD:-default}"
  _HOST_LOGFILE="${BUILD_LOG:-$INCUS_BUILD_LOG}"
}

incus_create_lxc_container() {
  LOGFILE="${INCUS_BUILD_LOG}"

  [[ "${CT_NAME:-}" ]] || { msg_error "Container name not set"; exit 203; }

  post_to_api 2>/dev/null || true
  post_progress_to_api "validation" 2>/dev/null || true

  check_storage_support "rootdir" || { msg_error "No Incus storage pools found"; exit 1; }

  if resolve_storage_preselect container "${CONTAINER_STORAGE:-}"; then
    STORAGE_POOL="$STORAGE_RESULT"
  elif [[ -z "${CONTAINER_STORAGE:-}" ]]; then
    select_storage container && STORAGE_POOL="$CONTAINER_STORAGE"
  else
    STORAGE_POOL="${CONTAINER_STORAGE}"
  fi

  msg_info "Validating storage '${STORAGE_POOL}'"
  incus storage info "$STORAGE_POOL" &>/dev/null || { msg_error "Storage pool '${STORAGE_POOL}' invalid"; exit 213; }
  msg_ok "Storage '${STORAGE_POOL}' validated${STORAGE_INFO:+ - ${STORAGE_INFO}}"

  if ! incus network show "${BRG}" >/dev/null 2>&1; then
    msg_warn "Network '${BRG}' not found, auto-selecting fallback"
    BRG="$(incus_pick_default_network)"
    msg_ok "Using network '${BRG}'"
  fi

  msg_info "Resolving container image"
  local image_name=""
  local resolve_rc=0
  _incus_resolve_launch_image || resolve_rc=$?
  if ((resolve_rc == 2)); then
    msg_error "${IMAGE_OS} ${IMAGE_VERSION} has no $(uname -m) image on the image server"
    exit 106
  elif ((resolve_rc == 0)); then
    image_name="${INCUS_LAUNCH_IMAGE}"
    msg_ok "Image ${BL}${image_name}${CL} (cached)"
  else
    image_name="${INCUS_LAUNCH_IMAGE:-images:${IMAGE_OS}/${IMAGE_VERSION}}"
    msg_custom "ℹ️" "${YW}" "Image ${image_name} not cached, pulling"
  fi

  msg_info "Creating container"
  incus_log_section "Container Creation: ${CT_NAME}"

  local launch_args=()
  launch_args+=("--config" "limits.cpu=${CORE_COUNT}")
  launch_args+=("--config" "limits.memory=${RAM_SIZE}MiB")
  launch_args+=("--config" "boot.autostart=true")
  [[ -n "${PROFILE:-}" && "${PROFILE}" != "default" ]] && launch_args+=("--profile" "${PROFILE}")
  launch_args+=("--network" "${BRG}")

  [[ "${ENABLE_NESTING:-1}" == "1" ]] && launch_args+=("--config" "security.nesting=true")

  # Settings the shared wizard already collects but that were dropped here.
  # mknod maps onto the syscall interception Incus offers; protection maps onto
  # the delete guard. keyctl has no Incus equivalent -- unprivileged containers
  # get their own keyring session -- so it is deliberately not faked.
  [[ "${ENABLE_MKNOD:-no}" == "yes" || "${ENABLE_MKNOD:-0}" == "1" ]] &&
    launch_args+=("--config" "security.syscalls.intercept.mknod=true")
  [[ "${PROTECTION:-no}" == "yes" || "${PROTECTION:-0}" == "1" ]] &&
    launch_args+=("--config" "security.protection.delete=true")

  # Container-only per the host's own /1.0/metadata/configuration. A core count
  # caps how many CPUs are visible, an allowance caps how much of them may be
  # used; both are cgroup constructs and do nothing on a VM.
  [[ -n "${CPU_ALLOWANCE:-}" ]] &&
    launch_args+=("--config" "limits.cpu.allowance=${CPU_ALLOWANCE}")
  [[ -n "${CPU_PRIORITY:-}" ]] &&
    launch_args+=("--config" "limits.cpu.priority=${CPU_PRIORITY}")
  [[ -n "${MEMORY_SWAP:-}" ]] &&
    launch_args+=("--config" "limits.memory.swap=${MEMORY_SWAP}")
  [[ -n "${KERNEL_MODULES:-}" ]] &&
    launch_args+=("--config" "linux.kernel_modules=${KERNEL_MODULES}")

  if [[ "${CT_TYPE:-1}" != "1" ]]; then
    launch_args+=("--config" "security.privileged=true")
  fi

  launch_args+=("--storage" "${STORAGE_POOL}")
  launch_args+=("--device" "root,size=${DISK_SIZE}GiB")

  # Prefer a unique name if the chosen one already exists.
  if incus_container_exists "${CT_NAME}"; then
    local alt
    alt="$(incus_get_next_name "${CT_NAME}")"
    msg_warn "Instance '${CT_NAME}' already exists — using '${alt}'"
    CT_NAME="$alt"
    CTID="$CT_NAME"
  fi

  {
    echo "=== incus launch ${image_name} ${CT_NAME} ==="
    echo "args: ${launch_args[*]}"
    echo "user: $(id -un) uid=$(id -u)"
  } >>"$LOGFILE"

  if ! incus launch "${image_name}" "${CT_NAME}" "${launch_args[@]}" >>"$LOGFILE" 2>&1; then
    # Retry alternate candidates once if primary pull failed
    local retry_img="" launched=0 tried=" ${image_name} "
    for retry_img in "images:${IMAGE_OS}/${IMAGE_VERSION}/cloud" \
      "images:${IMAGE_OS}/$(incus_get_image_alias "${IMAGE_OS}" "${IMAGE_VERSION}" 2>/dev/null || true)" \
      "images:${IMAGE_OS}/$(incus_get_image_alias "${IMAGE_OS}" "${IMAGE_VERSION}" 2>/dev/null || true)/cloud"; do
      [[ -z "$retry_img" || "$retry_img" == */ || "$tried" == *" ${retry_img} "* ]] && continue
      tried+="${retry_img} "
      msg_warn "Launch failed, retrying with ${retry_img}"
      if incus launch "${retry_img}" "${CT_NAME}" "${launch_args[@]}" >>"$LOGFILE" 2>&1; then
        image_name="$retry_img"
        launched=1
        break
      fi
    done
    if [[ "$launched" -ne 1 ]]; then
      msg_error "Failed to create container ${CT_NAME}"
      echo -e "${YW}Last launch errors:${CL}"
      tail -n 30 "$LOGFILE" 2>/dev/null | sed 's/^/  /' || true
      echo -e "${YW}Log: ${BL}${LOGFILE}${CL}"
      echo -e "${YW}Try manually:${CL} incus image copy images:${IMAGE_OS}/${IMAGE_VERSION} local: --alias ${IMAGE_OS}/${IMAGE_VERSION}"
      exit 1
    fi
  fi

  # Track for orphan cleanup on mid-create / mid-configure failures (EXIT trap).
  # Reset handled/ok so a rebuild after install-recovery can prompt again if needed.
  INCUS_CT_CREATED=1
  INCUS_ORPHAN_HANDLED=0
  INCUS_BUILD_OK=0
  export INCUS_CT_CREATED INCUS_ORPHAN_HANDLED INCUS_BUILD_OK CT_NAME CTID

  # Optional boot-time configs that some hosts/kernels reject for this
  # container type. They fail when the container *starts*, not at 'config set'
  # (e.g. kernel.keys.maxkeys is not writable from an unprivileged user
  # namespace), so a plain set can silently persist a config that aborts the
  # next boot. Apply best-effort and verify with a self-healing restart below.
  # kernel.keys.maxkeys cannot be written from an unprivileged user namespace -
  # lxc aborts the start with "Permission denied - Failed to setup sysctl
  # parameters kernel.keys.maxkeys to 2000". This was set for CT_TYPE=1, which
  # IS the unprivileged case, so every unprivileged create paid a failed start
  # plus a rollback to reach the state it would have had anyway. Privileged
  # only, and only when the host default is actually below what we want.
  local optional_sysctl_pending=0
  # The sysctl probe reads this machine; against a remote, just try the setting.
  if [[ "${CT_TYPE:-1}" == "0" ]] &&
    { [[ "${INCUS_REMOTE:-local}" != "local" ]] || (($(cat /proc/sys/kernel/keys/maxkeys 2>/dev/null || echo 2000) < 2000)); }; then
    if incus config set "${CT_NAME}" linux.sysctl.kernel.keys.maxkeys=2000 >>"$LOGFILE" 2>&1; then
      optional_sysctl_pending=1
    fi
  fi

  msg_ok "Container ${CT_NAME} created"

  msg_info "Waiting for container to initialize"
  local waited=0
  while ! incus_ct_exec true &>/dev/null; do
    sleep 2
    waited=$((waited + 2))
    [[ "$waited" -ge 60 ]] && { msg_error "Container not ready"; exit 1; }
  done
  msg_ok "Container started"

  incus_set_container_hostname

  local net_type="" net_reconfigure=0
  net_type=$(incus network show "${BRG}" 2>/dev/null | awk '/^type:/ {print $2; exit}')
  local nic_supports_ip=0
  _incus_nic_supports_ip "$BRG" && nic_supports_ip=1

  if [[ -n "${MAC:-}" ]]; then
    _incus_device_set hwaddr "${MAC}" "Could not apply MAC (${MAC})" && net_reconfigure=1 || true
  fi
  if [[ -n "${VLAN_TAG:-}" ]]; then
    _incus_device_set vlan "${VLAN_TAG}" "Could not apply VLAN (${VLAN_TAG})" && net_reconfigure=1 || true
  fi
  if [[ -n "${MTU:-}" ]]; then
    _incus_device_set mtu "${MTU}" "Could not apply MTU (${MTU})" && net_reconfigure=1 || true
  fi

  if [[ "$nic_supports_ip" -eq 1 ]]; then
    _incus_apply_addresses && net_reconfigure=1 || true
  else
    # An unmanaged bridge is the ordinary case here and not an error: the
    # container simply takes an address from the LAN's own DHCP. Worth saying
    # out loud though, because a static address typed into the wizard will not
    # be applied and the summary would otherwise imply that it was.
    if [[ -n "${NET:-}" && "${NET}" != "dhcp" ]]; then
      msg_warn "Network '${BRG}' is not managed by Incus - ${NET} cannot be reserved there. The container will use DHCP from your LAN; set the address inside the container or reserve it on your router."
    else
      msg_info "Network '${BRG}' is not managed by Incus (type=${net_type:-unknown}) - addressing is left to your LAN"
    fi
    if [[ -n "${NET:-}" && "${NET}" != "dhcp" ]]; then
      msg_custom "ℹ️" "${YW}" "Static IPv4 ${NET} was requested but cannot be set as device key on ${net_type:-this} network"
    fi
  fi

  if [[ -n "${TAGS:-}" ]]; then
    _incus_soft incus config set "${CT_NAME}" "user.tags=${TAGS}" >>"$LOGFILE" 2>&1
  fi

  # Restart when network devices changed, or to verify an optional boot-time
  # sysctl we set above (so a rejected one is rolled back now rather than
  # bricking a later reboot with boot.autostart=true).
  if [[ "$net_reconfigure" -eq 1 || "$optional_sysctl_pending" -eq 1 ]]; then
    if [[ "$net_reconfigure" -eq 1 ]]; then
      msg_info "Reconfiguring network settings"
    else
      msg_info "Verifying container configuration"
    fi
    if _incus_restart_ct; then
      if [[ "$net_reconfigure" -eq 1 ]]; then
        msg_ok "Network settings applied"
      else
        msg_ok "Container configuration verified"
      fi
    else
      # Everything past this point needs incus exec. Warning and carrying on
      # over a stopped container is what turned one failed restart into three
      # unrelated-looking errors further down.
      msg_error "Container ${CT_NAME} is not running after configuration changes"
      msg_custom "ℹ️" "${YW}" "See: incus info --show-log ${CT_NAME}"
      return 1
    fi
  fi
}

incus_set_container_hostname() {
  local hn="${CT_NAME}"
  [[ -n "${HN:-}" ]] && hn="${HN}"
  hn=$(echo "$hn" | tr '[:upper:]' '[:lower:]' | tr -d ' ' | tr '_' '-')
  [[ -z "$hn" ]] && return 0

  _incus_soft incus config set "${CT_NAME}" "user.hostname=${hn}" >>"${LOGFILE:-$INCUS_BUILD_LOG}" 2>&1
  # Prefer instance name for system hostname when UI used CT_ID as name
  local sys_hn="${CT_NAME}"
  # sh: a fresh Alpine image has no bash yet.
  if incus_ct_exec sh -c "
    echo '${sys_hn}' >/etc/hostname
    hostname '${sys_hn}' 2>/dev/null || true
    if command -v hostnamectl >/dev/null 2>&1; then
      hostnamectl set-hostname '${sys_hn}' 2>/dev/null || true
    fi
    if [ -f /etc/hosts ]; then
      if grep -qE '^127\\.0\\.1\\.1' /etc/hosts; then
        sed -i 's/^127\\.0\\.1\\.1.*/127.0.1.1 ${sys_hn}/' /etc/hosts
      else
        echo '127.0.1.1 ${sys_hn}' >>/etc/hosts
      fi
    fi
  " >>"${LOGFILE:-$INCUS_BUILD_LOG}" 2>&1; then
    :
  else
    msg_warn "Could not set the hostname inside ${CT_NAME} (see the log)"
  fi
}

incus_is_gpu_app() {
  [[ "${var_gpu:-no}" == "yes" || "${ENABLE_GPU:-no}" == "yes" ]]
}

# Populate INTEL_GPUS/AMD_GPUS/NVIDIA_GPUS as "pci=<addr>|id=<n>|vendorid=<id>" selectors
# per https://linuxcontainers.org/incus/docs/main/reference/devices_gpu/
incus_detect_gpu_devices() {
  INTEL_GPUS=()
  AMD_GPUS=()
  NVIDIA_GPUS=()
  NVIDIA_CHAR_DEVS=()

  local line pci vendor
  # Prefer domain:bus:slot.func from lspci -D
  while IFS= read -r line; do
    [[ -z "$line" ]] && continue
    pci=$(awk '{print $1}' <<<"$line")
    [[ "$pci" =~ ^[0-9a-fA-F]+:[0-9a-fA-F]+:[0-9a-fA-F]+\.[0-9a-fA-F]+$ ]] || continue
    if grep -q '\[8086:' <<<"$line"; then
      INTEL_GPUS+=("pci=${pci}")
    elif grep -qE '\[1002:|\[1022:' <<<"$line"; then
      AMD_GPUS+=("pci=${pci}")
    elif grep -q '\[10de:' <<<"$line"; then
      NVIDIA_GPUS+=("pci=${pci}")
    fi
  done < <(lspci -nn -D 2>/dev/null | grep -E 'VGA|Display|3D' || true)

  # DRM sysfs fallback (useful on ARM / non-PCI GPUs)
  if [[ ${#INTEL_GPUS[@]} -eq 0 && ${#AMD_GPUS[@]} -eq 0 && ${#NVIDIA_GPUS[@]} -eq 0 && -d /sys/class/drm ]]; then
    local card base drm_id vendor_hex
    for card in /sys/class/drm/card[0-9]*; do
      base=$(basename "$card")
      [[ "$base" == *-* ]] && continue
      drm_id="${base#card}"
      vendor_hex=$(cat "$card/device/vendor" 2>/dev/null || true)
      pci=$(basename "$(readlink -f "$card/device" 2>/dev/null)" 2>/dev/null || true)
      local sel=""
      if [[ -n "$pci" && "$pci" =~ ^[0-9a-fA-F]+:[0-9a-fA-F]+:[0-9a-fA-F]+\.[0-9a-fA-F]+$ ]]; then
        sel="pci=${pci}"
      elif [[ -n "$drm_id" ]]; then
        sel="id=${drm_id}"
      fi
      [[ -z "$sel" ]] && continue
      case "$vendor_hex" in
      0x8086) INTEL_GPUS+=("$sel") ;;
      0x1002 | 0x1022) AMD_GPUS+=("$sel") ;;
      0x10de) NVIDIA_GPUS+=("$sel") ;;
      esac
    done
  fi

  # NVIDIA char devices as optional extra (driver nodes inside CT)
  local d
  for d in /dev/nvidia*; do
    [[ -c "$d" ]] && NVIDIA_CHAR_DEVS+=("$d")
  done
  if [[ -d /dev/nvidia-caps ]]; then
    for d in /dev/nvidia-caps/*; do
      [[ -c "$d" ]] && NVIDIA_CHAR_DEVS+=("$d")
    done
  fi

  if [[ ${#INTEL_GPUS[@]} -gt 0 ]]; then
    msg_custom "🎮" "${BL}" "Detected Intel GPU (${#INTEL_GPUS[@]})"
  fi
  if [[ ${#AMD_GPUS[@]} -gt 0 ]]; then
    msg_custom "🎮" "${RD}" "Detected AMD GPU (${#AMD_GPUS[@]})"
  fi
  if [[ ${#NVIDIA_GPUS[@]} -gt 0 ]]; then
    msg_custom "🎮" "${GN}" "Detected NVIDIA GPU (${#NVIDIA_GPUS[@]})"
  fi
  return 0
}

_incus_add_gpu_physical() {
  # $1 device name, $2 selector like pci=0000:00:02.0 or id=0 or vendorid=8086
  local dev_name="$1" selector="$2"
  local -a args=(gpu "gputype=physical")
  args+=("$selector")

  local video_gid
  video_gid=$(getent group video 2>/dev/null | cut -d: -f3 || true)
  [[ -n "$video_gid" ]] && args+=("gid=${video_gid}")

  if incus config device add "${CT_NAME}" "$dev_name" "${args[@]}" >>"${LOGFILE:-$INCUS_BUILD_LOG}" 2>&1; then
    return 0
  fi
  # Retry without gid (some hosts reject host GIDs for unprivileged CTs)
  args=(gpu "gputype=physical" "$selector")
  if incus config device add "${CT_NAME}" "$dev_name" "${args[@]}" >>"${LOGFILE:-$INCUS_BUILD_LOG}" 2>&1; then
    return 0
  fi
  return 1
}

incus_configure_device_passthrough() {
  if incus_is_gpu_app; then
    incus_detect_gpu_devices
    local selected_gpu="" gpu_count=0
    local -a available_gpus=()
    if [[ ${#INTEL_GPUS[@]} -gt 0 ]]; then
      available_gpus+=("INTEL")
      gpu_count=$((gpu_count + 1))
    fi
    if [[ ${#AMD_GPUS[@]} -gt 0 ]]; then
      available_gpus+=("AMD")
      gpu_count=$((gpu_count + 1))
    fi
    if [[ ${#NVIDIA_GPUS[@]} -gt 0 || ${#NVIDIA_CHAR_DEVS[@]} -gt 0 ]]; then
      available_gpus+=("NVIDIA")
      gpu_count=$((gpu_count + 1))
    fi

    if [[ "$gpu_count" -gt 0 ]]; then
      # Several types can be attached together, and picking exactly one used to
      # default to the first -- always INTEL, by collection order. On a host with
      # an iGPU beside a discrete card that silently attached the iGPU only.
      local -a selected_types=("${available_gpus[@]}")
      if [[ "$gpu_count" -gt 1 ]]; then
        echo -e "\n${INFO} Multiple GPU types detected:"
        local gi
        for gi in "${!available_gpus[@]}"; do
          echo "  $((gi + 1))) ${available_gpus[$gi]}"
        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 [[ -n "$type_selection" && "$type_selection" != "A" ]]; then
          local -a gnums=()
          local gnum
          IFS=',' read -ra gnums <<<"$type_selection"
          selected_types=()
          for gnum in "${gnums[@]}"; do
            gnum="${gnum// /}"
            if [[ "$gnum" =~ ^[0-9]+$ ]] && ((gnum >= 1 && gnum <= gpu_count)); then
              selected_types+=("${available_gpus[$((gnum - 1))]}")
            fi
          done
          # A spare device 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

      # idx is shared across types so the device names stay unique.
      local sel added failed idx=0
      local -a configured_types=()
      for selected_gpu in "${selected_types[@]}"; do
        added=0
        failed=0
        case "$selected_gpu" in
        INTEL)
          for sel in "${INTEL_GPUS[@]}"; do
            if _incus_add_gpu_physical "gpu${idx}" "$sel"; then
              added=$((added + 1))
            else
              failed=$((failed + 1))
              msg_warn "Could not add Intel GPU (${sel})"
            fi
            idx=$((idx + 1))
          done
          # Vendor fallback if PCI/id adds failed entirely
          if [[ "$added" -eq 0 ]]; then
            _incus_add_gpu_physical "gpu0" "vendorid=8086" && added=1 || true
          fi
          if [[ "$added" -gt 0 ]]; then
            configured_types+=("INTEL")
            msg_ok "Intel GPU passthrough configured (${added})"
          fi
          ;;
        AMD)
          for sel in "${AMD_GPUS[@]}"; do
            if _incus_add_gpu_physical "gpu${idx}" "$sel"; then
              added=$((added + 1))
            else
              failed=$((failed + 1))
              msg_warn "Could not add AMD GPU (${sel})"
            fi
            idx=$((idx + 1))
          done
          if [[ "$added" -eq 0 ]]; then
            _incus_add_gpu_physical "gpu0" "vendorid=1002" && added=1 || true
          fi
          if [[ "$added" -gt 0 ]]; then
            configured_types+=("AMD")
            msg_ok "AMD GPU passthrough configured (${added})"
          fi
          ;;
        NVIDIA)
          for sel in "${NVIDIA_GPUS[@]}"; do
            if _incus_add_gpu_physical "gpu${idx}" "$sel"; then
              added=$((added + 1))
            else
              failed=$((failed + 1))
              msg_warn "Could not add NVIDIA GPU (${sel})"
            fi
            idx=$((idx + 1))
          done
          if [[ "$added" -eq 0 ]]; then
            _incus_add_gpu_physical "gpu0" "vendorid=10de" && added=1 || true
          fi
          # Optional NVIDIA char nodes (driver interface)
          local ndev nidx=0
          for ndev in "${NVIDIA_CHAR_DEVS[@]}"; do
            local nname
            nname=$(basename "$ndev" | tr -c 'A-Za-z0-9' '_')
            incus config device add "${CT_NAME}" "nvidia_${nname}_${nidx}" unix-char "source=${ndev}" "path=${ndev}" >>"${LOGFILE:-$INCUS_BUILD_LOG}" 2>&1 || true
            nidx=$((nidx + 1))
          done
          if [[ "$added" -gt 0 || "$nidx" -gt 0 ]]; then
            configured_types+=("NVIDIA")
            msg_ok "NVIDIA GPU passthrough configured (gpu=${added}, char=${nidx})"
          fi
          ;;
        esac
      done

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

      if [[ -z "${GPU_TYPE:-}" ]]; then
        msg_warn "GPU passthrough requested but no device could be attached (check permissions / incus info --resources)"
      fi
    else
      msg_custom "ℹ️" "${YW}" "No GPU devices found for passthrough (lspci/DRM empty)"
    fi
  fi

  # USB serial (privileged / optional bind) — mirrors PVE passthrough.func
  if [[ "${CT_TYPE:-1}" == "0" || "${ENABLE_USB:-no}" == "yes" ]]; then
    local usb_dev usb_idx=0
    for usb_dev in /dev/ttyUSB0 /dev/ttyUSB1 /dev/ttyACM0; do
      [[ -e "$usb_dev" ]] || continue
      local usb_name="usbchar${usb_idx}"
      if incus config device add "${CT_NAME}" "$usb_name" unix-char "source=${usb_dev}" "path=${usb_dev}" \
        >>"${LOGFILE:-$INCUS_BUILD_LOG}" 2>&1; then
        msg_ok "USB device ${usb_dev} attached as ${usb_name}"
      else
        msg_warn "Could not attach ${usb_dev} (need privileged CT or device permissions)"
      fi
      usb_idx=$((usb_idx + 1))
    done
  fi

  # Optional extra disk: INCUS_EXTRA_DISK=/path/or/pool/volume INCUS_EXTRA_DISK_PATH=/mnt/data
  if [[ -n "${INCUS_EXTRA_DISK:-${var_extra_disk:-}}" ]]; then
    local edisk="${INCUS_EXTRA_DISK:-$var_extra_disk}"
    local epath="${INCUS_EXTRA_DISK_PATH:-${var_extra_disk_path:-/mnt/extra}}"
    msg_info "Adding extra disk device"
    if incus config device add "${CT_NAME}" extradata disk "source=${edisk}" "path=${epath}" \
      >>"${LOGFILE:-$INCUS_BUILD_LOG}" 2>&1; then
      msg_ok "Extra disk mounted at ${epath}"
    else
      msg_warn "Could not add extra disk (source=${edisk})"
    fi
  fi

  if [[ "${ENABLE_TUN:-no}" == "yes" ]] && ! incus_ct_exec test -c /dev/net/tun 2>/dev/null; then
    if incus config device add "${CT_NAME}" tun unix-char source=/dev/net/tun path=/dev/net/tun \
      >>"${LOGFILE:-$INCUS_BUILD_LOG}" 2>&1; then
      msg_ok "TUN device attached"
    else
      msg_warn "Could not add TUN device"
      echo -e "${TAB}${INFO} Nesting/Docker apps: also enable nesting (security.nesting=true)."
    fi
  fi

  if [[ "${ENABLE_FUSE:-no}" == "yes" ]] && ! incus_ct_exec test -c /dev/fuse 2>/dev/null; then
    if incus config device add "${CT_NAME}" fuse unix-char source=/dev/fuse path=/dev/fuse \
      >>"${LOGFILE:-$INCUS_BUILD_LOG}" 2>&1; then
      msg_ok "FUSE device attached"
    else
      msg_warn "Could not add FUSE device"
    fi
  fi

  if [[ -e /dev/apex_0 ]]; then
    msg_custom "🔌" "${BL}" "Detected Coral TPU - configuring passthrough"
    _incus_soft incus config device add "${CT_NAME}" apex0 unix-char source=/dev/apex_0 path=/dev/apex_0 >>"${LOGFILE:-$INCUS_BUILD_LOG}" 2>&1
  fi
  return 0
}

incus_wait_for_network() {
  msg_info "Waiting for the container network"

  local net_type="" max_wait=40
  net_type=$(incus network show "${BRG:-}" 2>/dev/null | awk '/^type:/ {print $2; exit}')
  case "${net_type}" in
  physical | macvlan | sriov) max_wait=90 ;;
  esac

  local ip_in_lxc="" i
  for ((i = 1; i <= max_wait; i++)); do
    ip_in_lxc=$(incus_ct_exec ip -4 addr show dev eth0 2>/dev/null | awk '/inet / {print $2}' | cut -d/ -f1)
    [[ -z "$ip_in_lxc" ]] && ip_in_lxc=$(incus_ct_exec ip -6 addr show dev eth0 scope global 2>/dev/null | awk '/inet6 / {print $2}' | cut -d/ -f1 | head -n1)
    [[ -z "$ip_in_lxc" ]] && ip_in_lxc=$(incus_instance_field "${CT_NAME}" 4 | tr -d '"' | awk '{print $1}' | cut -d/ -f1)
    [[ -n "$ip_in_lxc" && "$ip_in_lxc" != "-" ]] && break
    sleep 1
  done

  if [[ -z "$ip_in_lxc" || "$ip_in_lxc" == "-" ]]; then
    msg_warn "No IP assigned to ${CT_NAME} after ${max_wait}s — continuing anyway"
    echo -e "${YW}Troubleshooting:${CL}"
    echo "  • Verify network ${BRG} exists and has connectivity"
    echo "  • Check DHCP server (physical/macvlan often needs >20s)"
    echo "  • Verify static IP configuration"
    echo -e "${YW}Installation will continue; network-dependent steps may fail.${CL}"
    export IP=""
    return 0
  fi

  local ping_success=false retry
  for retry in {1..3}; do
    if incus_ct_exec ping -c 1 -W 2 1.1.1.1 &>/dev/null ||
      incus_ct_exec ping -c 1 -W 2 8.8.8.8 &>/dev/null ||
      incus_ct_exec ping6 -c 1 -W 2 2606:4700:4700::1111 &>/dev/null ||
      incus_ct_exec timeout 3 bash -c 'exec 3<>/dev/tcp/1.1.1.1/443' &>/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"
    echo -e "${YW}Container may have limited internet access. Installation will continue...${CL}"
  else
    msg_ok "Network reachable (${ip_in_lxc})"
  fi
  export IP="$ip_in_lxc"
}

fix_gpu_gids() {
  [[ -z "${GPU_TYPE:-}" ]] && return 0
  msg_info "Detecting and setting correct GPU group IDs"
  local video_gid render_gid
  video_gid=$(incus_ct_exec getent group video 2>/dev/null | cut -d: -f3)
  render_gid=$(incus_ct_exec getent group render 2>/dev/null | cut -d: -f3)
  [[ -z "$video_gid" ]] && incus_ct_exec groupadd -r video 2>/dev/null || true
  [[ -z "$render_gid" ]] && incus_ct_exec groupadd -r render 2>/dev/null || true
  video_gid=$(incus_ct_exec getent group video 2>/dev/null | cut -d: -f3)
  render_gid=$(incus_ct_exec getent group render 2>/dev/null | cut -d: -f3)
  [[ -z "$video_gid" ]] && video_gid="44"
  [[ -z "$render_gid" ]] && render_gid="104"

  # Incus gpu devices support gid= (container ownership) — docs: devices_gpu
  local dev_name
  while IFS= read -r dev_name; do
    [[ -z "$dev_name" || "$dev_name" != gpu* ]] && continue
    _incus_soft incus config device set "${CT_NAME}" "$dev_name" "gid=${video_gid}" "mode=0660" >>"${LOGFILE:-$INCUS_BUILD_LOG}" 2>&1
  done < <(incus config device list "${CT_NAME}" 2>/dev/null || true)

  # Best-effort permissions inside the CT when /dev/dri is visible
  incus_ct_exec bash -c "
    if [[ -d /dev/dri ]]; then
      for dev in /dev/dri/*; do
        [[ -e \"\$dev\" ]] || continue
        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
      done
    fi
  " &>/dev/null || true
  msg_ok "GPU passthrough configured (video:${video_gid}, render:${render_gid})"
}

incus_fix_debian13_root_ownership() {
  [[ "${var_os:-}" == "debian" && "${var_version:-}" == "13" ]] || return 0
  incus_ct_exec chown root:root / 2>/dev/null || true
}

incus_set_root_password() {
  [[ -z "${PW:-}" ]] && return 0
  local pw_raw="${PW#--password }"
  [[ -z "$pw_raw" ]] && return 0
  msg_info "Setting root password"
  printf 'root:%s\n' "$pw_raw" | incus exec "${CT_NAME}" -- chpasswd &>/dev/null && msg_ok "Set root password" || msg_warn "Could not set root password"
}

incus_customize_container() {
  msg_info "Customizing container"
  ARCH="$(_cs_host_arch)"

  if [[ "${var_os:-debian}" == "alpine" ]]; then
    sleep 2
    local alpine_rel="v${IMAGE_VERSION:-${var_version:-3.21}}"
    [[ "$alpine_rel" != v3.* ]] && alpine_rel="latest-stable"
    incus_ct_exec /bin/sh -c "cat <<EOF >/etc/apk/repositories
http://dl-cdn.alpinelinux.org/alpine/${alpine_rel}/main
http://dl-cdn.alpinelinux.org/alpine/${alpine_rel}/community
EOF"
    incus_ct_exec ash -c "apk add bash newt curl openssh nano mc ncurses jq >/dev/null" || msg_warn "Alpine base package install had issues"
  elif [[ "${var_os:-debian}" =~ ^(debian|ubuntu|devuan)$ ]]; then
    sleep 2
    local _ct_env='export LC_ALL=C.UTF-8 LANG=C.UTF-8 DEBIAN_FRONTEND=noninteractive;'
    [[ "${var_os}" == "devuan" ]] && incus_ct_exec bash -c "${_ct_env} apt-get update >/dev/null && apt-get install -y locales >/dev/null" || true

    local tz_val="${timezone:-UTC}"
    [[ -z "$tz_val" ]] && tz_val=$(timedatectl show --property=Timezone --value 2>/dev/null || echo "UTC")
    [[ "$tz_val" == Etc/* ]] && tz_val="UTC"
    timezone="$tz_val"
    if incus_ct_exec test -e "/usr/share/zoneinfo/$tz_val"; then
      incus_ct_exec bash -c "${_ct_env} ln -sf \"/usr/share/zoneinfo/$tz_val\" /etc/localtime && echo \"$tz_val\" >/etc/timezone || true"
    fi

    local _base_pkgs="sudo curl mc gnupg2 jq"
    [[ "$ARCH" == "arm64" ]] && _base_pkgs+=" openssh-server wget gcc"

    if ! incus_ct_exec 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"
      incus_ct_exec bash -c "echo -e 'nameserver 8.8.8.8\nnameserver 1.1.1.1' >/etc/resolv.conf"
    fi

    incus_ct_exec bash -c "${_ct_env} apt-get update >/dev/null 2>&1 && apt-get install -y ${_base_pkgs} >/dev/null 2>&1" || {
      msg_warn "apt-get update failed, trying alternate mirrors..."
      msg_custom "ℹ️" "${YW}" "Probing alternate mirrors (this can take 1-2 minutes on network issues)"
      incus_ct_exec env APT_BASE="$_base_pkgs" bash -c '
        DISTRO=$(. /etc/os-release 2>/dev/null && echo "$ID" || echo "debian")
        if [ "$DISTRO" = "ubuntu" ]; then
          MIRRORS="de.archive.ubuntu.com fr.archive.ubuntu.com archive.ubuntu.com mirrors.edge.kernel.org"
        else
          MIRRORS="ftp.de.debian.org ftp.fr.debian.org ftp.nl.debian.org debian.mirror.lrz.de mirror.init7.net"
        fi
        echo "Acquire::By-Hash \"no\";" >/etc/apt/apt.conf.d/99no-by-hash
        for m in $MIRRORS; do
          sed -i "s|URIs: http[s]*://[^/]*/|URIs: http://${m}/|g; s|deb http[s]*://[^/]*/|deb http://${m}/|g" /etc/apt/sources.list.d/debian.sources 2>/dev/null || \
          sed -i "s|deb http[s]*://[^/]*/|deb http://${m}/|g" /etc/apt/sources.list 2>/dev/null || true
          rm -rf /var/lib/apt/lists/*
          apt-get update >/dev/null 2>&1 && apt-get install -y $APT_BASE >/dev/null 2>&1 && exit 0
        done
        exit 1
      ' || { msg_error "apt-get base packages installation failed"; exit 100; }
    }
  else
    sleep 2
    incus_ct_exec 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 zypper >/dev/null 2>&1 && zypper -n install curl >/dev/null 2>&1) || (command -v pacman >/dev/null 2>&1 && pacman -Sy --noconfirm curl >/dev/null 2>&1)" || true
  fi

  incus_set_root_password
  msg_ok "Container customized"
}

# ------------------------------------------------------------------------------
# _incus_wait_for_detached_install <base>
#
# The console closed while the install ran. incus ended the exec session that
# was watching it, but the install itself is detached and carries on. Wait for
# what it leaves behind: .failed (its exit code, read by the caller), .done, or
# the process gone without either.
# ------------------------------------------------------------------------------
_incus_wait_for_detached_install() {
  local base="$1" pid="" waited=0
  local poll="${_CS_HANGUP_POLL:-10}" limit="${_CS_HANGUP_TIMEOUT:-21600}"
  while :; do
    incus_ct_exec test -f "${base}.failed" >/dev/null 2>&1 && return 0
    incus_ct_exec test -f "${base}.done" >/dev/null 2>&1 && return 0
    pid="$(incus_ct_exec cat "${base}.pid" 2>/dev/null | tr -d '[:space:]')"
    if [[ "$pid" =~ ^[0-9]+$ ]] && ! incus_ct_exec kill -0 "$pid" >/dev/null 2>&1; then
      return 0
    fi
    ((waited >= limit)) && return 0
    sleep "$poll"
    waited=$((waited + poll))
  done
}

_incus_push_functions_and_run_install() {
  # Sets INCUS_LAST_INSTALL_EXIT (do not capture stdout — msg_* writes there).
  INCUS_LAST_INSTALL_EXIT=0
  incus_ct_exec bash -c "cat > /tmp/incus-functions <<'INNEREOF'
${FUNCTIONS_FILE_PATH}
INNEREOF" >>"${LOGFILE:-$INCUS_BUILD_LOG}" 2>&1 || { msg_error "Failed to push functions"; exit 1; }

  if [[ "${DNS_RETRY_OVERRIDE:-}" == "true" ]]; then
    msg_info "Applying the DNS override (8.8.8.8, 1.1.1.1)"
    incus_ct_exec bash -c "echo -e 'nameserver 8.8.8.8\nnameserver 1.1.1.1' >/etc/resolv.conf" || true
    msg_ok "DNS override applied"
  fi

  # Not msg_info: that starts a spinner, and nothing here ever stopped it. The
  # install script below runs for minutes and prints its own output, including
  # prompts - the spinner kept redrawing over them, which is why Immich's
  # machine-learning menu could not be read and the keystroke landed in the
  # spinner line. A static line, and the script owns the terminal from here.
  # Emptied first, or msg_custom would resume a block the host left open.
  _MSG_BLOCKS=()
  msg_custom "🚀" "${GN}" "Starting application installation"
  local _install_script _run_env lxc_exit=0 install_exit_code=0
  # Checked here: inside $(...) below, stdout is the capture pipe, never the terminal.
  local _incus_tty_out=0 _incus_tty_in=0
  [[ -t 1 ]] && _incus_tty_out=1
  [[ -t 0 ]] && _incus_tty_in=1
  _install_script="$(_cs_fetch_text "install/${var_install}.sh")"
  _run_env="$(_incus_build_install_env)"
  _run_env+=$'\nsource /dev/stdin <<<"$(cat /tmp/incus-functions)"'
  _run_env+=$'\n'"$(_incus_prompt_shim)"

  # No pty on purpose: under `incus exec -t` apt's tcsetattr fails with EIO and kills the shell.
  set +Eeuo pipefail
  trap - ERR

  # incus ends an exec session the moment its client goes away, so closing the
  # console killed the install outright - the one thing lxc-attach does not do.
  # Run it detached from that session and only watch it from here. The console
  # keeps the view and the keyboard: input reaches the install through a fifo
  # for as long as there is a console, and once there is none the reads return
  # EOF and the prompts take their defaults.
  local _base="/root/.install-${SESSION_ID}"
  local _runner _watcher _body
  _runner='setsid bash "$1".sh <"$1".in >>"$1".out 2>&1 &
echo $! >"$1".pid'
  _watcher='tail -n +1 -f "$1".out &
_tp=$!
while [ ! -f "$1".done ] && [ ! -f "$1".failed ]; do sleep 2; done
sleep 1
kill $_tp 2>/dev/null'
  # The trailing touch is a completion sentinel: no install script exits early.
  _body="${_run_env}
${_install_script}
touch ${_base}.done"

  incus exec "${CT_NAME}" -- bash -c "cat >${_base}.sh <<'CSBODYEOF'
${_body}
CSBODYEOF
cat >${_base}.run <<'CSRUNEOF'
${_runner}
CSRUNEOF
cat >${_base}.watch <<'CSWATCHEOF'
${_watcher}
CSWATCHEOF
rm -f ${_base}.in ${_base}.pid ${_base}.done ${_base}.failed ${_base}.out
mkfifo ${_base}.in" >>"${LOGFILE:-$INCUS_BUILD_LOG}" 2>&1

  # A writer has to hold the fifo open before the install opens it to read.
  incus exec "${CT_NAME}" -- sh -c "cat >${_base}.in" &
  local _feeder=$!
  incus exec "${CT_NAME}" -- bash "${_base}.run" "${_base}" >/dev/null 2>&1

  incus exec "${CT_NAME}" -- bash "${_base}.watch" "${_base}" 2>&1 |
    tee >(sed 's/.*\r//' >>"${LOGFILE:-$INCUS_BUILD_LOG}")
  kill "$_feeder" 2>/dev/null || true
  wait "$_feeder" 2>/dev/null || true

  # The watcher is gone either way - because the install ended, or because the
  # console did. Only the markers say which.
  _incus_wait_for_detached_install "$_base"
  lxc_exit=0
  set -Eeuo pipefail
  declare -f error_handler &>/dev/null && trap 'error_handler' ERR || true

  if [[ -n "${SESSION_ID:-}" ]]; then
    local error_flag="/root/.install-${SESSION_ID}.failed"
    if incus_ct_exec test -f "$error_flag" 2>/dev/null; then
      install_exit_code=$(incus_ct_exec cat "$error_flag" 2>/dev/null | tr -d '[:space:]') || true
      [[ "$install_exit_code" =~ ^[0-9]+$ ]] || install_exit_code=199
      incus_ct_exec rm -f "$error_flag" 2>/dev/null || true
    fi
  fi
  [[ "$install_exit_code" -eq 0 && "$lxc_exit" -ne 0 ]] && install_exit_code=$lxc_exit

  # A shell killed mid-run - by the kernel, or by the terminal fault the pty
  # experiment caused - never reaches its ERR trap, so no .failed flag is
  # written and `incus exec` still reports 0. Without the sentinel that counted
  # as success, and the operator got a URL pointing at an empty container.
  if [[ "$install_exit_code" -eq 0 && -n "${SESSION_ID:-}" ]]; then
    if incus_ct_exec test -f "/root/.install-${SESSION_ID}.done" 2>/dev/null; then
      incus_ct_exec rm -f "/root/.install-${SESSION_ID}.done" 2>/dev/null || true
    else
      msg_error "Install script stopped before it finished - nothing reported it"
      [[ "${_CS_HANGUP:-}" == "1" ]] && msg_custom "ℹ️" "${YW}" "The console was closed; the install ran on detached, so look at its log for the reason"
      msg_custom "ℹ️" "${YW}" "Output: incus exec ${CT_NAME} -- tail -50 /root/.install-${SESSION_ID}.log"
      install_exit_code=199
    fi
  fi
  incus_ct_exec rm -f "${_base}.sh" "${_base}.run" "${_base}.watch" "${_base}.in" "${_base}.pid" "${_base}.out" >/dev/null 2>&1 || true
  INCUS_LAST_INSTALL_EXIT=$install_exit_code
}

_incus_build_combined_log() {
  combined_log="${combined_log:-/tmp/incus-install-${SESSION_ID}-combined.log}"
  {
    echo "================================================================================"
    echo "COMBINED INSTALLATION LOG - ${APP:-LXC}"
    echo "Container: ${CT_NAME}"
    echo "Session ID: ${SESSION_ID}"
    echo "Timestamp: $(date '+%Y-%m-%d %H:%M:%S')"
    echo "================================================================================"
    echo ""
  } >"$combined_log"

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

  local temp_install_log="/tmp/.install-temp-${SESSION_ID}.log"
  if incus file pull "${CT_NAME}/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"
  fi

  # Pull the structured error capture (.errinfo) - primary source for the
  # telemetry error trace (exact output of the failing command)
  local host_errinfo="/tmp/.errinfo-${SESSION_ID}"
  if incus file pull "${CT_NAME}/root/.install-${SESSION_ID}.log.errinfo" "$host_errinfo" 2>/dev/null && [[ -s "$host_errinfo" ]]; then
    TELEMETRY_ERRINFO="$host_errinfo"
    export TELEMETRY_ERRINFO
  fi

  echo -e "${GN}✔${CL} Installation log: ${BL}${combined_log}${CL}"
  INSTALL_LOG="$combined_log"
  export INSTALL_LOG
}

incus_run_install_script_with_recovery() {
  incus_log_section "Application Installation: ${APP}"

  declare -f start_install_timer &>/dev/null && start_install_timer || true
  post_progress_to_api "installing" 2>/dev/null || true
  CONTAINER_INSTALLING=true
  export CONTAINER_INSTALLING

  _incus_push_functions_and_run_install
  local install_exit_code="${INCUS_LAST_INSTALL_EXIT:-1}"

  if [[ "$install_exit_code" -eq 0 ]]; then
    CONTAINER_INSTALLING=false
    INCUS_BUILD_OK=1
    export INCUS_BUILD_OK
    return 0
  fi

  msg_error "Installation failed in container ${CT_NAME} (exit code: ${install_exit_code})"
  _incus_build_combined_log
  post_update_to_api "failed" "$install_exit_code" 2>/dev/null || true
  # This menu owns cleanup — EXIT trap must not prompt again.
  INCUS_ORPHAN_HANDLED=1
  export INCUS_ORPHAN_HANDLED

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

  echo ""
  local is_oom=false is_network_issue=false is_apt_issue=false is_cmd_not_found=false
  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

  [[ $install_exit_code -eq 134 || $install_exit_code -eq 137 || $install_exit_code -eq 243 ]] && is_oom=true
  case "$install_exit_code" in
  100 | 101 | 102)
    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)
    [[ -f "$combined_log" ]] && grep -qiE 'dpkg|apt-get|broken packages|unmet dependencies' "$combined_log" && is_apt_issue=true
    ;;
  esac
  [[ $install_exit_code -eq 127 ]] && is_cmd_not_found=true
  case "$install_exit_code" in
  6 | 7 | 22 | 28 | 35 | 52 | 56 | 57 | 75 | 78) is_network_issue=true ;;
  100)
    [[ -f "$combined_log" ]] && grep -qiE 'Failed to fetch|Could not resolve|Network is unreachable' "$combined_log" && is_network_issue=true
    ;;
  esac
  if [[ $install_exit_code -eq 1 && -f "$combined_log" ]]; then
    grep -qiE 'E: Unable to|broken packages|unmet dependencies|dpkg --configure' "$combined_log" && is_apt_issue=true
    grep -qiE 'Cannot allocate memory|Out of memory|oom-killer|JavaScript heap' "$combined_log" && is_oom=true
    grep -qiE 'Could not resolve|DNS resolution failed|Temporary failure resolving|Network is unreachable|Failed to fetch' "$combined_log" && is_network_issue=true
    grep -qiE ': command not found' "$combined_log" && is_cmd_not_found=true
  fi

  [[ -n "$error_explanation" ]] && echo -e "${TAB}${RD}Error: ${error_explanation}${CL}" && echo ""
  if [[ $install_exit_code -eq 10 ]]; then
    echo -e "${TAB}${INFO} Privileged / nesting / device hint:"
    echo -e "${TAB}${INFO}  • Privileged: ${GN}security.privileged=true${CL} (USB, Docker-in-LXC)"
    echo -e "${TAB}${INFO}  • Nesting:     ${GN}security.nesting=true${CL} (Docker/Podman inside CT)"
    echo -e "${TAB}${INFO}  • Re-run Advanced settings and enable the matching options."
    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 APT_OPTION="" OOM_OPTION="" DNS_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
      echo -e "  ${GN}${next_option})${CL} Retry with more resources (RAM: ${RAM_SIZE}→$((RAM_SIZE * 2)) MiB, CPU: ${CORE_COUNT}→$((CORE_COUNT * 2)) cores)"
      OOM_OPTION=$next_option
      next_option=$((next_option + 1))
    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 read_rc=0
  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 ${CT_NAME}${CL}"
      incus_delete_container "${CT_NAME}"
      ;;
    2)
      echo -e "\n${TAB}${YW}Container ${CT_NAME} kept for debugging${CL}"
      echo -e "${TAB}${INFO} Access: ${GN}incus exec ${CT_NAME} -- bash${CL}"
      exit "$install_exit_code"
      ;;
    3)
      echo -e "\n${TAB}${HOLD}${YW}Removing container ${CT_NAME} for rebuild...${CL}"
      incus_delete_container "${CT_NAME}"
      local old_name="$CT_NAME"
      CT_NAME="$(get_valid_container_id "$CT_NAME")"
      CTID="$CT_NAME"
      export CT_NAME CTID VERBOSE=yes var_verbose=yes
      echo -e "${YW}Rebuilding: ${old_name} → ${CT_NAME} (verbose)${CL}"
      msg_info "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...${CL}"
          incus_ct_exec ash -c "apk fix 2>/dev/null || true; apk update 2>/dev/null || true" || true
        else
          echo -e "\n${TAB}${HOLD}${YW}Repairing APT/DPKG state...${CL}"
          incus_ct_exec bash -c "DEBIAN_FRONTEND=noninteractive dpkg --configure -a 2>/dev/null || true; apt-get -f install -y 2>/dev/null || true; apt-get update 2>/dev/null || true" || true
        fi
        export VERBOSE=yes var_verbose=yes
        msg_info "Re-running installation script..."
        # New telemetry execution for the in-place retry
        declare -f telemetry_new_attempt &>/dev/null && telemetry_new_attempt
        declare -f post_to_api &>/dev/null && post_to_api 2>/dev/null || true
        _incus_push_functions_and_run_install
        install_exit_code="${INCUS_LAST_INSTALL_EXIT:-1}"
        if [[ "$install_exit_code" -eq 0 ]]; then
          msg_ok "Installation completed successfully after package repair!"
          post_update_to_api "done" "0" "force" 2>/dev/null || true
          CONTAINER_INSTALLING=false
          INCUS_BUILD_OK=1
          export INCUS_BUILD_OK
          return 0
        fi
        msg_error "Installation still failed after repair (exit code: ${install_exit_code})"
      fi
      if [[ -n "${OOM_OPTION}" && "${response}" == "${OOM_OPTION}" ]]; then
        handled=true
        incus_delete_container "${CT_NAME}"
        local old_ram="$RAM_SIZE" old_cpu="$CORE_COUNT"
        CT_NAME="$(get_valid_container_id "$CT_NAME")"
        CTID="$CT_NAME"
        RAM_SIZE=$((RAM_SIZE * 2))
        CORE_COUNT=$((CORE_COUNT * 2))
        export CT_NAME CTID RAM_SIZE CORE_COUNT var_ram="$RAM_SIZE" var_cpu="$CORE_COUNT"
        export VERBOSE=yes var_verbose=yes RECOVERY_ATTEMPT=$((${RECOVERY_ATTEMPT:-0} + 1))
        echo -e "${YW}Rebuilding with more resources: RAM ${old_ram}→${RAM_SIZE}, CPU ${old_cpu}→${CORE_COUNT}${CL}"
        declare -f telemetry_new_attempt &>/dev/null && telemetry_new_attempt
        build_container
        return $?
      fi
      if [[ -n "${DNS_OPTION}" && "${response}" == "${DNS_OPTION}" ]]; then
        handled=true
        incus_delete_container "${CT_NAME}"
        CT_NAME="$(get_valid_container_id "$CT_NAME")"
        CTID="$CT_NAME"
        export CT_NAME CTID DNS_RETRY_OVERRIDE=true VERBOSE=yes var_verbose=yes
        echo -e "${YW}Rebuilding with DNS override${CL}"
        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 ${CT_NAME} kept.${CL}"
        exit "$install_exit_code"
      fi
      ;;
    esac
  elif [[ $read_rc -gt 128 ]]; then
    echo ""
    msg_info "No response - removing container ${CT_NAME}"
    incus_delete_container "${CT_NAME}"
    msg_ok "Container ${CT_NAME} removed"
  else
    # read itself failed (closed/broken tty, I/O error) rather than timing
    # out - keeping the container is the reversible choice.
    while read -r -t 0.1 -n 1 _ </dev/tty 2>/dev/null; do :; done
    echo ""
    msg_error "Could not read your selection (tty error) - keeping container ${CT_NAME} for safety."
    msg_error "Remove it manually if not needed: incus delete ${CT_NAME} --force"
  fi

  # No "force": the same failure was already reported earlier in this path, and
  # force bypasses the POST_UPDATE_DONE guard, so this duplicated every failed
  # install's terminal event. Same fix as pve/backend.func.
  post_update_to_api "failed" "$install_exit_code" 2>/dev/null || true
  exit "$install_exit_code"
}

# incus exec does not carry the caller's environment like lxc-attach does, so
# everything the install side reads is passed here, quoted with %q.
_incus_build_install_env() {
  local -a env=(
    DIAGNOSTICS="${DIAGNOSTICS:-no}"
    RANDOM_UUID="${RANDOM_UUID}"
    EXECUTION_ID="${EXECUTION_ID}"
    SESSION_ID="${SESSION_ID}"
    VERBOSE="${VERBOSE:-no}"
    STD="$([ "${VERBOSE:-no}" = "yes" ] && echo "" || echo silent)"
    APP="${APP}"
    APPLICATION="${APP}"
    NSAPP="${NSAPP}"
    app="${NSAPP}"
    PASSWORD="${PW:-}"
    CTID="${CT_NAME}"
    CTTYPE="${CT_TYPE:-1}"
    PCT_OSTYPE="${var_os:-debian}"
    PCT_OSVERSION="${var_version:-13}"
    PCT_DISK_SIZE="${DISK_SIZE}"
    tz="${timezone:-UTC}"
    MODE="${METHOD:-default}"
    ENABLE_FUSE="${ENABLE_FUSE:-no}"
    ENABLE_TUN="${ENABLE_TUN:-no}"
    ENABLE_GPU="${ENABLE_GPU:-no}"
    IPV6_METHOD="${IPV6_METHOD:-auto}"
    SSH_ROOT="${SSH:-no}"
    CACHER="${APT_CACHER:-}"
    CACHER_IP="${APT_CACHER_IP:-}"
    dev_mode="${dev_mode:-}"
    COMMUNITY_SCRIPTS_URL="${INCUS_COMMUNITY_SCRIPTS_URL}"
    COMMUNITY_SCRIPTS_CORE_URL="${COMMUNITY_SCRIPTS_CORE_URL}"
    INSTALL_LOG="/root/.install-${SESSION_ID}.log"
    REPO_SOURCE="${REPO_SOURCE:-}"
    REPO_SLUG="${REPO_SLUG:-}"
    TELEMETRY_PLATFORM="incus"
    TELEMETRY_URL="${TELEMETRY_URL:-}"
    TELEMETRY_PAYLOAD_VERSION="${TELEMETRY_PAYLOAD_VERSION:-}"
    CS_ANIMATION_OK="${_incus_tty_out:-0}"
    CS_STDIN_OK="${_incus_tty_in:-0}"
  )
  # lxc-attach carries the app's var_* settings into a Proxmox container; incus exec does not.
  local v
  for v in $(compgen -e var_ || true); do env+=("$v=${!v}"); done
  if [[ -n "${HTTP_PROXY:-}" ]]; then
    env+=(HTTP_PROXY="$HTTP_PROXY" HTTPS_PROXY="$HTTP_PROXY" http_proxy="$HTTP_PROXY" https_proxy="$HTTP_PROXY"
      NO_PROXY="${HTTP_NO_PROXY:-}" no_proxy="${HTTP_NO_PROXY:-}")
  fi
  echo 'export FUNCTIONS_FILE_PATH=$(cat /tmp/incus-functions)'
  local kv
  for kv in "${env[@]}"; do
    printf 'export %s=%q\n' "${kv%%=*}" "${kv#*=}"
  done
}

# bash shows a `read -p` prompt only on a terminal, so without a pty the question was invisible.
_incus_prompt_shim() {
  cat <<'SHIMEOF'
read() {
  local -a _args=()
  local _prompt="" _flags
  while (($#)); do
    if [[ "$1" == -*p && "$1" != --* && $# -ge 2 ]]; then
      _flags="${1%p}"
      [[ "$_flags" != "-" ]] && _args+=("$_flags")
      _prompt="$2"
      shift 2
      continue
    fi
    _args+=("$1")
    shift
  done
  [[ -n "$_prompt" ]] || {
    builtin read "${_args[@]}"
    return
  }
  printf '%s' "$_prompt" >&2
  if [[ "${CS_STDIN_OK:-0}" != "1" ]]; then
    printf '%s\n' "(no input available - using the default)" >&2
    return 0
  fi
  builtin read "${_args[@]}" || {
    printf '\n' >&2
    return 0
  }
}
SHIMEOF
}

incus_build_container() {
  _incus_sync_from_pve_settings
  _incus_prepare_install_exports

  if [[ -n "${CONTAINER_STORAGE:-$STORAGE_POOL}" ]]; then
    incus_validate_storage_space "${CONTAINER_STORAGE:-$STORAGE_POOL}" "${DISK_SIZE}" || true
  fi

  incus_create_lxc_container
  post_progress_to_api "configuring" 2>/dev/null || true

  incus_configure_device_passthrough
  incus_wait_for_network
  fix_gpu_gids
  incus_fix_debian13_root_ownership
  incus_customize_container
  install_ssh_keys_into_ct
  incus_run_install_script_with_recovery
}

create_lxc_container() { incus_create_lxc_container; }