omakit 0.5.0 → 0.6.1

package/tools/inspect/report.mjs

@@ -20,7 +20,6 @@
 import { colourEnabled, field, GUTTER, INSPECT_VERDICT, mark, outputColumns, styler, verdict, wrap } from "../marketplace/style.mjs"
 import { withHomeAbbreviated } from "../marketplace/paths.mjs"
 import { PATTERNS, SIZE } from "./patterns.mjs"
-import { toolOf } from "./processes.mjs"
 
 const NOTHING = "observed nothing of this kind"
 
@@ -35,11 +34,17 @@ function percent(share) {
   return `${rounded}%`
 }
 
-/** The score sentence after the number: the share, then the position among the listed trees the document itself carries. */
+/**
+ * The score sentence after the number: the share, then the position among
+ * the listed trees the document itself carries. The rank counts the listed
+ * trees with a strictly smaller share, so the tree is "no heavier than"
+ * the rest: a tie is level, not lighter.
+ */
 function scoreText(size) {
   const shares = size.sample.heavyShares
-  const rank = (shares.filter((share) => share < size.heavyShare).length / shares.length) * 100
-  return `${percent(size.heavyShare)} of its function lines sit in functions over the measured size, less than ${100 - Math.round(rank)} of 100 listed trees (${size.measurement})`
+  if (!shares.length) return `${percent(size.heavyShare)} of its function lines sit in functions over the measured size; no listed tree to place it among (${size.measurement})`
+  const lighter = shares.filter((share) => share < size.heavyShare).length
+  return `${percent(size.heavyShare)} of its function lines sit in functions over the measured size, no heavier than ${shares.length - lighter} of ${shares.length} listed trees (${size.measurement})`
 }
 
 /** Under --allow-dirty: what the checkout holds that the tree at the commit does not. */
