omakit 0.5.0 → 0.6.1

package/tools/lab/inspect.mjs

@@ -0,0 +1,240 @@
+// `omakit lab inspect`, and the lab lines of `omakit doctor`: what the pin
+// advertises, what is on disk, whether it was verified, what the host is
+// missing, and what each missing thing costs. Read-only: no directory is
+// created, no file is written, nothing is fetched. `--verify` re-hashes
+// the ISO and re-checks the signature now instead of reporting the record.
+
+import { existsSync, readdirSync, statSync } from "node:fs"
+import { join } from "node:path"
+import { LAB_DIR, bytesBoth, durationWords, labPin } from "./pin.mjs"
+import { allocatedBytes, labLayout, readJson } from "./paths.mjs"
+import { BUILD_COMMANDS, VERIFY_COMMANDS, freeBytesAt, probeCommands, probeRunHost } from "./host.mjs"
+import { judgeRelease, sha256File } from "./verify.mjs"
+import { qmpAlive } from "./qemu.mjs"
+
+/** The names the base directory holds; a manifest names the same. */
+export const BASE_FILES = Object.freeze({
+  disk: "base.qcow2",
+  vars: "firmware-vars.template",
+  key: "id_ed25519",
+  publicKey: "id_ed25519.pub",
+  manifest: "manifest.json",
+})
+
+/** The verified ISO's place under downloads: by digest, so a second release never shares a directory with the first. */
+export function downloadDir(layout, pin = labPin()) {
+  return join(layout.downloads, pin.release.sha256)
+}
+
+/**
+ * The ISO on disk against its verification record. The record is what
+ * `setup` wrote after the digest and the signature passed; the file is
+ * held to the record by size and mtime, which is what can be read in a
+ * millisecond, and `--verify` is the five-second re-hash.
+ */
+export function inspectDownload(layout, pin = labPin(), { verify = false, stagingRoot = layout.staging, onProgress } = {}) {
+  const dir = downloadDir(layout, pin)
+  const iso = join(dir, pin.release.fileName)
+  const out = { dir, iso, present: false, bytes: null, partial: null, record: readJson(join(dir, "verified.json")), verified: false, reason: null, sidecars: { checksum: existsSync(`${iso}.sha256`), signature: existsSync(`${iso}.sig`) } }
+  const part = `${iso}.part`
+  if (existsSync(part)) out.partial = statSync(part).size
+  if (!existsSync(iso)) {
+    out.reason = out.partial !== null ? `not there; a partial download of ${out.partial.toLocaleString("en-US")} of ${pin.release.bytes.toLocaleString("en-US")} B is waiting to resume` : "not there"
+    return out
+  }
+  const st = statSync(iso)
+  out.present = true
+  out.bytes = st.size
+  if (verify) {
+    const judged = judgeRelease({ file: iso, signature: out.sidecars.signature ? `${iso}.sig` : null, checksum: out.sidecars.checksum ? `${iso}.sha256` : null, pin, stagingRoot, onProgress })
+    out.verified = judged.ok
+    out.reason = judged.ok ? `verified now: ${judged.reason}` : `not verified: ${judged.reason}`
+    out.judged = judged
+    return out
+  }
+  if (!out.record) {
+    out.reason = `${st.size.toLocaleString("en-US")} B on disk with no verification record; \`omakit lab setup\` verifies it, or \`omakit lab inspect --verify\` checks it now`
+    return out
+  }
+  const same = out.record.bytes === st.size && out.record.sha256 === pin.release.sha256 && Math.abs(Number(out.record.mtimeMs) - st.mtimeMs) < 1
+  out.verified = same
+  out.reason = same
+    ? `verified ${out.record.verifiedAt}: sha256 ${out.record.sha256}, signed by ${out.record.fingerprint}; the file's size and mtime still match that record`
+    : `the file changed since the record of ${out.record.verifiedAt} (${out.record.bytes === st.size ? "same size, different mtime" : `${st.size.toLocaleString("en-US")} B now, ${Number(out.record.bytes).toLocaleString("en-US")} B then`}); \`omakit lab setup\` verifies it again`
+  return out
+}
+
+/**
+ * The base: missing, ready, mismatch (a base of another release than the
+ * pin), or invalid (files without a complete manifest, or a disk whose
+ * size is not the recorded one). Never booted here. `allocatedBytes` is
+ * `du -B1` over the directory, the figure prune will recover.
+ */
+export function inspectBase(layout, pin = labPin()) {
+  const dir = layout.base
+  const out = { dir, state: "missing", reason: "no base; run `omakit lab setup`", manifest: null, allocatedBytes: 0, disk: join(dir, BASE_FILES.disk) }
+  if (!existsSync(dir)) return out
+  out.allocatedBytes = allocatedBytes(dir)
+  const manifest = readJson(join(dir, BASE_FILES.manifest))
+  const diskThere = existsSync(out.disk)
+  if (!manifest || manifest.state !== "ready" || !manifest.release || !manifest.guest || !manifest.disk) {
+    out.state = "invalid"
+    out.reason = diskThere ? `${BASE_FILES.disk} is there (${bytesBoth(out.allocatedBytes)}) but ${BASE_FILES.manifest} is ${manifest ? "incomplete" : "missing"}; it will not be booted` : `a base directory with no disk and ${manifest ? "an incomplete" : "no"} manifest; \`omakit lab prune\` removes it`
+    return out
+  }
+  out.manifest = manifest
+  if (!diskThere) {
+    out.state = "invalid"
+    out.reason = `the manifest names ${BASE_FILES.disk} and it is not there; it will not be booted`
+    return out
+  }
+  const size = statSync(out.disk).size
+  if (size !== manifest.disk.bytes) {
+    out.state = "invalid"
+    out.reason = `${BASE_FILES.disk} is ${size.toLocaleString("en-US")} B and the manifest recorded ${Number(manifest.disk.bytes).toLocaleString("en-US")} B; it will not be booted`
+    return out
+  }
+  for (const name of [BASE_FILES.vars, BASE_FILES.key]) {
+    if (!existsSync(join(dir, name))) {
+      out.state = "invalid"
+      out.reason = `${name} is missing from the base directory; it will not be booted`
+      return out
+    }
+  }
+  if (manifest.release.sha256 !== pin.release.sha256 || manifest.guest.version !== pin.release.expectedGuestVersion) {
+    out.state = "mismatch"
+    out.reason = `cached Omarchy ${manifest.release.name} (guest ${manifest.guest.version}, iso ${manifest.release.sha256}); required ${pin.release.name} (guest ${pin.release.expectedGuestVersion}, iso ${pin.release.sha256}); \`omakit lab setup\` replaces it`
+    return out
+  }
+  out.state = "ready"
+  out.reason = `Omarchy ${manifest.release.name}, guest omarchy ${manifest.guest.version}; ${bytesBoth(out.allocatedBytes)}; created ${manifest.createdAt}`
+  return out
+}
+
+/**
+ * The toolchain: the omarchy-iso checkout `setup --toolchain` recorded,
+ * whose harness must hash to the pinned patched digest before setup runs
+ * it. What is checked is the file, not git state: a harness that hashes
+ * to the pin is the pinned commit with the patch applied, whatever else
+ * the checkout holds.
+ */
+export function inspectToolchain(layout, pin = labPin()) {
+  const record = readJson(layout.toolchain)
+  const out = { record, dir: record?.dir || null, harness: null, sha256: null, state: "missing", reason: null }
+  if (!record?.dir) {
+    out.reason = "no toolchain recorded; `omakit lab setup --toolchain <omarchy-iso checkout>` records one"
+    return out
+  }
+  out.harness = join(record.dir, pin.toolchain.harness)
+  if (!existsSync(out.harness)) {
+    out.reason = `${out.harness} is not there (the recorded checkout moved or was removed)`
+    return out
+  }
+  out.sha256 = sha256File(out.harness).sha256
+  if (out.sha256 === pin.toolchain.patchedHarnessSha256) {
+    out.state = "ready"
+    out.reason = `${out.harness} hashes to the pinned patched harness (omarchy-iso ${pin.toolchain.commit.slice(0, 12)} with ${pin.toolchain.patch})`
+  } else if (out.sha256 === pin.toolchain.upstreamHarnessSha256) {
+    out.state = "unpatched"
+    out.reason = `${out.harness} is the upstream harness at ${pin.toolchain.commit.slice(0, 12)} without the patch; \`git -C ${record.dir} apply ${join(LAB_DIR, pin.toolchain.patch)}\``
+  } else {
+    out.state = "unknown"
+    out.reason = `${out.harness} hashes to ${out.sha256}, neither the pinned patched harness nor the upstream one at ${pin.toolchain.commit.slice(0, 12)}`
+  }
+  return out
+}
+
+/**
+ * The one command that prepares a toolchain checkout, printed whole so it
+ * can be run as it stands. `dir` is under the resolved lab cache: with
+ * XDG_CACHE_HOME set, the remedy names that root, not ~/.cache (measured
+ * on 2026-09-19 by a first user under XDG_CACHE_HOME=/tmp/empty-cache,
+ * whose `lab inspect` printed clone and setup commands into ~/.cache;
+ * docs/evidence/ux/2026-09-19-first-user-test.json, finding 6).
+ */
+export function toolchainCommand(pin = labPin(), dir = join(labLayout().cache, "toolchain/omarchy-iso")) {
+  return `git clone ${pin.toolchain.repository} ${dir} && git -C ${dir} checkout --detach ${pin.toolchain.commit} && git -C ${dir} apply ${join(LAB_DIR, pin.toolchain.patch)} && omakit lab setup --toolchain ${dir}`
+}
+
+/** Staging directories, each with whether a QEMU still answers on its socket (the cross-namespace liveness question). */
+export async function inspectStaging(layout) {
+  if (!existsSync(layout.staging)) return []
+  const entries = []
+  for (const name of readdirSync(layout.staging).sort()) {
+    const dir = join(layout.staging, name)
+    let st
+    try {
+      st = statSync(dir)
+    } catch {
+      continue
+    }
+    if (!st.isDirectory()) continue
+    const socket = join(dir, "qmp.sock")
+    const alive = existsSync(socket) ? (await qmpAlive(socket)).alive : false
+    entries.push({ name, dir, allocatedBytes: allocatedBytes(dir), alive, socket: existsSync(socket) ? socket : null })
+  }
+  return entries
+}
+
+/** The lock: a directory with a record of the run holding it, and whether that run's QEMU still answers. */
+export async function inspectLock(layout) {
+  const record = readJson(join(layout.lock, "holder.json"))
+  if (!existsSync(layout.lock)) return { held: false, record: null, alive: false }
+  const alive = record?.qmpSocket ? (await qmpAlive(record.qmpSocket)).alive : false
+  let pidAlive = false
+  try {
+    if (record?.pid) {
+      process.kill(record.pid, 0)
+      pidAlive = true
+    }
+  } catch {
+    pidAlive = false
+  }
+  return { held: true, record, alive: alive || pidAlive, qemuAnswers: alive, holderPidAlive: pidAlive }
+}
+
+/**
+ * Everything `inspect` and `doctor` print, as one document. `host` is the
+ * run probes plus what acquisition and a build need; `missing` is the list
+ * of what stands between this host and a run, each with its cost and the
+ * one command.
+ */
+export async function inspectLab({ env = process.env, pin = labPin(), verify = false, onProgress, run } = {}) {
+  const layout = labLayout(env)
+  const download = inspectDownload(layout, pin, { verify, onProgress })
+  const base = inspectBase(layout, pin)
+  const toolchain = inspectToolchain(layout, pin)
+  const staging = await inspectStaging(layout)
+  const lock = await inspectLock(layout)
+  const host = { run: probeRunHost({ pin, run, env }), verify: probeCommands(VERIFY_COMMANDS, { run, env }), build: probeCommands(BUILD_COMMANDS, { run, env }) }
+  const free = freeBytesAt(layout.cache)
+  const runs = existsSync(layout.runs) ? readdirSync(layout.runs).filter((name) => /^\d{8}-\d{6}/.test(name)).sort() : []
+  const totals = {
+    cacheBytes: existsSync(layout.cache) ? allocatedBytes(layout.cache) : 0,
+    downloadsBytes: existsSync(layout.downloads) ? allocatedBytes(layout.downloads) : 0,
+    baseBytes: base.allocatedBytes,
+    stagingBytes: staging.reduce((sum, entry) => sum + entry.allocatedBytes, 0),
+    pluginsBytes: existsSync(layout.plugins) ? allocatedBytes(layout.plugins) : 0,
+    runsBytes: existsSync(layout.runs) ? allocatedBytes(layout.runs) : 0,
+  }
+  const missing = []
+  for (const line of host.run) if (line.state !== "ok") missing.push({ what: line.name, cost: line.reason, command: line.remedy })
+  if (!download.verified) {
+    missing.push({
+      what: "the verified ISO",
+      cost: download.present ? `verification of the ${bytesBoth(download.bytes)} on disk (about ${durationWords(5215 + 9430)} on the reference host: the hash and the signature check)` : `a download of ${bytesBoth(pin.release.bytes)} from ${pin.release.isoUrl}, verified against the pinned sha256 and the Omarchy signature, into ${download.dir}`,
+      command: "omakit lab setup",
+    })
+  }
+  if (toolchain.state !== "ready" && base.state !== "ready") {
+    missing.push({ what: "the toolchain", cost: `a checkout of omarchy-iso at ${pin.toolchain.commit.slice(0, 12)} with ${pin.toolchain.patch} applied; it drives the installer once, to build the base`, command: toolchainCommand(pin, join(layout.cache, "toolchain/omarchy-iso")) })
+  }
+  if (base.state !== "ready") {
+    missing.push({
+      what: base.state === "missing" ? "a prepared base" : `a usable base (the one there is ${base.state})`,
+      cost: `${bytesBoth(pin.measured.baseDirectoryBytes)} on disk, ${durationWords(pin.measured.buildMilliseconds)} to build on the reference host (M14), plus one verification boot`,
+      command: "omakit lab setup",
+    })
+  }
+  return { pin: { release: pin.release, toolchain: pin.toolchain, guest: pin.guest, measured: pin.measured }, layout, download, base, toolchain, staging, lock, host, free, runs, totals, missing }
+}

