#!/usr/bin/env bash
# FlashVM installer. Run once, as root:
#
#   curl -fsSL https://release.flashvmm.com/dist/flashvm/stable/install.sh | sudo bash
#
# It auto-detects the OS. On Linux it installs every shipped binary (`flash`, `flashvm`, `flashnet`, `flashpoold`) into
# /opt/flashvm/bin, installs + starts the flashpoold systemd unit,
# symlinks `flash` onto PATH, and can keep itself current from inside the binary it just installed
# (see auto-update below). On macOS (Apple Silicon) it installs a single Developer ID-signed,
# notarized `.pkg` via installer(8) — same /opt/flashvm layout — with no timer and no self-update
# (a new release is installed by re-running this). There is no second tool to fetch.
#
# ── AUTO-UPDATE IS OFF UNLESS YOU ASK FOR IT ────────────────────────────────────────────────
# This script installs **no timer** by default, and nothing on the machine will change a byte of
# FlashVM until an operator runs `flash self-update` by hand. Unattended updating is a real
# decision about a machine — on a host running long-lived VMs it is not obviously the one the
# owner wants — so it is made deliberately, once, and not by a script the owner piped into a
# shell:
#
#   curl -fsSL .../install.sh | sudo bash -s -- --enable-auto-update
#   FLASHVM_AUTOUPDATE=1 ...                       # same thing, for `curl | sudo bash`
#   sudo flash self-update --install-timer         # or turn it on later, any time
#
# `--interval 15min` sets the period; `sudo systemctl disable --now flashvm-self-update.timer`
# turns it back off. The timer's existence IS the state — there is no config key.
#
# ── WHAT IS TRUSTED, AND WHEN ───────────────────────────────────────────────────────────────
# Stated plainly rather than glossed, because the bootstrap is the one link that cannot be
# key-verified: this script and the tarball it fetches are trusted on **TLS and the URL** alone.
# `bootstrap.json` carries the tarball's sha256 and this script checks it, which catches a
# truncated or corrupted object but not a compromised bucket.
#
# **From the first `flash self-update` onward, TLS is not trusted for anything.** Every artifact
# is verified against a sha256 inside an ed25519-signed manifest, against a key compiled into
# the binary. To pin the bootstrap too, verify the tarball's sha256 against one you obtained
# out-of-band before running this.
set -euo pipefail

BASE="${FLASHVM_CHANNEL_URL:-https://release.flashvmm.com/dist/flashvm/stable}"
PREFIX="${FLASHVM_PREFIX:-/opt/flashvm}"
INTERVAL="${FLASHVM_INTERVAL:-15min}"

# Auto-update is OFF by default. `FLASHVM_AUTOUPDATE=1` exists because the documented way to run
# this is `curl | sudo bash`, which has nowhere to put an argument without `-s --`.
AUTOUPDATE="${FLASHVM_AUTOUPDATE:-0}"

die(){ echo "!! $*" >&2; exit 1; }
log(){ printf '\n\033[1m== %s\033[0m\n' "$*"; }
# render_flashpoold_unit TEMPLATE PREFIX — the shipped unit with this install's prefix. No --uplink:
# flashnet takes the default route's interface when each NAT member is created, as on macOS and
# Windows, so a route change never leaves the daemon pinned to a stale interface. ONE definition:
# the Linux release gate extracts and runs this very function (G7), so the unit a release installs
# is the unit the gate checked.
render_flashpoold_unit() {
  local esc; esc="$(printf '%s' "$2" | sed 's/[#&\\]/\\&/g')"
  sed "s#/opt/flashvm#$esc#g" "$1"
}

# ── THREE OUTCOMES, THREE STATUSES (OS-81) ──────────────────────────────────────────────────
# A failed converge is not a failed install, and it is not a clean one either. The binaries DID
# land; what did not happen is this machine reaching the published release. Those are three
# different states of a machine and the one machine-readable signal this script emits has to be
# able to tell them apart, because a CI job, a config-management run or an image build has
# nothing else to read:
#
#   0   installed, and converged to the published release.
#   1   nothing installed — every `die` above and below. The machine is as it was found.
#   3   installed, did not converge. All four binaries (and flashpoold's unit) are on the machine and usable; the
#       bundle they need is not known to be current, and may not be there at all.
#
# **3 is not 1, and that distinction is the entire point of this entry.** A caller has to be
# able to tell "I have no FlashVM" from "I have FlashVM at an unknown version" — the first wants
# the install re-run, the second wants a converge re-run and would be actively damaged by a
# re-install it does not need.
#
# **Why 3 and not 2** — the reasoning is OS-82's, one layer out: borrow a convention where one
# exists, and where none does take a number no convention has already claimed, so a reader can
# tell the cases apart WITHOUT parsing a message. There is no established code for "partially
# installed", and the low numbers are all spoken for. MEASURED on the test host: bash exits **2**
# on a syntax error in the script itself, so 2 already means "this script is broken" to anything
# that runs it; `scripts/run-tests.sh:835` uses `exit 2` for a usage error, which is this repo's
# own reading of it. **126** and **127** are `exec`'s — measured the same way, and already spent
# in this codebase at `workloads/guest-agent/src/main.rs:1253,1255`. 128+n is a signal, and 255
# is where out-of-range statuses go to be truncated. 3 is the lowest number in the 3–125 band
# that nothing has claimed.
EXIT_NOT_CONVERGED=3

