omakit 0.6.8 → 0.6.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omakit",
-  "version": "0.6.8",
+  "version": "0.6.10",
   "description": "Tested plumbing, the marketplace's own checks, and a disposable Omarchy to test in.",
   "license": "MIT",
   "author": "Maarten Tolhuijs",

package/tools/blocks/commit.json

@@ -1,5 +1,5 @@
 {
-  "commit": "0c11dd5671c8ed65a89ea71a2bf44ab5f38b1a90",
-  "recordedAt": "2026-09-23T07:35:32.560Z",
+  "commit": "517b87d52ba42465a12ab5722e979ed6f8d27805",
+  "recordedAt": "2026-10-01T02:52:49.108Z",
   "how": "Written by `node tools/blocks/record-commit.mjs` in the release workflow before `npm pack`, so a packaged omakit, which has no Git checkout, still names the commit its block files come from. In a checkout this file is null and `git rev-parse HEAD` is the source; a package with null here was packed without the release step, and `omakit add` refuses to stamp a header it cannot name."
 }

package/tools/lab/guest.mjs

@@ -134,7 +134,7 @@ export async function clearStartupNotifications(guest, { onPhase = () => {} } =
  * 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.
+ * inventory.md P8), and docs/LAB.md's run identity requires.
  */
 export function guestIdentity(guest) {
   const read = (command) => sshGuest(guest, command).stdout.trim()

package/tools/lab/host.mjs

@@ -1,7 +1,7 @@
 // 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
+// Nothing here installs anything (docs/LAB.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
@@ -168,7 +168,7 @@ export function probeRunHost({ pin = labPin(), run, env = process.env } = {}) {
 
 /**
  * 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
+ * the toolchain's `-smp $(nproc)` gave the reference build (32, M14). A
  * smaller number would be a guess about what a suite needs, and no run
  * has measured one.
  */

package/tools/lab/inspect.mjs

@@ -1,12 +1,15 @@
-// `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.
+// `omakit lab inspect`, and the lab lines of `omakit doctor`: the newest
+// release as the caller found it, what is on disk, whether it was
+// verified, whether the base is behind, what the host is missing, and
+// what each missing thing costs. Read-only: no directory is created, no
+// file is written, nothing is fetched here; the one read of the release
+// list is the caller's (release.mjs), handed in as `newest`. `--verify`
+// re-hashes the ISO and re-checks the signature now instead of reporting
+// the record.
 
-import { existsSync, readdirSync, statSync } from "node:fs"
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs"
 import { join } from "node:path"
-import { LAB_DIR, bytesBoth, durationWords, labPin } from "./pin.mjs"
+import { LAB_DIR, bytesBoth, compareVersions, durationWords, guestIsRelease, labPin, releaseOf, VERSION } 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"
@@ -26,13 +29,54 @@ export function downloadDir(layout, pin = labPin()) {
   return join(layout.downloads, pin.release.sha256)
 }
 
+/**
+ * The release the base on disk was built from, in the lab's release
+ * shape, from its manifest; null when there is no readable manifest. A
+ * run uses the base it has, so this is what a run holds the base to.
+ */
+export function baseRelease(layout, pin = labPin()) {
+  const manifest = readJson(join(layout.base, BASE_FILES.manifest))
+  const release = manifest?.release
+  if (!release || !VERSION.test(String(release.name)) || !/^[0-9a-f]{64}$/.test(String(release.sha256)) || !Number.isSafeInteger(release.bytes)) return null
+  return releaseOf(pin, { name: release.name, bytes: release.bytes, sha256: release.sha256 })
+}
+
+/**
+ * What one download directory holds, from its own files: the verification
+ * record names its release (a record written before 0.6.9 names only the
+ * digest, and then the ISO is the one `omarchy-<version>.iso` there).
+ * `{ name, fileName, record, verified }`, each null or false when absent.
+ */
+export function downloadEntry(dir, digest) {
+  const record = readJson(join(dir, "verified.json"))
+  let fileName = record?.fileName || null
+  let partial = null
+  if (!fileName && existsSync(dir)) {
+    try {
+      const names = readdirSync(dir)
+      fileName = names.find((name) => /^omarchy-\d+\.\d+\.\d+\.iso$/.test(name)) || null
+      partial = names.find((name) => /^omarchy-\d+\.\d+\.\d+\.iso\.part$/.test(name)) || null
+    } catch {
+      fileName = null
+    }
+  }
+  // A partial download names its release by its file name too, so a newer
+  // one is never mistaken for an older one.
+  const name = record?.name || (fileName || partial || "").match(/^omarchy-(\d+\.\d+\.\d+)\.iso/)?.[1] || null
+  const verified = Boolean(record) && record.sha256 === digest && Boolean(fileName) && existsSync(join(dir, fileName))
+  return { name, fileName, record, verified }
+}
+
 /**
  * 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.
+ * millisecond, and `--verify` is the five-second re-hash. With no release
+ * to look for (the newest was not found and there is no base), there is
+ * nothing to hold a file to, and the reason says so.
  */
 export function inspectDownload(layout, pin = labPin(), { verify = false, stagingRoot = layout.staging, onProgress } = {}) {
+  if (!pin.release) return { dir: null, iso: null, present: false, bytes: null, partial: null, record: null, verified: false, reason: "no release to look for: the newest was not found and there is no base to name one", sidecars: { checksum: false, signature: false } }
   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`) } }
@@ -65,10 +109,24 @@ export function inspectDownload(layout, pin = labPin(), { verify = false, stagin
 }
 
 /**
- * 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.
+ * The base, against `pin.release` (the newest release, or the base's own
+ * when a run holds it to itself):
+ * - `missing`: no base directory.
+ * - `invalid`: files without a complete manifest, or a disk whose size is
+ *   not the recorded one; never booted.
+ * - `ready`: built from exactly this release (name and ISO digest), its
+ *   guest the release's own package.
+ * - `outdated`: a good base of an older release, or of this release as it
+ *   was published before Omarchy replaced the ISO; a run still uses it,
+ *   and `setup` builds the newest and replaces it once that verifies.
+ * - `ahead`: a good base of a release newer than this one. Kept and used:
+ *   the release search passes a newer tag over on a 404, so a moment when
+ *   its checksum is being republished, or an offline `--from` of an older
+ *   file, would otherwise take a good base back a release and delete the
+ *   newer ISO. The lab never goes back on its own.
+ * - `mismatch`: a base whose guest is not its release's package.
+ * 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
@@ -77,7 +135,8 @@ export function inspectBase(layout, pin = labPin()) {
   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) {
+  const named = manifest?.release && VERSION.test(String(manifest.release.name)) && /^[0-9a-f]{64}$/.test(String(manifest.release.sha256)) && Number.isSafeInteger(manifest.release.bytes)
+  if (!manifest || manifest.state !== "ready" || !named || !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
@@ -101,13 +160,37 @@ export function inspectBase(layout, pin = labPin()) {
       return out
     }
   }
-  if (manifest.release.sha256 !== pin.release.sha256 || manifest.guest.version !== pin.release.expectedGuestVersion) {
+  const built = { name: manifest.release.name }
+  const described = `Omarchy ${manifest.release.name}, guest omarchy ${manifest.guest.version}; ${bytesBoth(out.allocatedBytes)}; created ${manifest.createdAt}`
+  if (!guestIsRelease(manifest.guest.version, built)) {
     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`
+    out.reason = `the base is Omarchy ${manifest.release.name} and its guest runs omarchy ${manifest.guest.version}, another release's package; \`omakit lab setup\` replaces it`
+    return out
+  }
+  const release = pin.release
+  if (!release) {
+    out.state = "ready"
+    out.reason = described
+    return out
+  }
+  const order = compareVersions(manifest.release.name, release.name)
+  if (order === 0 && manifest.release.sha256 === release.sha256) {
+    out.state = "ready"
+    out.reason = described
+    return out
+  }
+  if (order < 0) {
+    out.state = "outdated"
+    out.reason = `Omarchy ${manifest.release.name} (guest omarchy ${manifest.guest.version}); Omarchy ${release.name} is the newest release. A run still uses this base; \`omakit lab setup\` builds ${release.name} and replaces it once the new one verifies`
+    return out
+  }
+  if (order === 0) {
+    out.state = "outdated"
+    out.reason = `Omarchy ${manifest.release.name} as first published (iso ${manifest.release.sha256}); Omarchy has since republished it (iso ${release.sha256}). A run still uses this base; \`omakit lab setup\` rebuilds it from the republished ISO`
     return out
   }
-  out.state = "ready"
-  out.reason = `Omarchy ${manifest.release.name}, guest omarchy ${manifest.guest.version}; ${bytesBoth(out.allocatedBytes)}; created ${manifest.createdAt}`
+  out.state = "ahead"
+  out.reason = `Omarchy ${manifest.release.name} (guest omarchy ${manifest.guest.version}), newer than ${release.name}, the release this was held to; kept and used, never taken back a release (if Omarchy withdrew ${manifest.release.name}, \`omakit lab prune\` removes it and \`omakit lab setup\` builds ${release.name})`
   return out
 }
 
@@ -156,7 +239,45 @@ export function toolchainCommand(pin = labPin(), dir = join(labLayout().cache, "
   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). */
+/**
+ * QEMU processes a build under `dir` left running: the toolchain starts
+ * its guest with -daemonize and a pidfile under the staging directory, so
+ * a setup interrupted mid-build (measured on 2026-09-23: a 4.0.3 build
+ * interrupted at 09:49 left its QEMU running at a third of a core, and it
+ * was still writing the staged disk eighteen minutes later) leaves a guest
+ * no command owns, and its QMP socket is in /tmp, where the socket check
+ * below cannot see it. A pid counts only while /proc names it with this
+ * directory, so a reused pid is never taken for it. Reads only.
+ */
+export function buildGuests(dir) {
+  const found = []
+  const runsRoot = join(dir, "test-runs")
+  if (!existsSync(runsRoot)) return found
+  for (const release of readdirSync(runsRoot)) {
+    const runs = join(runsRoot, release, "runs")
+    if (!existsSync(runs)) continue
+    for (const run of readdirSync(runs)) {
+      const pidFile = join(runs, run, "qemu.pid")
+      let pid
+      try {
+        pid = Number(readFileSync(pidFile, "utf8").trim())
+      } catch {
+        continue
+      }
+      if (!Number.isSafeInteger(pid) || pid <= 1) continue
+      let cmdline = ""
+      try {
+        cmdline = readFileSync(`/proc/${pid}/cmdline`, "utf8")
+      } catch {
+        continue
+      }
+      if (cmdline.split("\0").some((arg) => arg.includes(`${dir}/`))) found.push({ pid, pidFile })
+    }
+  }
+  return found
+}
+
+/** Staging directories, each with whether a QEMU still answers on its socket or runs from its pidfile (the cross-namespace liveness question). */
 export async function inspectStaging(layout) {
   if (!existsSync(layout.staging)) return []
   const entries = []
@@ -170,8 +291,9 @@ export async function inspectStaging(layout) {
     }
     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 })
+    const guests = buildGuests(dir)
+    const alive = (existsSync(socket) ? (await qmpAlive(socket)).alive : false) || guests.length > 0
+    entries.push({ name, dir, allocatedBytes: allocatedBytes(dir), alive, socket: existsSync(socket) ? socket : null, pids: guests.map((guest) => guest.pid) })
   }
   return entries
 }
