omakit 0.5.1 → 0.6.1

package/tools/inspect/patterns.mjs

@@ -34,11 +34,20 @@ function hasFlag(flags, letter, long = null) {
   return flags.some((flag) => flag === `-${letter}` || (long && (flag === long || flag.startsWith(`${long}=`))) || (/^-[A-Za-z]+$/.test(flag) && flag.includes(letter)))
 }
 
-/** The tool a process resolves through PATH: its first non-wrapper word when that word has no slash. */
+/**
+ * The tool a process resolves through PATH: its first non-wrapper word
+ * when that word is a literal with no slash. A word that is an expression
+ * (`[script, name]`, `[root.helperPath("x.sh")]`) is not a name looked up
+ * in PATH; it is a value the text does not show, and the argument-grammar
+ * class already names the site. Measured on the Theme Manager port
+ * (2026-09-17): 12 of its 24 Run sites read as "resolved from PATH" with
+ * the tool `script`, an absolute path at run time.
+ */
 function pathResolved(process) {
   if (!Array.isArray(process.argv) || !process.argv.length) return null
-  const { tool } = toolOf(process.argv)
+  const { tool, index } = toolOf(process.argv)
   if (!tool || tool.includes("/")) return null
+  if ((process.expressions || []).some((entry) => entry.index === index)) return null
   return tool
 }
 
@@ -222,13 +231,19 @@ export const PATTERNS = Object.freeze([
     share: 0.07,
     sample: SAMPLE,
     precondition: ({ processes, hosts }) => {
-      const resolved = processes.map((row) => ({ row, tool: pathResolved(row) })).filter((entry) => entry.tool)
+      // A line of a helper started through Run resolves its tools in the
+      // block's closed PATH (docs/BLOCKS.md); it is counted apart, never as
+      // an ambient lookup.
+      const ambient = processes.filter((row) => !row.closedEnvironment)
+      const resolved = ambient.map((row) => ({ row, tool: pathResolved(row) })).filter((entry) => entry.tool)
+      const closed = processes.filter((row) => row.closedEnvironment && pathResolved(row))
       const curls = hosts.filter((row) => row.tool === "curl" && !hasFlag(row.flags, "q", "--disable"))
       const parts = []
       const names = [...new Set(resolved.map((entry) => entry.tool))]
       const named = names.length > 6 ? `${names.slice(0, 6).join(", ")} and ${names.length - 6} more` : names.join(", ")
       if (resolved.length) parts.push(`${plural(resolved.length, "tool")} resolved from PATH (${named}; ${sites(resolved.map((entry) => entry.row))})`)
       if (curls.length) parts.push(`curl without -q (${sites(curls)})`)
+      if (closed.length) parts.push(`${plural(closed.length, "tool name")} in ${plural(new Set(closed.map((row) => row.file)).size, "helper")} started through Run, resolved in the block's closed PATH and not counted`)
       return { sites: [...resolved.map((entry) => entry.row), ...curls].map(site), observation: `observed ${parts.join("; ")}` }
     },
   },

package/tools/inspect/processes.mjs

@@ -1,5 +1,7 @@
 // Process sites: every `Process {` block in QML (its `command:` inside the
-// block or assigned to its id elsewhere in the file), every
+// block or assigned to its id elsewhere in the file), every `Run {` block
+// where the tree carries the omakit run block unmodified (its deadline and
+// caps are the block's, docs/BLOCKS.md), every
 // `Quickshell.execDetached([...])`, and every command line of a shell
 // script. Each row carries the argv the text shows, whether a deadline is
 // observed for it, what collects its output and whether a producer-side
@@ -167,6 +169,7 @@ function qmlRow(file, text, block, command, commandOffset) {
     deadline: deadlineFor(text, id, resolved.argv),
     output: outputOf(block.body, resolved.argv),
     shellWrapper: isShellWrapper(resolved.argv),
+    closedEnvironment: false,
     pipedFrom: null,
   }
 }