# ── DISK, AND NOT BLAMING THE NETWORK FOR IT (OS-83) ────────────────────────────────────────
# Bytes free on the filesystem behind $1. $1 need not exist yet: the nearest existing ancestor
# is what `df` is asked about, which is the same filesystem unless a mount point gets created in
# between. Prints nothing and returns non-zero when `df` will not answer — every caller reads
# that as "unknown", never as "full".
avail_bytes(){
  local d="$1" kb
  while [ -n "$d" ] && [ "$d" != "/" ] && [ ! -d "$d" ]; do d="$(dirname "$d")"; done
  [ -d "$d" ] || return 1
  kb="$(df -Pk "$d" 2>/dev/null | awk 'NR==2{print $4}')"
  case "${kb:-x}" in ''|*[!0-9]*) return 1 ;; esac
  echo $(( kb * 1024 ))
}

# Whole MB, rounded, for the one place these numbers go: a message a human reads.
mb(){ echo $(( ($1 + 524288) / 1048576 )); }

# "N MB free on <path>", or an honest "free space unknown" when `df` would not say.
space_note(){
  local have
  if have="$(avail_bytes "$1")" && [ -n "$have" ]; then
    echo "$(mb "$have") MB free on $1"
  else
    echo "free space on $1 unknown"
  fi
}

# curl to a file, telling "the fetch failed" apart from "this machine could not store it".
#
# **`curl`'s exit 23 is `CURLE_WRITE_ERROR` and it means exactly one thing**: the bytes arrived
# and the LOCAL write is what failed — in practice, no room on the filesystem behind the
# destination. Reported as a fetch failure, with the URL as the only thing named, it sends the
# operator to the bucket policy, TLS, a proxy and DNS, none of which are involved; the fetch
# succeeded and the disk did not. So 23 says so, and names the path and the free space, which
# are the two facts that end the diagnosis.
#
# **Every other status keeps the caller's message, unchanged and deliberately.** No other curl
# exit is unambiguous in the same way — 18, 28 and 56 are all reachable from either side of the
# wire — and a handler that guesses at those would trade this bug for a subtler one.
fetch_to(){ # $1 url, $2 destination path, $3 the message for a genuine fetch failure
  local rc=0
  curl -fsSL "$1" -o "$2" || rc=$?
  if [ "$rc" -eq 0 ]; then return 0; fi
  if [ "$rc" -eq 23 ]; then
    die "cannot write $2 ($(space_note "$(dirname "$2")")): the download arrived and this machine could not store it. curl exit 23 is a local write failure — $1 is not the problem, the disk is."
  fi
  die "$3"
}

usage(){ cat >&2 <<'USAGE'
usage: install.sh [--enable-auto-update] [--interval <systemd time span>]

  --enable-auto-update   install and start the systemd timer that runs `flash self-update`
                         unattended. OFF BY DEFAULT: without this flag no timer is written,
                         no unit is enabled, and nothing updates this machine on its own.
                         Equivalent to FLASHVM_AUTOUPDATE=1.
  --interval SPAN        how often the timer checks (default 15min). Only meaningful with
                         --enable-auto-update.

Turning it on later needs no reinstall: `sudo flash self-update --install-timer`.
USAGE
}

while [ $# -gt 0 ]; do
  case "$1" in
    --enable-auto-update) AUTOUPDATE=1 ;;
    --interval)           [ $# -ge 2 ] || die "--interval needs a value"; INTERVAL="$2"; shift ;;
    --interval=*)         INTERVAL="${1#--interval=}" ;;
    -h|--help)            usage; exit 0 ;;
    *)                    usage; die "unknown argument $1" ;;
  esac
  shift
done

[ "$(id -u)" -eq 0 ] || die "run as root: this installs into $PREFIX"

