omakit 0.6.7 → 0.6.9

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")

package/tools/lab/release.mjs

@@ -0,0 +1,178 @@
+// The newest Omarchy release the lab can prepare, found each time it is
+// asked: the release list on GitHub, newest first by version, and for each
+// the three objects the ISO host must publish whole (the ISO, its .sha256
+// and its detached .sig). Only GETs, through github.mjs's one call site;
+// the ISO's size is read from a one-byte range request, so no image is
+// fetched here.
+//
+// What it will not do, each measured against a way the lab went wrong or
+// could:
+// - Stay on an old release unnoticed. 4.0.4 was published on 2026-09-15
+//   and the lab, pinned to 4.0.3 on 2026-09-18, still offered 4.0.3 on
+//   2026-09-23; nothing looked.
+// - Fall back past a release that could not be read. A newer release is
+//   skipped only when the host answers that an object is not there (404:
+//   tagged, not yet published, as 4.0.0 has no .sha256). Everything else
+//   stops the search with its reason: a timeout, a 5xx, a checksum that
+//   does not read, an ISO whose size is not announced. A fallback on any
+//   of those is the stale lab again.
+// - Take a release older than the floor, whatever the list says.
+// - Accept a signer it does not ship. The .sig names its issuers; one with
+//   none of them the pinned fingerprint stops the search before the ISO is
+//   asked for, rather than falling back to an older release the old key
+//   signed. A .sig with the pinned key among its signers (a rotation that
+//   signs with both) is the pinned key's.
+
+import { getJson, getStream } from "../marketplace/github.mjs"
+import { compareVersions, labPin, releaseOf, VERSION } from "./pin.mjs"
+import { signatureIssuers, signedByPinned } from "./verify.mjs"
+import { LabError } from "./run.mjs"
+
+/** A sidecar is a few dozen bytes; anything past this is not one. */
+const SIDECAR_LIMIT = 4096
+
+/** A GET that answers 404 is "not published"; every other failure is thrown as it came. */
+async function read(fetchStream, url, signal) {
+  try {
+    return await fetchStream(url, { signal })
+  } catch (error) {
+    if (error?.code === "not-found" || error?.status === 404) return null
+    throw error
+  }
+}
+
+/**
+ * A sidecar's body, refused past SIDECAR_LIMIT as announced or as it
+ * streams, never buffered whole first; `code` names the refusal for the
+ * caller (the search's release-unavailable, setup's sidecar-mismatch).
+ */
+export async function smallBody(response, url, code = "release-unavailable") {
+  const tooBig = (bytes) => new LabError(code, `${url} answered ${bytes.toLocaleString("en-US")} B or more; a sidecar is a few dozen`)
+  const announced = Number(response.headers?.get?.("content-length"))
+  if (Number.isFinite(announced) && announced > SIDECAR_LIMIT) {
+    try {
+      await response.body?.cancel()
+    } catch {
+      // Nothing left to cancel.
+    }
+    throw tooBig(announced)
+  }
+  if (!response.body?.getReader) {
+    const body = Buffer.from(await response.arrayBuffer())
+    if (body.length > SIDECAR_LIMIT) throw tooBig(body.length)
+    return body
+  }
+  const reader = response.body.getReader()
+  const chunks = []
+  let size = 0
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    size += value.length
+    if (size > SIDECAR_LIMIT) {
+      await reader.cancel()
+      throw tooBig(size)
+    }
+    chunks.push(Buffer.from(value))
+  }
+  return Buffer.concat(chunks)
+}
+
+/** The ISO's full size from a ranged answer (`Content-Range: bytes 0-0/<size>`), or from Content-Length when the host sent the whole object. */
+function announcedSize(response) {
+  const range = String(response.headers.get("content-range") || "").match(/^bytes\s+\d+-\d+\/(\d+)$/)
+  if (response.status === 206) return range ? Number(range[1]) : NaN
+  return Number(response.headers.get("content-length"))
+}
+
+/**
+ * The published digest from a `.sha256` sidecar: `<64 hex>  <file name>`,
+ * the name the ISO's own. Null for anything else.
+ */
+export function sidecarDigest(text, fileName) {
+  const match = String(text).trim().match(/^([0-9a-fA-F]{64})\s+\*?(\S+)\s*$/)
+  if (!match) return null
+  if (match[2].split("/").at(-1) !== fileName) return null
+  return match[1].toLowerCase()
+}
+
+/**
+ * One release checked on the ISO host, in the order that stops earliest:
+ * the checksum, the signature (whose signer is checked before the ISO is
+ * asked for, so a release omakit would refuse is never requested), then
+ * the ISO's announced size. `{ ok: true, release, signers }` when the three
+ * are there and read as they should; `{ ok: false, reason }` when the host
+ * says one is not published. A signer other than the pinned one throws
+ * `signer-changed`; any other failure throws as it came.
+ */
+export async function probeRelease({ pin, name, fetchStream = getStream, signal }) {
+  const shape = releaseOf(pin, { name, bytes: 0, sha256: "0".repeat(64) })
+  const checksum = await read(fetchStream, shape.checksumUrl, signal)
+  if (!checksum) return { ok: false, reason: `${shape.fileName}.sha256 is not published` }
+  const sha256 = sidecarDigest((await smallBody(checksum, shape.checksumUrl)).toString("utf8"), shape.fileName)
+  if (!sha256) throw new LabError("release-unavailable", `${shape.checksumUrl} is published but does not name ${shape.fileName} with a SHA-256; the lab will not fall back past it to an older release`)
+  const signature = await read(fetchStream, shape.signatureUrl, signal)
+  if (!signature) return { ok: false, reason: `${shape.fileName}.sig is not published` }
+  const signers = signatureIssuers(await smallBody(signature, shape.signatureUrl))
+  if (signedByPinned(signers, pin.releases.signingFingerprint) === false) {
+    const named = signers.map((signer) => signer.fingerprint || `key ${signer.keyId}`).join(" and ")
+    throw new LabError("signer-changed", `Omarchy ${name} is signed by ${named}, not the key omakit ships (${pin.releases.signingFingerprint}); omakit will not prepare it, and will not fall back to an older release the old key signed`, { remedy: "omakit upgrade: a newer omakit carries the new key once it is verified" })
+  }
+  // One byte of the image, for its size in Content-Range; the rest is never asked for.
+  const iso = await read((url, options) => fetchStream(url, { ...options, rangeEnd: 0 }), shape.isoUrl, signal)
+  if (!iso) return { ok: false, reason: `${shape.fileName} is not published` }
+  const bytes = announcedSize(iso)
+  try {
+    await iso.body?.cancel()
+  } catch {
+    // A body that is already closed has nothing left to cancel.
+  }
+  if (!Number.isSafeInteger(bytes) || bytes <= 0) throw new LabError("release-unavailable", `${shape.isoUrl} is published but its size is not announced; the lab will not fall back past it to an older release`)
+  return { ok: true, release: releaseOf(pin, { name, bytes, sha256 }), signers }
+}
+
+/**
+ * The newest release at or above the floor that is published whole.
+ * Returns `{ release, tag, publishedAt, checkedAt, list, skipped }`, where
+ * `skipped` names each newer release passed over and why. Throws a
+ * LabError: `release-unavailable` when none of the newest `candidates`
+ * is published whole, `signer-changed` when the newest is signed by
+ * another key; a network error comes through with its own code.
+ */
+export async function findNewestRelease({ pin = labPin(), readJson = getJson, fetchStream = getStream, signal, now = () => new Date() } = {}) {
+  const listed = await readJson(pin.releases.list, { signal })
+  if (!Array.isArray(listed)) throw new LabError("release-unavailable", `${pin.releases.list} did not answer with a list of releases`)
+  const seen = new Set()
+  const releases = listed
+    .filter((entry) => entry && typeof entry === "object" && !entry.draft && !entry.prerelease && typeof entry.tag_name === "string")
+    .map((entry) => ({ tag: entry.tag_name, name: entry.tag_name.replace(/^v/, ""), publishedAt: entry.published_at || null }))
+    .filter((entry) => VERSION.test(entry.name) && !seen.has(entry.name) && seen.add(entry.name))
+    .sort((a, b) => compareVersions(b.name, a.name))
+  const eligible = releases.filter((entry) => compareVersions(entry.name, pin.releases.floor) >= 0)
+  if (!eligible.length) {
+    throw new LabError("release-unavailable", `${pin.releases.list} lists no release at or above ${pin.releases.floor}${releases.length ? `; the newest listed is ${releases[0].name}` : ""}`)
+  }
+  const skipped = []
+  for (const entry of eligible.slice(0, pin.releases.candidates)) {
+    const probed = await probeRelease({ pin, name: entry.name, fetchStream, signal })
+    if (!probed.ok) {
+      skipped.push({ name: entry.name, reason: probed.reason })
+      continue
+    }
+    return { release: probed.release, tag: entry.tag, publishedAt: entry.publishedAt, checkedAt: now().toISOString(), list: pin.releases.list, skipped }
+  }
+  throw new LabError("release-unavailable", `none of the newest ${Math.min(eligible.length, pin.releases.candidates)} releases is published whole: ${skipped.map((entry) => `${entry.name} (${entry.reason})`).join("; ")}`)
+}
+
+/**
+ * The newest-release check as a value, never a throw: what inspect, doctor
+ * and a run print. `{ checked: true, ... }` with the release, or
+ * `{ checked: false, code, reason }`.
+ */
+export async function checkNewestRelease(options = {}) {
+  try {
+    return { checked: true, ...(await findNewestRelease(options)) }
+  } catch (error) {
+    return { checked: false, code: error?.code || "error", reason: error?.message || String(error) }
+  }
+}