package/tools/lab/omarchy.gpg

@@ -0,0 +1,13 @@
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+
+mDMEaLAsIhYJKwYBBAHaRw8BAQdAYmKmrWMlfpdIPh3QzvEMzzxdNd/kqDl/Bj8H
+mCavKji0Gk9tYXJjaHkgPHBrZ3NAb21hcmNoeS5vcmc+iJAEExYKADgWIQRA37Yw
+/0K8/7BHBGzwE07mgMrFcQUCaLAsIgIbAwULCQgHAgYVCgkICwIEFgIDAQIeAQIX
+gAAKCRDwE07mgMrFcRF2AQCjjvjgju/kowkN69nenqqRnE+v2MrHmWh2wU0ugIt9
+3gD/bXGugWc5J1vqoT+5aCnJAtfRRmHEfsrAiFgjduB+VA24OARosCwiEgorBgEE
+AZdVAQUBAQdAJoU73WdgxE/pEYK5ofyRvQDs1IFRdfJHV9j4Jm+tuDUDAQgHiHgE
+GBYKACAWIQRA37Yw/0K8/7BHBGzwE07mgMrFcQUCaLAsIgIbDAAKCRDwE07mgMrF
+cYXsAQC5eBEGK0xKsGwtnDDVeNAapx32dpvLgJ94W4DtIpdLlwEA85cSsTiBMuGy
+6kwYmHzqw7oFx3VYGXdMNl0SMKzvJA4=
+=G7wU
+-----END PGP PUBLIC KEY BLOCK-----

