From db9adcaf7a5a2a5a44d65e4ffe236dad34603c06 Mon Sep 17 00:00:00 2001
From: MickLesk <47820557+MickLesk@users.noreply.github.com>
Date: Wed, 7 Oct 2026 19:20:49 +0200
Subject: [PATCH 1/3] Add shared VM helpers for imports, releases, checksums
 and first boot

vm/common.func (loaded by the Proxmox and Incus engines) adds vm_require_tools, vm_release_asset, vm_latest_from_index, vm_firstboot_unit, vm_wait_http and a standard summary/finish block. pve/vm-core.func adds vm_import_disk, vm_start_vm, vm_guest_exec, vm_wait_guest_agent and vm_wait_for_ip; Incus refuses those explicitly. get_vm_ip matches the NIC by MAC and skips container bridges, wait_for_cloud_init uses the guest agent, and checksum discovery covers OpenWrt, FreeBSD and TurnKey plus --checksum-url. vm-app.func now uses these helpers instead of its own copies.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .github/workflows/verify-split-files.yml |   5 +
 core/build.func                          |   2 +-
 docs/README.md                           |   1 +
 docs/backends.md                         |   3 +-
 docs/vm.md                               |  49 +-
 incus/vm-core.func                       |  54 ++-
 pve/vm-app.func                          |  56 +--
 pve/vm-core.func                         | 172 ++++++-
 tests/vm-helpers.sh                      | 565 +++++++++++++++++++++++
 vm/cloud-init.func                       |  58 ++-
 vm/common.func                           | 412 +++++++++++++++++
 11 files changed, 1294 insertions(+), 83 deletions(-)
 create mode 100644 tests/vm-helpers.sh
 create mode 100644 vm/common.func

diff --git a/.github/workflows/verify-split-files.yml b/.github/workflows/verify-split-files.yml
index e94b868..6494fd1 100644
--- a/.github/workflows/verify-split-files.yml
+++ b/.github/workflows/verify-split-files.yml
@@ -24,6 +24,7 @@ on:
       - "incus/**"
       - "tests/vm-iso-storage.sh"
       - "tests/vm-consoles.sh"
+      - "tests/vm-helpers.sh"
       - ".github/workflows/verify-split-files.yml"
   push:
     branches: [main]
@@ -39,6 +40,7 @@ on:
       - "incus/**"
       - "tests/vm-iso-storage.sh"
       - "tests/vm-consoles.sh"
+      - "tests/vm-helpers.sh"
       - ".github/workflows/verify-split-files.yml"
   workflow_dispatch:
 
@@ -66,6 +68,9 @@ jobs:
       - name: VM console regression tests
         run: bash tests/vm-consoles.sh
 
+      - name: VM helper regression tests
+        run: bash tests/vm-helpers.sh
+
       - name: Prefetch lists cover every engine file
         run: |
           set -euo pipefail