package/tools/lab/report.mjs

@@ -30,25 +30,67 @@ export function labDoctorChecks(lab) {
   // To the GiB: the exact figure moves with every write on the filesystem,
   // and doctor's two consecutive runs are held to the same bytes (a tenth
   // of a GiB flipped once while another test packed a tarball beside it).
-  add("lab.disk", enough, `${Math.floor(lab.free.bytes / 2 ** 30).toLocaleString("en-US")} GiB free on the lab cache's filesystem; a prepared lab measured ${bytesBoth(lab.pin.measured.preparedLabBytes)} (M14)`, enough ? null : "omakit lab prune, or free the difference")
-  add("lab.iso", lab.download.verified, `${lab.pin.release.name}, ${lab.download.reason}`, lab.download.verified ? null : "omakit lab setup", { sha256: lab.pin.release.sha256, present: lab.download.present, verified: lab.download.verified })
-  add("lab.base", lab.base.state === "ready", `${lab.base.state}: ${lab.base.reason}`, lab.base.state === "ready" ? null : "omakit lab setup", { state: lab.base.state, release: lab.base.manifest?.release?.name ?? null, guestVersion: lab.base.manifest?.guest?.version ?? null, diskSha256: lab.base.manifest?.disk?.sha256 ?? null, allocatedBytes: lab.base.allocatedBytes, lockHeld: lab.lock.held, lockAlive: lab.lock.alive })
+  add("lab.disk", enough, `${Math.floor(lab.free.bytes / 2 ** 30).toLocaleString("en-US")} GiB free on the lab cache's filesystem; a prepared lab measured ${bytesBoth(lab.pin.measured.preparedLabBytes)} with Omarchy ${lab.pin.measured.release} (M14)`, enough ? null : "omakit lab prune, or free the difference")
+  checks.push(releaseCheck(lab))
+  const usable = ["ready", "outdated", "ahead"].includes(lab.base.state)
+  // The ISO is what a build needs: with a usable base there it is only
+  // advice when a build is ahead, and the release check says when that is.
+  const release = lab.pin.release
+  checks.push({
+    id: "lab.iso",
+    state: lab.download.verified ? "ok" : usable ? "info" : "advice",
+    detail: release ? `${release.name}, ${lab.download.reason}` : lab.download.reason,
+    action: lab.download.verified || usable ? null : "omakit lab setup",
+    evidence: { release: release?.name ?? null, sha256: release?.sha256 ?? null, present: lab.download.present, verified: lab.download.verified },
+  })
+  add("lab.base", usable, `${lab.base.state}: ${lab.base.reason}`, usable ? null : "omakit lab setup", { state: lab.base.state, release: lab.base.manifest?.release?.name ?? null, guestVersion: lab.base.manifest?.guest?.version ?? null, diskSha256: lab.base.manifest?.disk?.sha256 ?? null, allocatedBytes: lab.base.allocatedBytes, lockHeld: lab.lock.held, lockAlive: lab.lock.alive })
   if (lab.lock.held) add("lab.lock", !lab.lock.alive, lab.lock.alive ? `held by run ${lab.lock.record?.runId || "unknown"} (pid ${lab.lock.record?.pid || "?"})` : `a stale lock from ${lab.lock.record?.runId || "an unknown run"}`, lab.lock.alive ? "wait for the run" : "omakit lab prune")
   return checks
 }
 