package/tools/lab/patches/omarchy-iso-test.patch

@@ -0,0 +1,351 @@
+diff --git c/bin/omarchy-iso-test w/bin/omarchy-iso-test
+index 281cf56..be30127 100755
+--- c/bin/omarchy-iso-test
++++ w/bin/omarchy-iso-test
+@@ -21,10 +21,18 @@
+ #   --sync-omarchy DIR Push DIR's test/acceptance into the guest before running
+ #                      (defaults to OMARCHY_PATH when the suite is present)
+ #   --sync-all DIR     Push all of DIR (bin/config/shell/test) into the guest
++#   --dev-link         With --sync-all, start a fresh graphical session linked
++#                      to the checkout so the whole desktop uses local source
++#   --host-test FILE   Source FILE after boot; it must define omarchy_host_test
++#                      and may use the harness QMP/SSH/artifact helpers
++#   --host-test-only   Run only --host-test after source activation, skipping
++#                      the broad desktop and in-guest acceptance suites
+ #   --port PORT        Host port forwarded to guest SSH (default 2222)
+ #   --memory MB        VM memory (default 8192)
+ #   --timeout SECS     Install timeout (default 2400)
+ #   --keep-running     Leave the acceptance VM running after the suite finishes
++#   --discard-overlay  Delete the disposable run disk after the VM stops
++#   --keep-overlay     Retain the run disk (overrides --discard-overlay)
+ #   --no-preview       Do not open the collected screenshots in imv
+ 
+ set -euo pipefail
+@@ -42,12 +50,17 @@ PROVISION=false
+ REUSE_BASE=false
+ INSTALL_ONLY=false
+ KEEP_RUNNING=false
++DISCARD_OVERLAY=false
+ NO_PREVIEW=false
+ SYNC_DIR=""
+ SYNC_ALL=false
++DEV_LINK=false
++HOST_TEST=""
++HOST_TEST_ONLY=false
+ 
+ GUEST_USER="omarchy"
+ GUEST_PASSWORD="omarchy"
++GREETER_PATTERN='Opinionated\|Beautiful, Fun & Agentic Linux by DHH'
+ GUEST_HOSTNAME="omarchy-test"
+ 
+ while (($#)); do
+@@ -57,9 +70,14 @@ while (($#)); do
+     --reuse-base) REUSE_BASE=true ;;
+     --install-only) INSTALL_ONLY=true ;;
+     --keep-running) KEEP_RUNNING=true ;;
++    --discard-overlay) DISCARD_OVERLAY=true ;;
++    --keep-overlay) DISCARD_OVERLAY=false ;;
+     --no-preview) NO_PREVIEW=true ;;
+     --sync-omarchy) SYNC_DIR="$2"; shift ;;
+     --sync-all) SYNC_DIR="$2"; SYNC_ALL=true; shift ;;
++    --dev-link) DEV_LINK=true ;;
++    --host-test) HOST_TEST="$2"; shift ;;
++    --host-test-only) HOST_TEST_ONLY=true ;;
+     --port) SSH_PORT="$2"; shift ;;
+     --memory) MEMORY="$2"; shift ;;
+     --timeout) INSTALL_TIMEOUT="$2"; shift ;;
+@@ -69,6 +87,23 @@ while (($#)); do
+   shift
+ done
+ 
++if $DEV_LINK && ! $SYNC_ALL; then
++  echo "--dev-link requires --sync-all DIR" >&2
++  exit 1
++fi
++
++if [[ -n $HOST_TEST ]]; then
++  HOST_TEST=$(realpath -e "$HOST_TEST") || {
++    echo "Host test not found: $HOST_TEST" >&2
++    exit 1
++  }
++fi
++
++if $HOST_TEST_ONLY && [[ -z $HOST_TEST ]]; then
++  echo "--host-test-only requires --host-test FILE" >&2
++  exit 1
++fi
++
+ if [[ -z $SYNC_DIR && -f ${OMARCHY_PATH:-}/test/acceptance ]]; then
+   SYNC_DIR="$OMARCHY_PATH"
+ fi
+@@ -83,10 +118,21 @@ if [[ ! -f ${ISO:-} ]]; then
+   exit 1
+ fi
+ 
+-omarchy-pkg-add qemu-full edk2-ovmf socat imagemagick tesseract tesseract-data-eng
++for required_command in qemu-system-x86_64 qemu-img socat magick tesseract; do
++  if ! command -v "$required_command" >/dev/null; then
++    echo "Missing host prerequisite: $required_command" >&2
++    exit 1
++  fi
++done
+ 
+ OVMF_CODE="/usr/share/edk2/x64/OVMF_CODE.4m.fd"
+ OVMF_VARS_TEMPLATE="/usr/share/edk2/x64/OVMF_VARS.4m.fd"
++for firmware in "$OVMF_CODE" "$OVMF_VARS_TEMPLATE"; do
++  if [[ ! -r $firmware ]]; then
++    echo "Missing readable UEFI firmware: $firmware" >&2
++    exit 1
++  fi
++done
+ 
+ BASE_NAME="$(basename "$ISO" .iso)"
+ $ENCRYPT && BASE_NAME+="-encrypted"
+@@ -121,6 +167,52 @@ qmp() {
+     timeout 5 socat -t 2 - "UNIX-CONNECT:$QMP_SOCK" 2>/dev/null || true
+ }
+ 
++qmp_pointer_move() {
++  local width="$1" height="$2" x="$3" y="$4" qx qy response
++
++  if ((width < 2 || height < 2 || x < 0 || y < 0 || x >= width || y >= height)); then
++    printf 'invalid QMP pointer geometry: viewport=%sx%s point=%s,%s\n' \
++      "$width" "$height" "$x" "$y" >&2
++    return 2
++  fi
++  qx=$((x * 32767 / (width - 1)))
++  qy=$((y * 32767 / (height - 1)))
++  response=$(qmp "\"input-send-event\", \"arguments\": {\"events\": [
++    {\"type\":\"abs\",\"data\":{\"axis\":\"x\",\"value\":$qx}},
++    {\"type\":\"abs\",\"data\":{\"axis\":\"y\",\"value\":$qy}}
++  ]}")
++  if grep -q '"error"' <<<"$response"; then
++    printf 'QMP pointer move failed: %s\n' "$response" >&2
++    return 1
++  fi
++}
++
++qmp_pointer_tap() {
++  local width="$1" height="$2" x="$3" y="$4" button="${5:-left}" response
++
++  case $button in
++    left | right | middle) ;;
++    *)
++      printf 'invalid QMP pointer button: %s\n' "$button" >&2
++      return 2
++      ;;
++  esac
++  qmp_pointer_move "$width" "$height" 1 1
++  sleep 0.1
++  qmp_pointer_move "$width" "$height" "$x" "$y"
++  sleep 0.1
++  response=$(qmp "\"input-send-event\", \"arguments\": {\"events\": [
++    {\"type\":\"btn\",\"data\":{\"down\":true,\"button\":\"$button\"}}
++  ]}")
++  grep -q '"error"' <<<"$response" && return 1
++  sleep 0.12
++  response=$(qmp "\"input-send-event\", \"arguments\": {\"events\": [
++    {\"type\":\"btn\",\"data\":{\"down\":false,\"button\":\"$button\"}}
++  ]}")
++  grep -q '"error"' <<<"$response" && return 1
++  sleep 0.4
++}
++
+ screendump() {
+   qmp "\"screendump\", \"arguments\": {\"filename\": \"$1\"}" >/dev/null
+ }
+@@ -188,6 +280,15 @@ cleanup() {
+   if ! $KEEP_RUNNING; then
+     vm_running && log "Stopping test VM"
+     stop_vm
++
++    if $DISCARD_OVERLAY && [[ -f $RUN_DIR/run.qcow2 ]]; then
++      if vm_running; then
++        echo "WARN: VM did not stop; preserving its run overlay: $RUN_DIR/run.qcow2" >&2
++      else
++        rm -f -- "$RUN_DIR/run.qcow2"
++        log "Discarded the stopped VM overlay; run evidence remains in $RUN_DIR"
++      fi
++    fi
+   fi
+ 
+   rm -f "$RUN_DIR/.screen.ppm" "$RUN_DIR/.screen.png"
+@@ -355,7 +456,10 @@ wait_for_ssh() {
+ }
+ 
+ session_started() {
+-  ssh_guest "ls /run/user/1000/hypr 2>/dev/null | grep -q ." 2>/dev/null
++  # Hyprland leaves its runtime directory behind briefly after logout, while
++  # SDDM starts a different compositor as the sddm user. Only the compositor
++  # owned by the test user proves that the Omarchy session is actually ready.
++  ssh_guest "pgrep -u \$(id -u) -x Hyprland >/dev/null" 2>/dev/null
+ }
+ 
+ ssh_session() {
+@@ -367,7 +471,8 @@ ssh_session() {
+     export LANG=\${LANG:-C.UTF-8}; \
+     export HYPRLAND_INSTANCE_SIGNATURE=\$(ls -t \$XDG_RUNTIME_DIR/hypr | head -1); \
+     export WAYLAND_DISPLAY=\$(find \$XDG_RUNTIME_DIR -maxdepth 1 -name 'wayland-*' ! -name '*.lock' -printf '%f\\n' | head -1); \
+-    export OMARCHY_PATH=/usr/share/omarchy; \
++    [[ ! -f /etc/omarchy.conf ]] || source /etc/omarchy.conf; \
++    export OMARCHY_PATH=\${OMARCHY_PATH:-/usr/share/omarchy}; \
+     export PATH=\$OMARCHY_PATH/bin:\$PATH; \
+     $command" </dev/null
+ }
+@@ -399,6 +504,20 @@ guest_layer_absent() {
+   ! guest_layer_present "$1"
+ }
+ 
++session_stopped() {
++  ! session_started
++}
++
++clear_startup_notifications() {
++  [[ -n $HOST_TEST ]] || return 0
++
++  wait_for_guest_state "notification service is ready" 15 \
++    ssh_session "omarchy-shell notifications ping >/dev/null" || return 1
++  ssh_session "omarchy-shell notifications dismissAll >/dev/null" || return 1
++  wait_for_guest_state "startup notifications are dismissed" 15 \
++    guest_layer_absent "omarchy-notifications"
++}
++
+ cleanup_shortcut_state() {
+   ssh_session 'for plugin in omarchy.launcher omarchy.menu omarchy.emojis omarchy.clipboard omarchy.audio; do
+     omarchy-shell shell hide "$plugin" >/dev/null 2>&1 || true
+@@ -607,7 +726,10 @@ drive_configurator() {
+   log "Driving the installer wizard"
+ 
+   # A greeter (animated logo + tagline) opens the installer; Return begins.
+-  wait_for_screen "Opinionated" 300
++  # Released installers before v4.0.3 use the original slogan; v4.0.3 uses
++  # the exact replacement below. Keep this allowlist explicit so unrelated
++  # OCR text cannot be mistaken for an installer-ready signal.
++  wait_for_screen "$GREETER_PATTERN" 300
+   capture_console "success-installer-00-greeter"
+   press ret
+ 
+@@ -631,7 +753,10 @@ drive_configurator() {
+     capture_console "success-installer-04-prepare-disk-warning-encrypted"
+     if ! $ENCRYPT; then
+       press ctrl-c
+-      wait_for_screen "without encryption" 30
++      # The selected confirmation label is light text on a light background,
++      # which Tesseract intentionally loses. The prompt itself stays put, so
++      # give the Ctrl+C state change time to render and capture it as proof.
++      sleep 2
+       capture_console "success-installer-05-prepare-disk-warning-unencrypted"
+     fi
+     press ret
+@@ -695,7 +820,10 @@ drive_configurator() {
+   capture_console "success-installer-12-disk-warning-encrypted"
+   if ! $ENCRYPT; then
+     press ctrl-c # toggles the confirm to the unencrypted flow
+-    wait_for_screen "without encryption" 30
++    # The selected confirmation label is light text on a light background,
++    # which Tesseract intentionally loses. The prompt itself stays put, so
++    # give the Ctrl+C state change time to render and capture it as proof.
++    sleep 2
+     capture_console "success-installer-13-disk-warning-unencrypted"
+   fi
+   press ret
+@@ -716,7 +844,7 @@ drive_provision_owner() {
+   # layout — UK leaves every letter identical to US, so the typed password (sent
+   # as raw keycodes) still matches the literal one the harness pipes to sudo.
+   # A greeter (animated logo + tagline) opens first boot; Return begins.
+-  wait_for_screen "Opinionated" 600
++  wait_for_screen "$GREETER_PATTERN" 600
+   capture_console "success-provision-00-greeter"
+   press ret
+ 
+@@ -791,7 +919,7 @@ wait_for_install() {
+     # Deferred-provisioning installs skip the celebration and reboot on their own
+     # (no Reboot Now prompt); the first-boot greeter tagline appearing means the
+     # install finished and rebooted into setup.
+-    if $PROVISION && grep -qi "Opinionated" <<<"$text"; then
++    if $PROVISION && grep -qi "$GREETER_PATTERN" <<<"$text"; then
+       log "Install finished and auto-rebooted into first-boot setup."
+       capture_console "success-installer-15-autoreboot"
+       return 0
+@@ -1063,6 +1191,49 @@ sync_omarchy() {
+   fi
+ }
+ 
++activate_dev_checkout() {
++  $DEV_LINK || return 0
++
++  local target=".local/share/omarchy"
++  log "Linking the disposable guest session to the synced Omarchy checkout"
++
++  ssh_guest "echo '$GUEST_PASSWORD' | sudo -S -v && $target/bin/omarchy-dev-link $target --no-reboot"
++
++  # omarchy-dev-link deliberately leaves the running UWSM environment alone.
++  # A fresh graphical login is enough to rebuild that environment from
++  # /etc/omarchy.conf. Avoid rebooting here: the acceptance disk is already a
++  # throwaway overlay, and some released unencrypted ISOs have a separate
++  # post-install Limine/resume defect that would obscure source-level tests.
++  ssh_guest "uwsm stop" >/dev/null 2>&1 || true
++
++  if ! wait_for_guest_state "linked graphical session stops" 60 session_stopped; then
++    return 1
++  fi
++
++  establish_session
++  ssh_guest "grep -Fq '$target' /etc/omarchy.conf"
++  log "Disposable guest is running entirely from the synced checkout"
++}
++
++run_host_test() {
++  [[ -n $HOST_TEST ]] || return 0
++
++  log "Running host-driven acceptance: $HOST_TEST"
++  # The host test is trusted local test code sourced deliberately so it can use
++  # press, ssh_guest, ssh_session, capture_console, wait_for_guest_state, and
++  # the current RUN_DIR without duplicating the QMP/SSH harness.
++  source "$HOST_TEST"
++  declare -F omarchy_host_test >/dev/null || {
++    echo "$HOST_TEST must define omarchy_host_test()" >&2
++    return 1
++  }
++  set +e
++  omarchy_host_test 2>&1 | tee "$RUN_DIR/host-test.log"
++  local status=${PIPESTATUS[0]}
++  set -e
++  return "$status"
++}
++
+ acceptance_phase() {
+   log "Booting acceptance VM from base image overlay"
+ 
+@@ -1074,15 +1245,26 @@ acceptance_phase() {
+ 
+   establish_session
+   sync_omarchy
++  activate_dev_checkout
++  if ! clear_startup_notifications; then
++    capture_console "failure-startup-notifications"
++    return 1
++  fi
+ 
+   local status=0
+-  shortcut_smoke_phase || status=1
+ 
+-  log "Running acceptance suite"
+-  ssh_guest "OMARCHY_PATH=$guest_omarchy_path OMARCHY_ACCEPTANCE_DIR=/tmp/omarchy-acceptance bash .local/share/omarchy/test/acceptance" || status=$?
++  if $HOST_TEST_ONLY; then
++    run_host_test || status=1
++  else
++    shortcut_smoke_phase || status=1
++    run_host_test || status=1
+ 
+-  log "Collecting artifacts into $RUN_DIR"
+-  ssh_guest "tar -C /tmp -cf - omarchy-acceptance 2>/dev/null" | tar -C "$RUN_DIR" -xf - || true
++    log "Running acceptance suite"
++    ssh_guest "OMARCHY_PATH=$guest_omarchy_path OMARCHY_ACCEPTANCE_DIR=/tmp/omarchy-acceptance bash .local/share/omarchy/test/acceptance" || status=$?
++
++    log "Collecting artifacts into $RUN_DIR"
++    ssh_guest "tar -C /tmp -cf - omarchy-acceptance 2>/dev/null" | tar -C "$RUN_DIR" -xf - || true
++  fi
+   ssh_guest "echo $GUEST_PASSWORD | sudo -S cat /var/log/omarchy-install.log 2>/dev/null" >"$RUN_DIR/omarchy-install.log" 2>/dev/null || true
+   if ((status == 0)); then
+     capture_console "success-acceptance-final"