omakit 0.5.1 → 0.6.2

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"

package/tools/lab/paths.mjs

@@ -0,0 +1,173 @@
+// Where the lab keeps its bytes, and the one guard every write goes
+// through.
+//
+// Heavy files (the verified ISO, the base disk, a run's overlay) live
+// under the user cache, $XDG_CACHE_HOME/omakit/lab or ~/.cache/omakit/lab;
+// compact run records under the user state, $XDG_STATE_HOME/omakit/lab or
+// ~/.local/state/omakit/lab. Nothing is written anywhere else: every path
+// the lab writes to is built by `inLab`, which refuses a path outside the
+// resolved root, and tests/unit/self-containment.test.mjs holds every
+// write under tools/lab/ to that builder. Measured before this
+// (docs/history/2026-09-18-lab-inventory.md P6): the base, the firmware
+// variables and the SSH key lived inside the omarchy-iso checkout, named
+// by the ISO's file name.
+
+import { closeSync, createReadStream, createWriteStream, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs"
+import { pipeline } from "node:stream/promises"
+import { join, resolve, sep } from "node:path"
+import { omakitCacheDir, omakitStateDir } from "../marketplace/paths.mjs"
+
+/** The cache root: downloads, base, staging, the lock. */
+export function labCacheDir(env = process.env) {
+  return omakitCacheDir("lab", env)
+}
+
+/** The state root: run records, one directory per run id. */
+export function labStateDir(env = process.env) {
+  return omakitStateDir("lab", env)
+}
+
+/**
+ * The layout under the cache root. One base, not one per release
+ * (packaging/LAB_PLAN.md, the one-base rule): a pin update replaces it.
+ */
+export function labLayout(env = process.env) {
+  const cache = labCacheDir(env)
+  const state = labStateDir(env)
+  return Object.freeze({
+    cache,
+    state,
+    downloads: join(cache, "downloads"),
+    base: join(cache, "base"),
+    staging: join(cache, "staging"),
+    plugins: join(cache, "plugins"),
+    lock: join(cache, "lab.lock"),
+    toolchain: join(cache, "toolchain.json"),
+    runs: join(state, "runs"),
+  })
+}
+
+/**
+ * A path under one of the two lab roots, or a throw. Every write in
+ * tools/lab/ names its target through this, so a target outside the lab
+ * is a bug that fails before a byte moves, not a file somewhere else.
+ */
+export function inLab(root, ...parts) {
+  const target = resolve(root, ...parts)
+  const roots = [resolve(root)]
+  if (!roots.some((allowed) => target === allowed || target.startsWith(`${allowed}${sep}`))) {
+    throw new Error(`lab: ${target} is outside ${root}`)
+  }
+  return target
+}
+
+/** A directory under the lab, created private (0700) with its parents. */
+export function labDir(root, ...parts) {
+  const dir = inLab(root, ...parts)
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  return dir
+}
+
+/** JSON written whole and fsynced, so a manifest is either there or not. */
+export function writeJson(root, relative, value) {
+  const file = inLab(root, relative)
+  const fd = openSync(file, "w", 0o600)
+  try {
+    writeFileSync(fd, `${JSON.stringify(value, null, 2)}\n`)
+    fsyncSync(fd)
+  } finally {
+    closeSync(fd)
+  }
+  return file
+}
+
+export function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Move a file or directory within the lab: a rename when the two are on
+ * one filesystem, and for a file on another one a streamed copy followed
+ * by the removal of the source. The destination must not exist. This is
+ * the one place the lab renames anything, and tests/unit/self-containment
+ * holds the tree to it.
+ */
+export async function moveIntoLab(root, from, relative) {
+  const to = inLab(root, relative)
+  try {
+    statSync(to)
+    throw new Error(`lab: ${to} exists; nothing is moved over it`)
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error
+  }
+  try {
+    renameSync(from, to)
+    return to
+  } catch (error) {
+    if (error.code !== "EXDEV") throw error
+  }
+  const source = statSync(from)
+  if (!source.isFile()) throw new Error(`lab: ${from} is on another filesystem and is not a file; move it by hand`)
+  await copyIntoLab(root, from, relative)
+  unlinkSync(from)
+  return to
+}
+
+/** A streamed copy of one file into the lab, mode 0600, fsynced. The destination must not exist. */
+export async function copyIntoLab(root, from, relative) {
+  const to = inLab(root, relative)
+  try {
+    statSync(to)
+    throw new Error(`lab: ${to} exists; nothing is copied over it`)
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error
+  }
+  const out = createWriteStream(to, { mode: 0o600, flags: "wx" })
+  await pipeline(createReadStream(from), out)
+  const fd = openSync(to, "r")
+  try {
+    fsyncSync(fd)
+  } finally {
+    closeSync(fd)
+  }
+  return to
+}
+
+/** Remove something under the lab, and nothing outside it. */
+export function removeFromLab(root, relative) {
+  rmSync(inLab(root, relative), { recursive: true, force: true })
+}
+
+/** `20260918-150245`, the run id shape the toolchain used, kept so a run directory sorts by time. */
+export function stampNow(date = new Date()) {
+  const pad = (n) => String(n).padStart(2, "0")
+  return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`
+}
+
+/** Allocated bytes of a path, like `du -B1`: blocks times 512, so a sparse qcow2 is measured by what it takes. */
+export function allocatedBytes(path) {
+  const walk = (p) => {
+    let st
+    try {
+      st = statSync(p)
+    } catch {
+      return 0
+    }
+    let total = st.blocks * 512
+    if (st.isDirectory()) {
+      let entries = []
+      try {
+        entries = readdirSync(p)
+      } catch {
+        return total
+      }
+      for (const entry of entries) total += walk(join(p, entry))
+    }
+    return total
+  }
+  return walk(path)
+}

package/tools/lab/pin.json

@@ -0,0 +1,42 @@
+{
+  "schema": 1,
+  "release": {
+    "name": "4.0.3",
+    "embeddedBuild": "2026.09.08",
+    "volume": "OMARCHY_202609",
+    "isoUrl": "https://iso.omarchy.org/omarchy-4.0.3.iso",
+    "checksumUrl": "https://iso.omarchy.org/omarchy-4.0.3.iso.sha256",
+    "signatureUrl": "https://iso.omarchy.org/omarchy-4.0.3.iso.sig",
+    "fileName": "omarchy-4.0.3.iso",
+    "bytes": 6260654080,
+    "sha256": "03d60bc74306dca51f96e1a84b690871d8d606826b260edd0208962da8507d14",
+    "signingFingerprint": "40DFB630FF42BCFFB047046CF0134EE680CAC571",
+    "signingKey": "omarchy.gpg",
+    "signingKeySha256": "15d6aac44df688165b2ea35fe0b23af239bbc66a6909c10a5c219e8d94b707de",
+    "expectedGuestVersion": "4.0.3-1"
+  },
+  "toolchain": {
+    "repository": "https://github.com/omacom-io/omarchy-iso",
+    "commit": "268bac16d351a21d867e37565738f458b11cb06c",
+    "harness": "bin/omarchy-iso-test",
+    "upstreamHarnessSha256": "fbc236a674464743c6ff8e4cc53be932dc36a16c9fcb159932006e9d7452439c",
+    "patch": "patches/omarchy-iso-test.patch",
+    "patchedHarnessSha256": "8637e8cc82413fb421daa17eb758e3136cf71099b108b6412326172993974e97"
+  },
+  "guest": {
+    "memoryMiB": 5120,
+    "user": "omarchy",
+    "password": "omarchy",
+    "diskGiB": 40
+  },
+  "measured": {
+    "on": "2026-09-18",
+    "buildMilliseconds": 357800,
+    "baseAllocatedBytes": 6181490688,
+    "baseDirectoryBytes": 6182264832,
+    "preparedLabBytes": 12442931200,
+    "overlayAfterRunBytes": 610734080,
+    "pluginsBytes": 6836224,
+    "source": "docs/MEASUREMENTS.md M14, measured by omakit lab on the reference host; packaging/LAB_PLAN.md M4 to M7 are the 2026-09-10 to 2026-09-13 observations it re-measured"
+  }
+}

package/tools/lab/pin.mjs

@@ -0,0 +1,64 @@
+// The release pin: the one Omarchy release the lab prepares, its exact
+// digest, its signer, and the toolchain that builds a base from it.
+//
+// Read from tools/lab/pin.json, never from the network: the lab never
+// resolves "latest" (docs/history/2026-09-18-lab-inventory.md P13: the
+// old setup scraped omarchy.org for the first ISO link and verified it
+// against a sidecar downloaded beside it, so a substituted pair passed).
+// Updating the pin is a reviewed change, docs/LAB.md says how.
+
+import { readFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+export const LAB_DIR = dirname(fileURLToPath(import.meta.url))
+
+let cached = null
+
+/** The pin, parsed once. `file` is injectable for tests that need a small release. */
+export function labPin(file = join(LAB_DIR, "pin.json")) {
+  if (file === join(LAB_DIR, "pin.json") && cached) return cached
+  const pin = JSON.parse(readFileSync(file, "utf8"))
+  for (const key of ["release", "toolchain", "guest", "measured"]) {
+    if (!pin[key] || typeof pin[key] !== "object") throw new Error(`lab pin: no ${key} section in ${file}`)
+  }
+  if (!/^[0-9a-f]{64}$/.test(pin.release.sha256)) throw new Error("lab pin: the release sha256 is not 64 hex characters")
+  if (!/^[0-9A-F]{40}$/.test(pin.release.signingFingerprint)) throw new Error("lab pin: the signing fingerprint is not 40 hex characters")
+  if (!Number.isInteger(pin.release.bytes) || pin.release.bytes <= 0) throw new Error("lab pin: the release byte count is not a positive integer")
+  if (/latest/i.test(pin.release.isoUrl)) throw new Error("lab pin: the ISO URL resolves latest; the pin names one release")
+  if (file === join(LAB_DIR, "pin.json")) cached = pin
+  return pin
+}
+
+/**
+ * Bytes for a person, in both units, so a size cannot be made to look
+ * smaller by choosing one: `6,260,654,080 B (6.261 GB / 5.831 GiB)`.
+ * Decimal GB is what the download page and the disk vendor say, binary
+ * GiB is what `df` and `du -h` say; both are printed every time.
+ */
+export function bytesBoth(bytes) {
+  const n = Number(bytes)
+  const gb = (n / 1e9).toFixed(3)
+  const gib = (n / 2 ** 30).toFixed(3)
+  return `${n.toLocaleString("en-US")} B (${gb} GB / ${gib} GiB)`
+}
+
+/** The two units without the byte count, for a breakdown whose total already printed it: `6.261 GB / 5.831 GiB`. */
+export function gbBoth(bytes) {
+  const n = Number(bytes)
+  return `${(n / 1e9).toFixed(3)} GB / ${(n / 2 ** 30).toFixed(3)} GiB`
+}
+
+/** `4m 49.5s` from milliseconds, the way a person reads a build time. */
+export function durationWords(ms) {
+  const seconds = Math.round(ms / 100) / 10
+  if (seconds < 60) return `${seconds.toFixed(1)}s`
+  const minutes = Math.floor(seconds / 60)
+  return `${minutes}m ${(seconds - minutes * 60).toFixed(1)}s`
+}
+
+/** The first eight and last eight characters of a digest or fingerprint, for a line that names it without being it. */
+export function shortId(value) {
+  const s = String(value)
+  return s.length > 20 ? `${s.slice(0, 8)}...${s.slice(-8)}` : s
+}