diff --git a/core/build.func b/core/build.func
index d31fd18..bf748a4 100644
--- a/core/build.func
+++ b/core/build.func
@@ -236,7 +236,7 @@ _CS_ENGINE_FILES=(
   api/errorlog.func api/exitcodes.func api/sysinfo.func
   api/telemetry.func
   ui/build-ui.func ui/advanced.func ui/defaults.func
-  ui/menu.func ui/validate.func vm/cloud-init.func
+  ui/menu.func ui/validate.func vm/cloud-init.func vm/common.func
   core/core.func core/dev-mode.func core/error_handler.func
   lxc/install.func lxc/platform.func host/preflight.func
   host/source-origin.func lib/tools.func lib/db.func
diff --git a/docs/README.md b/docs/README.md
index 53f58b5..2d650ca 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -104,6 +104,7 @@ an update before it starts.
 | [`api/sysinfo.func`](../api/sysinfo.func) | Host and container facts, origin detection |
 | [`api/telemetry.func`](../api/telemetry.func) | Payload assembly and delivery |
 | [`vm/cloud-init.func`](../vm/cloud-init.func) | Cloud-init configuration for VMs |
+| [`vm/common.func`](../vm/common.func) | Backend-independent VM script helpers (tools, releases, checksums, first boot, summary) |
 | [`pve/backend.func`](../pve/backend.func) | Container creation via `pct` |
 | [`pve/vm-core.func`](../pve/vm-core.func) | VM creation via `qm` |
 | [`pve/vm-app.func`](../pve/vm-app.func) | Running LXC applications inside a VM |
diff --git a/docs/backends.md b/docs/backends.md
index a71bcf6..ca47423 100644
--- a/docs/backends.md
+++ b/docs/backends.md
@@ -140,7 +140,8 @@ is changed. Missing or invalid ISO storage is reported before VM creation.
 On Incus this helper explicitly fails: these installer scripts require
 Proxmox's `pvesm` and `qm`.
 
-Run the host-independent regression tests with `bash tests/vm-iso-storage.sh`.
+Run the host-independent regression tests with `bash tests/vm-iso-storage.sh`
+and, for the shared VM helpers, `bash tests/vm-helpers.sh`.
 
 ### Backend-specific VM creation
 
diff --git a/docs/vm.md b/docs/vm.md
index 055cd3e..dfd71b6 100644
--- a/docs/vm.md
+++ b/docs/vm.md
@@ -1,4 +1,4 @@
-# `vm/` — cloud-init
+# `vm/` — cloud-init and shared VM helpers
 
 Back to the [index](README.md).
 
@@ -27,8 +27,55 @@ helpers as unavailable is what keeps it on its fallback branch instead of
 letting it call into a function that would need `qm`. `vm_provision` applies
 the same `CLOUDINIT_*` variables through the `cloud-init.*` instance keys.
 
+`get_vm_ip <vmid> [timeout] [mac]` reads addresses through the guest agent.
+Pass the VM's MAC: only that NIC then counts, which is the only reliable answer
+once the guest runs Docker, Podman or Kubernetes. Without a MAC, bridge and
+tunnel interfaces those create are skipped; loopback and link-local addresses
+never count. `wait_for_cloud_init` asks the guest agent
+(`cloud-init status --wait`) first, which needs neither an address nor SSH
+keys, and falls back to SSH only for guests without an agent.
+
 One thing to know before editing it: this file declares its functions as
 `function name() {` rather than `name() {` — the only one that does, apart from
 `get_lxc_ip` in [`core/core.func`](../core/core.func). Anything that greps for
 function definitions across the engine will miss them unless it accounts for
 that.
+
+## [`common.func`](../vm/common.func)
+
+Helpers a VM script needs whatever the hypervisor. Both
+[`pve/vm-core.func`](../pve/vm-core.func) and
+[`incus/vm-core.func`](../incus/vm-core.func) load it, so a script finds the
+same functions on either host. Nothing in it calls `qm` or `incus`.
+
+| Function | Contract |
+| --- | --- |
+| `vm_require_tools <cmd>...` | Installs the packages for missing commands (`jq`, `xz`, `virt-customize`, `unzip`, `zstd`, `7z`, …) before anything is created; returns non-zero, with the reason, when it cannot. |
+| `vm_release_asset <github\|gitlab\|codeberg> <owner/repo> <asset regex> [tag]` | Resolves a release through [`lib/forge.func`](../lib/forge.func) — tokens, rate limits and the API-less GitHub fallback included. Sets `VM_RELEASE_TAG`, `VM_RELEASE_VERSION`, `VM_RELEASE_ASSET`, `VM_RELEASE_URL` and, from GitHub's asset digest, `VM_RELEASE_SHA256`. |
+| `vm_latest_from_index <url> <pcre> [--sort-by <pcre>] [--probe <url with {}>]...` | Newest match on an HTML download index (`grep -oP`, so `\K` works). `--sort-by` orders by part of the match; each `--probe` template is tried newest first and the first answering URL wins. Sets `VM_INDEX_LATEST` and `VM_INDEX_URL`. Never falls back to a hardcoded release. |
+| `vm_firstboot_unit <image> <name> <script> [--description …] [--after <unit>]... [--requires-path <path>] [--cloud-init yes\|no]` | Stages `<script>` as `/usr/local/sbin/<name>` plus a run-once `<name>.service`. The marker `/var/lib/community-scripts/<name>.done` (`VM_FIRSTBOOT_MARKER`) is written only after success, so a failure is retried on the next boot. With Cloud-Init the unit is wanted by `cloud-init.target` and ordered after `cloud-final.service`; wanting `multi-user.target` there would create an ordering cycle. |
+| `vm_wait_http <url> [timeout] [--insecure]` | Succeeds on any 2xx/3xx, or 401/403 from a login page. |
+| `vm_print_summary ["Label=value"]...`, `vm_next_steps <step>...`, `vm_finish [message]` | The standard closing block: VM ID, hostname, resources, state and `VM_IP`, extra rows, numbered next steps, then the `done` telemetry and the completion message. |
+
+Checksums: `vm_fetch_image` verifies the vendor checksum for Debian, Ubuntu,
+TrueNAS, OpenWrt (`sha256sums`), FreeBSD VM images (`CHECKSUM.SHA256`) and
+TurnKey (`.hash`) by itself. Elsewhere pass `--sha256` (for example
+`VM_RELEASE_SHA256`) or `--checksum-url <sums file>`; GNU, BSD and bare-hash
+layouts are understood and the algorithm follows from the hash length.
+
+### Proxmox-only counterparts
+
+[`pve/vm-core.func`](../pve/vm-core.func) adds the steps that drive `qm`:
+
+| Function | Contract |
+| --- | --- |
+| `vm_import_disk <vmid> <image> <storage> [format]` | `qm disk import` (or `qm importdisk` on older hosts) with `DISK_IMPORT_FORMAT`; sets `VM_IMPORTED_DISK` to the volume Proxmox reported or the `unusedN` entry the import added. Never guesses a name. |
+| `vm_start_vm [label]` | Starts the VM when `START_VM=yes`. |
+| `vm_wait_guest_agent <vmid> [timeout]` | Waits until the guest agent answers. |
+| `vm_guest_exec <vmid> <timeout> [--] <cmd>...` | Runs a command through the guest agent; prints its stdout and returns its exit code (124: still running). |
+| `vm_wait_for_ip [timeout]` | Sets `VM_IP` from the NIC matching `MAC`; warns and returns non-zero when there is none yet. |
+
+On Incus these fail with exit 119 and say why: `incus_vm_create` imports,
+starts and waits for the agent itself.
+
+Run the host-independent regression tests with `bash tests/vm-helpers.sh`.
diff --git a/incus/vm-core.func b/incus/vm-core.func
index 38d6269..cab2de8 100644
--- a/incus/vm-core.func
+++ b/incus/vm-core.func
@@ -45,6 +45,8 @@ _incus_vm_source "core/core.func"
 # Value checks that do not depend on the platform — the Proxmox VE VM path
 # loads the same file, so an MTU means the same thing on both.
 _incus_vm_source "host/validate.func"
+# Helpers that do not touch qm or incus, shared with pve/vm-core.func.
+_incus_vm_source "vm/common.func"
 _incus_vm_source "incus/core.func"
 load_incus_functions
 incus_install_compat_aliases
@@ -871,6 +873,19 @@ vm_select_iso_storage() {
   return 119
 }
 
+# qm-specific steps of the Proxmox VM scripts. incus_vm_create imports, starts
+# and waits for the agent itself, so there is nothing to translate them into;
+# they fail loudly instead of pretending to have worked.
+_incus_vm_qm_only() {
+  msg_error "$1 drives qm and is only available on Proxmox VE; use incus_vm_create on Incus."
+  return 119
+}
+vm_import_disk() { _incus_vm_qm_only vm_import_disk; }
+vm_start_vm() { _incus_vm_qm_only vm_start_vm; }
+vm_wait_guest_agent() { _incus_vm_qm_only vm_wait_guest_agent; }
+vm_guest_exec() { _incus_vm_qm_only vm_guest_exec; }
+vm_wait_for_ip() { _incus_vm_qm_only vm_wait_for_ip; }
+
 # The Proxmox counterpart picks a disk format from the storage type because qm
 # importdisk has to be told one. Incus decides the on-pool layout itself and
 # never exposes it, so the only thing left to decide is the format the image
@@ -1252,26 +1267,21 @@ check_hostname_conflict() {
 # which guest agent is worth installing.
 
 vm_image_checksum() {
-  local url="${1:?url}" tool sums style want
+  local url="${1:?url}" name sums
 
+  name="${url%%\?*}"
+  name="${name##*/}"
   case "$url" in
-  *cloud.debian.org/*) tool=sha512sum; sums="${url%/*}/SHA512SUMS"; style=sums ;;
-  *cloud-images.ubuntu.com/*) tool=sha256sum; sums="${url%/*}/SHA256SUMS"; style=sums ;;
-  *download.truenas.com/*) tool=sha256sum; sums="${url}.sha256"; style=bare ;;
+  *cloud.debian.org/*) sums="${url%/*}/SHA512SUMS" ;;
+  *cloud-images.ubuntu.com/*) sums="${url%/*}/SHA256SUMS" ;;
+  *download.truenas.com/*) sums="${url}.sha256" ;;
+  *downloads.openwrt.org/*) sums="${url%/*}/sha256sums" ;;
+  *download.freebsd.org/*/VM-IMAGES/*) sums="${url%/*}/CHECKSUM.SHA256" ;;
+  *mirror.turnkeylinux.org/*) sums="${url}.hash" ;;
   *) return 1 ;;
   esac
 
-  command -v "$tool" >/dev/null 2>&1 || return 1
-
-  if [[ "$style" == bare ]]; then
-    want=$(curl -fsSL --max-time 30 "$sums" 2>/dev/null | tr -d '[:space:]')
-  else
-    want=$(curl -fsSL --max-time 30 "$sums" 2>/dev/null |
-      awk -v f="$(basename "$url")" '$NF == f || $NF == "*" f {print $1; exit}')
-  fi
-
-  [[ "$want" =~ ^([0-9a-fA-F]{64}|[0-9a-fA-F]{128})$ ]] || return 1
-  printf '%s %s' "$tool" "$want"
+  _vm_checksum_from_sums "$sums" "$name"
 }
 
 _vm_image_ok() {
@@ -1312,12 +1322,13 @@ vm_image_cache_path() {
 
 # vm_fetch_image <url> <target> [--cache] [--verify-xz] [--min-bytes N]
 #                               [--exact-bytes N] [--sha256 H] [--sha1 H]
-#                               [--advisory-sha1 H] [--needs-bytes N]
+#                               [--checksum-url URL] [--advisory-sha1 H]
+#                               [--needs-bytes N]
 vm_fetch_image() {
   local url="${1:?url}" target="${2:?target}"
   shift 2
   local min_bytes=0 exact_bytes="" sha256="" sha1="" advisory_sha1="" needs_bytes=""
-  local cache=no xz=no
+  local checksum_url="" cache=no xz=no
   local got avail_mib need_mib have part sha_tool="" sha_want="" discovered
 
   while [[ $# -gt 0 ]]; do
@@ -1328,6 +1339,7 @@ vm_fetch_image() {
     --exact-bytes) exact_bytes="$2"; shift 2 ;;
     --sha256) sha256="$2"; shift 2 ;;
     --sha1) sha1="$2"; shift 2 ;;
+    --checksum-url) checksum_url="$2"; shift 2 ;;
     --advisory-sha1) advisory_sha1="$2"; shift 2 ;;
     --needs-bytes) needs_bytes="$2"; shift 2 ;;
     *) msg_error "vm_fetch_image: unknown option $1"; return 2 ;;
@@ -1335,9 +1347,15 @@ vm_fetch_image() {
   done
 
   if [[ -n "$sha256" ]]; then
-    sha_tool=sha256sum sha_want="$sha256"
+    sha_tool=sha256sum sha_want="${sha256,,}"
   elif [[ -n "$sha1" ]]; then
     sha_tool=sha1sum sha_want="$sha1"
+  elif [[ -n "$checksum_url" ]]; then
+    if discovered=$(_vm_checksum_from_sums "$checksum_url" "$(basename "$target")"); then
+      read -r sha_tool sha_want <<<"$discovered"
+    else
+      msg_warn "No checksum for $(basename "$target") in ${checksum_url}; checking the size only"
+    fi
   elif discovered=$(vm_image_checksum "$url"); then
     read -r sha_tool sha_want <<<"$discovered"
   fi
diff --git a/pve/vm-app.func b/pve/vm-app.func
index b7c7f77..2a0b847 100644
--- a/pve/vm-app.func
+++ b/pve/vm-app.func
@@ -294,18 +294,14 @@ get_image_url() {
 download_and_cache_image() {
   msg_info "Retrieving the URL for the ${OS_DISPLAY} Qcow2 Disk Image"
   URL=$(get_image_url)
-  CACHE_DIR="/var/lib/vz/template/cache"
-  CACHE_FILE="$CACHE_DIR/$(basename "$URL")"
-  mkdir -p "$CACHE_DIR"
+  CACHE_FILE="$(vm_image_cache_path "$URL")"
+  CACHE_DIR="$(dirname "$CACHE_FILE")"
   msg_ok "${CL}${BL}${URL}${CL}"
 
-  if [[ ! -s "$CACHE_FILE" ]]; then
-    curl -f#SL -o "$CACHE_FILE" "$URL"
-    echo -en "\e[1A\e[0K"
-    msg_ok "Downloaded ${CL}${BL}$(basename "$CACHE_FILE")${CL}"
-  else
-    msg_ok "Using cached image ${CL}${BL}$(basename "$CACHE_FILE")${CL}"
-  fi
+  # Through vm_fetch_image: a partial file is never mistaken for the image, and
+  # the vendor checksum is verified where one is published.
+  vm_fetch_image "$URL" "$CACHE_FILE" --cache --min-bytes $((10 * 1024 * 1024)) || exit 1
+  msg_ok "Image ready ${CL}${BL}$(basename "$CACHE_FILE")${CL}"
 }
 
 # ==============================================================================
@@ -318,12 +314,7 @@ download_and_cache_image() {
 # Ensures virt-customize (libguestfs-tools) is installed on the Proxmox host.
 # ------------------------------------------------------------------------------
 ensure_virt_customize() {
-  if ! command -v virt-customize &>/dev/null; then
-    msg_info "Installing libguestfs-tools"
-    apt-get -qq update >/dev/null
-    apt-get -qq install libguestfs-tools -y >/dev/null
-    msg_ok "Installed libguestfs-tools"
-  fi
+  vm_require_tools virt-customize || exit 1
 }
 
 # ------------------------------------------------------------------------------
@@ -467,22 +458,8 @@ create_app_vm() {
   msg_ok "Created VM shell"
 
   # Import disk
-  msg_info "Importing disk into storage ($STORAGE)"
-  if qm disk import --help >/dev/null 2>&1; then
-    IMPORT_CMD=(qm disk import)
-  else
-    IMPORT_CMD=(qm importdisk)
-  fi
-
-  IMPORT_OUT="$("${IMPORT_CMD[@]}" "$VMID" "$WORK_FILE" "$STORAGE" ${DISK_IMPORT:-} 2>&1 || true)"
-  DISK_REF_IMPORTED="$(printf '%s\n' "$IMPORT_OUT" | sed -n "s/.*successfully imported disk '\([^']\+\)'.*/\1/p" | tr -d "\r\"'")"
-  [[ -z "$DISK_REF_IMPORTED" ]] && DISK_REF_IMPORTED="$(pvesm list "$STORAGE" | awk -v id="$VMID" '$5 ~ ("vm-"id"-disk-") {print $1":"$5}' | sort | tail -n1)"
-  [[ -z "$DISK_REF_IMPORTED" ]] && {
-    msg_error "Unable to determine imported disk reference."
-    echo "$IMPORT_OUT"
-    exit 1
-  }
-  msg_ok "Imported disk (${CL}${BL}${DISK_REF_IMPORTED}${CL})"
+  vm_import_disk "$VMID" "$WORK_FILE" "$STORAGE" || exit 1
+  DISK_REF_IMPORTED="$VM_IMPORTED_DISK"
 
   # Clean up work file
   rm -f "$WORK_FILE"
@@ -537,15 +514,12 @@ wait_for_vm_ip() {
     return 0
   fi
 
-  set +e
-  for i in {1..20}; do
-    VM_IP=$(qm guest cmd "$VMID" network-get-interfaces 2>/dev/null |
-      jq -r '.[] | select(.name != "lo") | ."ip-addresses"[]? | select(."ip-address-type" == "ipv4") | ."ip-address"' 2>/dev/null |
-      grep -v "^127\." | head -1) || true
-    [ -n "$VM_IP" ] && break
-    sleep 3
-  done
-  set -e
+  # Matched by the NIC's MAC: the app may run Docker, whose bridge address
+  # used to be reported as the VM's.
+  if load_cloud_init_functions; then
+    VM_IP="$(get_vm_ip "$VMID" 60 "${MAC:-}")" || VM_IP=""
+  fi
+  return 0
 }
 
 # ------------------------------------------------------------------------------
diff --git a/pve/vm-core.func b/pve/vm-core.func
index 5302dfd..d697233 100644
--- a/pve/vm-core.func
+++ b/pve/vm-core.func
@@ -47,6 +47,19 @@ else
     wget -qO- "${_vm_validate_base}/host/validate.func")
 fi
 
+# Helpers that do not touch qm, shared with incus/vm-core.func.
+if declare -f _cs_source_func >/dev/null 2>&1; then
+  _cs_source_func "vm/common.func"
+elif [[ -n "${COMMUNITY_SCRIPTS_CORE_DIR:-}" && -f "${COMMUNITY_SCRIPTS_CORE_DIR}/vm/common.func" ]]; then
+  # shellcheck disable=SC1091
+  source "${COMMUNITY_SCRIPTS_CORE_DIR}/vm/common.func"
+else
+  _vm_common_base="${COMMUNITY_SCRIPTS_CORE_URL:-https://raw.githubusercontent.com/community-scripts/core/main}"
+  # shellcheck disable=SC1090
+  source <(curl -fsSL "${_CS_CURL_RETRY[@]}" "${_vm_common_base}/vm/common.func" 2>/dev/null ||
+    wget -qO- "${_vm_common_base}/vm/common.func")
+fi
+
 SPINNER_PID=""
 SPINNER_ACTIVE=0
 SPINNER_MSG=""
@@ -1598,26 +1611,21 @@ vm_prompt_start_vm() {
 #                               [--exact-bytes N] [--sha256 H] [--sha1 H]
 #                               [--advisory-sha1 H] [--needs-bytes N]
 vm_image_checksum() {
-  local url="${1:?url}" tool sums style want
+  local url="${1:?url}" name sums
 
+  name="${url%%\?*}"
+  name="${name##*/}"
   case "$url" in
-  *cloud.debian.org/*) tool=sha512sum; sums="${url%/*}/SHA512SUMS"; style=sums ;;
-  *cloud-images.ubuntu.com/*) tool=sha256sum; sums="${url%/*}/SHA256SUMS"; style=sums ;;
-  *download.truenas.com/*) tool=sha256sum; sums="${url}.sha256"; style=bare ;;
+  *cloud.debian.org/*) sums="${url%/*}/SHA512SUMS" ;;
+  *cloud-images.ubuntu.com/*) sums="${url%/*}/SHA256SUMS" ;;
+  *download.truenas.com/*) sums="${url}.sha256" ;;
+  *downloads.openwrt.org/*) sums="${url%/*}/sha256sums" ;;
+  *download.freebsd.org/*/VM-IMAGES/*) sums="${url%/*}/CHECKSUM.SHA256" ;;
+  *mirror.turnkeylinux.org/*) sums="${url}.hash" ;;
   *) return 1 ;;
   esac
 
-  command -v "$tool" >/dev/null 2>&1 || return 1
-
-  if [[ "$style" == bare ]]; then
-    want=$(curl -fsSL --max-time 30 "$sums" 2>/dev/null | tr -d '[:space:]')
-  else
-    want=$(curl -fsSL --max-time 30 "$sums" 2>/dev/null |
-      awk -v f="$(basename "$url")" '$NF == f || $NF == "*" f {print $1; exit}')
-  fi
-
-  [[ "$want" =~ ^([0-9a-fA-F]{64}|[0-9a-fA-F]{128})$ ]] || return 1
-  printf '%s %s' "$tool" "$want"
+  _vm_checksum_from_sums "$sums" "$name"
 }
 
 _vm_image_ok() {
@@ -1678,7 +1686,7 @@ vm_fetch_image() {
   local url="${1:?url}" target="${2:?target}"
   shift 2
   local min_bytes=0 exact_bytes="" sha256="" sha1="" advisory_sha1="" needs_bytes=""
-  local cache=no xz=no
+  local checksum_url="" cache=no xz=no
   local got avail_mib need_mib have part sha_tool="" sha_want="" discovered
 
   while [[ $# -gt 0 ]]; do
@@ -1689,6 +1697,7 @@ vm_fetch_image() {
     --exact-bytes) exact_bytes="$2"; shift 2 ;;
     --sha256) sha256="$2"; shift 2 ;;
     --sha1) sha1="$2"; shift 2 ;;
+    --checksum-url) checksum_url="$2"; shift 2 ;;
     --advisory-sha1) advisory_sha1="$2"; shift 2 ;;
     --needs-bytes) needs_bytes="$2"; shift 2 ;;
     *) msg_error "vm_fetch_image: unknown option $1"; return 2 ;;
@@ -1696,9 +1705,17 @@ vm_fetch_image() {
   done
 
   if [[ -n "$sha256" ]]; then
-    sha_tool=sha256sum sha_want="$sha256"
+    sha_tool=sha256sum sha_want="${sha256,,}"
   elif [[ -n "$sha1" ]]; then
     sha_tool=sha1sum sha_want="$sha1"
+  elif [[ -n "$checksum_url" ]]; then
+    # Looked up by the file's own name: download URLs such as SourceForge's
+    # .../file.iso/download do not end in it.
+    if discovered=$(_vm_checksum_from_sums "$checksum_url" "$(basename "$target")"); then
+      read -r sha_tool sha_want <<<"$discovered"
+    else
+      msg_warn "No checksum for $(basename "$target") in ${checksum_url}; checking the size only"
+    fi
   elif discovered=$(vm_image_checksum "$url"); then
     read -r sha_tool sha_want <<<"$discovered"
   fi
@@ -2324,6 +2341,127 @@ vm_resize_disk() {
   fi
 }
 
+# ------------------------------------------------------------------------------
+# vm_import_disk <vmid> <image> <storage> [format]
+#
+# Imports an image and sets VM_IMPORTED_DISK to the volume Proxmox actually
+# created. Scripts predicted that name, parsed qm's output three different
+# ways, or took the last `pvesm list` entry, which sorts disk-10 before disk-9.
+# The volume is read from qm's report, else from the unusedN entry the import
+# added. The format defaults to DISK_IMPORT_FORMAT from vm_select_storage.
+# ------------------------------------------------------------------------------
+vm_import_disk() {
+  local vmid="${1:?vmid}" file="${2:?image}" storage="${3:?storage}" format="${4:-${DISK_IMPORT_FORMAT:-}}"
+  local out before volume
+  local -a cmd=(qm importdisk) opts=()
+
+  VM_IMPORTED_DISK=""
+  qm disk import --help >/dev/null 2>&1 && cmd=(qm disk import)
+  [[ -n "$format" ]] && opts=(--format "$format")
+  before="$(qm config "$vmid" 2>/dev/null | sed -n 's/^unused[0-9]*: //p')" || before=""
+
+  msg_info "Importing $(basename "$file") to ${storage}"
+  if ! out="$("${cmd[@]}" "$vmid" "$file" "$storage" "${opts[@]}" 2>&1)"; then
+    msg_error "Importing $(basename "$file") into VM ${vmid} failed"
+    printf '%s\n' "$out" | tail -n 5 >&2
+    return 1
+  fi
+
+  volume="$(printf '%s\n' "$out" | sed -n "s/.*successfully imported disk '\([^']*\)'.*/\1/p" | tail -n 1)"
+  if [[ -z "$volume" ]]; then
+    volume="$(qm config "$vmid" 2>/dev/null | sed -n 's/^unused[0-9]*: //p' |
+      grep -vxF -f <(printf '%s\n' "$before") | tail -n 1)" || volume=""
+  fi
+  volume="${volume//[$'\r\"\'']/}"
+
+  if [[ -z "$volume" ]]; then
+    msg_error "Imported $(basename "$file"), but could not tell which volume Proxmox created"
+    printf '%s\n' "$out" | tail -n 5 >&2
+    return 1
+  fi
+
+  VM_IMPORTED_DISK="$volume"
+  msg_ok "Imported disk ${CL}${BL}${VM_IMPORTED_DISK}${CL}"
+}
+
+# ------------------------------------------------------------------------------
+# vm_start_vm [label]
+#
+# Starts the VM when START_VM is yes. A failed start after vm_mark_created is a
+# post-create error: the VM is kept.
+# ------------------------------------------------------------------------------
+vm_start_vm() {
+  local label="${1:-${APP:-VM}}"
+  [[ "${START_VM:-yes}" == "yes" ]] || return 0
+  msg_info "Starting ${label}"
+  ${STD:-} qm start "$VMID"
+  msg_ok "Started ${label}"
+}
+
+# ------------------------------------------------------------------------------
+# vm_wait_guest_agent <vmid> [timeout seconds]
+# vm_guest_exec <vmid> <timeout seconds> [--] <command> [args]...
+#
+# The guest agent answers without SSH keys or a known address. vm_guest_exec
+# prints the command's stdout and returns its exit code; 124 means it was still
+# running at the timeout.
+# ------------------------------------------------------------------------------
+vm_wait_guest_agent() {
+  local vmid="${1:?vmid}" timeout="${2:-120}" waited=0
+  while ((waited < timeout)); do
+    qm guest cmd "$vmid" ping >/dev/null 2>&1 && return 0
+    sleep 3
+    waited=$((waited + 3))
+  done
+  return 1
+}
+
+vm_guest_exec() {
+  local vmid="${1:?vmid}" timeout="${2:?timeout}" json rc
+  shift 2
+  [[ "${1:-}" == "--" ]] && shift
+  if (($# == 0)); then
+    msg_error "vm_guest_exec: no command given"
+    return 2
+  fi
+
+  # qm reports the guest's exit status in the JSON, not in its own.
+  json="$(qm guest exec "$vmid" --timeout "$timeout" -- "$@" 2>/dev/null)" || true
+  [[ -n "$json" ]] || return 1
+  rc="$(jq -r 'if .exited == 1 then (.exitcode // 1) else 124 end' <<<"$json" 2>/dev/null)" || return 1
+  [[ "$rc" =~ ^[0-9]+$ ]] || return 1
+  jq -r '."out-data" // empty' <<<"$json" 2>/dev/null || true
+  return "$rc"
+}
+
+# ------------------------------------------------------------------------------
+# vm_wait_for_ip [timeout seconds]
+#
+# Sets VM_IP to the address on the VM's own NIC (matched by MAC), so a Docker
+# or Podman bridge inside the guest is not reported as the VM's address.
+# Returns non-zero with a warning when the VM was not started or no address
+# appeared; callers continue either way.
+# ------------------------------------------------------------------------------
+vm_wait_for_ip() {
+  local timeout="${1:-${VM_IP_TIMEOUT:-120}}"
+  VM_IP=""
+  [[ "${START_VM:-yes}" == "yes" ]] || return 1
+  vm_require_tools jq || return 1
+  if ! load_cloud_init_functions; then
+    msg_warn "The IP lookup helpers are unavailable; read the address from the Proxmox summary"
+    return 1
+  fi
+
+  msg_info "Waiting for the VM's IP address (up to ${timeout}s)"
+  VM_IP="$(get_vm_ip "$VMID" "$timeout" "${MAC:-}")" || VM_IP=""
+  if [[ -n "$VM_IP" ]]; then
+    msg_ok "VM IP address ${CL}${BL}${VM_IP}${CL}"
+    return 0
+  fi
+  msg_warn "No IP address yet -- the guest agent may still be starting; check the Proxmox summary or console"
+  return 1
+}
+
 check_hostname_conflict() {
   local hostname="$1"
   if qm list | awk '{print $2}' | grep -qx "$hostname"; then
diff --git a/tests/vm-helpers.sh b/tests/vm-helpers.sh
new file mode 100644
index 0000000..e277fb7
--- /dev/null
+++ b/tests/vm-helpers.sh
@@ -0,0 +1,565 @@
+#!/usr/bin/env bash
+# Host-independent regression tests for vm/common.func and the qm helpers in
+# pve/vm-core.func. Every host command (qm, curl, apt-get, virt-customize) is
+# mocked; nothing is downloaded or created.
+set -euo pipefail
+
+COMMUNITY_SCRIPTS_CORE_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
+export COMMUNITY_SCRIPTS_CORE_DIR
+pveversion() { :; }
+# shellcheck disable=SC1091
+source "${COMMUNITY_SCRIPTS_CORE_DIR}/pve/vm-core.func"
+load_cloud_init_functions
+set -euo pipefail
+
+TEST_DIR="$(mktemp -d)"
+trap 'rm -rf -- "$TEST_DIR"' EXIT
+LOG="$TEST_DIR/calls.log"
+ERRORS="$TEST_DIR/errors.log"
+WARNINGS="$TEST_DIR/warnings.log"
+CL="" BL="" GN="" TAB="  " DGN="" BGN="" INFO="" BOLD="" YW="" STD=""
+passed=0
+
+# Windows' jq writes CRLF; the engine only ever runs where it does not.
+if [[ "$(uname -s)" == *_NT* || "$(uname -o 2>/dev/null)" == Cygwin || "$(uname -o 2>/dev/null)" == Msys ]]; then
+  jq() { command jq "$@" | tr -d '\r'; }
+fi
+
+msg_info() { :; }
+msg_ok() { :; }
+msg_error() { printf '%s\n' "$*" >>"$ERRORS"; }
+msg_warn() { printf '%s\n' "$*" >>"$WARNINGS"; }
+_ci_msg_info() { :; }
+_ci_msg_ok() { :; }
+_ci_msg_warn() { printf '%s\n' "$*" >>"$WARNINGS"; }
+sleep() { :; }
+
+reset_logs() { : >"$LOG"; : >"$ERRORS"; : >"$WARNINGS"; }
+
+fail() {
+  printf 'FAIL: %s\n' "$*" >&2
+  [[ -s "$ERRORS" ]] && sed 's/^/  error: /' "$ERRORS" >&2
+  exit 1
+}
+assert_eq() { [[ "$1" == "$2" ]] || fail "${3:-value}: expected <$2>, got <$1>"; }
+assert_contains() { grep -qF -- "$2" "$1" || fail "${3:-$1} does not contain <$2>"; }
+ok() {
+  passed=$((passed + 1))
+  printf 'ok %d - %s\n' "$passed" "$1"
+}
+
+# ── curl mock ───────────────────────────────────────────────────────────────
+# URL -> fixture file. -o writes it, -I/-w answer from MOCK_STATUS_<n>.
+declare -A FIXTURE=()
+declare -A HEAD_OK=()
+# A file, not an array: curl -w runs inside a command substitution.
+HTTP_CODES_FILE="$TEST_DIR/http-codes"
+http_codes() { printf '%s\n' "$@" >"$HTTP_CODES_FILE"; }
+curl() {
+  local url="" out="" head=no write=""
+  while (($#)); do
+    case "$1" in
+    -o) out="$2"; shift 2 ;;
+    -w) write="$2"; shift 2 ;;
+    --max-time | --retry | --retry-delay | --connect-timeout) shift 2 ;;
+    -*I*) head=yes; shift ;;
+    http*://*) url="$1"; shift ;;
+    *) shift ;;
+    esac
+  done
+  printf 'curl %s %s\n' "$head" "$url" >>"$LOG"
+
+  if [[ -n "$write" ]]; then
+    local code
+    code="$(head -n 1 "$HTTP_CODES_FILE" 2>/dev/null)"
+    sed -i '1d' "$HTTP_CODES_FILE" 2>/dev/null || true
+    code="${code:-000}"
+    printf '%s' "$code"
+    [[ "$code" == 000 ]] && return 7
+    return 0
+  fi
+  if [[ "$head" == yes ]]; then
+    [[ -n "${HEAD_OK[$url]:-}" ]] && return 0
+    return 22
+  fi
+  [[ -n "${FIXTURE[$url]:-}" ]] || return 22
+  if [[ -n "$out" && "$out" != /dev/null ]]; then
+    cp -- "${FIXTURE[$url]}" "$out"
+  else
+    cat -- "${FIXTURE[$url]}"
+  fi
+}
+
+fixture() {
+  local url="$1" file
+  file="$TEST_DIR/fixture-$(printf '%s' "$url" | sha256sum | cut -c1-16)"
+  cat >"$file"
+  FIXTURE[$url]="$file"
+}
+
+# ── checksums ───────────────────────────────────────────────────────────────
+IMAGE="$TEST_DIR/image.img"
+printf 'pretend image\n' >"$IMAGE"
+IMAGE_SHA256="$(sha256sum "$IMAGE" | awk '{print $1}')"
+IMAGE_SHA512="$(sha512sum "$IMAGE" | awk '{print $1}')"
+
+fixture "https://sums.test/gnu" <<EOF
+0000000000000000000000000000000000000000000000000000000000000000 *other.img
+${IMAGE_SHA256} *openwrt.img.gz
+EOF
+assert_eq "$(_vm_checksum_from_sums https://sums.test/gnu openwrt.img.gz)" "sha256sum ${IMAGE_SHA256}" "GNU binary-mode line"
+ok "GNU checksum list with *file"
+
+fixture "https://sums.test/bsd" <<EOF
+SHA256 (FreeBSD-other.qcow2.xz) = 1111111111111111111111111111111111111111111111111111111111111111
+SHA256 (FreeBSD-15.1-RELEASE-amd64-ufs.qcow2.xz) = ${IMAGE_SHA256^^}
+EOF
+assert_eq "$(_vm_checksum_from_sums https://sums.test/bsd FreeBSD-15.1-RELEASE-amd64-ufs.qcow2.xz)" \
+  "sha256sum ${IMAGE_SHA256}" "BSD line, upper-case hash"
+ok "BSD checksum list is read and lower-cased"
+
+fixture "https://sums.test/turnkey" <<EOF
+-----BEGIN PGP SIGNED MESSAGE-----
+Hash: SHA512
+
+    \$ sha256sum turnkey-nextcloud.iso
+      ${IMAGE_SHA256}  turnkey-nextcloud.iso
+    \$ sha512sum turnkey-nextcloud.iso
+      ${IMAGE_SHA512}  turnkey-nextcloud.iso
+EOF
+assert_eq "$(_vm_checksum_from_sums https://sums.test/turnkey turnkey-nextcloud.iso)" \
+  "sha256sum ${IMAGE_SHA256}" "TurnKey signed hash file"
+ok "TurnKey .hash skips the '\$ sha256sum file' line"
+
+fixture "https://sums.test/bare" <<<"  ${IMAGE_SHA512}  "
+assert_eq "$(_vm_checksum_from_sums https://sums.test/bare anything)" "sha512sum ${IMAGE_SHA512}" "bare hash"
+ok "bare hash file, algorithm from its length"
+
+if _vm_checksum_from_sums https://sums.test/gnu missing.img >/dev/null; then fail "a file absent from the list must not resolve"; fi
+if _vm_checksum_from_sums https://sums.test/unreachable openwrt.img.gz >/dev/null; then fail "an unreachable list must not resolve"; fi
+ok "absent entry and unreachable list return non-zero"
+
+reset_logs
+fixture "https://downloads.openwrt.org/releases/25.12.5/targets/x86/64/sha256sums" <<EOF
+${IMAGE_SHA256} *openwrt-25.12.5-x86-64-generic-ext4-combined.img.gz
+EOF
+assert_eq "$(vm_image_checksum https://downloads.openwrt.org/releases/25.12.5/targets/x86/64/openwrt-25.12.5-x86-64-generic-ext4-combined.img.gz)" \
+  "sha256sum ${IMAGE_SHA256}" "OpenWrt mapping"
+assert_contains "$LOG" "https://downloads.openwrt.org/releases/25.12.5/targets/x86/64/sha256sums"
+for url in \
+  "https://download.freebsd.org/releases/VM-IMAGES/15.1-RELEASE/amd64/Latest/FreeBSD-15.1-RELEASE-amd64-ufs.qcow2.xz|https://download.freebsd.org/releases/VM-IMAGES/15.1-RELEASE/amd64/Latest/CHECKSUM.SHA256" \
+  "https://mirror.turnkeylinux.org/turnkeylinux/images/iso/turnkey-nextcloud-19.0-trixie-amd64.iso|https://mirror.turnkeylinux.org/turnkeylinux/images/iso/turnkey-nextcloud-19.0-trixie-amd64.iso.hash" \
+  "https://cloud.debian.org/images/cloud/trixie/latest/debian-13-generic-amd64.qcow2|https://cloud.debian.org/images/cloud/trixie/latest/SHA512SUMS"; do
+  reset_logs
+  vm_image_checksum "${url%%|*}" >/dev/null || true
+  assert_contains "$LOG" "${url#*|}"
+done
+if vm_image_checksum "https://sourceforge.net/projects/x/files/a.iso/download" >/dev/null; then fail "unknown hosts have no checksum"; fi
+ok "vendor checksum files are derived from the download URL"
+
+# ── vm_fetch_image checksum options ─────────────────────────────────────────
+fixture "https://dl.test/openwrt.img.gz" <"$IMAGE"
+reset_logs
+vm_fetch_image "https://dl.test/openwrt.img.gz" "$TEST_DIR/cache/openwrt.img.gz" --checksum-url https://sums.test/gnu ||
+  fail "--checksum-url with a matching hash must succeed"
+[[ -s "$TEST_DIR/cache/openwrt.img.gz" ]] || fail "verified download was not moved into place"
+ok "vm_fetch_image --checksum-url verifies by the target's file name"
+
+reset_logs
+if vm_fetch_image "https://dl.test/openwrt.img.gz" "$TEST_DIR/cache/bad.img" --sha256 "$(printf '%064d' 0)"; then
+  fail "a sha256 mismatch must fail"
+fi
+[[ ! -e "$TEST_DIR/cache/bad.img" && ! -e "$TEST_DIR/cache/bad.img.part" ]] || fail "a rejected download must leave nothing behind"
+assert_contains "$ERRORS" "mismatch"
+ok "vm_fetch_image --sha256 mismatch fails and removes the partial file"
+
+reset_logs
+vm_fetch_image "https://dl.test/openwrt.img.gz" "$TEST_DIR/cache/upper.img" --sha256 "${IMAGE_SHA256^^}" ||
+  fail "an upper-case digest must match"
+vm_fetch_image "https://dl.test/openwrt.img.gz" "$TEST_DIR/cache/nosums.img" --checksum-url https://sums.test/unreachable ||
+  fail "an unavailable checksum list falls back to the size checks"
+assert_contains "$WARNINGS" "checking the size only"
+ok "digest case is ignored; missing checksum list warns and continues"
+
+# ── vm_import_disk ──────────────────────────────────────────────────────────
+VMID=100
+QM_MODERN=yes
+QM_IMPORT_RC=0
+QM_IMPORT_OUT=""
+QM_CONFIG_BEFORE=""
+QM_CONFIG_AFTER=""
+# A file, not a variable: the import runs inside a command substitution.
+QM_IMPORTED_FLAG="$TEST_DIR/qm-imported"
+qm() {
+  printf 'qm %s\n' "$*" >>"$LOG"
+  case "$1 ${2:-}" in
+  "disk import")
+    if [[ "${3:-}" == --help ]]; then [[ "$QM_MODERN" == yes ]]; return; fi
+    : >"$QM_IMPORTED_FLAG"
+    printf '%s\n' "$QM_IMPORT_OUT"
+    return "$QM_IMPORT_RC"
+    ;;
+  "importdisk "*)
+    : >"$QM_IMPORTED_FLAG"
+    printf '%s\n' "$QM_IMPORT_OUT"
+    return "$QM_IMPORT_RC"
+    ;;
+  "config "*)
+    if [[ -e "$QM_IMPORTED_FLAG" ]]; then printf '%s\n' "$QM_CONFIG_AFTER"; else printf '%s\n' "$QM_CONFIG_BEFORE"; fi
+    ;;
+  "guest cmd")
+    case "$4" in
+    ping) [[ "${GUEST_PING:-yes}" == yes ]] ;;
+    network-get-interfaces) printf '%s\n' "$GUEST_IFACES" ;;
+    esac
+    ;;
+  "guest exec") printf '%s\n' "$GUEST_EXEC_JSON" ;;
+  "start "*) return "${QM_START_RC:-0}" ;;
+  *) return 0 ;;
+  esac
+}
+
+import_case() {
+  rm -f "$QM_IMPORTED_FLAG"
+  reset_logs
+  VM_IMPORTED_DISK="stale"
+}
+
+import_case
+DISK_IMPORT_FORMAT=raw
+QM_IMPORT_OUT="transferred 1.0 GiB of 1.0 GiB (100.00%)
+unused0: successfully imported disk 'local-lvm:vm-100-disk-1'"
+vm_import_disk 100 "$IMAGE" local-lvm || fail "modern import"
+assert_eq "$VM_IMPORTED_DISK" "local-lvm:vm-100-disk-1" "volume from qm's report"
+assert_contains "$LOG" "qm disk import 100 $IMAGE local-lvm --format raw"
+ok "vm_import_disk uses qm disk import and the reported volume"
+
+import_case
+QM_MODERN=no
+vm_import_disk 100 "$IMAGE" local-lvm qcow2 || fail "legacy import"
+assert_contains "$LOG" "qm importdisk 100 $IMAGE local-lvm --format qcow2"
+QM_MODERN=yes
+ok "vm_import_disk falls back to qm importdisk and honours an explicit format"
+
+import_case
+QM_IMPORT_OUT="transferred 1.0 GiB of 1.0 GiB (100.00%)"
+QM_CONFIG_BEFORE=$'boot: order=scsi0\nunused0: local-lvm:vm-100-disk-9'
+QM_CONFIG_AFTER=$'boot: order=scsi0\nunused0: local-lvm:vm-100-disk-9\nunused1: local-lvm:vm-100-disk-10'
+vm_import_disk 100 "$IMAGE" local-lvm || fail "import without a report line"
+assert_eq "$VM_IMPORTED_DISK" "local-lvm:vm-100-disk-10" "new unused entry, not the lexically last"
+ok "vm_import_disk reads the new unusedN entry (disk-10 after disk-9)"
+
+import_case
+QM_IMPORT_OUT="storage 'local-lvm' does not exist"
+QM_IMPORT_RC=255
+if vm_import_disk 100 "$IMAGE" local-lvm 2>/dev/null; then fail "a failed import must fail"; fi
+assert_eq "$VM_IMPORTED_DISK" "" "no volume after a failed import"
+QM_IMPORT_RC=0
+ok "vm_import_disk reports a failed import instead of swallowing it"
+
+import_case
+QM_IMPORT_OUT="done"
+QM_CONFIG_BEFORE="unused0: local-lvm:vm-100-disk-1"
+QM_CONFIG_AFTER="unused0: local-lvm:vm-100-disk-1"
+if vm_import_disk 100 "$IMAGE" local-lvm 2>/dev/null; then fail "an unidentifiable volume must fail"; fi
+assert_contains "$ERRORS" "could not tell which volume"
+QM_CONFIG_BEFORE="" QM_CONFIG_AFTER=""
+ok "vm_import_disk never guesses a volume name"
+
+# ── guest agent and IP ──────────────────────────────────────────────────────
+GUEST_IFACES='[
+ {"name":"lo","hardware-address":"00:00:00:00:00:00","ip-addresses":[{"ip-address-type":"ipv4","ip-address":"127.0.0.1"}]},
+ {"name":"docker0","hardware-address":"02:42:aa:bb:cc:dd","ip-addresses":[{"ip-address-type":"ipv4","ip-address":"172.17.0.1"}]},
+ {"name":"ens18","hardware-address":"02:ab:cd:ef:01:23","ip-addresses":[
+   {"ip-address-type":"ipv4","ip-address":"169.254.10.10"},
+   {"ip-address-type":"ipv6","ip-address":"fe80::1"},
+   {"ip-address-type":"ipv4","ip-address":"192.168.1.50"}]}
+]'
+assert_eq "$(get_vm_ip 100 2 02:AB:CD:EF:01:23)" "192.168.1.50" "MAC match, case-insensitive"
+assert_eq "$(get_vm_ip 100 2)" "192.168.1.50" "no MAC: Docker bridge and link-local skipped"
+if get_vm_ip 100 2 02:00:00:00:00:99 >/dev/null; then fail "an unknown MAC must not return an address"; fi
+ok "get_vm_ip matches the NIC by MAC and skips container bridges"
+
+MAC="02:AB:CD:EF:01:23" START_VM=yes
+vm_wait_for_ip 4 || fail "vm_wait_for_ip"
+assert_eq "$VM_IP" "192.168.1.50" "vm_wait_for_ip"
+START_VM=no
+if vm_wait_for_ip 4; then fail "a stopped VM has no IP to wait for"; fi
+assert_eq "$VM_IP" "" "VM_IP cleared for a stopped VM"
+START_VM=yes
+ok "vm_wait_for_ip sets VM_IP only for a started VM"
+
+GUEST_EXEC_JSON='{"exited":1,"exitcode":3,"out-data":"hello\n"}'
+rc=0
+out="$(vm_guest_exec 100 30 -- echo hello)" || rc=$?
+assert_eq "$rc" 3 "guest exit code"
+assert_eq "$out" "hello" "guest stdout"
+GUEST_EXEC_JSON='{"exited":0,"pid":42}'
+rc=0
+vm_guest_exec 100 30 sleep 99 >/dev/null || rc=$?
+assert_eq "$rc" 124 "still running"
+ok "vm_guest_exec returns the guest's exit code, 124 when still running"
+
+GUEST_PING=yes
+vm_wait_guest_agent 100 6 || fail "agent answers"
+GUEST_PING=no
+if vm_wait_guest_agent 100 6; then fail "a silent agent must time out"; fi
+GUEST_PING=yes
+ok "vm_wait_guest_agent"
+
+reset_logs
+GUEST_EXEC_JSON='{"exited":1,"exitcode":2,"out-data":"status: degraded done\n"}'
+wait_for_cloud_init 100 30 || fail "degraded cloud-init still completed"
+assert_contains "$WARNINGS" "recoverable errors"
+GUEST_EXEC_JSON='{"exited":1,"exitcode":1}'
+if wait_for_cloud_init 100 30; then fail "a cloud-init error must be reported"; fi
+ok "wait_for_cloud_init uses the guest agent and maps cloud-init's exit codes"
+
+reset_logs
+QM_START_RC=0 START_VM=yes
+vm_start_vm "Test VM"
+assert_contains "$LOG" "qm start 100"
+reset_logs
+START_VM=no
+vm_start_vm
+[[ ! -s "$LOG" ]] || fail "START_VM=no must not start the VM"
+START_VM=yes
+ok "vm_start_vm honours START_VM"
+
+# ── release and index discovery ─────────────────────────────────────────────
+FORGE_JSON=""
+_forge_release_json() {
+  printf '%s %s %s\n' "$1" "$2" "$3" >>"$LOG"
+  [[ -n "$FORGE_JSON" ]] || return 22
+  printf '%s\n' "$FORGE_JSON" >"$5"
+}
+
+reset_logs
+FORGE_JSON='{"tag_name":"v1.5.4","assets":[
+  {"name":"zimaos-x86_64-1.5.4.img","browser_download_url":"https://gh.test/a.img","digest":"sha256:'"${IMAGE_SHA256^^}"'"},
+  {"name":"zimaos-x86_64-1.5.4_installer.iso","browser_download_url":"https://gh.test/b.iso","digest":"sha256:'"${IMAGE_SHA256}"'"}]}'
+vm_release_asset github IceWhaleTech/ZimaOS 'zimaos-x86_64-.*_installer\.iso$' || fail "release asset"
+assert_eq "$VM_RELEASE_TAG" "v1.5.4" "tag"
+assert_eq "$VM_RELEASE_VERSION" "1.5.4" "version"
+assert_eq "$VM_RELEASE_ASSET" "zimaos-x86_64-1.5.4_installer.iso" "asset"
+assert_eq "$VM_RELEASE_URL" "https://gh.test/b.iso" "url"
+assert_eq "$VM_RELEASE_SHA256" "$IMAGE_SHA256" "digest"
+assert_contains "$LOG" "github IceWhaleTech/ZimaOS latest"
+ok "vm_release_asset picks the matching GitHub asset and its digest"
+
+FORGE_JSON='{"tag_name":"16.0","assets":{"links":[{"name":"haos.qcow2.xz","url":"https://gl.test/x","direct_asset_url":"https://gl.test/direct"}]}}'
+vm_release_asset gitlab group/project 'qcow2\.xz$' 16.0 || fail "gitlab release asset"
+assert_eq "$VM_RELEASE_URL" "https://gl.test/direct" "GitLab direct asset URL"
+assert_eq "$VM_RELEASE_SHA256" "" "GitLab publishes no digest"
+ok "vm_release_asset reads GitLab asset links"
+
+reset_logs
+FORGE_JSON='{"tag_name":"v2","assets":[{"name":"other.iso","browser_download_url":"https://gh.test/o"}]}'
+if vm_release_asset github a/b 'installer\.iso$'; then fail "no matching asset must fail"; fi
+assert_eq "$VM_RELEASE_URL" "" "no URL without a match"
+FORGE_JSON=""
+if vm_release_asset github a/b 'x'; then fail "an unreadable release must fail"; fi
+ok "vm_release_asset fails without a matching asset or release"
+
+fixture "https://index.test/freebsd/" <<'EOF'
+<a href="14.4-RELEASE/">14.4-RELEASE/</a>
+<a href="14.10-RELEASE/">14.10-RELEASE/</a>
+<a href="14.9-RELEASE/">14.9-RELEASE/</a>
+<a href="15.1-RELEASE/">15.1-RELEASE/</a>
+EOF
+vm_latest_from_index "https://index.test/freebsd/" '14\.[0-9]+-RELEASE' || fail "index"
+assert_eq "$VM_INDEX_LATEST" "14.10-RELEASE" "version order, not lexical"
+ok "vm_latest_from_index orders by version"
+
+HEAD_OK["https://index.test/freebsd/14.9-RELEASE/img-ufs.qcow2.xz"]=1
+vm_latest_from_index "https://index.test/freebsd/" '14\.[0-9]+-RELEASE' \
+  --probe 'https://index.test/freebsd/{}/img.qcow2.xz' \
+  --probe 'https://index.test/freebsd/{}/img-ufs.qcow2.xz' || fail "probe"
+assert_eq "$VM_INDEX_LATEST" "14.9-RELEASE" "newest entry with a file"
+assert_eq "$VM_INDEX_URL" "https://index.test/freebsd/14.9-RELEASE/img-ufs.qcow2.xz" "probed URL"
+ok "vm_latest_from_index --probe skips releases without files and tries every template"
+
+fixture "https://index.test/bliss/" <<'EOF'
+Bliss-v16.9.7-x86_64-OFFICIAL-foss-20250101.iso
+Bliss-v16.9.10-x86_64-OFFICIAL-foss-20240601.iso
+Bliss-v16.9.7-x86_64-OFFICIAL-foss-20250315.iso
+Bliss-v16.9.7-x86_64-OFFICIAL-foss-20250315.iso
+EOF
+vm_latest_from_index "https://index.test/bliss/" 'Bliss-v[0-9.]+-x86_64-OFFICIAL-foss-[0-9]{8}\.iso' \
+  --sort-by 'foss-\K[0-9]{8}' || fail "sort-by"
+assert_eq "$VM_INDEX_LATEST" "Bliss-v16.9.7-x86_64-OFFICIAL-foss-20250315.iso" "newest build date"
+ok "vm_latest_from_index --sort-by orders by the selected key"
+
+reset_logs
+if vm_latest_from_index "https://index.test/freebsd/" '99\.[0-9]+-RELEASE'; then fail "no match must fail"; fi
+assert_eq "$VM_INDEX_LATEST" "" "no stale value"
+if vm_latest_from_index "https://index.test/missing/" 'x'; then fail "an unreadable index must fail"; fi
+if vm_latest_from_index "https://index.test/freebsd/" '14\.[0-9]+-RELEASE' --probe 'https://none.test/{}'; then
+  fail "no probed file must fail"
+fi
+ok "vm_latest_from_index fails instead of falling back"
+
+# ── vm_firstboot_unit ───────────────────────────────────────────────────────
+CUSTOMIZE_FAIL=no
+_vm_customize() {
+  local label="$1"
+  shift 2
+  printf 'customize %s %s\n' "$label" "$*" >>"$LOG"
+  while (($#)); do
+    if [[ "$1" == --upload && "$2" == *:/etc/systemd/system/* ]]; then
+      cp -- "${2%%:*}" "$TEST_DIR/unit.service"
+    fi
+    shift
+  done
+  [[ "$CUSTOMIZE_FAIL" == yes ]] && _VM_PREPARE_FAILED+=("$label")
+  return 0
+}
+printf '#!/bin/bash\nset -Eeuo pipefail\necho hi\n' >"$TEST_DIR/setup.sh"
+
+reset_logs
+vm_firstboot_unit "$IMAGE" app-setup "$TEST_DIR/setup.sh" --cloud-init yes --after docker.service \
+  --requires-path /opt/app.bin --description "App setup" || fail "first-boot unit"
+UNIT="$TEST_DIR/unit.service"
+assert_contains "$UNIT" "After=network-online.target cloud-final.service docker.service"
+assert_contains "$UNIT" "Wants=network-online.target cloud-final.service docker.service"
+assert_contains "$UNIT" "WantedBy=cloud-init.target"
+assert_contains "$UNIT" "ConditionPathExists=!/var/lib/community-scripts/app-setup.done"
+assert_contains "$UNIT" "ConditionPathExists=/opt/app.bin"
+assert_contains "$UNIT" "ExecStart=/usr/local/sbin/app-setup"
+assert_contains "$UNIT" "touch /var/lib/community-scripts/app-setup.done"
+assert_contains "$UNIT" "Type=oneshot"
+assert_contains "$UNIT" "Description=App setup"
+assert_contains "$LOG" "--chmod 0755:/usr/local/sbin/app-setup"
+assert_contains "$LOG" "--run-command systemctl enable app-setup.service"
+assert_eq "$VM_FIRSTBOOT_MARKER" "/var/lib/community-scripts/app-setup.done" "marker"
+grep -q 'multi-user.target' "$UNIT" && fail "a Cloud-Init unit must not involve multi-user.target"
+ok "vm_firstboot_unit with Cloud-Init: cloud-init.target after cloud-final, no cycle"
+
+vm_firstboot_unit "$IMAGE" app-setup "$TEST_DIR/setup.sh" --cloud-init no || fail "first-boot without CI"
+assert_contains "$UNIT" "WantedBy=multi-user.target"
+grep -q 'cloud-final' "$UNIT" && fail "without Cloud-Init there is no cloud-final dependency"
+ok "vm_firstboot_unit without Cloud-Init: multi-user.target"
+
+USE_CLOUD_INIT=yes
+vm_firstboot_unit "$IMAGE" app-setup "$TEST_DIR/setup.sh" || fail "first-boot default"
+assert_contains "$UNIT" "WantedBy=cloud-init.target"
+unset USE_CLOUD_INIT
+ok "vm_firstboot_unit follows USE_CLOUD_INIT by default"
+
+rc=0
+vm_firstboot_unit "$IMAGE" "Bad Name" "$TEST_DIR/setup.sh" || rc=$?
+assert_eq "$rc" 2 "invalid unit name"
+rc=0
+vm_firstboot_unit "$IMAGE" app "$TEST_DIR/missing.sh" || rc=$?
+assert_eq "$rc" 1 "unreadable script"
+CUSTOMIZE_FAIL=yes
+_VM_PREPARE_FAILED=()
+if vm_firstboot_unit "$IMAGE" app "$TEST_DIR/setup.sh"; then fail "a failed image change must be reported"; fi
+CUSTOMIZE_FAIL=no
+ok "vm_firstboot_unit rejects bad input and reports image failures"
+
+# ── vm_require_tools ────────────────────────────────────────────────────────
+TOOLS_BIN="$TEST_DIR/bin"
+mkdir -p "$TOOLS_BIN"
+CHMOD="$(command -v chmod)"
+APT_RC=0
+apt-get() {
+  printf 'apt-get %s\n' "$*" >>"$LOG"
+  [[ "$1" == install ]] || return 0
+  ((APT_RC == 0)) || return "$APT_RC"
+  local p t
+  for p in "$@"; do
+    case "$p" in
+    xz-utils) printf '#!/bin/sh\n' >"$TOOLS_BIN/xz" && "$CHMOD" +x "$TOOLS_BIN/xz" ;;
+    libguestfs-tools)
+      for t in virt-customize virt-resize virt-filesystems; do
+        printf '#!/bin/sh\n' >"$TOOLS_BIN/$t" && "$CHMOD" +x "$TOOLS_BIN/$t"
+      done
+      ;;
+    esac
+  done
+}
+
+with_path() {
+  local saved="$PATH" rc=0
+  PATH="$TOOLS_BIN"
+  hash -r
+  "$@" || rc=$?
+  PATH="$saved"
+  hash -r
+  return "$rc"
+}
+
+reset_logs
+with_path vm_require_tools xz virt-customize virt-resize || fail "installable tools"
+assert_contains "$LOG" "apt-get install -y xz-utils libguestfs-tools"
+[[ "$(grep -c 'apt-get install' "$LOG")" == 1 ]] || fail "one install for all missing tools"
+ok "vm_require_tools installs each package once"
+
+reset_logs
+with_path vm_require_tools xz || fail "present tool"
+[[ ! -s "$LOG" ]] || fail "nothing to install when the tool exists"
+ok "vm_require_tools is a no-op when everything is present"
+
+reset_logs
+rm -f "$TOOLS_BIN/xz"
+APT_RC=100
+if with_path vm_require_tools xz; then fail "a failed install must fail"; fi
+assert_contains "$ERRORS" "Could not install xz-utils"
+APT_RC=0
+reset_logs
+if with_path vm_require_tools frobnicate; then fail "an unknown tool must fail"; fi
+assert_contains "$ERRORS" "cannot be installed automatically: frobnicate"
+[[ ! -s "$LOG" ]] || fail "unknown tools are not guessed into apt"
+ok "vm_require_tools fails for failed installs and unknown tools"
+
+# ── vm_wait_http and the closing block ──────────────────────────────────────
+http_codes 000 502 302
+vm_wait_http https://10.0.0.5:11443 30 --insecure || fail "302 counts as up"
+http_codes 000 401
+vm_wait_http https://10.0.0.5 30 || fail "401 counts as up"
+http_codes 000 503 503 503 503 503 503
+if vm_wait_http https://10.0.0.5 30; then fail "5xx is not up"; fi
+ok "vm_wait_http: 2xx/3xx/401/403 up, 5xx and no answer not"
+
+APP="Test App" VMID=100 HN=test-vm CORE_COUNT=2 RAM_SIZE=2048 DISK_SIZE=20G VM_IP=192.168.1.50 START_VM=yes
+summary="$(vm_print_summary "Version=1.2.3" "Empty=" "URL=https://192.168.1.50:8443")"
+for want in "Test App Summary:" "VM ID: 100" "Hostname: test-vm" "Resources: 2 vCPU, 2048 MiB RAM, 20G disk" \
+  "State: running" "IP Address: 192.168.1.50" "Version: 1.2.3" "URL: https://192.168.1.50:8443"; do
+  [[ "$summary" == *"$want"* ]] || fail "summary lacks <$want>: $summary"
+done
+[[ "$summary" != *"Empty:"* ]] || fail "empty rows are skipped"
+START_VM=no VM_IP=""
+summary="$(vm_print_summary)"
+[[ "$summary" == *"State: stopped"* && "$summary" != *"IP Address"* ]] || fail "stopped VM summary: $summary"
+steps="$(vm_next_steps "Open the console" "Detach the ISO")"
+[[ "$steps" == *"Next Steps:"*"1. Open the console"*"2. Detach the ISO"* ]] || fail "next steps: $steps"
+[[ -z "$(vm_next_steps)" ]] || fail "no steps, no heading"
+ok "vm_print_summary and vm_next_steps"
+
+reset_logs
+post_update_to_api() { printf 'api %s %s\n' "$1" "$2" >>"$LOG"; }
+msg_ok() { printf 'ok %s\n' "$*" >>"$LOG"; }
+vm_finish "Created; installation continues in the VM" >/dev/null
+assert_contains "$LOG" "api done none"
+assert_contains "$LOG" "ok Created; installation continues in the VM"
+ok "vm_finish reports done and the given message"
+
+# ── Incus counterparts ──────────────────────────────────────────────────────
+grep -qx '_incus_vm_source "vm/common.func"' "${COMMUNITY_SCRIPTS_CORE_DIR}/incus/vm-core.func" ||
+  fail "incus/vm-core.func must load vm/common.func"
+(
+  eval "$(awk '/^_incus_vm_qm_only\(\)/,/^}/' "${COMMUNITY_SCRIPTS_CORE_DIR}/incus/vm-core.func")"
+  eval "$(grep -E '^vm_(import_disk|start_vm|wait_guest_agent|guest_exec|wait_for_ip)\(\) \{ _incus_vm_qm_only' \
+    "${COMMUNITY_SCRIPTS_CORE_DIR}/incus/vm-core.func")"
+  for fn in vm_import_disk vm_start_vm vm_wait_guest_agent vm_guest_exec vm_wait_for_ip; do
+    reset_logs
+    rc=0
+    "$fn" 100 x y || rc=$?
+    assert_eq "$rc" 119 "$fn on Incus"
+    assert_contains "$ERRORS" "only available on Proxmox VE"
+  done
+) || exit 1
+ok "Incus loads the shared helpers and refuses the qm-only ones with exit 119"
+
+printf '\n%d VM helper tests passed\n' "$passed"
diff --git a/vm/cloud-init.func b/vm/cloud-init.func
index 57a0836..dfba968 100644
--- a/vm/cloud-init.func
+++ b/vm/cloud-init.func
@@ -759,15 +759,31 @@ EOF
 
 # ------------------------------------------------------------------------------
 # get_vm_ip - Get VM IP address via qemu-guest-agent
+#
+#   get_vm_ip <vmid> [timeout seconds] [mac]
+#
+# With a MAC only the interface carrying it counts, which is the only reliable
+# answer once the guest runs Docker, Podman or Kubernetes. Without one, bridge
+# and tunnel interfaces those create are skipped. Loopback and link-local
+# addresses never count.
 # ------------------------------------------------------------------------------
 function get_vm_ip() {
   local vmid="$1"
   local timeout="${2:-30}"
+  local mac="${3:-}"
+  mac="${mac,,}"
 
-  local elapsed=0
+  local elapsed=0 vm_ip
   while [ $elapsed -lt $timeout ]; do
-    local vm_ip=$(qm guest cmd "$vmid" network-get-interfaces 2>/dev/null |
-      jq -r '.[] | select(.name != "lo") | ."ip-addresses"[]? | select(."ip-address-type" == "ipv4") | ."ip-address"' 2>/dev/null | head -1)
+    vm_ip=$(qm guest cmd "$vmid" network-get-interfaces 2>/dev/null |
+      jq -r --arg mac "$mac" '
+        .[] | select(.name != "lo")
+        | select(if $mac != ""
+                 then ((."hardware-address" // "") | ascii_downcase) == $mac
+                 else (.name | test("^(docker|br-|veth|podman|cni|flannel|cali|cilium|kube|virbr|lxc|vnet|tun|tap|wg|tailscale|zt)") | not)
+                 end)
+        | ."ip-addresses"[]? | select(."ip-address-type" == "ipv4") | ."ip-address"
+        | select(test("^(127\\.|169\\.254\\.)") | not)' 2>/dev/null | head -1)
 
     if [ -n "$vm_ip" ]; then
       echo "$vm_ip"
@@ -782,13 +798,47 @@ function get_vm_ip() {
 }
 
 # ------------------------------------------------------------------------------
-# wait_for_cloud_init - Wait for Cloud-Init to complete (requires SSH access)
+# wait_for_cloud_init - Wait for Cloud-Init to complete
+#
+# Asks through the guest agent first, which needs neither an address nor SSH
+# keys. Falls back to SSH for guests without an agent.
 # ------------------------------------------------------------------------------
 function wait_for_cloud_init() {
   local vmid="$1"
   local timeout="${2:-300}"
   local vm_ip="${3:-}"
 
+  local waited=0 json rc=""
+  while [ $waited -lt 60 ]; do
+    qm guest cmd "$vmid" ping >/dev/null 2>&1 && break
+    sleep 3
+    waited=$((waited + 3))
+  done
+
+  if [ $waited -lt 60 ]; then
+    _ci_msg_info "Waiting for Cloud-Init to complete (guest agent)"
+    json=$(qm guest exec "$vmid" --timeout "$timeout" -- cloud-init status --wait 2>/dev/null) || true
+    rc=$(jq -r 'if .exited == 1 then (.exitcode // 1) else 124 end' <<<"$json" 2>/dev/null) || rc=""
+    case "$rc" in
+    0)
+      _ci_msg_ok "Cloud-Init completed successfully"
+      return 0
+      ;;
+    2)
+      _ci_msg_warn "Cloud-Init completed with recoverable errors -- see /var/log/cloud-init.log in the VM"
+      return 0
+      ;;
+    124)
+      _ci_msg_warn "Cloud-Init did not complete within ${timeout}s"
+      return 1
+      ;;
+    [0-9]*)
+      _ci_msg_warn "Cloud-Init reported an error (exit ${rc}) -- see /var/log/cloud-init.log in the VM"
+      return 1
+      ;;
+    esac
+  fi
+
   # Get IP if not provided
   if [ -z "$vm_ip" ]; then
     vm_ip=$(get_vm_ip "$vmid" 60)
diff --git a/vm/common.func b/vm/common.func
new file mode 100644
index 0000000..2a8bf6e
--- /dev/null
+++ b/vm/common.func
@@ -0,0 +1,412 @@
+#!/usr/bin/env bash
+# Copyright (c) 2021-2026 community-scripts ORG
+# License: MIT | https://raw.githubusercontent.com/community-scripts/core/main/LICENSE
+
+# ==============================================================================
+# VM/COMMON.FUNC - BACKEND-INDEPENDENT VM SCRIPT HELPERS
+# ==============================================================================
+#
+# Sourced by pve/vm-core.func and incus/vm-core.func, so a VM script finds the
+# same helpers on either host. Nothing in here calls qm or incus: the parts of
+# a VM script that are not about the hypervisor -- which tools the host needs,
+# which release to download and how to verify it, what the guest does on its
+# first boot, how the run ends -- were copied from script to script and had
+# drifted apart.
+#
+#   vm_require_tools        Install missing host tools up front, or stop
+#   vm_release_asset        Release asset (URL, version, sha256) from a forge
+#   vm_latest_from_index    Newest entry of an HTML download index
+#   vm_firstboot_unit       Stage a run-once systemd unit into an image
+#   vm_wait_http            Wait until a web UI answers
+#   vm_print_summary        Standard closing summary
+#   vm_next_steps           Numbered follow-up instructions
+#   vm_finish               Report success and end the run
+# ==============================================================================
+
+[[ -n "${_VM_COMMON_LOADED:-}" ]] && return 0
+_VM_COMMON_LOADED=1
+
+# ------------------------------------------------------------------------------
+# vm_require_tools <command>...
+#
+# Commands the script will need later, checked before anything is created. A
+# missing xz used to surface after the VM existed, half configured.
+# ------------------------------------------------------------------------------
+_vm_tool_package() {
+  case "$1" in
+  jq | curl | pv | unzip | zstd | bzip2 | gzip | openssl | wget | rsync) echo "$1" ;;
+  gunzip) echo gzip ;;
+  xz) echo xz-utils ;;
+  7z) echo 7zip ;;
+  virt-customize | virt-resize | virt-filesystems | guestfish) echo libguestfs-tools ;;
+  *) return 1 ;;
+  esac
+}
+
+vm_require_tools() {
+  local tool pkg
+  local -a missing=() pkgs=() unknown=()
+
+  for tool in "$@"; do
+    command -v "$tool" >/dev/null 2>&1 && continue
+    missing+=("$tool")
+    if pkg="$(_vm_tool_package "$tool")"; then
+      [[ " ${pkgs[*]} " == *" ${pkg} "* ]] || pkgs+=("$pkg")
+    else
+      unknown+=("$tool")
+    fi
+  done
+
+  ((${#missing[@]})) || return 0
+
+  if ((${#unknown[@]})); then
+    msg_error "Required tools are missing and cannot be installed automatically: ${unknown[*]}"
+    return 1
+  fi
+  if ! command -v apt-get >/dev/null 2>&1; then
+    msg_error "Required tools are missing: ${missing[*]} -- install ${pkgs[*]}"
+    return 1
+  fi
+
+  msg_info "Installing ${pkgs[*]}"
+  ${STD:-} apt-get update || true
+  if ! ${STD:-} apt-get install -y "${pkgs[@]}"; then
+    msg_error "Could not install ${pkgs[*]} (needed for ${missing[*]})"
+    return 1
+  fi
+  for tool in "${missing[@]}"; do
+    if ! command -v "$tool" >/dev/null 2>&1; then
+      msg_error "${tool} is still missing after installing ${pkgs[*]}"
+      return 1
+    fi
+  done
+  msg_ok "Installed ${pkgs[*]}"
+}
+
+# ------------------------------------------------------------------------------
+# _vm_checksum_from_sums <sums url> <file name>
+#
+# "<tool> <hash>" for one file from a published checksum list. Reads the three
+# layouts vendors actually use: GNU ("hash  file", "hash *file"), BSD
+# ("SHA256 (file) = hash") and a bare hash. The algorithm follows from the hash
+# length. Lines that merely mention the file -- TurnKey's signed .hash files
+# contain "$ sha256sum file" -- are skipped because their first field is not hex.
+# ------------------------------------------------------------------------------
+_vm_checksum_from_sums() {
+  local sums_url="${1:?sums url}" file="${2:?file name}" body want stripped tool
+
+  body="$(curl -fsSL --max-time 30 "$sums_url" 2>/dev/null)" || return 1
+  stripped="${body//[[:space:]]/}"
+
+  if [[ "$stripped" =~ ^([0-9a-fA-F]{40}|[0-9a-fA-F]{64}|[0-9a-fA-F]{128})$ ]]; then
+    want="$stripped"
+  else
+    want="$(printf '%s\n' "$body" | awk -v f="$file" '
+      { sub(/\r$/, "") }
+      $1 ~ /^SHA(1|256|512)$/ && $2 == "(" f ")" && $3 == "=" { print $4; exit }
+      NF == 2 && $1 ~ /^[0-9a-fA-F]+$/ && ($2 == f || $2 == "*" f) { print $1; exit }
+    ')"
+  fi
+
+  case ${#want} in
+  40) tool=sha1sum ;;
+  64) tool=sha256sum ;;
+  128) tool=sha512sum ;;
+  *) return 1 ;;
+  esac
+  [[ "$want" =~ ^[0-9a-fA-F]+$ ]] || return 1
+  command -v "$tool" >/dev/null 2>&1 || return 1
+  printf '%s %s' "$tool" "${want,,}"
+}
+
+# ------------------------------------------------------------------------------
+# vm_release_asset <github|gitlab|codeberg> <owner/repo> <asset regex> [tag]
+#
+# Resolves one release asset through lib/forge.func, which already handles
+# tokens, rate limits, the API-less fallback and prereleases. Sets
+# VM_RELEASE_TAG, VM_RELEASE_VERSION (tag without a leading v),
+# VM_RELEASE_ASSET, VM_RELEASE_URL and, when the forge publishes one (GitHub
+# asset digests), VM_RELEASE_SHA256 -- pass it to vm_fetch_image --sha256.
+# ------------------------------------------------------------------------------
+_vm_load_forge() {
+  declare -f _forge_release_json >/dev/null 2>&1 && return 0
+  local rel="lib/forge.func"
+  local base="${COMMUNITY_SCRIPTS_CORE_URL:-https://raw.githubusercontent.com/community-scripts/core/main}"
+
+  if [[ -n "${COMMUNITY_SCRIPTS_CORE_DIR:-}" && -f "${COMMUNITY_SCRIPTS_CORE_DIR}/${rel}" ]]; then
+    # shellcheck disable=SC1090
+    source "${COMMUNITY_SCRIPTS_CORE_DIR}/${rel}"
+  elif declare -f _cs_source_func >/dev/null 2>&1; then
+    _cs_source_func "$rel" 2>/dev/null || true
+  else
+    # shellcheck disable=SC1090
+    source <(curl -fsSL --retry 3 --retry-delay 1 --connect-timeout 10 "${base}/${rel}" 2>/dev/null) 2>/dev/null || true
+  fi
+  declare -f _forge_release_json >/dev/null 2>&1
+}
+
+vm_release_asset() {
+  local forge="${1:?forge}" repo="${2:?owner/repo}" pattern="${3:?asset pattern}" version="${4:-latest}"
+  local json asset digest rc=0
+
+  VM_RELEASE_TAG="" VM_RELEASE_VERSION="" VM_RELEASE_ASSET="" VM_RELEASE_URL="" VM_RELEASE_SHA256=""
+
+  vm_require_tools jq || return 1
+  if ! _vm_load_forge; then
+    msg_error "The release helpers (lib/forge.func) could not be loaded"
+    return 1
+  fi
+
+  json="$(mktemp)" || return 1
+  _forge_release_json "$forge" "$repo" "$version" "" "$json" || rc=$?
+  # forge.func keeps the raw payload for hwaccel.func; nothing here reads it.
+  if [[ -n "${TOOLS_GH_REL_JSON:-}" ]]; then
+    rm -f "$TOOLS_GH_REL_JSON"
+    TOOLS_GH_REL_JSON=""
+  fi
+  if ((rc != 0)); then
+    rm -f "$json"
+    msg_error "Could not read the ${version} release of ${repo}"
+    return 1
+  fi
+
+  VM_RELEASE_TAG="$(jq -r '.tag_name // empty' "$json" 2>/dev/null)" || VM_RELEASE_TAG=""
+  # GitLab hangs its files off .assets.links, GitHub and Codeberg off .assets.
+  asset="$(jq -c --arg re "$pattern" '
+    (if (.assets | type) == "object"
+     then ((.assets.links // []) | map({name, url: (.direct_asset_url // .url), digest: null}))
+     else ((.assets // []) | map({name, url: .browser_download_url, digest: (.digest // null)}))
+     end)
+    | map(select(.name | test($re))) | first // empty' "$json" 2>/dev/null)" || asset=""
+  rm -f "$json"
+
+  if [[ -z "$VM_RELEASE_TAG" || -z "$asset" ]]; then
+    msg_error "${repo} ${VM_RELEASE_TAG:-release} has no asset matching ${pattern}"
+    return 1
+  fi
+
+  VM_RELEASE_ASSET="$(jq -r '.name' <<<"$asset")"
+  VM_RELEASE_URL="$(jq -r '.url' <<<"$asset")"
+  digest="$(jq -r '.digest // empty' <<<"$asset")"
+  [[ "$digest" =~ ^sha256:([0-9a-fA-F]{64})$ ]] && VM_RELEASE_SHA256="${BASH_REMATCH[1],,}"
+  VM_RELEASE_VERSION="${VM_RELEASE_TAG#[vV]}"
+  return 0
+}
+
+# ------------------------------------------------------------------------------
+# vm_latest_from_index <index url> <pcre> [--sort-by <pcre>] [--probe <url>]...
+#
+# The newest match of <pcre> (grep -oP, so \K works) on an HTML download page.
+# Ordered by version, or by the part of each match that --sort-by selects when
+# the version does not order the builds (BlissOS reuses versions across build
+# dates). Each --probe is a URL template with {} for the match; the first match
+# whose template answers is taken, newest first, so a release directory that
+# exists before its files does not win. Sets VM_INDEX_LATEST and, with
+# --probe, VM_INDEX_URL. Never falls back to a hardcoded release.
+# ------------------------------------------------------------------------------
+vm_latest_from_index() {
+  local url="${1:?index url}" pattern="${2:?pattern}"
+  shift 2
+  local sort_by="" page candidate template probe_url
+  local -a templates=() candidates=()
+
+  while (($#)); do
+    case "$1" in
+    --sort-by) sort_by="${2:?sort pattern}"; shift 2 ;;
+    --probe) templates+=("${2:?url template}"); shift 2 ;;
+    *) msg_error "vm_latest_from_index: unknown option $1"; return 2 ;;
+    esac
+  done
+
+  VM_INDEX_LATEST="" VM_INDEX_URL=""
+
+  if ! page="$(curl -fsSL --max-time 30 --retry 3 --retry-delay 2 "$url" 2>/dev/null)"; then
+    msg_error "Could not read ${url}"
+    return 1
+  fi
+
+  if [[ -n "$sort_by" ]]; then
+    mapfile -t candidates < <(
+      { grep -oP -- "$pattern" <<<"$page" || true; } | sort -u |
+        while IFS= read -r candidate; do
+          printf '%s\t%s\n' "$({ grep -oP -m1 -- "$sort_by" <<<"$candidate" || true; } | head -n1)" "$candidate"
+        done | sort -t $'\t' -k1,1Vr | cut -f2-
+    )
+  else
+    mapfile -t candidates < <({ grep -oP -- "$pattern" <<<"$page" || true; } | sort -Vru)
+  fi
+
+  if ((${#candidates[@]} == 0)); then
+    msg_error "Nothing at ${url} matches ${pattern}"
+    return 1
+  fi
+
+  if ((${#templates[@]} == 0)); then
+    VM_INDEX_LATEST="${candidates[0]}"
+    return 0
+  fi
+
+  for candidate in "${candidates[@]}"; do
+    for template in "${templates[@]}"; do
+      probe_url="${template//\{\}/$candidate}"
+      if curl -fsIL --max-time 20 -o /dev/null "$probe_url" 2>/dev/null; then
+        VM_INDEX_LATEST="$candidate"
+        VM_INDEX_URL="$probe_url"
+        return 0
+      fi
+    done
+  done
+
+  msg_error "None of the ${#candidates[@]} entries at ${url} has a downloadable file"
+  return 1
+}
+
+# ------------------------------------------------------------------------------
+# vm_firstboot_unit <image> <name> <script> [--description <text>]
+#                   [--after <unit>]... [--requires-path <path>]
+#                   [--cloud-init yes|no]
+#
+# Uploads <script> as /usr/local/sbin/<name> and enables <name>.service, a
+# oneshot that runs once: a marker under /var/lib/community-scripts is written
+# only after the script succeeded, so a failed run is retried on the next boot
+# and VM_FIRSTBOOT_MARKER tells the caller what to test for.
+#
+# With Cloud-Init the unit is pulled in by cloud-init.target and ordered after
+# cloud-final.service, so users, keys and network exist first. Wanting
+# multi-user.target there instead creates an ordering cycle, because
+# cloud-final itself runs after multi-user.target. Without Cloud-Init the unit
+# is wanted by multi-user.target. Every --after unit is also wanted.
+#
+# Returns non-zero when the image could not be changed; the caller decides
+# whether a VM without its first-boot step is still worth creating.
+# ------------------------------------------------------------------------------
+vm_firstboot_unit() {
+  local image="${1:?image}" name="${2:?unit name}" script="${3:?script file}"
+  shift 3
+  local description="" requires_path="" cloud_init="${USE_CLOUD_INIT:-no}"
+  local -a after=()
+
+  while (($#)); do
+    case "$1" in
+    --description) description="${2:?description}"; shift 2 ;;
+    --after) after+=("${2:?unit}"); shift 2 ;;
+    --requires-path) requires_path="${2:?path}"; shift 2 ;;
+    --cloud-init) cloud_init="${2:?yes|no}"; shift 2 ;;
+    *) msg_error "vm_firstboot_unit: unknown option $1"; return 2 ;;
+    esac
+  done
+
+  if [[ ! "$name" =~ ^[a-z0-9][a-z0-9-]*$ ]]; then
+    msg_error "vm_firstboot_unit: invalid unit name '${name}'"
+    return 2
+  fi
+  if [[ ! -r "$script" ]]; then
+    msg_error "vm_firstboot_unit: cannot read ${script}"
+    return 1
+  fi
+
+  local marker="/var/lib/community-scripts/${name}.done"
+  local deps="network-online.target" wanted_by="multi-user.target" unit before
+  if [[ "$cloud_init" == "yes" ]]; then
+    deps+=" cloud-final.service"
+    wanted_by="cloud-init.target"
+  fi
+  ((${#after[@]})) && deps+=" ${after[*]}"
+
+  unit="$(mktemp)" || return 1
+  {
+    printf '[Unit]\n'
+    printf 'Description=%s\n' "${description:-Community-Scripts first boot: ${name}}"
+    printf 'After=%s\n' "$deps"
+    printf 'Wants=%s\n' "$deps"
+    printf 'ConditionPathExists=!%s\n' "$marker"
+    [[ -n "$requires_path" ]] && printf 'ConditionPathExists=%s\n' "$requires_path"
+    printf '\n[Service]\n'
+    printf 'Type=oneshot\n'
+    printf 'ExecStart=/usr/local/sbin/%s\n' "$name"
+    printf "ExecStartPost=/bin/sh -c 'mkdir -p /var/lib/community-scripts && touch %s'\n" "$marker"
+    printf 'RemainAfterExit=yes\n'
+    printf 'TimeoutStartSec=infinity\n'
+    printf 'StandardOutput=journal+console\n'
+    printf 'StandardError=journal+console\n'
+    printf '\n[Install]\n'
+    printf 'WantedBy=%s\n' "$wanted_by"
+  } >"$unit"
+
+  before=${#_VM_PREPARE_FAILED[@]}
+  _vm_customize "first-boot ${name}" "$image" \
+    --mkdir /usr/local/sbin \
+    --upload "${script}:/usr/local/sbin/${name}" \
+    --chmod "0755:/usr/local/sbin/${name}" \
+    --upload "${unit}:/etc/systemd/system/${name}.service" \
+    --run-command "systemctl enable ${name}.service"
+  rm -f "$unit"
+
+  ((${#_VM_PREPARE_FAILED[@]} > before)) && return 1
+  VM_FIRSTBOOT_MARKER="$marker"
+  return 0
+}
+
+# ------------------------------------------------------------------------------
+# vm_wait_http <url> [timeout seconds] [--insecure]
+#
+# 0 once the URL answers like a running web UI: any 2xx or 3xx, or 401/403 from
+# a login wall. 5xx is a proxy whose backend is still starting.
+# ------------------------------------------------------------------------------
+vm_wait_http() {
+  local url="${1:?url}" timeout="${2:-120}" waited=0 code
+  local -a opts=(-sS -o /dev/null -w '%{http_code}' --max-time 5)
+  [[ "${3:-}" == "--insecure" ]] && opts+=(-k)
+
+  while ((waited < timeout)); do
+    code="$(curl "${opts[@]}" "$url" 2>/dev/null)" || code="000"
+    [[ "$code" =~ ^([23][0-9][0-9]|401|403)$ ]] && return 0
+    sleep 5
+    waited=$((waited + 5))
+  done
+  return 1
+}
+
+# ------------------------------------------------------------------------------
+# vm_print_summary ["Label=value"]...
+# vm_next_steps <step>...
+# vm_finish [message]
+#
+# The closing block every VM script printed in its own layout. Empty values are
+# skipped, so a VM that was not started simply has no IP row.
+# ------------------------------------------------------------------------------
+_vm_summary_row() {
+  [[ -n "${2:-}" ]] && echo -e "${TAB:-  }${DGN:-}${1}: ${BGN:-}${2}${CL:-}"
+  return 0
+}
+
+vm_print_summary() {
+  local item state="running"
+  [[ "${START_VM:-yes}" == "yes" ]] || state="stopped -- start it from the Proxmox UI"
+
+  echo -e "\n${INFO:-}${BOLD:-}${GN:-}${APP:-VM} Summary:${CL:-}"
+  _vm_summary_row "VM ID" "${VMID:-}"
+  _vm_summary_row "Hostname" "${HN:-}"
+  _vm_summary_row "Resources" "${CORE_COUNT:+${CORE_COUNT} vCPU, }${RAM_SIZE:+${RAM_SIZE} MiB RAM, }${DISK_SIZE:+${DISK_SIZE} disk}"
+  _vm_summary_row "State" "$state"
+  _vm_summary_row "IP Address" "${VM_IP:-}"
+  for item in "$@"; do
+    _vm_summary_row "${item%%=*}" "${item#*=}"
+  done
+}
+
+vm_next_steps() {
+  local step i=1
+  (($#)) || return 0
+  echo -e "\n${INFO:-}${BOLD:-}${YW:-}Next Steps:${CL:-}"
+  for step in "$@"; do
+    echo -e "${TAB:-  }${i}. ${step}"
+    i=$((i + 1))
+  done
+}
+
+vm_finish() {
+  declare -f post_update_to_api >/dev/null 2>&1 && post_update_to_api "done" "none"
+  echo
+  msg_ok "${1:-Completed successfully!}\n"
+}

From 908ca6b83aa34408e0f100908d296f0ccd9aa231 Mon Sep 17 00:00:00 2001
From: MickLesk <47820557+MickLesk@users.noreply.github.com>
Date: Wed, 7 Oct 2026 19:22:59 +0200
Subject: [PATCH 2/3] Add vm_customize for script-owned image steps

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 docs/vm.md          |  1 +
 tests/vm-helpers.sh |  9 +++++++++
 vm/common.func      | 15 +++++++++++++++
 3 files changed, 25 insertions(+)

diff --git a/docs/vm.md b/docs/vm.md
index dfd71b6..ef93ca4 100644
--- a/docs/vm.md
+++ b/docs/vm.md
@@ -51,6 +51,7 @@ same functions on either host. Nothing in it calls `qm` or `incus`.
 | Function | Contract |
 | --- | --- |
 | `vm_require_tools <cmd>...` | Installs the packages for missing commands (`jq`, `xz`, `virt-customize`, `unzip`, `zstd`, `7z`, …) before anything is created; returns non-zero, with the reason, when it cannot. |
+| `vm_customize <label> <image> <virt-customize args>...` | A script's own image step. Warns with libguestfs' reason like the shared preparation steps, and returns non-zero so a required step can stop the run. |
 | `vm_release_asset <github\|gitlab\|codeberg> <owner/repo> <asset regex> [tag]` | Resolves a release through [`lib/forge.func`](../lib/forge.func) — tokens, rate limits and the API-less GitHub fallback included. Sets `VM_RELEASE_TAG`, `VM_RELEASE_VERSION`, `VM_RELEASE_ASSET`, `VM_RELEASE_URL` and, from GitHub's asset digest, `VM_RELEASE_SHA256`. |
 | `vm_latest_from_index <url> <pcre> [--sort-by <pcre>] [--probe <url with {}>]...` | Newest match on an HTML download index (`grep -oP`, so `\K` works). `--sort-by` orders by part of the match; each `--probe` template is tried newest first and the first answering URL wins. Sets `VM_INDEX_LATEST` and `VM_INDEX_URL`. Never falls back to a hardcoded release. |
 | `vm_firstboot_unit <image> <name> <script> [--description …] [--after <unit>]... [--requires-path <path>] [--cloud-init yes\|no]` | Stages `<script>` as `/usr/local/sbin/<name>` plus a run-once `<name>.service`. The marker `/var/lib/community-scripts/<name>.done` (`VM_FIRSTBOOT_MARKER`) is written only after success, so a failure is retried on the next boot. With Cloud-Init the unit is wanted by `cloud-init.target` and ordered after `cloud-final.service`; wanting `multi-user.target` there would create an ordering cycle. |
diff --git a/tests/vm-helpers.sh b/tests/vm-helpers.sh
index e277fb7..a38042d 100644
--- a/tests/vm-helpers.sh
+++ b/tests/vm-helpers.sh
@@ -446,6 +446,15 @@ assert_contains "$UNIT" "WantedBy=cloud-init.target"
 unset USE_CLOUD_INIT
 ok "vm_firstboot_unit follows USE_CLOUD_INIT by default"
 
+_VM_PREPARE_FAILED=()
+CUSTOMIZE_FAIL=no
+vm_customize "Docker" "$IMAGE" --run-command true || fail "a successful step returns 0"
+CUSTOMIZE_FAIL=yes
+if vm_customize "Docker" "$IMAGE" --run-command false; then fail "a failed step must return non-zero"; fi
+CUSTOMIZE_FAIL=no
+_VM_PREPARE_FAILED=()
+ok "vm_customize returns the step's failure"
+
 rc=0
 vm_firstboot_unit "$IMAGE" "Bad Name" "$TEST_DIR/setup.sh" || rc=$?
 assert_eq "$rc" 2 "invalid unit name"
diff --git a/vm/common.func b/vm/common.func
index 2a8bf6e..4c34d39 100644
--- a/vm/common.func
+++ b/vm/common.func
@@ -14,6 +14,7 @@
 # drifted apart.
 #
 #   vm_require_tools        Install missing host tools up front, or stop
+#   vm_customize            virt-customize step that reports and returns failure
 #   vm_release_asset        Release asset (URL, version, sha256) from a forge
 #   vm_latest_from_index    Newest entry of an HTML download index
 #   vm_firstboot_unit       Stage a run-once systemd unit into an image
@@ -83,6 +84,20 @@ vm_require_tools() {
   msg_ok "Installed ${pkgs[*]}"
 }
 
+# ------------------------------------------------------------------------------
+# vm_customize <label> <image> <virt-customize args>...
+#
+# One named virt-customize step for a script's own image changes. Failures are
+# warned about with the reason libguestfs gave, like the shared preparation
+# steps, but also returned, so a step the VM cannot work without can stop the
+# run: `vm_customize "Docker" "$image" --run-command "..." || exit 1`.
+# ------------------------------------------------------------------------------
+vm_customize() {
+  local before=${#_VM_PREPARE_FAILED[@]}
+  _vm_customize "$@"
+  ((${#_VM_PREPARE_FAILED[@]} == before))
+}
+
 # ------------------------------------------------------------------------------
 # _vm_checksum_from_sums <sums url> <file name>
 #

From a126a1a9a514cd5914bb1b6a5736ff1a588902ba Mon Sep 17 00:00:00 2001
From: MickLesk <47820557+MickLesk@users.noreply.github.com>
Date: Thu, 8 Oct 2026 09:17:39 +0200
Subject: [PATCH 3/3] Read qm's real import report, bound vm_wait_http by the
 clock, trim comments

qm prints "Successfully imported disk as 'unused0:<volume>'": capital S, "as", and the unusedN: prefix. The regex matched none of that and the test encoded the wrong line, so every import went through the unusedN fallback. vm_wait_http counted 5s per round but each round could take 10s. The summary no longer names the Proxmox UI, since common.func serves Incus too.
---
 incus/vm-core.func  |   5 +-
 pve/vm-core.func    |  40 ++++++----------
 tests/vm-helpers.sh |   7 +--
 vm/common.func      | 109 +++++++++++++-------------------------------
 4 files changed, 51 insertions(+), 110 deletions(-)

diff --git a/incus/vm-core.func b/incus/vm-core.func
index cab2de8..b393d90 100644
--- a/incus/vm-core.func
+++ b/incus/vm-core.func
@@ -873,9 +873,8 @@ vm_select_iso_storage() {
   return 119
 }
 
-# qm-specific steps of the Proxmox VM scripts. incus_vm_create imports, starts
-# and waits for the agent itself, so there is nothing to translate them into;
-# they fail loudly instead of pretending to have worked.
+# The qm-driven steps have no Incus counterpart: incus_vm_create imports,
+# starts and waits for the agent itself.
 _incus_vm_qm_only() {
   msg_error "$1 drives qm and is only available on Proxmox VE; use incus_vm_create on Incus."
   return 119
diff --git a/pve/vm-core.func b/pve/vm-core.func
index d697233..2496b85 100644
--- a/pve/vm-core.func
+++ b/pve/vm-core.func
@@ -2341,15 +2341,12 @@ vm_resize_disk() {
   fi
 }
 
-# ------------------------------------------------------------------------------
 # vm_import_disk <vmid> <image> <storage> [format]
-#
-# Imports an image and sets VM_IMPORTED_DISK to the volume Proxmox actually
-# created. Scripts predicted that name, parsed qm's output three different
-# ways, or took the last `pvesm list` entry, which sorts disk-10 before disk-9.
-# The volume is read from qm's report, else from the unusedN entry the import
-# added. The format defaults to DISK_IMPORT_FORMAT from vm_select_storage.
-# ------------------------------------------------------------------------------
+# Sets VM_IMPORTED_DISK to the volume Proxmox created: from qm's own report
+# ("Successfully imported disk as 'unused0:<volume>'"), else from the unusedN
+# entry the import added. Scripts used to guess the name or take the last
+# `pvesm list` line, which sorts disk-10 before disk-9. The format defaults to
+# DISK_IMPORT_FORMAT from vm_select_storage.
 vm_import_disk() {
   local vmid="${1:?vmid}" file="${2:?image}" storage="${3:?storage}" format="${4:-${DISK_IMPORT_FORMAT:-}}"
   local out before volume
@@ -2367,7 +2364,8 @@ vm_import_disk() {
     return 1
   fi
 
-  volume="$(printf '%s\n' "$out" | sed -n "s/.*successfully imported disk '\([^']*\)'.*/\1/p" | tail -n 1)"
+  volume="$(printf '%s\n' "$out" | sed -n "s/.*[Ss]uccessfully imported disk\( as\)\? '\([^']*\)'.*/\2/p" | tail -n 1)"
+  volume="${volume#unused[0-9]*:}"
   if [[ -z "$volume" ]]; then
     volume="$(qm config "$vmid" 2>/dev/null | sed -n 's/^unused[0-9]*: //p' |
       grep -vxF -f <(printf '%s\n' "$before") | tail -n 1)" || volume=""
@@ -2384,12 +2382,8 @@ vm_import_disk() {
   msg_ok "Imported disk ${CL}${BL}${VM_IMPORTED_DISK}${CL}"
 }
 
-# ------------------------------------------------------------------------------
 # vm_start_vm [label]
-#
-# Starts the VM when START_VM is yes. A failed start after vm_mark_created is a
-# post-create error: the VM is kept.
-# ------------------------------------------------------------------------------
+# Starts the VM when START_VM is yes; a failed start keeps the created VM.
 vm_start_vm() {
   local label="${1:-${APP:-VM}}"
   [[ "${START_VM:-yes}" == "yes" ]] || return 0
@@ -2398,14 +2392,10 @@ vm_start_vm() {
   msg_ok "Started ${label}"
 }
 
-# ------------------------------------------------------------------------------
 # vm_wait_guest_agent <vmid> [timeout seconds]
 # vm_guest_exec <vmid> <timeout seconds> [--] <command> [args]...
-#
-# The guest agent answers without SSH keys or a known address. vm_guest_exec
-# prints the command's stdout and returns its exit code; 124 means it was still
-# running at the timeout.
-# ------------------------------------------------------------------------------
+# vm_guest_exec prints the command's stdout and returns its exit code, 124 when
+# it was still running at the timeout.
 vm_wait_guest_agent() {
   local vmid="${1:?vmid}" timeout="${2:-120}" waited=0
   while ((waited < timeout)); do
@@ -2434,14 +2424,10 @@ vm_guest_exec() {
   return "$rc"
 }
 
-# ------------------------------------------------------------------------------
 # vm_wait_for_ip [timeout seconds]
-#
-# Sets VM_IP to the address on the VM's own NIC (matched by MAC), so a Docker
-# or Podman bridge inside the guest is not reported as the VM's address.
-# Returns non-zero with a warning when the VM was not started or no address
-# appeared; callers continue either way.
-# ------------------------------------------------------------------------------
+# Sets VM_IP from the NIC matching MAC, so a Docker or Podman bridge in the
+# guest is never reported as the VM's address. Warns and returns non-zero when
+# the VM was not started or no address appeared.
 vm_wait_for_ip() {
   local timeout="${1:-${VM_IP_TIMEOUT:-120}}"
   VM_IP=""
diff --git a/tests/vm-helpers.sh b/tests/vm-helpers.sh
index a38042d..bdcd1a5 100644
--- a/tests/vm-helpers.sh
+++ b/tests/vm-helpers.sh
@@ -32,7 +32,8 @@ msg_warn() { printf '%s\n' "$*" >>"$WARNINGS"; }
 _ci_msg_info() { :; }
 _ci_msg_ok() { :; }
 _ci_msg_warn() { printf '%s\n' "$*" >>"$WARNINGS"; }
-sleep() { :; }
+# No real waiting; SECONDS still moves so deadline loops end.
+sleep() { SECONDS=$((SECONDS + ${1%%.*})); }
 
 reset_logs() { : >"$LOG"; : >"$ERRORS"; : >"$WARNINGS"; }
 
@@ -228,9 +229,9 @@ import_case() {
 import_case
 DISK_IMPORT_FORMAT=raw
 QM_IMPORT_OUT="transferred 1.0 GiB of 1.0 GiB (100.00%)
-unused0: successfully imported disk 'local-lvm:vm-100-disk-1'"
+Successfully imported disk as 'unused0:local-lvm:vm-100-disk-1'"
 vm_import_disk 100 "$IMAGE" local-lvm || fail "modern import"
-assert_eq "$VM_IMPORTED_DISK" "local-lvm:vm-100-disk-1" "volume from qm's report"
+assert_eq "$VM_IMPORTED_DISK" "local-lvm:vm-100-disk-1" "volume from qm's report, without the unused0: prefix"
 assert_contains "$LOG" "qm disk import 100 $IMAGE local-lvm --format raw"
 ok "vm_import_disk uses qm disk import and the reported volume"
 
diff --git a/vm/common.func b/vm/common.func
index 4c34d39..8cc43ab 100644
--- a/vm/common.func
+++ b/vm/common.func
@@ -5,13 +5,9 @@
 # ==============================================================================
 # VM/COMMON.FUNC - BACKEND-INDEPENDENT VM SCRIPT HELPERS
 # ==============================================================================
-#
-# Sourced by pve/vm-core.func and incus/vm-core.func, so a VM script finds the
-# same helpers on either host. Nothing in here calls qm or incus: the parts of
-# a VM script that are not about the hypervisor -- which tools the host needs,
-# which release to download and how to verify it, what the guest does on its
-# first boot, how the run ends -- were copied from script to script and had
-# drifted apart.
+# Loaded by pve/vm-core.func and incus/vm-core.func. Nothing here calls qm or
+# incus: host tools, release lookups, checksums, first boot and the closing
+# block, which every VM script used to carry in its own copy.
 #
 #   vm_require_tools        Install missing host tools up front, or stop
 #   vm_customize            virt-customize step that reports and returns failure
@@ -27,12 +23,8 @@
 [[ -n "${_VM_COMMON_LOADED:-}" ]] && return 0
 _VM_COMMON_LOADED=1
 
-# ------------------------------------------------------------------------------
 # vm_require_tools <command>...
-#
-# Commands the script will need later, checked before anything is created. A
-# missing xz used to surface after the VM existed, half configured.
-# ------------------------------------------------------------------------------
+# Checked before anything is created, so a missing tool cannot surface halfway.
 _vm_tool_package() {
   case "$1" in
   jq | curl | pv | unzip | zstd | bzip2 | gzip | openssl | wget | rsync) echo "$1" ;;
@@ -84,29 +76,20 @@ vm_require_tools() {
   msg_ok "Installed ${pkgs[*]}"
 }
 
-# ------------------------------------------------------------------------------
 # vm_customize <label> <image> <virt-customize args>...
-#
-# One named virt-customize step for a script's own image changes. Failures are
-# warned about with the reason libguestfs gave, like the shared preparation
-# steps, but also returned, so a step the VM cannot work without can stop the
-# run: `vm_customize "Docker" "$image" --run-command "..." || exit 1`.
-# ------------------------------------------------------------------------------
+# Like the shared image steps it warns with libguestfs' reason, but it also
+# returns the failure: `vm_customize "Docker" "$image" --run-command ... || exit 1`.
 vm_customize() {
   local before=${#_VM_PREPARE_FAILED[@]}
   _vm_customize "$@"
   ((${#_VM_PREPARE_FAILED[@]} == before))
 }
 
-# ------------------------------------------------------------------------------
 # _vm_checksum_from_sums <sums url> <file name>
-#
-# "<tool> <hash>" for one file from a published checksum list. Reads the three
-# layouts vendors actually use: GNU ("hash  file", "hash *file"), BSD
-# ("SHA256 (file) = hash") and a bare hash. The algorithm follows from the hash
-# length. Lines that merely mention the file -- TurnKey's signed .hash files
-# contain "$ sha256sum file" -- are skipped because their first field is not hex.
-# ------------------------------------------------------------------------------
+# Prints "<tool> <hash>" for one file. Reads GNU ("hash  file", "hash *file"),
+# BSD ("SHA256 (file) = hash") and bare-hash lists; the algorithm follows from
+# the hash length. TurnKey's "$ sha256sum file" lines have no hex first field
+# and are skipped.
 _vm_checksum_from_sums() {
   local sums_url="${1:?sums url}" file="${2:?file name}" body want stripped tool
 
@@ -134,15 +117,11 @@ _vm_checksum_from_sums() {
   printf '%s %s' "$tool" "${want,,}"
 }
 
-# ------------------------------------------------------------------------------
 # vm_release_asset <github|gitlab|codeberg> <owner/repo> <asset regex> [tag]
-#
-# Resolves one release asset through lib/forge.func, which already handles
-# tokens, rate limits, the API-less fallback and prereleases. Sets
-# VM_RELEASE_TAG, VM_RELEASE_VERSION (tag without a leading v),
-# VM_RELEASE_ASSET, VM_RELEASE_URL and, when the forge publishes one (GitHub
-# asset digests), VM_RELEASE_SHA256 -- pass it to vm_fetch_image --sha256.
-# ------------------------------------------------------------------------------
+# Resolves through lib/forge.func (tokens, rate limits, API-less fallback).
+# Sets VM_RELEASE_TAG, VM_RELEASE_VERSION (tag without a leading v),
+# VM_RELEASE_ASSET, VM_RELEASE_URL and, from GitHub asset digests,
+# VM_RELEASE_SHA256 for vm_fetch_image --sha256.
 _vm_load_forge() {
   declare -f _forge_release_json >/dev/null 2>&1 && return 0
   local rel="lib/forge.func"
@@ -208,17 +187,11 @@ vm_release_asset() {
   return 0
 }
 
-# ------------------------------------------------------------------------------
 # vm_latest_from_index <index url> <pcre> [--sort-by <pcre>] [--probe <url>]...
-#
-# The newest match of <pcre> (grep -oP, so \K works) on an HTML download page.
-# Ordered by version, or by the part of each match that --sort-by selects when
-# the version does not order the builds (BlissOS reuses versions across build
-# dates). Each --probe is a URL template with {} for the match; the first match
-# whose template answers is taken, newest first, so a release directory that
-# exists before its files does not win. Sets VM_INDEX_LATEST and, with
-# --probe, VM_INDEX_URL. Never falls back to a hardcoded release.
-# ------------------------------------------------------------------------------
+# Newest match of <pcre> (grep -oP) on a download page, ordered by version or
+# by what --sort-by selects from each match. With --probe ({} = match) the
+# newest entry whose template answers wins, so an empty release directory is
+# skipped. Sets VM_INDEX_LATEST and, with --probe, VM_INDEX_URL.
 vm_latest_from_index() {
   local url="${1:?index url}" pattern="${2:?pattern}"
   shift 2
@@ -276,25 +249,14 @@ vm_latest_from_index() {
   return 1
 }
 
-# ------------------------------------------------------------------------------
 # vm_firstboot_unit <image> <name> <script> [--description <text>]
-#                   [--after <unit>]... [--requires-path <path>]
-#                   [--cloud-init yes|no]
-#
-# Uploads <script> as /usr/local/sbin/<name> and enables <name>.service, a
-# oneshot that runs once: a marker under /var/lib/community-scripts is written
-# only after the script succeeded, so a failed run is retried on the next boot
-# and VM_FIRSTBOOT_MARKER tells the caller what to test for.
-#
-# With Cloud-Init the unit is pulled in by cloud-init.target and ordered after
-# cloud-final.service, so users, keys and network exist first. Wanting
-# multi-user.target there instead creates an ordering cycle, because
-# cloud-final itself runs after multi-user.target. Without Cloud-Init the unit
-# is wanted by multi-user.target. Every --after unit is also wanted.
-#
-# Returns non-zero when the image could not be changed; the caller decides
-# whether a VM without its first-boot step is still worth creating.
-# ------------------------------------------------------------------------------
+#                   [--after <unit>]... [--requires-path <path>] [--cloud-init yes|no]
+# Uploads <script> as /usr/local/sbin/<name> and enables a oneshot <name>.service
+# that runs once: its marker (VM_FIRSTBOOT_MARKER) is written only after
+# success, so a failed run is retried on the next boot. With Cloud-Init the
+# unit hangs off cloud-init.target after cloud-final.service; wanting
+# multi-user.target there would be an ordering cycle, since cloud-final itself
+# runs after multi-user.target.
 vm_firstboot_unit() {
   local image="${1:?image}" name="${2:?unit name}" script="${3:?script file}"
   shift 3
@@ -362,34 +324,27 @@ vm_firstboot_unit() {
   return 0
 }
 
-# ------------------------------------------------------------------------------
 # vm_wait_http <url> [timeout seconds] [--insecure]
-#
-# 0 once the URL answers like a running web UI: any 2xx or 3xx, or 401/403 from
-# a login wall. 5xx is a proxy whose backend is still starting.
-# ------------------------------------------------------------------------------
+# 0 once the URL answers like a web UI: 2xx, 3xx, or 401/403 from a login wall.
 vm_wait_http() {
-  local url="${1:?url}" timeout="${2:-120}" waited=0 code
+  local url="${1:?url}" timeout="${2:-120}" code
+  local deadline=$((SECONDS + timeout))
   local -a opts=(-sS -o /dev/null -w '%{http_code}' --max-time 5)
   [[ "${3:-}" == "--insecure" ]] && opts+=(-k)
 
-  while ((waited < timeout)); do
+  while ((SECONDS < deadline)); do
     code="$(curl "${opts[@]}" "$url" 2>/dev/null)" || code="000"
     [[ "$code" =~ ^([23][0-9][0-9]|401|403)$ ]] && return 0
     sleep 5
-    waited=$((waited + 5))
   done
   return 1
 }
 
-# ------------------------------------------------------------------------------
 # vm_print_summary ["Label=value"]...
 # vm_next_steps <step>...
 # vm_finish [message]
-#
-# The closing block every VM script printed in its own layout. Empty values are
-# skipped, so a VM that was not started simply has no IP row.
-# ------------------------------------------------------------------------------
+# The closing block. Empty values are skipped, so a VM that was not started
+# simply has no IP row.
 _vm_summary_row() {
   [[ -n "${2:-}" ]] && echo -e "${TAB:-  }${DGN:-}${1}: ${BGN:-}${2}${CL:-}"
   return 0
@@ -397,7 +352,7 @@ _vm_summary_row() {
 
 vm_print_summary() {
   local item state="running"
-  [[ "${START_VM:-yes}" == "yes" ]] || state="stopped -- start it from the Proxmox UI"
+  [[ "${START_VM:-yes}" == "yes" ]] || state="stopped -- start it when you are ready"
 
   echo -e "\n${INFO:-}${BOLD:-}${GN:-}${APP:-VM} Summary:${CL:-}"
   _vm_summary_row "VM ID" "${VMID:-}"