@@ -100,7 +105,7 @@ function hostRow(host, c) {
 }
 
 function writeRow(write, c) {
-  const what = write.via === "FileView" ? `FileView path: ${write.path}` : `${write.via} ${write.path}`
+  const what = write.via === "FileView" ? `FileView path: ${write.path}` : write.via === "block-store" ? `Store ${write.path} (through the store block)` : `${write.via} ${write.path}`
   const where = write.controlledDirectory === "observed"
     ? `observed (${write.controlledBy})`
     : write.controlledDirectory === "not-observed"
@@ -257,6 +262,7 @@ export function renderInspect(document, { colour = colourEnabled(), full = false
   out.push(...field("subject", `${withHomeAbbreviated(document.subject.dir)} at ${document.subject.commit ? document.subject.commit.slice(0, 8) : "no commit"}`, c))
   out.push(...uncommittedLine(document, c))
   out.push(...field("baseline", baselineText(document.marketplaceBaseline), c))
+  if (document.blocks.length) out.push(...field("blocks", blocksText(document.blocks), c))
   const score = document.size.score
   out.push(...field("size score", score === null
     ? `none: no function to rank`
@@ -271,7 +277,12 @@ export function renderInspect(document, { colour = colourEnabled(), full = false
   if (!ranked.length && !over.length) {
     out.push(...field("attention", `nothing: no function over the size of ${SIZE.sample} (${SIZE.measurement}), and none of the ${PATTERNS.length} classes reviewers raise shows in this tree (${PATTERNS[0]?.measurement || "M11"})`, c))
   } else {
-    out.push(...field("attention", `${over.length ? `long functions first, by length, then ` : ""}${plural(shown.length, "class", "classes")} reviewers raise, biggest first by share of review findings (${PATTERNS[0].measurement}); up to ${SHOWN_SITES} sites each`, c))
+    const classes = shown.length
+      ? `${plural(shown.length, "class", "classes")} reviewers raise, biggest first by share of review findings (${PATTERNS[0].measurement}); up to ${SHOWN_SITES} sites each`
+      : below.length
+        ? `only classes under ${Math.round(MIN_SHARE * 100)}% of review findings show (${PATTERNS[0].measurement}), counted below`
+        : `none of the classes reviewers raise shows in this tree (${PATTERNS[0].measurement})`
+    out.push(...field("attention", `${over.length ? `long functions first, by length${shown.length ? ", then " : "; "}` : ""}${classes}`, c))
   }
   // Long functions first: what the person asked about, so the order is a
   // preference and the heading says whose thresholds it uses.
@@ -325,6 +336,7 @@ function renderFull(document, { colour }) {
   out.push(...field("subject", `${withHomeAbbreviated(document.subject.dir)} at ${document.subject.commit ? document.subject.commit.slice(0, 8) : "no commit"}, ${plural(total, "file")} read${kinds.length ? ` (${kinds.join(", ")})` : ""}`, c))
   out.push(...uncommittedLine(document, c))
   out.push(...field("method", document.method, c))
+  if (document.blocks.length) out.push(...field("blocks", blocksText(document.blocks), c))
   out.push("")
 
   const sections = [
@@ -359,6 +371,21 @@ function renderFull(document, { colour }) {
 }
 
 /** The process split in words: how many are QML Process sites and how many are shell lines. */
+/**
+ * The omakit blocks in the tree, one clause each: an unmodified block is
+ * its name, version and file count, and its files raised no row; a
+ * modified one names the files whose body is not a shipped one, which
+ * were read like any other file.
+ */
+function blocksText(blocks) {
+  return blocks.map((block) => {
+    const version = block.shippedVersion && block.shippedVersion !== block.version ? `${block.version} (omakit ships ${block.shippedVersion})` : block.version
+    if (block.state === "unmodified") return `${block.name} ${version}, ${plural(block.files.length, "file")}, unmodified${block.complete ? "" : ", incomplete"}: no row of its own`
+    const changed = block.files.filter((file) => file.state === "modified").map((file) => file.path)
+    return `${block.name} ${version}, modified (${changed.join(", ")}): read like any other file`
+  }).join("; ")
+}
+
 function split({ qml, shell }) {
   if (!shell) return qml === 1 ? "in qml" : "all in qml"
   if (!qml) return shell === 1 ? "a shell line" : "all shell lines"

package/tools/inspect/writes.mjs

@@ -68,9 +68,26 @@ function row(file, line, rawPath, via, pluginId, mode = null) {
   return { file: file.path, line, path: String(rawPath).trim(), canonicalPath: canonical, via, ...classified, mode }
 }
 
-function qmlWrites(file, pluginId) {
+/**
+ * A `Store {` site of the omakit store block: one file under the plugin's
+ * private directory in the XDG state or cache base (docs/BLOCKS.md), so
+ * the path is `$XDG_STATE_HOME/<pluginId>/<name>` or the cache one, a
+ * directory the plugin controls, written at mode 0600 through a staging
+ * file. Read only where the tree carries the store block unmodified.
+ */
+function storeRow(file, text, block, pluginId) {
+  const kind = stringLiteral(propertyValue(block.body, "kind")?.text ?? "") ?? "state"
+  const base = kind === "cache" ? "$XDG_CACHE_HOME" : "$XDG_STATE_HOME"
+  const id = stringLiteral(propertyValue(block.body, "pluginId")?.text ?? "")
+  const name = stringLiteral(propertyValue(block.body, "name")?.text ?? "")
+  const path = `${base}/${id || "<pluginId>"}/${name || "<name>"}`
+  return { ...row(file, lineOf(text, block.start), path, "block-store", pluginId, "0600"), block: "store" }
+}
+
+function qmlWrites(file, pluginId, { storeBlock = false } = {}) {
   const text = blankComments(file.text)
   const rows = []
+  if (storeBlock) for (const block of blocks(text, "Store")) rows.push(storeRow(file, text, block, pluginId))
   for (const block of blocks(text, "FileView")) {
     const path = propertyValue(block.body, "path")
     if (!path) continue
@@ -182,11 +199,12 @@ function shellWrites(file, pluginId) {
 
 /**
  * @param {{ path: string, kind: string, text: string }} file
- * @param {{ pluginId?: string|null }} [context]
+ * @param {{ pluginId?: string|null, storeBlock?: boolean }} [options] storeBlock: the tree carries the store block unmodified, so `Store {` is a write site
  * @returns {Array} write rows, in file order
  */
-export function extractWrites(file, { pluginId = null } = {}) {
-  if (file.kind === "qml") return qmlWrites(file, pluginId)
+export function extractWrites(file, options = {}) {
+  const { pluginId = null } = options
+  if (file.kind === "qml") return qmlWrites(file, pluginId, options)
   if (file.kind === "js") return jsWrites(file, pluginId)
   if (file.kind === "shell") return shellWrites(file, pluginId)
   if (file.kind === "python") return pythonWrites(file, pluginId)

package/tools/lab/guest.mjs

@@ -0,0 +1,155 @@
+// Talking to the guest: SSH with the lab's own key to 127.0.0.1 and
+// nowhere else, the session established the way a person logs in (the
+// password typed at SDDM through the virtual keyboard until a Hyprland
+// owned by the user exists), and the identity read from inside.
+//
+// The SSH argument list is pure and tests/unit/lab.test.mjs reads it: the
+// key is the base's, the host is the loopback address, BatchMode, no
+// agent, no forwarding of any kind, no known-hosts entry written into the
+// user's file (the guest's host key is new with every base and the
+// connection is to a port QEMU forwards on the loopback interface).
+
+import { spawnSync } from "node:child_process"
+
+export const GUEST_HOST = "127.0.0.1"
+
+/** @param {{ key: string, port: number, user: string }} guest */
+export function sshArgs({ key, port, user }) {
+  return [
+    "-i", key,
+    "-p", String(port),
+    "-o", "BatchMode=yes",
+    "-o", "IdentitiesOnly=yes",
+    "-o", "IdentityAgent=none",
+    "-o", "StrictHostKeyChecking=no",
+    "-o", "UserKnownHostsFile=/dev/null",
+    "-o", "ForwardAgent=no",
+    "-o", "ForwardX11=no",
+    "-o", "ConnectTimeout=5",
+    "-o", "LogLevel=ERROR",
+    `${user}@${GUEST_HOST}`,
+  ]
+}
+
+/**
+ * The environment a command needs to reach the running session from an
+ * SSH login, as the toolchain's `ssh_session` set it: the runtime
+ * directory, the session bus, the Hyprland signature, the Wayland display,
+ * and the Omarchy path from /etc/omarchy.conf when there is one (a
+ * dev-linked guest names its checkout there).
+ */
+export const SESSION_PREAMBLE = [
+  "export XDG_RUNTIME_DIR=/run/user/$(id -u)",
+  "export DBUS_SESSION_BUS_ADDRESS=unix:path=$XDG_RUNTIME_DIR/bus",
+  "export LANG=$(systemctl --user show-environment | sed -n 's/^LANG=//p' | head -1)",
+  "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)",
+  "[[ ! -f /etc/omarchy.conf ]] || source /etc/omarchy.conf",
+  "export OMARCHY_PATH=${OMARCHY_PATH:-/usr/share/omarchy}",
+  "export PATH=$OMARCHY_PATH/bin:$PATH",
+].join("; ")
+
+/** Run one command in the guest; stdout captured, status returned, never a throw. */
+export function sshGuest(guest, command, { input = "", timeoutMs = 120000 } = {}) {
+  const result = spawnSync("ssh", [...sshArgs(guest), command], { encoding: "utf8", input, stdio: ["pipe", "pipe", "pipe"], timeout: timeoutMs })
+  return { status: result.status ?? 255, stdout: result.stdout || "", stderr: result.stderr || "", error: result.error || null }
+}
+
+/** The same, inside the session's environment. */
+export function sshSession(guest, command, options) {
+  return sshGuest(guest, `${SESSION_PREAMBLE}; ${command}`, options)
+}
+
+/** One wait, shared by every lab module that polls. */
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+/** Wait until `ssh true` answers, polling every 5 s like the toolchain; `alive()` says whether the VM is still there. */
+export async function waitForSsh(guest, { timeoutSeconds, alive, onPhase = () => {} }) {
+  const started = Date.now()
+  for (;;) {
+    if (sshGuest(guest, "true", { timeoutMs: 10000 }).status === 0) return Math.round((Date.now() - started) / 1000)
+    if (alive && !(await alive())) throw Object.assign(new Error("the guest exited while the lab waited for SSH"), { code: "guest-exited" })
+    const waited = (Date.now() - started) / 1000
+    if (waited >= timeoutSeconds) throw Object.assign(new Error(`no SSH answer from the guest after ${timeoutSeconds} s`), { code: "guest-timeout" })
+    onPhase(`waiting for the guest's SSH (${Math.round(waited)} s)`)
+    await sleep(5000)
+  }
+}
+
+/** Only a Hyprland owned by the guest user proves the session: SDDM runs a compositor of its own as sddm. */
+export function sessionStarted(guest) {
+  return sshGuest(guest, "pgrep -u $(id -u) -x Hyprland >/dev/null", { timeoutMs: 10000 }).status === 0
+}
+
+/**
+ * Log in at SDDM the way a person does: the password field is focused
+ * for the remembered user, so type the password and Enter, wait ten
+ * seconds, look for Hyprland, repeat. Measured by the toolchain: a login
+ * takes one or two rounds after first boot.
+ */
+export async function establishSession({ guest, socket, password, typeText, press, timeoutSeconds = 300, onPhase = () => {} }) {
+  const started = Date.now()
+  let rounds = 0
+  while (!sessionStarted(guest)) {
+    if ((Date.now() - started) / 1000 >= timeoutSeconds) throw Object.assign(new Error(`no Hyprland session owned by ${guest.user} after ${timeoutSeconds} s`), { code: "session-timeout" })
+    rounds += 1
+    onPhase(`logging in at the greeter (round ${rounds})`)
+    await typeText(socket, password)
+    await press(socket, ["ret"])
+    await sleep(10000)
+  }
+  return { rounds, seconds: Math.round((Date.now() - started) / 1000) }
+}
+
+/** `hyprctl -j layers` says whether a namespace is on screen; used to wait for the startup notifications to go. */
+export function layerPresent(guest, namespace) {
+  return sshSession(guest, `hyprctl -j layers | jq -e --arg namespace '${namespace}' '[.. | objects | select(.namespace? == $namespace)] | length > 0'`).status === 0
+}
+
+/**
+ * The startup notifications a fresh base shows, dismissed so a suite's
+ * screen is deterministic; a notification the suite raises later is its
+ * own. Ported from the toolchain's clear_startup_notifications.
+ */
+export async function clearStartupNotifications(guest, { onPhase = () => {} } = {}) {
+  onPhase("waiting for the notification service")
+  const deadline = Date.now() + 15000
+  while (sshSession(guest, "omarchy-shell notifications ping >/dev/null").status !== 0) {
+    if (Date.now() > deadline) return { cleared: false, reason: "the notification service did not answer within 15 s" }
+    await sleep(1000)
+  }
+  sshSession(guest, "omarchy-shell notifications dismissAll >/dev/null")
+  const gone = Date.now() + 15000
+  while (layerPresent(guest, "omarchy-notifications")) {
+    if (Date.now() > gone) return { cleared: false, reason: "the notification layer stayed on screen for 15 s after dismissAll" }
+    await sleep(1000)
+  }
+  return { cleared: true, reason: null }
+}
+
+/**
+ * Who the guest is, read from inside before any suite runs: the installed
+ * omarchy package, the kernel, and whether the session is running from
+ * the package or from a linked checkout (`OMARCHY_PATH` in
+ * /etc/omarchy.conf; a dev-linked guest names `.local/share/omarchy`).
+ * This is the line the old gates never wrote (docs/history/2026-09-18-lab-
+ * inventory.md P8), and packaging/LAB_PLAN.md's run identity requires.
+ */
+export function guestIdentity(guest) {
+  const read = (command) => sshGuest(guest, command).stdout.trim()
+  const omarchyPackage = read("pacman -Q omarchy 2>/dev/null")
+  const version = omarchyPackage.split(/\s+/)[1] || null
+  const conf = read("cat /etc/omarchy.conf 2>/dev/null")
+  const omarchyPath = conf.match(/^OMARCHY_PATH=(.+)$/m)?.[1]?.replace(/^["']|["']$/g, "") || null
+  const linked = Boolean(omarchyPath && !/^\/usr\/share\/omarchy\/?$/.test(omarchyPath))
+  return {
+    omarchyPackage: omarchyPackage || null,
+    version,
+    kernel: read("uname -r") || null,
+    hostname: read("cat /etc/hostname") || null,
+    omarchyPath,
+    linked,
+    testedSource: linked ? `linked checkout at ${omarchyPath}` : (omarchyPackage ? `installed package ${omarchyPackage}` : "unknown"),
+  }
+}

package/tools/lab/harness.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/bash
+# The one harness every suite runs through, on the host, against a guest
+# that `omakit lab prove` has already booted, logged in and identified.
+#
+#   bash tools/lab/harness.sh <suite.sh> <run-dir> <ssh-key> <ssh-port> <qmp-socket> <repo-root> <session-preamble> <guest-user> <guest-password> [suite arguments...]
+#
+# Every value comes in as an argument, none from the environment: omakit
+# reads no variable of its own, and the harness inherits that. The suite
+# file defines `omakit_lab_suite`, which gets the suite arguments and the
+# helpers below, the same six the toolchain's host tests had (log,
+# ssh_guest, ssh_session, wait_for_guest_state, capture_console, RUN_DIR)
+# plus the staging and detached-job helpers the three gates each wrote for
+# themselves (docs/history/2026-09-18-lab-inventory.md P1). Nothing here
+# reaches the host's own session: every ssh goes to 127.0.0.1 on the
+# forwarded port with the lab's key, and tests/unit/lab.test.mjs reads
+# this file for the words it must not contain.
+set -u
+set -o pipefail
+
+LAB_SUITE_FILE=$1; RUN_DIR=$2; LAB_SSH_KEY=$3; LAB_SSH_PORT=$4; LAB_QMP_SOCKET=$5; OMAKIT_DIR=$6; LAB_SESSION_PREAMBLE=$7; GUEST_USER=$8; GUEST_PASSWORD=$9
+shift 9
+
+log() { printf '==> %s\n' "$1"; }
+
+ssh_guest() {
+  ssh -i "$LAB_SSH_KEY" -p "$LAB_SSH_PORT" \
+    -o BatchMode=yes -o IdentitiesOnly=yes -o IdentityAgent=none \
+    -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+    -o ForwardAgent=no -o ForwardX11=no -o ConnectTimeout=5 -o LogLevel=ERROR \
+    "$GUEST_USER@127.0.0.1" "$@"
+}
+
+# The same command inside the session: the preamble omakit built (the
+# runtime directory, the session bus, the Hyprland signature, the Wayland
+# display, the Omarchy path) comes in as one argument, so bash and Node
+# agree on it by construction.
+ssh_session() {
+  ssh_guest "$LAB_SESSION_PREAMBLE; $1" </dev/null
+}
+
+wait_for_guest_state() {
+  local description="$1" timeout="$2"
+  shift 2
+  local deadline=$((SECONDS + timeout))
+  until "$@" >/dev/null 2>&1; do
+    if ((SECONDS >= deadline)); then
+      printf 'not ok - %s\n' "$description" >&2
+      return 1
+    fi
+    sleep 1
+  done
+  printf 'ok - %s\n' "$description"
+}
+
+# A screendump into the run directory, converted to PNG when magick is on
+# PATH and left as PPM otherwise; QMP is spoken by node, never by socat.
+capture_console() {
+  local name="$1" shot="$RUN_DIR/$1.ppm"
+  sleep 1
+  node "$OMAKIT_DIR/tools/lab/qmp-cli.mjs" "$LAB_QMP_SOCKET" screendump "$shot" >/dev/null 2>&1 || return 0
+  [[ -s $shot ]] || { rm -f "$shot"; return 0; }
+  if command -v magick >/dev/null 2>&1; then
+    magick "$shot" "$RUN_DIR/$name.png" 2>/dev/null && rm -f "$shot"
+  fi
+  return 0
+}
+
+# A directory into the guest, whole, under a fresh destination.
+stage_tree() {
+  local src="$1" dest="$2"
+  shift 2
+  tar -C "$src" "$@" -cf - . | ssh_guest "rm -rf $dest && mkdir -p $dest && tar -C $dest -xf -"
+}
+
+# Named paths under a source directory into the guest, under a destination.
+stage_paths() {
+  local src="$1" dest="$2"
+  shift 2
+  tar -C "$src" -cf - "$@" | ssh_guest "mkdir -p $dest && tar -C $dest -xf -"
+}
+
+# A staged tree turned into a local git repository in the guest, which is
+# what omarchy-plugin-add takes.
+stage_plugin() {
+  stage_tree "$1" "$2" --exclude=.git --exclude=.cache --exclude=node_modules
+  ssh_guest "git -C $2 init -q && git -C $2 add . && git -C $2 -c user.name=Lab -c user.email=lab@invalid commit -qm staged"
+}
+
+# One detached job in the session: a suite that restarts the shell, or
+# that must outlive the ssh call, runs under setsid and reports through a
+# done file; its log is copied back beside host.log when it ends.
+#   guest_job <tag> <limit-seconds> <command>
+guest_job() {
+  local tag="$1" limit="$2" command="$3"
+  ssh_session "rm -f /tmp/omakit-lab-$tag.done /tmp/omakit-lab-$tag.log; \
+    setsid bash -c '$command > /tmp/omakit-lab-$tag.log 2>&1; echo \$? > /tmp/omakit-lab-$tag.done' >/dev/null 2>&1 < /dev/null &" || return 1
+  wait_for_guest_state "the $tag job finished" "$limit" ssh_guest "test -f /tmp/omakit-lab-$tag.done" || {
+    ssh_guest "tail -n 40 /tmp/omakit-lab-$tag.log" || true
+    ssh_guest "cat /tmp/omakit-lab-$tag.log" > "$RUN_DIR/$tag.log" 2>/dev/null || true
+    return 1
+  }
+  ssh_guest "cat /tmp/omakit-lab-$tag.log" > "$RUN_DIR/$tag.log" 2>/dev/null || true
+}
+guest_job_status() { ssh_guest "cat /tmp/omakit-lab-$1.done"; }
+
+# A file out of the guest into the run directory.
+guest_file() { ssh_guest "cat $1" > "$RUN_DIR/$2" 2>/dev/null; }
+
+# The two questions every gate asks after its suite: the shell answers,
+# and Hyprland reports no configuration error.
+guest_shell_healthy() {
+  ssh_session "omarchy-shell shell ping | grep -qx ok" || { echo "the guest's shell does not answer after the suite" >&2; return 1; }
+  ssh_session "test -z \"\$(hyprctl configerrors)\"" || { echo "hyprctl reports configuration errors after the suite" >&2; return 1; }
+}
+
+# shellcheck source=/dev/null
+source "$LAB_SUITE_FILE"
+declare -F omakit_lab_suite >/dev/null || { echo "$LAB_SUITE_FILE must define omakit_lab_suite()" >&2; exit 2; }
+omakit_lab_suite "$@"

package/tools/lab/host.mjs

@@ -0,0 +1,177 @@
+// What the host has and what it lacks, each with its measured reason.
+//
+// Read-only: every probe is a stat, a read of /proc, or a `--version`.
+// Nothing here installs anything (packaging/LAB_PLAN.md: lab-only host
+// capabilities are preflighted and reported, never installed). Measured
+// before this (docs/history/2026-09-18-lab-inventory.md P10, P20): the
+// upstream harness ran `omarchy-pkg-add` for six packages at the top of
+// every invocation, and the old doctor refused on the first missing thing
+// without saying what it cost.
+
+import { accessSync, constants, existsSync, readFileSync, statSync, statfsSync } from "node:fs"
+import { spawnSync } from "node:child_process"
+import { cpus } from "node:os"
+import { dirname } from "node:path"
+import { labPin } from "./pin.mjs"
+
+export const OVMF_CODE = "/usr/share/edk2/x64/OVMF_CODE.4m.fd"
+export const OVMF_VARS_TEMPLATE = "/usr/share/edk2/x64/OVMF_VARS.4m.fd"
+
+/** The commands a run needs, and what each is for. `--version` is the whole question asked of any of them here. */
+export const RUN_COMMANDS = Object.freeze([
+  Object.freeze({ command: "qemu-system-x86_64", package: "qemu-full", why: "boots the guest" }),
+  Object.freeze({ command: "qemu-img", package: "qemu-full", why: "creates the per-run overlay and inspects disks" }),
+  Object.freeze({ command: "ssh", versionArgs: ["-V"], package: "openssh", why: "runs the suite in the guest" }),
+])
+
+/** What base preparation needs beyond a run: the toolchain's console driver reads the installer's screen. */
+export const BUILD_COMMANDS = Object.freeze([
+  Object.freeze({ command: "socat", versionArgs: ["-V"], package: "socat", why: "the toolchain's QMP transport" }),
+  Object.freeze({ command: "magick", package: "imagemagick", why: "the toolchain's screendump conversion" }),
+  Object.freeze({ command: "tesseract", package: "tesseract, tesseract-data-eng", why: "the toolchain reads the installer's screens" }),
+  // `-l -f /dev/null` is a read that fails; a bare `ssh-keygen` starts
+  // generating a key at ~/.ssh/id_ed25519 (measured: it printed
+  // "Generating public/private ed25519 key pair." under this probe). The
+  // probe's output is an error sentence, not a version, so the line says
+  // the command is there and nothing it printed (measured on 2026-09-19:
+  // doctor showed "ok  ssh-keygen  /dev/null is not a public key file.").
+  Object.freeze({ command: "ssh-keygen", versionArgs: ["-l", "-f", "/dev/null"], presenceOnly: true, package: "openssh", why: "the guest's lab key" }),
+  Object.freeze({ command: "python3", package: "python", why: "the toolchain's one-file bootstrap server" }),
+])
+
+/** What acquisition needs: the signature check. */
+export const VERIFY_COMMANDS = Object.freeze([
+  Object.freeze({ command: "gpg", package: "gnupg", why: "verifies the release signature against the packaged key" }),
+])
+
+/**
+ * Whether a command is on PATH, and the first line it prints for its
+ * version. Presence is what matters and is read from the spawn itself: a
+ * command that is there answers, whatever its exit status (`ssh -V` prints
+ * on stderr, `ssh-keygen` has no version flag and prints usage with exit
+ * 1), and one that is not is ENOENT.
+ */
+function versionOf(entry, run = spawnSync, env = process.env) {
+  const result = run(entry.command, [...(entry.versionArgs || ["--version"])], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 4000, env })
+  if (result.error?.code === "ENOENT") return null
+  if (entry.presenceOnly) return `${entry.command} is on PATH (${entry.package})`
+  const line = `${result.stdout || ""}\n${result.stderr || ""}`.split("\n").map((l) => l.trim()).find(Boolean)
+  return line || `${entry.command} is on PATH`
+}
+
+/** One line per command: present with its first version line, or missing with the package that provides it. */
+export function probeCommands(list, { run, env = process.env } = {}) {
+  return list.map((entry) => {
+    const version = versionOf(entry, run, env)
+    return {
+      name: entry.command,
+      state: version ? "ok" : "missing",
+      reason: version ? version : `${entry.command} is not on PATH (${entry.why})`,
+      remedy: version ? null : `sudo pacman -S --needed ${entry.package}`,
+    }
+  })
+}
+
+/**
+ * Where this process runs, when /dev/kvm is not there: a container leaves
+ * marks (`/.dockerenv`, `/run/.containerenv`, a container runtime in
+ * /proc/1/cgroup), and a loaded kvm module without its device node is a
+ * missing node, not a missing kernel feature. Measured on 2026-09-19 by a
+ * first user whose `doctor` said /dev/kvm was absent on the machine whose
+ * lab suites had run hours earlier: the product was run from inside a
+ * sandbox without the device, and the message blamed the kernel and the
+ * firmware (docs/evidence/ux/2026-09-19-first-user-test.json, finding 11).
+ */
+export function kvmContext({ files = { dockerenv: "/.dockerenv", containerenv: "/run/.containerenv", cgroup: "/proc/1/cgroup", module: "/sys/module/kvm" } } = {}) {
+  const marks = []
+  if (existsSync(files.dockerenv)) marks.push(files.dockerenv)
+  if (existsSync(files.containerenv)) marks.push(files.containerenv)
+  try {
+    const cgroup = readFileSync(files.cgroup, "utf8")
+    const runtime = cgroup.match(/docker|lxc|podman|containerd|libpod|machine\.slice|nspawn/)?.[0]
+    if (runtime) marks.push(`${files.cgroup} names ${runtime}`)
+  } catch {
+    // no cgroup file to read: not Linux, or no /proc; nothing to conclude
+  }
+  return { container: marks.length > 0, marks, moduleLoaded: existsSync(files.module) }
+}
+
+/** /dev/kvm: a character device this user can open for reading and writing, which is what QEMU needs from it. */
+export function probeKvm(path = "/dev/kvm", context = kvmContext) {
+  try {
+    const st = statSync(path)
+    if (!st.isCharacterDevice()) return { name: "kvm", state: "missing", reason: `${path} is not a character device`, remedy: "load the kvm module for this CPU (kvm_amd or kvm_intel)" }
+    accessSync(path, constants.R_OK | constants.W_OK)
+    return { name: "kvm", state: "ok", reason: `${path} is a character device this user can open read-write` }
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      const where = context()
+      if (where.container) return { name: "kvm", state: "missing", reason: `${path} is not there in this environment, which is a container (${where.marks.join("; ")}); the host's device is not mapped in, and a lab that ran on the host says nothing about this process`, remedy: "run omakit on the host itself, or start the container with --device /dev/kvm" }
+      if (where.moduleLoaded) return { name: "kvm", state: "missing", reason: `${path} is not there although the kvm module is loaded (/sys/module/kvm exists): the device node is missing, or this process runs in a mount namespace without the host's /dev`, remedy: "check udev for /dev/kvm on the host, or run omakit outside the sandbox" }
+      return { name: "kvm", state: "missing", reason: `${path} is not there and no kvm module is loaded: virtualisation may be off in firmware, or this is a virtual machine without nested virtualisation`, remedy: "enable virtualisation in firmware (kvm_amd or kvm_intel loads on its own); a guest without KVM is not something the lab runs" }
+    }
+    return { name: "kvm", state: "missing", reason: `${path} exists but this user cannot open it (${error.code}): a permission of the device node or a group this login does not carry yet`, remedy: "sudo usermod -aG kvm $USER, then log in again (a new login picks the group up; a new shell does not)" }
+  }
+}
+
+/** The two firmware files QEMU boots the guest with, readable. */
+export function probeOvmf(code = OVMF_CODE, vars = OVMF_VARS_TEMPLATE) {
+  const missing = [code, vars].filter((file) => {
+    try {
+      accessSync(file, constants.R_OK)
+      return false
+    } catch {
+      return true
+    }
+  })
+  if (missing.length) return { name: "ovmf", state: "missing", reason: `${missing.join(" and ")} not readable`, remedy: "sudo pacman -S --needed edk2-ovmf" }
+  return { name: "ovmf", state: "ok", reason: `${code} (${statSync(code).size.toLocaleString("en-US")} B) and the ${statSync(vars).size.toLocaleString("en-US")} B variables template readable` }
+}
+
+/** Free bytes on the filesystem that holds (or would hold) the lab cache, from the nearest existing ancestor. */
+export function freeBytesAt(path) {
+  let probe = path
+  while (!existsSync(probe)) {
+    const parent = dirname(probe)
+    if (parent === probe) break
+    probe = parent
+  }
+  const fs = statfsSync(probe)
+  return { path: probe, bytes: Number(fs.bavail) * Number(fs.bsize) }
+}
+
+/** MemTotal and MemAvailable from /proc/meminfo, in bytes. */
+export function memoryBytes(file = "/proc/meminfo") {
+  const text = readFileSync(file, "utf8")
+  const read = (key) => Number(text.match(new RegExp(`^${key}:\\s+(\\d+) kB`, "m"))?.[1] || 0) * 1024
+  return { total: read("MemTotal"), available: read("MemAvailable") }
+}
+
+/**
+ * The host for a run: KVM, the three commands, the firmware, memory against
+ * the guest's, and the CPU count the guest gets. `--json` carries the same
+ * fields.
+ */
+export function probeRunHost({ pin = labPin(), run, env = process.env } = {}) {
+  const memory = memoryBytes()
+  const guestBytes = pin.guest.memoryMiB * 1024 * 1024
+  const lines = [probeKvm(), ...probeCommands(RUN_COMMANDS, { run, env }), probeOvmf()]
+  lines.push({
+    name: "memory",
+    state: memory.total >= guestBytes * 1.5 ? "ok" : "missing",
+    reason: `${(memory.total / 2 ** 20).toFixed(0)} MiB total, ${(memory.available / 2 ** 20).toFixed(0)} MiB available; the guest takes ${pin.guest.memoryMiB} MiB`,
+    remedy: memory.total >= guestBytes * 1.5 ? null : `the guest needs ${pin.guest.memoryMiB} MiB and the host its own; this host has less than one and a half times that`,
+  })
+  lines.push({ name: "cpus", state: "ok", reason: `${cpus().length} logical CPUs, and the guest gets every one, as the toolchain's -smp $(nproc) gave the reference build (32, M14)` })
+  return lines
+}
+
+/**
+ * The vCPU count a run gives the guest: every logical CPU, which is what
+ * the toolchain's `-smp $(nproc)` gave the reference build (32, packaging/LAB_PLAN.md M4, M14). A
+ * smaller number would be a guess about what a suite needs, and no run
+ * has measured one.
+ */
+export function guestCpus() {
+  return Math.max(1, cpus().length)
+}