+/**
+ * Whether the lab is on the newest Omarchy release, one check: ok when the
+ * base is built from it, advice when a newer one is out, info when there
+ * is no base yet or the check was skipped (--offline), unknown when the
+ * release list could not be read.
+ */
+export function releaseCheck(lab) {
+  const newest = lab.newest || { checked: false, code: "not-asked", reason: "the newest release was not looked up" }
+  const evidence = { newest: newest.checked ? newest.release.name : null, tag: newest.checked ? newest.tag : null, base: lab.base.manifest?.release?.name ?? null, code: newest.checked ? null : newest.code }
+  if (!newest.checked) {
+    if (newest.code === "offline") return { id: "lab.release", state: "info", detail: "the newest Omarchy release is not looked up (--offline)", action: null, evidence }
+    // Found, and refused: a finding, not a lookup that failed.
+    if (newest.code === "signer-changed") return { id: "lab.release", state: "advice", detail: newest.reason, action: "omakit upgrade: a newer omakit carries Omarchy's new key once it is verified", evidence }
+    return { id: "lab.release", state: "unknown", detail: `could not look up the newest Omarchy release: ${newest.reason}`, action: newest.code === "network-unavailable" ? "Connect to the network, or pass --offline to skip the checks that need it." : null, evidence }
+  }
+  const name = newest.release.name
+  if (lab.base.state === "ready") return { id: "lab.release", state: "ok", detail: `Omarchy ${name} is the newest release, and the lab's base is built from it`, action: null, evidence }
+  if (lab.base.state === "ahead") return { id: "lab.release", state: "info", detail: `the lab's base is Omarchy ${lab.base.manifest.release.name}, newer than ${name}, the newest release published whole now; it is kept`, action: null, evidence }
+  if (lab.base.state === "outdated") return { id: "lab.release", state: "advice", detail: `Omarchy ${name} is the newest release; the lab's base is ${lab.base.manifest.release.name}${lab.base.manifest.release.name === name ? " as first published" : ""}, and a run still uses it`, action: "omakit lab setup", evidence }
+  return { id: "lab.release", state: "info", detail: `Omarchy ${name} is the newest release; \`omakit lab setup\` prepares it`, action: null, evidence }
+}
+
 /** `omakit lab inspect`. */
 export function renderLab(lab, { colour = colourEnabled(), env = process.env } = {}) {
   const c = styler(colour)
   const home = (text) => withHomeAbbreviated(text, env)
   const out = []
   const { release } = lab.pin
-  out.push(...section("the release the lab is pinned to", c))
-  out.push(...field("release", `Omarchy ${release.name}; guest package expected ${release.expectedGuestVersion}; ISO build ${release.embeddedBuild}, volume ${release.volume}`, c))
-  out.push(...field("iso", release.isoUrl, c))
-  out.push(...field("size", bytesBoth(release.bytes), c))
-  out.push(...field("sha256", release.sha256, c, { wrapValue: false }))
-  out.push(...field("signed by", `${release.signingFingerprint} (Omarchy <pkgs@omarchy.org>, the packaged key)`, c))
+  const newest = lab.newest || { checked: false, reason: "the newest release was not looked up" }
+  out.push(...section("the newest release", c))
+  if (newest.checked) {
+    out.push(...field("release", `Omarchy ${release.name} (${newest.tag}${newest.publishedAt ? `, published ${newest.publishedAt.slice(0, 10)}` : ""}), the newest in ${newest.list.replace(/^https:\/\/api\.github\.com\/repos\/([^/]+\/[^/]+)\/releases.*$/, "github.com/$1")} with its ISO, checksum and signature published`, c))
+    for (const skipped of newest.skipped || []) out.push(...field("passed over", `${skipped.name}: ${skipped.reason}`, c))
+  } else {
+    const why = newest.code === "signer-changed" ? `refused: ${newest.reason}` : `not looked up: ${newest.reason}`
+    out.push(...field("release", `${why}${release ? `; the lab is held to its base's release, Omarchy ${release.name}` : ""}`, c))
+  }
+  if (release) {
+    out.push(...field("iso", release.isoUrl, c))
+    out.push(...field("size", bytesBoth(release.bytes), c))
+    out.push(...field("sha256", release.sha256, c, { wrapValue: false }))
+  }
+  out.push(...field("signed by", `${lab.pin.releases.signingFingerprint} (Omarchy <pkgs@omarchy.org>, the key omakit ships); every release must carry it`, c))
   out.push(...field("toolchain", `omarchy-iso ${lab.pin.toolchain.commit.slice(0, 12)} with ${lab.pin.toolchain.patch}; harness sha256 ${shortId(lab.pin.toolchain.patchedHarnessSha256)}`, c))
   out.push("")
   out.push(...section("on disk", c))
@@ -61,7 +103,7 @@ export function renderLab(lab, { colour = colourEnabled(), env = process.env } =
   out.push(...wrap(home(lab.toolchain.reason), { indent: GUTTER }, c))
   if (lab.staging.length) {
     out.push(`${mark(lab.staging.some((entry) => entry.alive) ? "info" : "advisory", c)}${c("name", "staging")}`)
-    for (const entry of lab.staging) out.push(...wrap(home(`${entry.name}: ${bytesBoth(entry.allocatedBytes)}${entry.alive ? ", a QEMU answers on its socket" : ", inactive"}`), { indent: GUTTER }, c))
+    for (const entry of lab.staging) out.push(...wrap(home(`${entry.name}: ${bytesBoth(entry.allocatedBytes)}${entry.pids?.length ? `, a build's QEMU still runs (pid ${entry.pids.join(", ")})` : entry.alive ? ", a QEMU answers on its socket" : ", inactive"}`), { indent: GUTTER }, c))
   }
   if (lab.lock.held) {
     out.push(`${mark(lab.lock.alive ? "info" : "advisory", c)}${c("name", "lock")}`)
@@ -77,6 +119,13 @@ export function renderLab(lab, { colour = colourEnabled(), env = process.env } =
     out.push(...wrap(line.reason, { indent: GUTTER }, c))
   }
   out.push("")
+  // Behind is said whether or not something else is missing: a host that
+  // is fixed next still has an older base, and hears it here first.
+  if (lab.behind) {
+    out.push(...field("behind", `Omarchy ${lab.behind.newest} is out and the base is ${lab.behind.base}: ${lab.behind.cost}`, c))
+    out.push(...action(lab.behind.command, c))
+    out.push("")
+  }
   if (lab.missing.length) {
     out.push(...section(`missing for \`omakit lab prove\`: ${lab.missing.length}`, c))
     for (const item of lab.missing) {
@@ -85,9 +134,12 @@ export function renderLab(lab, { colour = colourEnabled(), env = process.env } =
       if (item.command) out.push(...action(home(item.command), c))
     }
     out.push("")
-    out.push(...verdict("advisory", "NOT PREPARED", `${lab.missing.length} thing${lab.missing.length === 1 ? "" : "s"} before a run; nothing was fetched or written.`, c))
+    out.push(...verdict("advisory", "NOT PREPARED", `${lab.missing.length} thing${lab.missing.length === 1 ? "" : "s"} before a run; ${lab.newest?.checked ? "only the release list was read" : "nothing was fetched or written"}.`, c))
+  } else if (lab.behind) {
+    out.push(...verdict("advisory", "PREPARED", `on Omarchy ${lab.behind.base}, which a run uses; Omarchy ${lab.behind.newest} is the newest, and \`omakit lab setup\` builds it. Only the release list was read.`, c))
   } else {
-    out.push(...verdict("pass", "PREPARED", `verified ${release.name}, a ready base, the host can run it; nothing was fetched or written.`, c))
+    const on = lab.base.manifest?.release?.name
+    out.push(...verdict("pass", "PREPARED", `${on ? `Omarchy ${on}, ` : ""}a ready base the host can run${newest.checked ? ", the newest release" : `; the newest release was not looked up (${newest.reason})`}. ${newest.checked ? "Only the release list was read." : "Nothing was fetched or written."}`, c))
   }
   return out.join("\n")
 }
@@ -106,7 +158,9 @@ export function renderSetupPlan(plan, { colour = colourEnabled(), env = process.
     return out.join("\n")
   }
   if (!plan.steps.length) {
-    out.push(...verdict("pass", "PREPARED", "the verified ISO and a ready base are there; nothing to acquire.", c))
+    if (plan.stale) out.push(...verdict("advisory", "PREPARED", `the base on disk is Omarchy ${plan.stale.base}, left as it is: the newest release could not be looked up (${plan.stale.reason}). Run \`omakit lab setup\` again with the network.`, c))
+    else if (plan.ahead) out.push(...verdict("advisory", "PREPARED", `the base on disk is Omarchy ${plan.ahead.base}, newer than ${plan.ahead.release}, ${plan.ahead.from === "newest" ? "the newest release published whole now" : "the release the file named by --from is"}; it is kept, and nothing older is fetched or built over it.`, c))
+    else out.push(...verdict("pass", "PREPARED", `Omarchy ${plan.pin.release.name}, ${plan.newest?.checked ? "the newest release" : "the release the file named by --from is (the newest was not looked up)"}: the verified ISO and a ready base are there; nothing to acquire.`, c))
     return out.join("\n")
   }
   out.push(...section("what setup will do, once you say yes", c))
@@ -123,11 +177,13 @@ export function renderSetupResult(result, { colour = colourEnabled(), env = proc
     else if (step.kind === "import") out.push(`${mark("pass", c)}copied ${bytesBoth(step.bytes)} from ${withHomeAbbreviated(step.from, env)} in ${durationWords(step.milliseconds)}`)
     else if (step.kind === "sidecars") out.push(`${mark("pass", c)}fetched the checksum and signature sidecars into ${withHomeAbbreviated(step.to, env)}`)
     else if (step.kind === "verify") out.push(`${mark("pass", c)}verified ${withHomeAbbreviated(step.file, env)}`, ...wrap(step.reason, { indent: GUTTER }, c))
-    else if (step.kind === "build") out.push(`${mark("pass", c)}built and promoted the base in ${durationWords(step.milliseconds)}: guest omarchy ${step.guest.version}, ${bytesBoth(step.allocatedBytes)} allocated, disk sha256 ${step.diskSha256}`)
+    else if (step.kind === "build") out.push(`${mark("pass", c)}built and promoted the Omarchy ${step.release} base in ${durationWords(step.milliseconds)}: guest omarchy ${step.guest.version}, ${bytesBoth(step.allocatedBytes)} allocated, disk sha256 ${step.diskSha256}`)
+    else if (step.kind === "superseded" && step.removed.length) out.push(`${mark("pass", c)}removed ${step.removed.length === 1 ? "the older download" : `${step.removed.length} older downloads`} (${step.removed.map((entry) => entry.name || entry.digest.slice(0, 12)).join(", ")}), ${bytesBoth(step.removed.reduce((sum, entry) => sum + entry.bytes, 0))}`)
     else if (step.kind === "plugins") out.push(`${mark("pass", c)}${step.fetched.length} listed plugins in the lab cache: ${step.fetched.map((row) => `${row.id} ${row.state}`).join(", ")}`)
   }
   out.push("")
-  out.push(...verdict("pass", "PREPARED", "the lab is ready; `omakit lab prove <suite>` boots it.", c))
+  const built = result.done.find((step) => step.kind === "build")
+  out.push(...verdict("pass", "PREPARED", `the lab is ready${built ? ` on Omarchy ${built.release}` : ""}; \`omakit lab prove <suite>\` boots it.`, c))
   return out.join("\n")
 }
 
@@ -136,12 +192,16 @@ export function renderRunIdentity(record, { colour = colourEnabled() } = {}) {
   const c = styler(colour)
   const out = []
   out.push(...field("run", record.runId, c))
-  out.push(...field("release", record.pin.release, c))
+  out.push(...field("release", `Omarchy ${record.pin.release}`, c))
+  const newest = record.newest || { release: null, reason: "not looked up" }
+  out.push(...field("newest", record.behind
+    ? `Omarchy ${newest.release} is out and this base is ${record.pin.release}: the run uses the base there; \`omakit lab setup\` builds ${newest.release}`
+    : newest.release ? `this is the newest release (${newest.tag}, checked ${String(newest.checkedAt).slice(0, 10)})` : `not looked up: ${newest.reason}`, c))
   out.push(...field("guest", record.guest ? `omarchy ${record.guest.version || "unknown"} on ${record.guest.kernel || "?"}` : "not read", c))
   out.push(...field("iso sha256", record.pin.isoSha256, c, { wrapValue: false }))
   out.push(...field("base", `created ${record.base.createdAt}; ${bytesBoth(record.base.allocatedBytes)}; disk sha256 ${shortId(record.base.diskSha256)}`, c))
   out.push(...field("tested", record.testedSource || "unknown", c))
-  out.push(...field("skew", record.skew === null ? "unknown" : record.skew ? `true: the guest is ${record.guest?.linked ? "linked to a checkout" : `omarchy ${record.guest?.version}`}, the pin expects ${record.pin.expectedGuestVersion}` : `false: the installed package is the pinned ${record.pin.expectedGuestVersion}`, c))
+  out.push(...field("skew", record.skew === null ? "unknown" : record.skew ? `true: the guest is ${record.guest?.linked ? "linked to a checkout" : `omarchy ${record.guest?.version}`}, the base was built with ${record.pin.expectedGuestVersion}` : `false: the installed package is the base's ${record.pin.expectedGuestVersion}`, c))
   return out.join("\n")
 }
 
@@ -154,7 +214,7 @@ export function renderRunResult(record, { colour = colourEnabled(), env = proces
   if (record.document) out.push(...field("document", withHomeAbbreviated(record.document, env), c))
   out.push(...field("record", withHomeAbbreviated(`${record.runDir}/run.json`, env), c))
   out.push("")
-  if (record.ok) out.push(...verdict("pass", "PROVED", `${record.suite}: ${record.assertion?.reason || "ok"}; guest omarchy ${record.guest?.version}, skew ${record.skew}.`, c))
+  if (record.ok) out.push(...verdict("pass", "PROVED", `${record.suite}: ${record.assertion?.reason || "ok"}; guest omarchy ${record.guest?.version}, skew ${record.skew}${record.behind ? `; Omarchy ${record.newest.release} is out, and \`omakit lab setup\` builds it` : ""}.`, c))
   else out.push(...verdict("fail", "NOT PROVED", `${record.suite}: ${record.assertion?.reason || record.error || `the suite exited ${record.suiteStatus}`}.`, c))
   return out.join("\n")
 }

package/tools/lab/run.mjs

@@ -40,10 +40,10 @@ import { spawn, spawnSync } from "node:child_process"
 import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, statSync, writeFileSync } from "node:fs"
 import { createServer } from "node:net"
 import { join, resolve } from "node:path"
-import { bytesBoth, labPin } from "./pin.mjs"
+import { bytesBoth, compareVersions, guestIsRelease, labPin, withRelease } from "./pin.mjs"
 import { allocatedBytes, inLab, labDir, labLayout, readJson, removeFromLab, stampNow, writeJson } from "./paths.mjs"
 import { freeBytesAt, guestCpus, probeRunHost } from "./host.mjs"
-import { BASE_FILES, inspectBase, inspectLock } from "./inspect.mjs"
+import { BASE_FILES, baseRelease, inspectBase, inspectLock } from "./inspect.mjs"
 import { press, qemuArgs, qmpExecute, startQemu, typeText } from "./qemu.mjs"
 import { clearStartupNotifications, establishSession, guestIdentity, SESSION_PREAMBLE, sleep, sshGuest, waitForSsh } from "./guest.mjs"
 import { SUITES, suitePreflight } from "./suites.mjs"
@@ -209,13 +209,16 @@ export async function withGuest({ baseDir, stagingName, logFile, layout, pin, on
 
 /**
  * Everything a run needs before a guest boots, or a LabError naming what
- * is missing. Reads only.
+ * is missing. Reads only. The base is held to its own release: a run uses
+ * the base that is there, and whether a newer release is out is the run
+ * record's `newest`, said beside the result, never a reason to refuse.
  */
 export function preflightRun({ suiteName, env = process.env, pin = labPin(), repoRoot, options = {} }) {
   const suite = SUITES[suiteName]
   if (!suite) throw new LabError("usage", `no suite named ${JSON.stringify(suiteName)}; the suites are ${Object.keys(SUITES).join(", ")}`, { remedy: `omakit lab prove <${Object.keys(SUITES).join("|")}>` })
   const layout = labLayout(env)
   const missing = []
+  pin = withRelease(pin, baseRelease(layout, pin))
   const base = inspectBase(layout, pin)
   if (base.state !== "ready") missing.push({ what: `a ready base (${base.state})`, cost: base.reason, command: "omakit lab setup" })
   for (const line of probeRunHost({ pin, env })) if (line.state !== "ok") missing.push({ what: line.name, cost: line.reason, command: line.remedy })
@@ -223,7 +226,7 @@ export function preflightRun({ suiteName, env = process.env, pin = labPin(), rep
   const free = freeBytesAt(layout.cache)
   if (free.bytes < pin.measured.overlayAfterRunBytes) missing.push({ what: "disk for one overlay", cost: `${bytesBoth(free.bytes)} free at ${free.path}; one run's overlay measured ${bytesBoth(pin.measured.overlayAfterRunBytes)} (M14)`, command: "omakit lab prune" })
   if (missing.length) throw new LabError("lab-not-ready", `\`omakit lab prove ${suiteName}\` cannot start: ${missing.length} thing${missing.length === 1 ? " is" : "s are"} missing`, { missing, remedy: missing[0].command })
-  return { suite, layout, base, free }
+  return { suite, layout, base, free, pin }
 }
 
 /**
@@ -232,8 +235,21 @@ export function preflightRun({ suiteName, env = process.env, pin = labPin(), rep
  * Returns the run record; the suite's document is in the run directory,
  * with its provenance.
  */
-export async function runSuite({ suiteName, env = process.env, pin = labPin(), repoRoot, options = {}, onPhase = () => {}, onLine = () => {}, signal }) {
-  const { suite, layout, base } = preflightRun({ suiteName, env, pin, repoRoot, options })
+export async function runSuite({ suiteName, env = process.env, pin = labPin(), repoRoot, options = {}, onPhase = () => {}, onLine = () => {}, signal, checkNewest = null }) {
+  const preflight = preflightRun({ suiteName, env, pin, repoRoot, options })
+  const { suite, layout, base } = preflight
+  pin = preflight.pin
+  // Whether a newer release is out, asked once the run can start, so a
+  // run that cannot start reads nothing from the network. A failed check
+  // is recorded as not checked; it never stops a run.
+  let newest = { checked: false, code: "not-asked", reason: "the newest release was not looked up" }
+  if (checkNewest) {
+    onPhase("looking for the newest Omarchy release")
+    newest = await checkNewest()
+    // An interrupt during the lookup is an interrupt: nothing is booted.
+    if (signal?.aborted || newest.code === "interrupted") throw new LabError("interrupted", "interrupted while looking for the newest release; nothing was booted", { remedy: `omakit lab prove ${suite.name}, when you are ready` })
+  }
+  const behind = newest.checked ? compareVersions(pin.release.name, newest.release.name) < 0 || (pin.release.name === newest.release.name && pin.release.sha256 !== newest.release.sha256) : null
   const runId = `${stampNow()}-${suite.name}`
   const runDir = labDir(layout.state, "runs", runId)
   const startedAt = new Date()
@@ -242,7 +258,9 @@ export async function runSuite({ suiteName, env = process.env, pin = labPin(), r
     runId,
     suite: suite.name,
     startedAt: startedAt.toISOString(),
-    pin: { release: pin.release.name, isoSha256: pin.release.sha256, expectedGuestVersion: pin.release.expectedGuestVersion },
+    pin: { release: pin.release.name, isoSha256: pin.release.sha256, expectedGuestVersion: base.manifest.guest.version },
+    newest: newest.checked ? { release: newest.release.name, isoSha256: newest.release.sha256, tag: newest.tag, publishedAt: newest.publishedAt, checkedAt: newest.checkedAt } : { release: null, code: newest.code, reason: newest.reason },
+    behind,
     base: { dir: base.dir, createdAt: base.manifest.createdAt, allocatedBytes: base.allocatedBytes, diskSha256: base.manifest.disk.sha256, varsSha256: base.manifest.vars.sha256, origin: base.manifest.build?.origin || null },
     guest: null,
     skew: null,
@@ -266,7 +284,7 @@ export async function runSuite({ suiteName, env = process.env, pin = labPin(), r
     booted = await withGuest({ baseDir: base.dir, stagingName: `run-${runId}`, logFile: join(runDir, "qemu.log"), layout, pin, onPhase, signal }, async ({ guest, paths, identity }) => {
       record.guest = identity
       record.host.sshPort = guest.port
-      record.skew = identity.linked || identity.version !== pin.release.expectedGuestVersion
+      record.skew = identity.linked || !guestIsRelease(identity.version, pin.release)
       record.testedSource = identity.testedSource
       save()
       onLine({ state: "info", text: `guest omarchy ${identity.version || "unknown"} on ${identity.kernel || "?"}; tested source ${identity.testedSource}; skew ${record.skew}`, record })
@@ -286,7 +304,7 @@ export async function runSuite({ suiteName, env = process.env, pin = labPin(), r
         // files already carried by hand (`where`), plus the identity a
         // reader can check: run id, guest version, pin, skew.
         document.where = `the ${record.skew ? "linked" : "stock"} Omarchy ${identity.version || "?"} guest of omakit lab, run ${runId}`
-        document.lab = { runId, suite: suite.name, guest: identity, skew: record.skew, testedSource: identity.testedSource, pin: record.pin, base: { createdAt: record.base.createdAt, diskSha256: record.base.diskSha256, origin: record.base.origin }, host: record.host, startedAt: record.startedAt }
+        document.lab = { runId, suite: suite.name, guest: identity, skew: record.skew, testedSource: identity.testedSource, pin: record.pin, newest: record.newest, behind: record.behind, base: { createdAt: record.base.createdAt, diskSha256: record.base.diskSha256, origin: record.base.origin }, host: record.host, startedAt: record.startedAt }
         writeJson(layout.state, `runs/${runId}/${suite.document}`, document)
       }
     })