@@ -195,16 +198,42 @@ function detachedRows(file, text) {
       deadline: { observed: false, via: null, ms: null },
       output: { collector: "none", capObserved: false, via: null },
       shellWrapper: isShellWrapper(resolved.argv),
+      closedEnvironment: false,
       pipedFrom: null,
     })
   }
   return rows
 }
 
-/** Every `Process {` block and detached exec in a QML file. */
-export function qmlProcesses(file) {
+/**
+ * A `Run {` site of the omakit run block: the deadline is the block's
+ * (`deadlineMs`, default 10000), the caps are the block's (`maxBytes`),
+ * and a shell string is refused unless `allowShellString: true` is on the
+ * block's own line, in which case the wrapper is observed as it would be
+ * on a Process.
+ */
+function runRow(file, text, block) {
+  const inside = propertyValue(block.body, "command")
+  const command = inside && !/^\[\s*\]$/.test(inside.text) ? inside : assignedCommand(text, block.id)
+  const offset = inside && !/^\[\s*\]$/.test(inside.text) ? block.open + 1 + inside.offset : command ? command.offset : null
+  const row = qmlRow(file, text, block, command, offset)
+  const deadline = numeric(propertyValue(block.body, "deadlineMs")?.text)
+  const allowShellString = propertyValue(block.body, "allowShellString")?.text === "true"
+  return {
+    ...row,
+    running: row.running || (block.id ? new RegExp(`(?<![\\w.])${block.id}\\.start\\s*\\(`).test(text) : false),
+    block: "run",
+    deadline: { observed: true, via: "block-run", ms: deadline ?? 10000 },
+    output: { collector: "Run", capObserved: true, via: "maxBytes" },
+    shellWrapper: allowShellString ? row.shellWrapper : false,
+  }
+}
+
+/** Every `Process {` block and detached exec in a QML file; `Run {` blocks too when the tree carries the run block. */
+export function qmlProcesses(file, { runBlock = false } = {}) {
   const text = blankComments(file.text)
   const rows = []
+  if (runBlock) for (const block of blocks(text, "Run")) rows.push(runRow(file, text, block))
   for (const block of blocks(text, "Process")) {
     const inside = propertyValue(block.body, "command")
     // `command: []` is a placeholder for a value set later: the assignment to
@@ -235,6 +264,9 @@ function commandWords(segment) {
     if (words[0] === "for" || words[0] === "case" || words[0] === "select" || words[0] === "function") return null
     words = words.slice(1)
   }
+  // `exec cmd` replaces the shell with cmd: a process site, the wrapper
+  // dropped; `exec` alone or with only redirections runs nothing.
+  while (words.length > 1 && words[0] === "exec" && !/^[<>&\d]/.test(words[1])) words = words.slice(1)
   if (!words.length) return null
   if (/^[A-Za-z_]\w*\(\)$/.test(words[0])) return null
   if (BUILTINS.has(basename(words[0])) && basename(words[0]) !== "eval") return null
@@ -278,6 +310,7 @@ export function shellProcesses(file) {
         deadline: stripped.some((word) => basename(word) === "timeout") ? { observed: true, via: "timeout-argv", ms: deadlineMs } : { observed: false, via: null, ms: null },
         output: { collector: "none", capObserved: lineCap.observed, via: lineCap.via },
         shellWrapper: isShellWrapper(stripped),
+        closedEnvironment: false,
         pipedFrom: segment.operator === "|" || segment.operator === "|&" ? previous : null,
       }
       rows.push(row)
@@ -291,8 +324,8 @@ export function shellProcesses(file) {
  * @param {{ path: string, kind: string, text: string }} file
  * @returns {Array} process rows, in file order
  */
-export function extractProcesses(file) {
-  if (file.kind === "qml") return qmlProcesses(file)
+export function extractProcesses(file, options = {}) {
+  if (file.kind === "qml") return qmlProcesses(file, options)
   if (file.kind === "shell") return shellProcesses(file)
   return []
 }

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"
 
@@ -106,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"
@@ -263,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`
@@ -336,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 = [
@@ -370,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 "$@"