omakit 0.6.7 → 0.6.9

package/package.json

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

package/skills/omarchy-plugin-build/SKILL.md

@@ -164,4 +164,8 @@ that asked for each are in `docs/BLOCKS.md`; the ones that shape the call:
 `omakit inspect` lists an unmodified store block as one row and each
 `Store {}` site as a write under a directory the plugin controls at mode
 0600; a `FileView` write or a shell redirect that remains names a site
-that still keeps state on its own.
+that still keeps state on its own. A `cp`, `mv`, `install` or `ln` to a
+variable destination is not state Store keeps: the file goes wherever
+the variable points (a hook, a wallpaper), and no block covers that yet;
+the review's requirements for the class are in `docs/MEASUREMENTS.md`
+(M11).

package/tools/blocks/commit.json

@@ -1,5 +1,5 @@
 {
-  "commit": "5dd9db1969775b87b10f21445570557cf82e8073",
-  "recordedAt": "2026-09-21T20:24:57.368Z",
+  "commit": "275ab1557edc5c8d152068e323659a5cc831ebbe",
+  "recordedAt": "2026-09-23T09:18:44.425Z",
   "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/inspect/contract.mjs

@@ -14,7 +14,7 @@ const ARGV_FORMS = new Set(["array", "string", "computed"])
 const DEADLINE_VIA = new Set(["timer-kill", "timeout-argv", "destruction", "block-run", null])
 const COLLECTORS = new Set(["StdioCollector", "SplitParser", "Run", "none", "unknown"])
 const BLOCK_STATES = new Set(["unmodified", "modified"])
-const CONTROLLED = new Set(["observed", "not-observed", "unknown"])
+const CONTROLLED = new Set(["observed", "not-observed", "variable", "unknown"])
 const DECLARED_IN = new Set(["qml", "shell"])
 const FILE_KINDS = ["qml", "js", "shell", "python", "other"]
 
@@ -83,9 +83,10 @@ function write(row, at, problems) {
   if (!isString(row.path)) problems.push(`${at}.path is not a string`)
   if (!nullOr(isString)(row.canonicalPath)) problems.push(`${at}.canonicalPath is neither a string nor null`)
   if (!isString(row.via)) problems.push(`${at}.via is not a string`)
-  if (!CONTROLLED.has(row.controlledDirectory)) problems.push(`${at}.controlledDirectory is not observed, not-observed or unknown`)
+  if (!CONTROLLED.has(row.controlledDirectory)) problems.push(`${at}.controlledDirectory is not observed, not-observed, variable or unknown`)
   if ((row.controlledDirectory === "observed") !== isString(row.controlledBy)) problems.push(`${at}.controlledBy names a directory exactly when controlledDirectory is observed`)
   if (row.canonicalPath === null && row.controlledDirectory !== "unknown") problems.push(`${at}.controlledDirectory is decided for a path that could not be read`)
+  if (row.controlledDirectory === "variable" && (!/^\$(?:[A-Za-z_]\w*|\d)\/?$/.test(row.canonicalPath ?? "") || /^\$(?:HOME|XDG_)/.test(row.canonicalPath))) problems.push(`${at}.controlledDirectory is variable for a path that is not one variable other than $HOME and the XDG names`)
   if (!isBool(row.temp)) problems.push(`${at}.temp is not a boolean`)
   if (!nullOr(isString)(row.mode)) problems.push(`${at}.mode is neither a string nor null`)
   if ((row.via === "block-store") !== (row.block === "store")) problems.push(`${at}.via block-store and block: "store" go together`)

package/tools/inspect/patterns.mjs

@@ -51,6 +51,39 @@ function pathResolved(process) {
   return tool
 }
 
+/**
+ * The verbs that put a file at a destination the caller names. A write by
+ * one of them whose destination is one variable (`cp "$src" "$dest"`) is
+ * the shape of both file-boundary blockers in one review thread,
+ * `install-wallpaper.sh` (`cp -f`, 2026-09-11) and `install-hook.sh`
+ * (`cp`, 2026-09-22), and the class cited neither copy: the path was
+ * `unknown`, with 52 of that tree's 54 writes. A link planted at the
+ * destination picks where the file lands for all four, measured on GNU
+ * coreutils 9.11: `cp` writes through a link to a file, and all four put
+ * the file inside a linked directory. A redirect or `tee` onto a variable
+ * is left out, measured over 15 plugin trees on 2026-09-23: 28 writes by
+ * these four verbs to a variable, against 61 redirects and tees, 24 of
+ * them `>>` appends to a log (docs/MEASUREMENTS.md, M11).
+ */
+const PLACING = new Set(["cp", "mv", "install", "ln"])
+
+/**
+ * The writes the file and state boundary class cites, by what it cites
+ * them for. Each test reads one row alone, so the report can ask it of the
+ * rows at one site and show the write the class cited there, not another
+ * write on the same line (`printf ... > "$f.tmp" && mv "$f.tmp" "$f"`).
+ */
+export function boundaryWrites(writes) {
+  return {
+    outside: writes.filter((row) => row.controlledDirectory === "not-observed" && row.via !== "mktemp"),
+    placed: writes.filter((row) => row.controlledDirectory === "variable" && PLACING.has(row.via)),
+    unmoded: writes.filter((row) => row.via === "mkdir" && row.mode === null),
+  }
+}
+
+/** Words as a list a person reads, in the order given: "cp", "cp and ln", "mv, cp and ln". */
+const listed = (words) => (words.length > 1 ? `${words.slice(0, -1).join(", ")} and ${words.at(-1)}` : words[0])
+
 const SECRET = /authorization|bearer|token=|api[_-]?key|password|secret=/i
 const PRIVILEGED = new Set(["sudo", "pkexec", "doas", "docker"])
 
@@ -210,17 +243,17 @@ export const PATTERNS = Object.freeze([
   {
     id: "file-and-state-boundary",
     label: "file and state boundary",
-    notObserved: "no write outside a controlled directory",
+    notObserved: "no write outside a controlled directory or by cp, mv, install or ln to a variable, no mkdir without a mode",
     measurement: "M11",
     share: 0.15,
     sample: SAMPLE,
     precondition: ({ writes }) => {
-      const outside = writes.filter((row) => row.controlledDirectory === "not-observed" && row.via !== "mktemp")
-      const unmoded = writes.filter((row) => row.via === "mkdir" && row.mode === null)
+      const { outside, placed, unmoded } = boundaryWrites(writes)
       const parts = []
       if (outside.length) parts.push(`${plural(outside.length, "write")} outside a controlled directory (${sites(outside)})`)
+      if (placed.length) parts.push(`${plural(placed.length, "write")} by ${listed([...new Set(placed.map((row) => row.via))])} to a variable destination, not resolvable to a controlled directory (${sites(placed)})`)
       if (unmoded.length) parts.push(`${plural(unmoded.length, "mkdir")} with no mode (${sites(unmoded)})`)
-      return { sites: [...outside, ...unmoded].map(site), observation: `observed ${parts.join("; ")}` }
+      return { sites: [...outside, ...placed, ...unmoded].map(site), observation: `observed ${parts.join("; ")}` }
     },
   },
   {

package/tools/inspect/report.mjs

@@ -19,7 +19,7 @@
 
 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 { boundaryWrites, PATTERNS, SIZE } from "./patterns.mjs"
 
 const NOTHING = "observed nothing of this kind"
 
@@ -110,7 +110,9 @@ function writeRow(write, c) {
     ? `observed (${write.controlledBy})`
     : write.controlledDirectory === "not-observed"
       ? `not observed${write.temp ? ` (${write.canonicalPath.split("/").slice(0, 2).join("/")} is shared)` : ""}`
-      : "unknown (path not readable as a literal prefix)"
+      : write.controlledDirectory === "variable"
+        ? `not resolvable (${write.canonicalPath} is a variable)`
+        : "unknown (path not readable as a literal prefix)"
   const notes = [`under a directory the plugin controls: ${where}`]
   if (write.mode) notes.push(`mode ${write.mode}`)
   return row("info", site(write), what, c, [notes.join("; ")])
@@ -207,7 +209,7 @@ function commandLine(process) {
 }
 
 /**
- * The fact at a site, in one line: the write there for the file class, the
+ * The fact at a site, in one line: the write the file class cited there, the
  * host there for the egress class, otherwise the command, then the host,
  * then the write, whichever the site has.
  */
@@ -222,7 +224,9 @@ function factAt(document, at, patternId) {
     return row ? `${row.scheme}://${row.host}${row.tool ? ` via ${row.tool}` : ""}` : ""
   }
   const write = () => {
-    const row = document.observed.writes.find(same)
+    // On a line with two writes, the one the file class cited, not the first.
+    const here = document.observed.writes.filter(same)
+    const row = (patternId === "file-and-state-boundary" ? Object.values(boundaryWrites(here)).flat()[0] : null) ?? here[0]
     return row ? `${row.via} ${row.canonicalPath ?? row.path}` : ""
   }
   const order = patternId === "file-and-state-boundary" ? [write, process, host] : patternId === "network-egress" ? [host, process, write] : [process, host, write]

package/tools/inspect/writes.mjs

@@ -3,7 +3,11 @@
 // or `touch` in shell; `writeFile` and its variants in JavaScript; `open()`
 // for writing in Python. Each row says whether the path's literal prefix,
 // after the `$HOME`, `~` and `XDG_*` idioms are expanded, falls under a
-// directory the plugin controls, and which mode the file shows for it.
+// directory the plugin controls, and which mode the file shows for it. A
+// path that is one variable and nothing else (`$dest`, `$2`, `$target/`)
+// is said apart from any other path the classification cannot place: the
+// write names no directory, and the extraction follows no assignment to
+// find one.
 
 import { basename, blankComments, blocks, closingBracket, lineOf, propertyValue, blankShellExpressions, shellLogicalLines, shellPieces, shellWords, stringLiteral, withoutRedirections } from "./text.mjs"
 
@@ -11,6 +15,8 @@ import { basename, blankComments, blocks, closingBracket, lineOf, propertyValue,
 export const CONTROLLED = Object.freeze(["$XDG_STATE_HOME", "$XDG_CACHE_HOME", "$XDG_RUNTIME_DIR"])
 export const SHARED_TEMP = Object.freeze(["/tmp", "/var/tmp", "/dev/shm"])
 const DEVICES = new Set(["/dev/null", "/dev/stderr", "/dev/stdout", "/dev/tty"])
+/** A canonical path that is one variable expansion, a name or a positional parameter, with at most a trailing slash. */
+const VARIABLE = /^\$(?:[A-Za-z_]\w*|\d)\/?$/
 
 /**
  * A path's literal prefix in canonical form: `~` and `$HOME` idioms,
@@ -45,8 +51,12 @@ export function canonicalPath(raw) {
 }
 
 /**
- * Whether a canonical path is under a directory the plugin controls.
- * @returns {{ controlledDirectory: "observed"|"not-observed"|"unknown", controlledBy: string|null, temp: boolean }}
+ * Whether a canonical path is under a directory the plugin controls:
+ * `variable` when the path is one variable other than `$HOME` and the XDG
+ * names, so the write names no directory; `unknown` for any other path it
+ * cannot place, an expression, a relative path or a path under a variable
+ * (`$dir/name`).
+ * @returns {{ controlledDirectory: "observed"|"not-observed"|"variable"|"unknown", controlledBy: string|null, temp: boolean }}
  */
 export function classifyPath(path, pluginId) {
   if (path === null || path === undefined) return { controlledDirectory: "unknown", controlledBy: null, temp: false }
@@ -59,6 +69,7 @@ export function classifyPath(path, pluginId) {
     if (path === prefix || path.startsWith(`${prefix}/`)) return { controlledDirectory: "not-observed", controlledBy: null, temp: true }
   }
   if (path.startsWith("/") || path.startsWith("$HOME") || path.startsWith("$XDG_")) return { controlledDirectory: "not-observed", controlledBy: null, temp: false }
+  if (VARIABLE.test(path)) return { controlledDirectory: "variable", controlledBy: null, temp: false }
   return { controlledDirectory: "unknown", controlledBy: null, temp: false }
 }
 
@@ -126,21 +137,31 @@ function pythonWrites(file, pluginId) {
   return rows
 }
 
-/** The words that are not options, and the value of `-m`/`--mode` when one is given. */
-function operands(all) {
+/**
+ * The words that are not options, the value of `-m`/`--mode` when one is
+ * given, and, with `targets`, of `-t`/`--target-directory`: for `cp`, `mv`,
+ * `install` and `ln` that directory is the destination, and every operand
+ * a source.
+ */
+function operands(all, { targets = false } = {}) {
   const words = withoutRedirections(all)
   const out = []
   let mode = null
+  let target = null
   for (let index = 1; index < words.length; index += 1) {
     const word = words[index]
     if (word === "-m" || word === "--mode") {
       mode = words[index + 1] ?? null
       index += 1
     } else if (word.startsWith("--mode=")) mode = word.slice("--mode=".length)
+    else if (targets && (word === "-t" || word === "--target-directory")) {
+      target = words[index + 1] ?? null
+      index += 1
+    } else if (targets && word.startsWith("--target-directory=")) target = word.slice("--target-directory=".length)
     else if (word.startsWith("-") && word !== "-") continue
     else out.push(word)
   }
-  return { operands: out, mode }
+  return { operands: out, mode, target }
 }
 
 function shellWrites(file, pluginId) {
@@ -179,8 +200,9 @@ function shellWrites(file, pluginId) {
         const { operands: paths, mode } = operands(words)
         for (const path of paths) rows.push(row(file, line, path, command, pluginId, mode))
       } else if (["cp", "mv", "install", "ln"].includes(command)) {
-        const { operands: paths, mode } = operands(words)
-        if (paths.length >= 2) rows.push(row(file, line, paths[paths.length - 1], command, pluginId, mode))
+        const { operands: paths, mode, target } = operands(words, { targets: true })
+        if (target !== null && paths.length >= 1) rows.push(row(file, line, target, command, pluginId, mode))
+        else if (paths.length >= 2) rows.push(row(file, line, paths[paths.length - 1], command, pluginId, mode))
       } else if (command === "mktemp") {
         const { operands: paths } = operands(words)
         const template = paths[0] || (words.includes("-p") ? `${words[words.indexOf("-p") + 1]}/tmp.XXXXXX` : "/tmp/tmp.XXXXXX")

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/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; packaging/LAB_PLAN.md M4 to M7 are the 2026-09-10 to 2026-09-13 observations it re-measured"
   }
 }