@@ -194,13 +316,19 @@ export async function inspectLock(layout) {
 }
 
 /**
- * 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.
+ * Everything `inspect` and `doctor` print, as one document. `newest` is the
+ * caller's release check (release.mjs `checkNewestRelease`, or
+ * `{ checked: false, code: "offline" }` when it was skipped); the lab is
+ * held to that release when it was found, and to the base's own release
+ * when it was not, which the document says. `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. An
+ * `outdated` base is not missing: a run uses it, and `behind` says so.
  */
-export async function inspectLab({ env = process.env, pin = labPin(), verify = false, onProgress, run } = {}) {
+export async function inspectLab({ env = process.env, pin = labPin(), newest = { checked: false, code: "not-asked", reason: "the newest release was not looked up" }, verify = false, onProgress, run } = {}) {
   const layout = labLayout(env)
+  const reference = newest?.checked ? newest.release : baseRelease(layout, pin)
+  pin = { ...pin, release: reference }
   const download = inspectDownload(layout, pin, { verify, onProgress })
   const base = inspectBase(layout, pin)
   const toolchain = inspectToolchain(layout, pin)
@@ -218,23 +346,34 @@ export async function inspectLab({ env = process.env, pin = labPin(), verify = f
     runsBytes: existsSync(layout.runs) ? allocatedBytes(layout.runs) : 0,
   }
   const missing = []
+  const usable = ["ready", "outdated", "ahead"].includes(base.state)
   for (const line of host.run) if (line.state !== "ok") missing.push({ what: line.name, cost: line.reason, command: line.remedy })
-  if (!download.verified) {
+  // The verified ISO matters for building a base; with a usable base
+  // there, a run needs none, and a newer release's ISO is part of what
+  // `behind` names rather than something a run is missing.
+  if (!download.verified && !usable) {
     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}`,
+      cost: !pin.release
+        ? `the newest Omarchy release, which could not be looked up (${newest?.reason || "not asked"}); \`omakit lab setup\` looks it up and downloads it`
+        : 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 its published sha256 and the Omarchy signature, into ${download.dir}`,
       command: "omakit lab setup",
     })
   }
-  if (toolchain.state !== "ready" && base.state !== "ready") {
+  if (toolchain.state !== "ready" && !usable) {
     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") {
+  if (!usable) {
     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`,
+      cost: `${bytesBoth(pin.measured.baseDirectoryBytes)} on disk, ${durationWords(pin.measured.buildMilliseconds)} to build on the reference host with Omarchy ${pin.measured.release} (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 }
+  const behind = base.state === "outdated"
+    ? { base: base.manifest.release.name, newest: pin.release.name, command: "omakit lab setup", cost: `${download.verified ? "0 B to download" : `a download of ${bytesBoth(pin.release.bytes)}`}, a build of about ${durationWords(pin.measured.buildMilliseconds)} (Omarchy ${pin.measured.release} on the reference host, M14); the base there stays until the new one verifies` }
+    : null
+  return { pin: { release: pin.release, releases: pin.releases, toolchain: pin.toolchain, guest: pin.guest, measured: pin.measured }, newest, layout, download, base, behind, toolchain, staging, lock, host, free, runs, totals, missing }
 }

package/tools/lab/paths.mjs

@@ -29,7 +29,7 @@ export function labStateDir(env = process.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.
+ * (docs/LAB.md): setup replaces it when a newer release is built.
  */
 export function labLayout(env = process.env) {
   const cache = labCacheDir(env)

package/tools/lab/pin.json

@@ -1,19 +1,13 @@
 {
-  "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",
+  "schema": 2,
+  "releases": {
+    "list": "https://api.github.com/repos/omacom/omarchy/releases?per_page=30",
+    "iso": "https://iso.omarchy.org/omarchy-{version}.iso",
+    "floor": "4.0.3",
+    "candidates": 3,
     "signingFingerprint": "40DFB630FF42BCFFB047046CF0134EE680CAC571",
     "signingKey": "omarchy.gpg",
-    "signingKeySha256": "15d6aac44df688165b2ea35fe0b23af239bbc66a6909c10a5c219e8d94b707de",
-    "expectedGuestVersion": "4.0.3-1"
+    "signingKeySha256": "15d6aac44df688165b2ea35fe0b23af239bbc66a6909c10a5c219e8d94b707de"
   },
   "toolchain": {
     "repository": "https://github.com/omacom-io/omarchy-iso",
@@ -31,12 +25,14 @@
   },
   "measured": {
     "on": "2026-09-18",
+    "release": "4.0.3",
+    "isoBytes": 6260654080,
     "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"
+    "source": "docs/MEASUREMENTS.md M14, measured by omakit lab on the reference host with Omarchy 4.0.3, re-measuring the lab plan's observations of 2026-09-10 to 2026-09-13 (M4 to M7, in git history at 9c667f9)"
   }
 }

package/tools/lab/pin.mjs

@@ -1,11 +1,17 @@
-// The release pin: the one Omarchy release the lab prepares, its exact
-// digest, its signer, and the toolchain that builds a base from it.
+// What the lab holds fixed: where Omarchy's releases are listed and where
+// their ISOs are published, the signer every release must carry, the
+// oldest release it will take, the toolchain that builds a base, and the
+// costs measured on the reference host.
 //
-// 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.
+// Which release the lab prepares is not in this file: `release.mjs` finds
+// the newest one that is published whole (ISO, checksum, signature) each
+// time `setup` runs, so the lab never stays on an old release unnoticed.
+// The trust is the signature, not the list: a file is the release only
+// when its detached signature verifies against the packaged key at the
+// pinned fingerprint (verify.mjs). The inventory's objection to "latest"
+// (docs/history/2026-09-18-lab-inventory.md P13) was a checksum trusted
+// from the same host as the file with no signature checked at all; that
+// is what the pinned signer answers.
 
 import { readFileSync } from "node:fs"
 import { dirname, join } from "node:path"
@@ -13,23 +19,82 @@ import { fileURLToPath } from "node:url"
 
 export const LAB_DIR = dirname(fileURLToPath(import.meta.url))
 
+/** A release name the lab takes: three numbers, as Omarchy tags them without the v. */
+export const VERSION = /^(\d+)\.(\d+)\.(\d+)$/
+
 let cached = null
 
-/** The pin, parsed once. `file` is injectable for tests that need a small release. */
+/** The pin, parsed once. `file` is injectable for tests that need their own. */
 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"]) {
+  for (const key of ["releases", "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")
+  const { releases } = pin
+  if (!/^https:\/\/api\.github\.com\/repos\/[\w.-]+\/[\w.-]+\/releases(?:\?[\w=&]*)?$/.test(releases.list)) throw new Error("lab pin: the release list is not a GitHub releases URL")
+  if (!/^https:\/\/[\w.-]+\/[\w./-]*\{version\}[\w./-]*\.iso$/.test(releases.iso)) throw new Error("lab pin: the ISO URL is not an https template with {version}")
+  if (/latest/i.test(releases.iso)) throw new Error("lab pin: the ISO URL names latest; a release is found by its version")
+  if (!VERSION.test(releases.floor)) throw new Error("lab pin: the floor is not a release name")
+  if (!Number.isInteger(releases.candidates) || releases.candidates < 1) throw new Error("lab pin: candidates is not a positive integer")
+  if (!/^[0-9A-F]{40}$/.test(releases.signingFingerprint)) throw new Error("lab pin: the signing fingerprint is not 40 hex characters")
+  if (!/^[0-9a-f]{64}$/.test(releases.signingKeySha256)) throw new Error("lab pin: the signing key digest is not 64 hex characters")
   if (file === join(LAB_DIR, "pin.json")) cached = pin
   return pin
 }
 
+/** -1, 0 or 1, by the three numbers; a name that is not a release sorts below every one that is. */
+export function compareVersions(a, b) {
+  const left = String(a).match(VERSION)
+  const right = String(b).match(VERSION)
+  if (!left || !right) return left ? 1 : right ? -1 : 0
+  for (const index of [1, 2, 3]) {
+    const difference = Number(left[index]) - Number(right[index])
+    if (difference) return difference < 0 ? -1 : 1
+  }
+  return 0
+}
+
+/**
+ * One release in the shape the lab reads everywhere: its name, where its
+ * ISO and the two sidecars are, its byte count and digest as published,
+ * and the pinned signer it must carry. `bytes` and `sha256` come from the
+ * host that publishes the release; the signature is what makes them
+ * trusted, and verify.mjs checks it before anything boots the file.
+ */
+export function releaseOf(pin, { name, bytes, sha256 }) {
+  if (!VERSION.test(String(name))) throw new Error(`lab: ${JSON.stringify(name)} is not a release name`)
+  const isoUrl = pin.releases.iso.replace("{version}", name)
+  return {
+    name,
+    fileName: isoUrl.split("/").at(-1),
+    isoUrl,
+    checksumUrl: `${isoUrl}.sha256`,
+    signatureUrl: `${isoUrl}.sig`,
+    bytes,
+    sha256,
+    signingFingerprint: pin.releases.signingFingerprint,
+    signingKey: pin.releases.signingKey,
+    signingKeySha256: pin.releases.signingKeySha256,
+  }
+}
+
+/** The pin with one release in it: what setup, inspect and a run read as `pin.release`. */
+export function withRelease(pin, release) {
+  return { ...pin, release }
+}
+
+/**
+ * Whether an installed `omarchy` package version is this release's: the
+ * release name and one package revision (`4.0.3-1`). The ISO installs the
+ * package it carries, so any other version is a mislabelled release.
+ */
+export function guestIsRelease(version, release) {
+  if (!release || typeof version !== "string") return false
+  const match = version.match(/^(\d+\.\d+\.\d+)-(\d+)$/)
+  return Boolean(match) && match[1] === release.name
+}
+
 /**
  * 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)`.

package/tools/lab/prune.mjs

@@ -9,9 +9,9 @@
 
 import { existsSync, lstatSync, readdirSync } from "node:fs"
 import { join } from "node:path"
-import { bytesBoth, labPin } from "./pin.mjs"
+import { bytesBoth, labPin, withRelease } from "./pin.mjs"
 import { allocatedBytes, labLayout, removeFromLab } from "./paths.mjs"
-import { inspectBase, inspectLock, inspectStaging } from "./inspect.mjs"
+import { baseRelease, downloadEntry, inspectBase, inspectLock, inspectStaging } from "./inspect.mjs"
 import { LabError } from "./run.mjs"
 
 /**
@@ -32,19 +32,22 @@ export async function planPrune({ env = process.env, pin = labPin(), keepIso = f
   const active = staging.filter((entry) => entry.alive)
   const blockers = []
   if (lock.held && lock.alive) blockers.push(`run ${lock.record?.runId || "unknown"} holds the lab (pid ${lock.record?.pid || "?"}${lock.qemuAnswers ? ", its QEMU answers on QMP" : ""})`)
-  for (const entry of active) blockers.push(`a QEMU still answers on ${entry.socket}`)
+  for (const entry of active) blockers.push(entry.pids?.length ? `a build's QEMU still runs in ${entry.dir} (pid ${entry.pids.join(", ")}), left by a setup that ended; stop it with \`kill ${entry.pids.join(" ")}\` (the next setup that builds stops it too)` : `a QEMU still answers on ${entry.socket}`)
   if (existsSync(layout.downloads)) {
     for (const digest of readdirSync(layout.downloads)) {
+      // Each download directory says what it holds: its verification
+      // record names the release (a record written before 0.6.9 names only
+      // the digest, and the ISO is the one .iso file in the directory).
       const dir = join(layout.downloads, digest)
-      const verified = digest === pin.release.sha256 && existsSync(join(dir, "verified.json")) && existsSync(join(dir, pin.release.fileName))
+      const { name, fileName, verified } = lstatSync(dir).isDirectory() ? downloadEntry(dir, digest) : { name: null, fileName: null, verified: false }
       if (verified && keepIso) {
-        add(layout.cache, `downloads/${digest}/${pin.release.fileName}.part`, "a partial download beside the verified ISO")
+        add(layout.cache, `downloads/${digest}/${fileName}.part`, "a partial download beside the verified ISO")
         continue
       }
-      add(layout.cache, `downloads/${digest}`, verified ? `the verified ISO of ${pin.release.name} and its record` : digest === pin.release.sha256 ? "the unverified or partial download of the pinned release" : `a download directory of another digest (${digest.slice(0, 12)})`)
+      add(layout.cache, `downloads/${digest}`, verified ? `the verified ISO of ${name ? `Omarchy ${name}` : digest.slice(0, 12)} and its record` : `an unverified or partial download${name ? ` of Omarchy ${name}` : ` (${digest.slice(0, 12)})`}`)
     }
   }
-  const base = inspectBase(layout, pin)
+  const base = inspectBase(layout, withRelease(pin, baseRelease(layout, pin)))
   if (base.state !== "missing") add(layout.cache, "base", `the ${base.state} base${base.manifest ? ` (Omarchy ${base.manifest.release.name}, guest ${base.manifest.guest.version})` : ""}`)
   for (const entry of staging) if (!entry.alive) add(layout.cache, `staging/${entry.name}`, `staging left by ${entry.name}`)
   if (existsSync(layout.plugins)) add(layout.cache, "plugins", "the listed plugins cached for the weigh evidence gate")