# ── macOS (Apple Silicon) ───────────────────────────────────────────────────────────────────
# The macOS/HVF build ships as ONE Developer ID-signed, notarized, stapled .pkg (binaries + guest
# bundle together — mac/Scripts/release-macos.sh), published by `release.py publish-macos` under
# `bootstrap-macos-<arch>.json`. So the Darwin path is its own, much shorter flow: fetch the record,
# fetch the .pkg, verify its sha256, and hand it to installer(8) — Gatekeeper then makes its own
# offline check against the stapled notarization ticket. There is no tarball to unpack, no bundle to
# converge (the guest ships inside the pkg), and no timer: `flash self-update` is Linux-only, so a
# new release is installed by re-running this installer. Placed before the Linux arch-case below
# because `uname -m` is `arm64` on Apple Silicon, which that case does not (and should not) accept.
if [ "$(uname -s)" = "Darwin" ]; then
  [ "$(uname -m)" = "arm64" ] || die "the FlashVMM macOS build is Apple Silicon only — $(uname -m) is not supported"
  command -v curl >/dev/null || die "curl is required to bootstrap"
  command -v installer >/dev/null || die "installer(8) is required (it ships with macOS)"
  [ "$AUTOUPDATE" = "1" ] && echo "note: --enable-auto-update is ignored on macOS (self-update is Linux-only)" >&2
  # `arm64` (uname) maps to `aarch64` (std::env::consts::ARCH), the spelling release.py's record uses.
  REC="bootstrap-macos-aarch64.json"
  TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT

  log "fetching the macOS bootstrap record"
  fetch_to "$BASE/$REC" "$TMP/rec.json" "no $REC at $BASE — is this channel publishing a macOS build?"
  KEY=$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1]))["pkg"])' "$TMP/rec.json" 2>/dev/null \
        || sed -n 's/.*"pkg"[^"]*"\([^"]*\)".*/\1/p' "$TMP/rec.json")
  WANT=$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1]))["sha256"])' "$TMP/rec.json" 2>/dev/null \
        || sed -n 's/.*"sha256"[^"]*"\([^"]*\)".*/\1/p' "$TMP/rec.json")
  [ -n "$KEY" ] && [ -n "$WANT" ] || die "$REC is malformed"
  SIZE=$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("size",""))' "$TMP/rec.json" 2>/dev/null \
        || sed -n 's/.*"size"[^0-9]*\([0-9][0-9]*\).*/\1/p' "$TMP/rec.json")

  # Space precheck (require_space is defined further down, past the Linux flow, so inline it here
  # with the helpers defined up top). Warn-and-proceed on anything unknown; only a known-too-small
  # number stops the install. ~3x the pkg covers the download plus what installer expands under /opt.
  if [ -n "${SIZE:-}" ] && [ "$SIZE" -gt 0 ] 2>/dev/null; then
    if have="$(avail_bytes /)" && [ -n "$have" ]; then
      [ "$have" -ge $(( SIZE * 3 )) ] \
        || die "not enough free space: $(mb $(( SIZE * 3 ))) MB needed under /, $(mb "$have") MB free. Nothing has been downloaded or installed."
      echo "  space  /: $(mb "$have") MB free, $(mb $(( SIZE * 3 ))) MB needed"
    else
      echo "  space  /: free space unknown — proceeding without the precheck"
    fi
  fi

  log "fetching $KEY"
  fetch_to "$BASE/$KEY" "$TMP/flashvm.pkg" "cannot fetch $BASE/$KEY"
  GOT=$(shasum -a256 "$TMP/flashvm.pkg" | cut -d' ' -f1)
  [ "$GOT" = "$WANT" ] || die "pkg sha256 is $GOT, $REC says $WANT"
  echo "  sha256 ${GOT:0:12} verified"

  log "installing the notarized package (installer -pkg)"
  # Gatekeeper verifies the stapled Developer ID notarization here, offline. -target / places
  # /opt/flashvm/{bin,bundles/default} and the /usr/local/bin symlinks (flash, flashnet, flash-mcp,
  # flashpoold) from the pkg payload.
  installer -pkg "$TMP/flashvm.pkg" -target / >/dev/null || die "installer -pkg failed"

  for b in flashvm flash flashnet flashpoold flashhostd flash-mcp flashgpud flashnetd; do
    [ -x "$PREFIX/bin/$b" ] || die "the pkg did not install $PREFIX/bin/$b"
    "$PREFIX/bin/$b" --version </dev/null
  done
  echo
  echo "FlashVMM installed. \`flash --help\` is the manual."
  echo "  binaries   $PREFIX/bin  (flash, flashnet, flash-mcp, flashpoold, flashhostd, flashgpud, flashnetd on PATH via /usr/local/bin)"
  echo "  host       start once: cp $PREFIX/com.elysianedge.flashhostd.plist ~/Library/LaunchAgents/ && launchctl bootstrap gui/\$(id -u) ~/Library/LaunchAgents/com.elysianedge.flashhostd.plist"
  echo "  GPU pools  start once: cp $PREFIX/com.elysianedge.flashgpud.plist ~/Library/LaunchAgents/ && launchctl bootstrap gui/\$(id -u) ~/Library/LaunchAgents/com.elysianedge.flashgpud.plist"
  echo "  bundle     $PREFIX/bundles/default  (guest kernel + initramfs, shipped in the pkg)"
  echo "  networking gvproxy user-mode NAT — see \`flashnet --help\`"
  echo "  updates    manual: re-run this installer for a new release (self-update is Linux-only)"
  exit 0
fi

[ "$(uname -s)" = "Linux" ] || die "FlashVM supports Linux and macOS (Apple Silicon) only — not $(uname -s)"
# `uname -m`'s own vocabulary (`x86_64`/`aarch64`) — the same one the manifest's `arch` field and
# `HOST_ARCH` in `flash-cli/selfupdate.rs` already standardized on (OS-126,
# how-to-publish-flashvm.md §13), so this needs no translation table either. Named explicitly
# rather than falling through to a default: an unrecognised arch is a real "this doesn't exist
# yet" refusal, not a silent attempt at bytes built for a different machine.
case "$(uname -m)" in
  x86_64)  BOOTSTRAP_RECORD="bootstrap.json" ;;
  aarch64) BOOTSTRAP_RECORD="bootstrap-aarch64.json" ;;
  *)       die "FlashVM has no build for $(uname -m) — only x86_64 and aarch64 are published" ;;
esac
command -v curl >/dev/null || die "curl is required to bootstrap (it is NOT required afterwards)"

TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT

log "fetching the bootstrap record"
fetch_to "$BASE/$BOOTSTRAP_RECORD" "$TMP/bootstrap.json" "no $BOOTSTRAP_RECORD at $BASE"
KEY=$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1]))["tarball"])' "$TMP/bootstrap.json" 2>/dev/null \
      || sed -n 's/.*"tarball"[^"]*"\([^"]*\)".*/\1/p' "$TMP/bootstrap.json")
WANT=$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1]))["sha256"])' "$TMP/bootstrap.json" 2>/dev/null \
      || sed -n 's/.*"sha256"[^"]*"\([^"]*\)".*/\1/p' "$TMP/bootstrap.json")
[ -n "$KEY" ] && [ -n "$WANT" ] || die "bootstrap.json is malformed"
SIZE=$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("size",""))' "$TMP/bootstrap.json" 2>/dev/null \
      || sed -n 's/.*"size"[^0-9]*\([0-9][0-9]*\).*/\1/p' "$TMP/bootstrap.json")

# ── WILL IT FIT? ASKED BEFORE THE DOWNLOAD, NOT AFTER IT (OS-83) ────────────────────────────
# `bootstrap.json` carries the tarball's byte size, so the one question worth asking about a
# disk can be answered before spending 5 MB of it. An installer that fills the filesystem and
# *then* reports the failure has done the damage and named the wrong cause; the cost of asking
# first is one `df`, and what it buys is the number the operator needs — how much is wanted and
# how much is there.
#
# **The multipliers are measured, not guessed.** For 0.1.12 the tarball is 4 939 538 bytes and
# the tree it unpacks to is 10 609 241 — 2.15x — and BOTH are under $TMP at once, because the
# tarball is not removed before `tar -xzf`. Peak under $TMP is therefore ~3.15x the tarball, and
# 4x is that with headroom. $PREFIX takes the unpacked binaries alone, which 3x covers the same
# way.
#
# **The first bundle is NOT covered here, and saying so matters more than the check does.**
# `bootstrap.json` carries the tarball's size and nothing else; the bundle's own file sizes live
# in the signed manifest that `flash self-update` fetches further down, after this precheck has
# run and long after it could have used them. So passing here means *the bootstrap* fits — not
# that this machine has room for a release.
#
# **It warns and proceeds on anything it cannot establish.** A `bootstrap.json` with no `size`,
# a `df` that will not answer, a path that will not resolve: none of those are evidence of a
# full disk, and an installer that refuses to run because it could not read `df` is worse than
# one that tries. Only a number that is known AND too small stops the install.
require_space(){ # $1 path, $2 bytes needed, $3 what for
  local have
  if ! have="$(avail_bytes "$1")" || [ -z "$have" ]; then
    echo "  space  $1: free space unknown — proceeding without the precheck"
    return 0
  fi
  if [ "$have" -lt "$2" ]; then
    die "not enough free space for $3: $(mb "$2") MB needed under $1, $(mb "$have") MB free. Nothing has been downloaded or installed — free some space and run this again."
  fi
  echo "  space  $1: $(mb "$have") MB free, $(mb "$2") MB needed for $3"
}

log "checking free space"
if [ -n "${SIZE:-}" ] && [ "$SIZE" -gt 0 ] 2>/dev/null; then
  require_space "$TMP"    $(( SIZE * 4 )) "the download and unpack"
  require_space "$PREFIX" $(( SIZE * 3 )) "the installed binaries"
else
  echo "  space  bootstrap.json carries no tarball size — proceeding without the precheck"
fi

log "fetching $KEY"
fetch_to "$BASE/$KEY" "$TMP/flashvm.tar.gz" "cannot fetch $BASE/$KEY"
GOT=$(sha256sum "$TMP/flashvm.tar.gz" | cut -d' ' -f1)
[ "$GOT" = "$WANT" ] || die "tarball sha256 is $GOT, bootstrap.json says $WANT"
echo "  sha256 ${GOT:0:12} verified"

# Legacy layout (releases up to 0.1.79 installed the per-VM process as `flashvmm` under
# /opt/flashvmm). Move its state, stop and drop units that point into it, remove it. Units that
# share a name with ours are re-rendered below because their text is deleted here. Once only.
OLD=/opt/flashvmm
if [ -d "$OLD" ] && [ "$OLD" != "$PREFIX" ]; then
  log "replacing the old $OLD layout"
  for u in /etc/systemd/system/*.service /etc/systemd/system/*.timer; do
    [ -f "$u" ] && grep -q "$OLD" "$u" || continue
    systemctl disable --now "$(basename "$u")" >/dev/null 2>&1 || true
    rm -f "$u"
  done
  command -v systemctl >/dev/null 2>&1 && systemctl daemon-reload >/dev/null 2>&1 || true
  if [ -d /var/lib/flashvmm ] && [ ! -e /var/lib/flashvm ]; then mv /var/lib/flashvmm /var/lib/flashvm; fi
  rm -rf /var/lib/flashvmm
  for l in /usr/local/bin/*; do
    [ -L "$l" ] && case "$(readlink "$l")" in "$OLD"/*) rm -f "$l" ;; esac
  done
  rm -rf "$OLD"
fi

log "installing into $PREFIX/bin"
mkdir -p "$PREFIX/bin" "$PREFIX/bundles" /var/lib/flashvm
tar -xzf "$TMP/flashvm.tar.gz" -C "$TMP"
SRC="$(dirname "$(find "$TMP" -type f -name flashvm -path '*/bin/*' | head -1)")"
[ -n "$SRC" ] || die "the tarball has no bin/flashvm"
# EVERY binary the release ships — a first install must not depend on the converge below to
# bring the rest (it used to install only flash + flashvm; flashnet/flashpoold then existed only
# if `self-update` succeeded, so a failed converge left a machine with no networking and no pools).
for b in flashvm flash flashnet flashpoold flashhostd flash-mcp flashgpud flashnetd; do
  [ -f "$SRC/$b" ] || die "the tarball has no bin/$b"
done
for b in flashvm flash flashnet flashpoold flashhostd flash-mcp flashgpud flashnetd; do
  # A re-install is a new inode: carry flashnet's operator-granted file capabilities
  # (`setcap cap_net_admin,...`) across it, or non-root `flashnet -- flash run` breaks.
  CAPS=""
  if [ -f "$PREFIX/bin/$b" ] && command -v getcap >/dev/null 2>&1; then
    # Everything after the path (and the old libcap's " = "): multi-clause caps stay whole.
    CAPS="$( { getcap "$PREFIX/bin/$b" 2>/dev/null || true; } | head -1)"
    CAPS="${CAPS#"$PREFIX/bin/$b"}"; CAPS="${CAPS# }"; CAPS="${CAPS#= }"
  fi
  install -m 0755 "$SRC/$b" "$PREFIX/bin/.$b.tmp"
  [ -n "$CAPS" ] && { setcap "$CAPS" "$PREFIX/bin/.$b.tmp" 2>/dev/null || echo "  note: could not re-apply '$CAPS' to $b" >&2; }
  mv -f "$PREFIX/bin/.$b.tmp" "$PREFIX/bin/$b"
done
# `flash` and `flashvm` are SIBLINGS, which is what lets `flash` find the VMM with no `--vmm`
# flag and no PATH entry (resolve_vmm in flash-cli). The symlinks below put the four commands a
# person types on PATH — the same four as on macOS and Windows (whose install dir is on PATH) — so
# `sudo flashnet …` works as documented (sudo's secure_path has /usr/local/bin, not $PREFIX/bin).
# Nothing depends on them, and current_exe() resolves through them.
for b in flash flashnet flash-mcp flashpoold flashhostd flashgpud flashnetd; do
  [ -x "$PREFIX/bin/$b" ] || continue
  # Replace only a missing path or our own link; a file someone else put there is theirs.
  if [ -e "/usr/local/bin/$b" ] && [ ! -L "/usr/local/bin/$b" ]; then
    echo "  note: /usr/local/bin/$b exists and is not a link — left alone; $b is at $PREFIX/bin/$b" >&2
  else
    ln -sfn "$PREFIX/bin/$b" "/usr/local/bin/$b"
  fi
done
# The FlashVMM License, beside the binaries (the text is built into `flash`, which prints it).
"$PREFIX/bin/flash" license > "$PREFIX/LICENSE" 2>/dev/null || true
# Docs ship with the binary — a licensee has no other manual.
for f in openapi.yaml VERSIONING.md README.md; do
  [ -f "$SRC/../$f" ] && install -m 0644 "$SRC/../$f" "$PREFIX/$f"
done

# The GPU-pool engine (gpu-pool-plan.md): bin/engine/ — swapped in whole, never merged file by file
# (a half-old engine directory would mix libraries from two builds). Stamped with the release
# version so `flash self-update` knows which engine this machine has.
if [ -d "$SRC/engine" ]; then
  [ -x "$SRC/engine/llama-server" ] || die "the tarball's bin/engine has no llama-server"
  ENGINE_VER="$("$PREFIX/bin/flash" --version </dev/null | awk '{print $2}')"
  echo "$ENGINE_VER" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$' || die "cannot read this release's version to stamp the engine with (got '$ENGINE_VER')"
  rm -rf "$PREFIX/bin/.engine.new" "$PREFIX/bin/.engine.old"
  cp -a "$SRC/engine" "$PREFIX/bin/.engine.new"
  # Root's, not the build host's: flashgpud runs it as root, so nobody else may be able to write it.
  chown -R 0:0 "$PREFIX/bin/.engine.new"
  chmod -R go-w "$PREFIX/bin/.engine.new"
  echo "$ENGINE_VER" > "$PREFIX/bin/.engine.new/.flashvm-version"
  [ -d "$PREFIX/bin/engine" ] && mv "$PREFIX/bin/engine" "$PREFIX/bin/.engine.old"
  mv "$PREFIX/bin/.engine.new" "$PREFIX/bin/engine"
  rm -rf "$PREFIX/bin/.engine.old"
fi

for f in flashpoold-openapi.yaml flashhostd-openapi.yaml flashgpud-openapi.yaml; do
  [ -f "$SRC/../$f" ] && install -m 0644 "$SRC/../$f" "$PREFIX/$f"
done
# `flash demo`'s in-VM agent (the demo itself is built into `flash`). The old script goes.
if [ -f "$SRC/../demo/flash-agent" ]; then
  install -d -m 0755 "$PREFIX/demo" && install -m 0755 "$SRC/../demo/flash-agent" "$PREFIX/demo/flash-agent"
  rm -f "$PREFIX/demo/flashvm-demo.sh"
fi

# flashhostd's unit (the host daemon, flashhostd-work-order.md): enabled and started before
# flashpoold (pool members ask it whether they fit). An existing unit is the operator's: its text
# is left alone and a running daemon is restarted onto the binary just installed. Never aborts.
HUNIT=/etc/systemd/system/flashhostd.service
if [ -f "$SRC/../flashhostd.service" ] && command -v systemctl >/dev/null 2>&1 && [ -d /run/systemd/system ]; then
  if [ -f "$HUNIT" ]; then
    systemctl try-restart flashhostd.service >/dev/null 2>&1 || true
    HOST_STATE="unit kept as is ($(systemctl is-active flashhostd.service 2>/dev/null || true))"
  elif render_flashpoold_unit "$SRC/../flashhostd.service" "$PREFIX" > "$HUNIT.tmp" && mv -f "$HUNIT.tmp" "$HUNIT" \
       && systemctl daemon-reload >/dev/null 2>&1; then
    if systemctl enable --now flashhostd.service >/dev/null 2>&1 && sleep 1 && systemctl is-active --quiet flashhostd.service; then
      HOST_STATE="enabled + running"
    else
      HOST_STATE="installed but NOT running — see: journalctl -u flashhostd"
    fi
  else
    rm -f "$HUNIT.tmp"
    HOST_STATE="could not install $HUNIT — run $PREFIX/bin/flashhostd yourself (as root)"
  fi
else
  HOST_STATE="no systemd — run $PREFIX/bin/flashhostd yourself (as root)"
fi

# flashpoold's unit. An existing unit is the operator's: its text is left
# alone, but a running daemon is restarted so it runs the binary just installed (a same-version
# converge below changes nothing and would not restart it). Nothing in this block may abort the
# script: the binaries are already installed, so exit 1 ("nothing installed") would be a lie.
UNIT=/etc/systemd/system/flashpoold.service
if [ -f "$SRC/../flashpoold.service" ] && command -v systemctl >/dev/null 2>&1 && [ -d /run/systemd/system ]; then
  # A unit an older install wrote with no default route (inactive, never enabled, still the old
  # shipped `--uplink eth0`) is ours to redo: the new unit needs no uplink. Anything else is the
  # operator's.
  if [ -f "$UNIT" ] && ! systemctl is-enabled --quiet flashpoold.service 2>/dev/null \
     && ! systemctl is-active --quiet flashpoold.service 2>/dev/null \
     && grep -q -- '--uplink eth0' "$UNIT" && ! ip -o link show eth0 >/dev/null 2>&1; then
    rm -f "$UNIT"
  fi
  if [ -f "$UNIT" ]; then
    systemctl try-restart flashpoold.service >/dev/null 2>&1 || true
    POOL_STATE="unit kept as is ($(systemctl is-active flashpoold.service 2>/dev/null || true))"
    systemctl is-active --quiet flashpoold.service 2>/dev/null \
      || POOL_STATE="$POOL_STATE — check $UNIT, then: systemctl enable --now flashpoold"
  else
    if render_flashpoold_unit "$SRC/../flashpoold.service" "$PREFIX" > "$UNIT.tmp" && mv -f "$UNIT.tmp" "$UNIT" \
       && systemctl daemon-reload >/dev/null 2>&1; then
      if systemctl enable --now flashpoold.service >/dev/null 2>&1 && sleep 2 \
           && systemctl is-active --quiet flashpoold.service; then
        POOL_STATE="enabled + running (NAT members ride the default route)"
      else
        POOL_STATE="installed but NOT running — see: journalctl -u flashpoold"
      fi
    else
      rm -f "$UNIT.tmp"
      POOL_STATE="could not install $UNIT — run $PREFIX/bin/flashpoold yourself"
    fi
  fi
else
  POOL_STATE="no systemd — run $PREFIX/bin/flashpoold yourself"
fi

# flashnetd's unit (NIC pools, nic-pool-work-order.md): enabled and started like flashpoold. An
# existing unit is the operator's: its text is left alone and a running daemon is restarted onto
# the binary just installed. Never aborts the script.
NUNIT=/etc/systemd/system/flashnetd.service
if [ -f "$SRC/../flashnetd.service" ] && command -v systemctl >/dev/null 2>&1 && [ -d /run/systemd/system ]; then
  if [ -f "$NUNIT" ]; then
    systemctl try-restart flashnetd.service >/dev/null 2>&1 || true
    NETD_STATE="unit kept as is ($(systemctl is-active flashnetd.service 2>/dev/null || true))"
  elif render_flashpoold_unit "$SRC/../flashnetd.service" "$PREFIX" > "$NUNIT.tmp" && mv -f "$NUNIT.tmp" "$NUNIT" \
       && systemctl daemon-reload >/dev/null 2>&1; then
    if systemctl enable --now flashnetd.service >/dev/null 2>&1 && sleep 1 && systemctl is-active --quiet flashnetd.service; then
      NETD_STATE="enabled + running"
    else
      NETD_STATE="installed but NOT running — see: journalctl -u flashnetd"
    fi
  else
    rm -f "$NUNIT.tmp"
    NETD_STATE="could not install $NUNIT — run $PREFIX/bin/flashnetd yourself (as root)"
  fi
else
  NETD_STATE="no systemd — run $PREFIX/bin/flashnetd yourself (as root)"
fi

# flashgpud's unit — installed always, ENABLED only when the engine sees a GPU (it serves a guest
# port; a host with no GPU has nothing for it to do). An existing unit is the operator's: a running
# daemon is restarted onto the new binary, its text left alone. Nothing here may abort the script.
GUNIT=/etc/systemd/system/flashgpud.service
if [ -f "$SRC/../flashgpud.service" ] && command -v systemctl >/dev/null 2>&1 && [ -d /run/systemd/system ]; then
  if [ -f "$GUNIT" ]; then
    systemctl try-restart flashgpud.service >/dev/null 2>&1 || true
    GPU_STATE="unit kept as is ($(systemctl is-active flashgpud.service 2>/dev/null || true))"
  elif render_flashpoold_unit "$SRC/../flashgpud.service" "$PREFIX" > "$GUNIT.tmp" && mv -f "$GUNIT.tmp" "$GUNIT" \
       && systemctl daemon-reload >/dev/null 2>&1; then
    GPUS="$(timeout 15 "$PREFIX/bin/engine/llama-server" --list-devices 2>/dev/null | grep -E '^[[:space:]]+[A-Za-z]+[0-9]+: ' || true)"
    if [ -z "$GPUS" ]; then
      GPU_STATE="installed, not enabled — the engine sees no GPU here (needs a Vulkan driver: libvulkan1 + your GPU's driver)"
    elif systemctl enable --now flashgpud.service >/dev/null 2>&1 && sleep 2 && systemctl is-active --quiet flashgpud.service; then
      GPU_STATE="enabled + running on: $(echo "$GPUS" | head -1 | sed 's/^[[:space:]]*//')"
    else
      GPU_STATE="installed but NOT running — see: journalctl -u flashgpud"
    fi
  else
    rm -f "$GUNIT.tmp"
    GPU_STATE="could not install $GUNIT — run $PREFIX/bin/flashgpud yourself"
  fi
else
  GPU_STATE="no systemd — run $PREFIX/bin/flashgpud yourself"
fi

for b in flashvm flash flashnet flashpoold flashhostd flash-mcp flashgpud flashnetd; do "$PREFIX/bin/$b" --version </dev/null; done
echo "  flashhostd $HOST_STATE"
echo "  flashpoold $POOL_STATE"
echo "  flashgpud $GPU_STATE"
echo "  flashnetd $NETD_STATE"

"$PREFIX/bin/flash" self-update --show-trust

log "converging to the published release"
# **The status is captured, not discarded (OS-81).** The `||` that used to be here consumed the
# failure so `set -euo pipefail` never saw it, and control fell through to a banner that said
# `FlashVM installed.` and exited 0 for a machine with no bundle. It still must not `die` — the
# install itself succeeded and undoing it would throw away work that is fine — so the fact is
# carried to the banner instead, where it can be reported and then charged to the exit status.
CONVERGED=1
CONVERGE_RC=0
"$PREFIX/bin/flash" self-update || { CONVERGE_RC=$?; CONVERGED=0; }
if [ "$CONVERGED" = 0 ]; then
  # On stderr, and immediately, because the converge's own `Error:` line is on stderr too: on a
  # `curl | sudo bash` the two streams are buffered differently and a note put on stdout drifts
  # away from the failure it is about. MEASURED — in the reproduction of this bug the `Error:`
  # line surfaced three lines BELOW the consolation message that was meant to explain it.
  echo "!! the first converge failed: \`flash self-update\` exited $CONVERGE_RC. The binaries are installed; this machine is NOT on the published release. This is recoverable — see below." >&2
fi

# **The converge runs FIRST and the timer is armed after it, and the order is the fix for OS-80.**
# `systemctl enable --now` on a monotonic timer whose `OnBootSec=2min` elapse point is already in
# the past — which is every machine that has been up for three minutes — does not wait two
# minutes. It triggers the service *at arm time*. Measured on the c8i: the timer started at
# 00:17:09.234 and the service it triggers at 00:17:09.242, eight milliseconds later, while this
# script was still running. With the arm above the converge, this installer put two `flash
# self-update` processes on the machine itself, and the foreground one died on a staging directory
# the other had deleted.
#
# Arming after the converge is what stops the installer racing *itself*: by the time the unit is
# loaded there is no foreground converge left to collide with, and the tick it fires immediately
# lands on a machine that is already converged, so it is a no-op. The *general* case — a tick over
# a hand-run, two operators, a config-management pass — is not an ordering problem and is not
# fixed here; it is fixed by the converge lock in `selfupdate.rs`, which this ordering does not
# replace and is not a substitute for.
#
# **The installed end state is unchanged.** `--install-timer` still runs `systemctl enable --now`
# and the unit is still enabled, started and scheduled when auto-update was asked for. Only the
# moment it is armed moved.
#
# **The timer is the opt-in, and it is the whole opt-in.** Its presence is the machine's entire
# auto-update state, so the default path below writes nothing and prints the one line that turns
# it on. A machine that was never asked stays exactly as the operator left it.
TIMER_RC=0
if [ "$AUTOUPDATE" = "1" ]; then
  log "enabling auto-update (you asked for it)"
  # OS-105: captured the same way OS-81 captures the converge's status, and for the same
  # reason — an unhandled failure here used to abort the WHOLE script under `set -e`, printing
  # no banner at all and exiting 1, the code this file reserves for "nothing was installed".
  # The binaries and the bundle can both be down and converged with only the timer missing, and
  # 1 told a caller to re-install a machine that mostly did not need it.
  "$PREFIX/bin/flash" self-update --install-timer --interval "$INTERVAL" || TIMER_RC=$?
  if [ "$TIMER_RC" != 0 ]; then
    echo "!! enabling the timer failed: \`flash self-update --install-timer\` exited $TIMER_RC. The binaries (and bundle, if converged) are installed; only auto-update is not armed. This is recoverable — see below." >&2
  fi
else
  log "auto-update: OFF (default)"
  echo "  No timer was installed and nothing will update this machine on its own."
  echo "  To turn it on:  sudo $PREFIX/bin/flash self-update --install-timer --interval $INTERVAL"
fi

echo
# **The converged banner is byte-for-byte what it always was**, deliberately: a healthy install
# is the overwhelmingly common case, its output is what the docs quote and what people grep for,
# and this entry is not a reason to move it. Everything that changed is on the other branch.
if [ "$CONVERGED" = 1 ] && [ "$TIMER_RC" = 0 ]; then
  echo "FlashVM installed. \`flash --help\` is the manual."
  echo "  binaries  $PREFIX/bin"
  echo "  bundles   $PREFIX/bundles/current   (after the first bundle lands)"
  if [ "$AUTOUPDATE" = "1" ]; then
    echo "  updates   automatic, every $INTERVAL — systemctl list-timers flashvm-self-update.timer"
  else
    echo "  updates   manual: run \`sudo flash self-update\`  (auto-update is off; --enable-auto-update turns it on)"
  fi
  exit 0
fi

# ── INSTALLED, NOT CONVERGED — OR CONVERGED BUT THE TIMER DID NOT ARM (OS-105) ──────────────
# Says what landed and what did not, in that order, because both halves are true and an operator
# who is told only one of them will act on the wrong one.
if [ "$CONVERGED" = 1 ]; then
  # The converge succeeded; only the timer failed. A different headline on purpose — this
  # machine DID reach the published release, and saying otherwise would send an operator
  # chasing the wrong half.
  echo "FlashVM installed and converged, but auto-update could not be armed."
else
  echo "FlashVM is INSTALLED but this machine did NOT reach the published release."
fi
echo "  installed  $PREFIX/bin — \`flash --help\` is the manual, and both binaries work"
# What is in `bundles` is CHECKED and not assumed. On a first install there is nothing there and
# no VM can boot; on a re-install over a working machine the previous bundle is untouched and
# still bootable — it simply is not known to be the published one. Asserting the first shape on a
# machine in the second would be this bug's own mistake in a new place: a confident sentence
# about a state nobody looked at.
if [ "$CONVERGED" = 1 ]; then
  echo "  bundles    $PREFIX/bundles/current — converged to the published release"
elif [ -e "$PREFIX/bundles/current" ]; then
  echo "  kept       $PREFIX/bundles/current — the bundle that was already here is untouched,"
  echo "             and is NOT known to be the published one"
else
  echo "  MISSING    a bundle. $PREFIX/bundles is empty, so no VM can boot on this machine yet"
fi
if [ "$CONVERGED" = 0 ]; then
  echo "  failed     \`flash self-update\` exited $CONVERGE_RC — its error is above, on stderr"
fi
if [ "$TIMER_RC" != 0 ]; then
  echo "  failed     \`flash self-update --install-timer\` exited $TIMER_RC — its error is above, on stderr"
fi
if [ "$AUTOUPDATE" = "1" ] && [ "$TIMER_RC" = 0 ]; then
  echo "  updates   automatic, every $INTERVAL — the timer is armed and will retry on its own"
elif [ "$AUTOUPDATE" = "1" ]; then
  echo "  updates   NOT armed — \`--install-timer\` failed above; retry: sudo $PREFIX/bin/flash self-update --install-timer --interval $INTERVAL"
else
  echo "  updates   manual: run \`sudo $PREFIX/bin/flash self-update\`  (auto-update is off)"
fi
echo
# **The reassurance stays, because it is true**: nothing was undone, nothing needs cleaning up,
# and one command finishes the job. What changes is that the exit status stops contradicting it.
if [ "$CONVERGED" = 1 ]; then
  # OS-105: the converge already succeeded — telling an operator to re-run `self-update` here
  # would be asking them to redo the one thing that worked. Only the timer needs a retry.
  echo "  Nothing has been undone and nothing needs to be: this machine IS on the published release."
  echo "  Only the timer needs a retry, and the command for it is above. Re-running the installer is not needed."
else
  echo "  Nothing has been undone and nothing needs to be: run \`sudo $PREFIX/bin/flash self-update\`"
  echo "  again when convenient and this machine is finished. Re-running the installer is not needed."
fi
echo "  Exiting $EXIT_NOT_CONVERGED, which is neither 0 (this machine is not fully done)"
echo "  nor 1 (which would mean nothing was installed — the binaries above are real)."
exit "$EXIT_NOT_CONVERGED"
