omakit 0.6.8 → 0.6.9

package/tools/lab/verify.mjs

@@ -1,10 +1,12 @@
-// The two checks that make a file the pinned release: its SHA-256 against
-// the pin, and its detached signature against the packaged Omarchy key at
-// the pinned fingerprint.
+// The two checks that make a file the release: its SHA-256 against the
+// digest the release publishes, and its detached signature against the
+// packaged Omarchy key at the pinned fingerprint.
 //
-// The digest is the identity the package reviewed; the signature is the
-// independent Omarchy authenticity check. Both, every time, and a mismatch
-// in either fails closed (packaging/LAB_PLAN.md, the acquisition boundary).
+// The signature is the trust: a substituted ISO with a substituted
+// checksum beside it fails here, because only Omarchy's key signs. The
+// digest names the file and catches a download that went wrong. Both,
+// every time, and a mismatch in either fails closed (packaging/LAB_PLAN.md,
+// the acquisition boundary).
 // The key is imported into a throwaway GNUPGHOME under the lab, never into
 // the user's keyring: a lab that added keys to ~/.gnupg would be changing
 // the host, and the only host change the lab makes is the lab.
@@ -42,20 +44,139 @@ export function sha256File(file, { onProgress } = {}) {
   return { sha256: hash.digest("hex"), bytes: read }
 }
 
-/** The packaged key, checked against its pinned digest before it is trusted with anything. */
+/**
+ * The packaged key, checked against its pinned digest before it is trusted
+ * with anything. The release names it (releaseOf copies it from the pin,
+ * never from the network); with no release, the pin's own.
+ */
 export function packagedKey(pin = labPin(), dir = LAB_DIR) {
-  const file = join(dir, pin.release.signingKey)
+  const name = pin.release?.signingKey || pin.releases.signingKey
+  const digest = pin.release?.signingKeySha256 || pin.releases.signingKeySha256
+  const file = join(dir, name)
   const { sha256 } = sha256File(file)
-  if (sha256 !== pin.release.signingKeySha256) {
-    throw Object.assign(new Error(`the packaged signing key at ${file} has digest ${sha256}, not the pinned ${pin.release.signingKeySha256}`), { code: "key-mismatch" })
+  if (sha256 !== digest) {
+    throw Object.assign(new Error(`the packaged signing key at ${file} has digest ${sha256}, not the pinned ${digest}`), { code: "key-mismatch" })
   }
   return file
 }
 
+/**
+ * Who a detached OpenPGP signature says signed it, read from the packet
+ * without gpg, so the release search can refuse a changed signer before
+ * a six-gigabyte download: `{ fingerprint, keyId }`, each null when the
+ * packet does not carry it. A version 4 signature packet in either header
+ * format, binary or armoured; the issuer fingerprint subpacket (33) and
+ * the issuer key id (16). Anything it cannot read is `{ null, null }`,
+ * never a throw: the verdict is gpg's, over the whole file, in
+ * judgeRelease; this only lets a wrong key stop early. Measured on the
+ * 4.0.3 and 4.0.4 signatures (119 B each): fingerprint
+ * 40DFB630FF42BCFFB047046CF0134EE680CAC571 in a hashed subpacket.
+ */
+export function signatureIssuer(input) {
+  return signatureIssuers(input)[0] || { fingerprint: null, keyId: null }
+}
+
+/**
+ * Every signer a detached signature names, one per signature packet: a
+ * `.sig` made during a key rotation can carry the new key's signature and
+ * the old one's, and gpg verifies it when any of them is the trusted key,
+ * so the early check must see them all. An empty list when nothing reads.
+ */
+export function signatureIssuers(input) {
+  try {
+    let bytes = Buffer.isBuffer(input) ? input : Buffer.from(input || [])
+    const text = bytes.toString("latin1")
+    if (text.startsWith("-----BEGIN PGP SIGNATURE-----")) {
+      const body = text.split(/\r?\n\r?\n/).slice(1).join("\n").split(/\r?\n/).filter((line) => line && !line.startsWith("=") && !line.startsWith("-----")).join("")
+      bytes = Buffer.from(body, "base64")
+    }
+    const found = []
+    let at = 0
+    while (at < bytes.length && found.length < 16) {
+      const packet = readPacket(bytes, at)
+      if (!packet) break
+      const issuer = packet.tag === 2 ? readIssuer(packet.body) : null
+      if (issuer && (issuer.fingerprint || issuer.keyId)) found.push(issuer)
+      at = packet.next
+    }
+    return found
+  } catch {
+    return []
+  }
+}
+
+/** One OpenPGP packet at `at`, either header format: its tag, body and where the next begins; null when it does not read. */
+function readPacket(bytes, at) {
+  const header = bytes[at]
+  if (header === undefined || !(header & 0x80)) return null
+  let tag
+  let offset
+  let length
+  if (header & 0x40) {
+    tag = header & 0x3f
+    const first = bytes[at + 1]
+    if (first < 192) [offset, length] = [at + 2, first]
+    else if (first < 224 && bytes.length > at + 2) [offset, length] = [at + 3, ((first - 192) << 8) + bytes[at + 2] + 192]
+    else if (first === 255 && bytes.length > at + 5) [offset, length] = [at + 6, bytes.readUInt32BE(at + 2)]
+    else return null
+  } else {
+    tag = (header >> 2) & 0x0f
+    const type = header & 3
+    if (type === 0 && bytes.length > at + 1) [offset, length] = [at + 2, bytes[at + 1]]
+    else if (type === 1 && bytes.length > at + 2) [offset, length] = [at + 3, bytes.readUInt16BE(at + 1)]
+    else if (type === 2 && bytes.length > at + 4) [offset, length] = [at + 5, bytes.readUInt32BE(at + 1)]
+    else return null
+  }
+  const body = bytes.subarray(offset, offset + length)
+  if (body.length !== length) return null
+  return { tag, body, next: offset + length }
+}
+
+/** The issuer of one version 4 signature packet's body, from its subpackets; null for any other version. */
+function readIssuer(packet) {
+  if (packet.length < 6 || packet[0] !== 4) return null
+  const out = { fingerprint: null, keyId: null }
+  const readSubpackets = (start, end) => {
+    let at = start
+    while (at < end) {
+      let size
+      const first = packet[at]
+      if (first < 192) [size, at] = [first, at + 1]
+      else if (first < 255) [size, at] = [((first - 192) << 8) + packet[at + 1] + 192, at + 2]
+      else [size, at] = [packet.readUInt32BE(at + 1), at + 5]
+      if (!size || at + size > end) return
+      const type = packet[at] & 0x7f
+      const data = packet.subarray(at + 1, at + size)
+      if (type === 33 && data[0] === 4 && data.length === 21) out.fingerprint = data.subarray(1).toString("hex").toUpperCase()
+      if (type === 16 && data.length === 8) out.keyId = data.toString("hex").toUpperCase()
+      at += size
+    }
+  }
+  const hashedLength = packet.readUInt16BE(4)
+  if (6 + hashedLength + 2 > packet.length) return null
+  readSubpackets(6, 6 + hashedLength)
+  const unhashedStart = 6 + hashedLength + 2
+  const unhashedLength = packet.readUInt16BE(6 + hashedLength)
+  if (unhashedStart + unhashedLength <= packet.length) readSubpackets(unhashedStart, unhashedStart + unhashedLength)
+  return out
+}
+
+/**
+ * Whether the signers a signature names include the pinned one: `true`
+ * when one does, `false` when every signer it names is another key,
+ * `null` when it names none that can be read (the verdict is then gpg's
+ * alone, over the whole file).
+ */
+export function signedByPinned(issuers, fingerprint) {
+  const named = issuers.filter((issuer) => issuer.fingerprint || issuer.keyId)
+  if (!named.length) return null
+  return named.some((issuer) => issuer.fingerprint ? issuer.fingerprint === fingerprint : fingerprint.endsWith(issuer.keyId))
+}
+
 /**
  * Verify a detached signature with gpg in a throwaway keyring under
  * `stagingRoot`. The answer is the fingerprint gpg reports as VALIDSIG, or
- * null; the caller compares it with the pin. `run` is injectable.
+ * null; the caller compares it with the pinned signer. `run` is injectable.
  */
 export function verifySignature({ file, signature, keyFile, stagingRoot, run = spawnSync }) {
   const home = labDir(stagingRoot, `gnupg-${process.pid}`)
@@ -68,21 +189,29 @@ export function verifySignature({ file, signature, keyFile, stagingRoot, run = s
     const verified = run("gpg", ["--batch", "--status-fd", "1", "--verify", signature, file], { env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 600_000 })
     const status = String(verified.stdout || "")
     const valid = status.match(/^\[GNUPG:\] VALIDSIG ([0-9A-F]{40}) /m)
-    if (valid && verified.status === 0) return { state: "valid", fingerprint: valid[1], detail: status.match(/^\[GNUPG:\] GOODSIG \S+ (.+)$/m)?.[1] || null }
-    const bad = status.match(/^\[GNUPG:\] (BADSIG|NO_PUBKEY|ERRSIG|NODATA)\b.*$/m)
-    return { state: bad ? bad[1].toLowerCase() : "invalid", fingerprint: null, detail: (bad?.[0] || String(verified.stderr || "").trim().split("\n")[0] || "gpg did not report a valid signature").trim() }
+    // A .sig made during a key rotation carries a second signature by a key
+    // this keyring does not hold: gpg reports VALIDSIG for the packaged key,
+    // NO_PUBKEY for the other, and exits 2 (gpg 2.4.9). The keyring holds
+    // the packaged key alone, so a VALIDSIG can only be its own; the file is
+    // valid when there is one and no signature failed (BADSIG), whatever
+    // else gpg could not check.
+    const bad = /^\[GNUPG:\] BADSIG\b/m.test(status)
+    const unknownOnly = verified.status === 2 && /^\[GNUPG:\] (?:NO_PUBKEY|ERRSIG)\b/m.test(status)
+    if (valid && !bad && (verified.status === 0 || unknownOnly)) return { state: "valid", fingerprint: valid[1], detail: status.match(/^\[GNUPG:\] GOODSIG \S+ (.+)$/m)?.[1] || null }
+    const failed = status.match(/^\[GNUPG:\] (BADSIG|NO_PUBKEY|ERRSIG|NODATA)\b.*$/m)
+    return { state: failed ? failed[1].toLowerCase() : "invalid", fingerprint: null, detail: (failed?.[0] || String(verified.stderr || "").trim().split("\n")[0] || "gpg did not report a valid signature").trim() }
   } finally {
     removeFromLab(stagingRoot, `gnupg-${process.pid}`)
   }
 }
 
 /**
- * The whole judgement over a file on disk against the pin: byte count,
+ * The whole judgement over a file on disk against the release: byte count,
  * digest, signature. Every field is reported even after the first failure,
  * so a report can say "the size matches, the digest does not" rather than
  * only the first thing wrong. The sidecar's digest is compared too, so a
- * published checksum that disagrees with the pin is named (it would mean
- * the object at the versioned URL was replaced).
+ * checksum on disk that disagrees with the release's digest is named (the
+ * object at the versioned URL was replaced after the release was read).
  */
 export function judgeRelease({ file, signature, checksum, pin = labPin(), stagingRoot, keyFile = packagedKey(pin), onProgress, run }) {
   const verdict = { file, bytes: null, bytesMatch: false, sha256: null, sha256Match: false, sidecarSha256: null, sidecarMatch: null, signature: null, ok: false }
@@ -96,7 +225,7 @@ export function judgeRelease({ file, signature, checksum, pin = labPin(), stagin
   verdict.bytes = st.size
   verdict.bytesMatch = st.size === pin.release.bytes
   if (!verdict.bytesMatch) {
-    verdict.reason = `${file} is ${st.size.toLocaleString("en-US")} B, the pin says ${pin.release.bytes.toLocaleString("en-US")} B`
+    verdict.reason = `${file} is ${st.size.toLocaleString("en-US")} B; Omarchy ${pin.release.name} is ${pin.release.bytes.toLocaleString("en-US")} B as published`
     return verdict
   }
   verdict.sha256 = sha256File(file, { onProgress }).sha256
@@ -111,7 +240,7 @@ export function judgeRelease({ file, signature, checksum, pin = labPin(), stagin
     }
   }
   if (!verdict.sha256Match) {
-    verdict.reason = `${file} has digest ${verdict.sha256}, the pin says ${pin.release.sha256}`
+    verdict.reason = `${file} has digest ${verdict.sha256}; Omarchy ${pin.release.name} publishes ${pin.release.sha256}`
     return verdict
   }
   if (!signature) {
@@ -125,7 +254,7 @@ export function judgeRelease({ file, signature, checksum, pin = labPin(), stagin
     return verdict
   }
   if (signed.fingerprint !== pin.release.signingFingerprint) {
-    verdict.reason = `the signature is by ${signed.fingerprint}, the pin says ${pin.release.signingFingerprint}`
+    verdict.reason = `the signature is by ${signed.fingerprint}, not the key omakit ships (${pin.release.signingFingerprint})`
     return verdict
   }
   verdict.ok = true

package/tools/marketplace/README.md

@@ -81,22 +81,23 @@ in the document:
 
 | File | Purpose |
 | --- | --- |
-| `lab/pin.json`, `lab/pin.mjs` | The release pin: Omarchy 4.0.3, its URL, exact bytes, SHA-256, signer fingerprint, expected guest package; the toolchain commit and the digests of its harness before and after the patch; the measured costs. Refuses a URL that resolves latest. `bytesBoth` prints every size in GB and GiB. |
+| `lab/pin.json`, `lab/pin.mjs` | What the lab holds fixed, never a release: where Omarchy's releases are listed (GitHub) and published (the ISO URL template), the floor (4.0.3), how many newer tags are read, the signer fingerprint and the key's digest; the toolchain commit and the digests of its harness before and after the patch; the costs measured with Omarchy 4.0.3. Refuses an ISO URL that names latest. `releaseOf` gives one release in the shape every module reads, `compareVersions` orders by the three numbers, `guestIsRelease` holds a guest package to its release. `bytesBoth` prints every size in GB and GiB. |
 | `lab/omarchy.gpg` | The Omarchy public signing key, 632 bytes of armoured text, pinned by digest. |
-| `lab/patches/omarchy-iso-test.patch` | The working harness of the reference host against the pinned omarchy-iso commit: the 4.0.3 greeter, no host package install, the host-test extensions. Applied by a person, never by omakit. |
+| `lab/release.mjs` | The newest release, looked up each time through `github.mjs`'s GETs: the release list, newest first by version, drafts and pre-releases aside, at or above the floor, each candidate's `.sha256` and `.sig` and the ISO's announced size (its body cancelled unread). A 404 passes a newer tag over and names it; any other failure stops the search; a signer other than the pinned one stops it before the ISO is asked for (`signer-changed`). `checkNewestRelease` is the same as a value for inspect, doctor and a run. |
+| `lab/patches/omarchy-iso-test.patch` | The working harness of the reference host against the pinned omarchy-iso commit: the 4.0.3 greeter (unchanged in 4.0.4), no host package install, the host-test extensions. Applied by a person, never by omakit. |
 | `lab/paths.mjs` | The two lab roots under the user cache and state, the layout, and `inLab`, the guard every write goes through; the one rename and the one stream copy in the tree. |
 | `lab/host.mjs` | Read-only probes: KVM, the commands a run, a build and a verification need (`--version`, never `ssh-keygen` bare), the OVMF firmware, free disk, memory, the CPU count. Installs nothing. |
-| `lab/verify.mjs` | SHA-256 streamed in Node, the signature check in a throwaway keyring, and `judgeRelease`: byte count, digest, sidecar, signature, fingerprint, in that order, every field reported. |
-| `lab/inspect.mjs` | The read-only view: the download and its verification record, the base's state from its manifest (`ready`, `mismatch`, `invalid`, `missing`), the toolchain by its harness's hash, staging with QMP liveness, the lock, the totals, what is missing with its cost and command. |
+| `lab/verify.mjs` | SHA-256 streamed in Node, the signature check in a throwaway keyring, `judgeRelease`: byte count, digest, sidecar, signature, fingerprint, in that order, every field reported, against the release as published; and `signatureIssuer`, the signer read from the `.sig` packet without gpg, so a changed key stops the search before a download. |
+| `lab/inspect.mjs` | The read-only view, against the newest release its caller looked up (or the base's own): the download and its verification record, each download directory by what it holds, the base's state from its manifest (`ready`, `outdated`, `mismatch`, `invalid`, `missing`), whether the lab is behind, the toolchain by its harness's hash, staging with QMP liveness and the build QEMUs a pidfile and `/proc` show still running, the lock, the totals, what is missing with its cost and command. |
 | `lab/qemu.mjs` | QEMU's argument list, pure; QMP over the Unix socket from Node; the qcode table and `typeText` for the greeter. |
 | `lab/guest.mjs` | SSH to 127.0.0.1 with the base's key and no forwarding; the session preamble; the login loop; the startup-notification dismissal; the guest's identity (`pacman -Q omarchy`, the kernel, whether the session is linked). |
 | `lab/run.mjs` | The lifecycle: the lock, `withGuest` (overlay, the run's firmware copy, QEMU as a child, SSH, login, identity, the body, power-off, the overlay measured and removed, the base checked unchanged), `preflightRun`, `runSuite` with the harness as a child and the document's provenance. |
-| `lab/setup.mjs` | The plan and the disclosure, the resumable literal GET through `github.mjs`'s one call site, the import of a local file, verification and promotion of the ISO, the toolchain record, the build through a copy of the toolchain's harness under staging, the verification boot, the manifest, the promotion; the listed plugins for the evidence suite. |
-| `lab/prune.mjs` | The inventory of what the lab owns with allocated bytes, the refusal while a QEMU answers, the removal of exactly the targets, recovered and remaining bytes. |
+| `lab/setup.mjs` | The plan (first what no release changes, so a host that cannot build is refused before the network; then the newest release, or `--from` named by its file offline) and the disclosure, the resumable literal GET through `github.mjs`'s one call site, the import of a local file, verification and promotion of the ISO, the toolchain record, the build through a copy of the toolchain's harness under staging with every QEMU it left stopped, the verification boot, the manifest, the promotion, and after it the removal of older downloads; the listed plugins for the evidence suite. |
+| `lab/prune.mjs` | The inventory of what the lab owns with allocated bytes, each download named by its own record, the refusal while a QEMU answers or a build's QEMU still runs, the removal of exactly the targets, recovered and remaining bytes. |
 | `lab/suites.mjs` | The four suites as data: host body, files needed, document, assertion, timeout, arguments; the listed plugin ids for `weigh-evidence`, their commits the pinned catalog's. |
 | `lab/harness.sh`, `lab/suites/*.sh` | The one harness every suite runs through, every value an argument; the Run, Store and weigh bodies. |
 | `lab/qmp-cli.mjs` | QMP from a shell: a screendump or a chord, for the harness. |
-| `lab/report.mjs` | The lab's lines for `doctor`, and `inspect`, `setup`, `run` and `prune` for a person, drawn with `style.mjs`. |
+| `lab/report.mjs` | The lab's lines for `doctor` (`lab.release`: on the newest release, behind, or not looked up), and `inspect`, `setup`, `run` and `prune` for a person, drawn with `style.mjs`. |
 
 ```text
 omakit pin

package/tools/marketplace/cli.mjs

@@ -54,6 +54,7 @@ import { addBlock } from "../blocks/add.mjs"
 import { inspectLab } from "../lab/inspect.mjs"
 import { runSuite } from "../lab/run.mjs"
 import { CONSENT_QUESTION, planSetup, recordToolchain, setupLab } from "../lab/setup.mjs"
+import { checkNewestRelease } from "../lab/release.mjs"
 import { planPrune, prune } from "../lab/prune.mjs"
 import { renderLab, renderPrunePlan, renderPruneResult, renderRunIdentity, renderRunResult, renderSetupPlan, renderSetupResult } from "../lab/report.mjs"
 
@@ -101,12 +102,14 @@ const REMEDY = Object.freeze({
   "lab-not-ready": "omakit lab inspect",
   "lab-busy": "omakit lab inspect",
   "iso-mismatch": "omakit lab prune, then omakit lab setup",
-  "size-mismatch": "The object at the pinned URL is not the pinned release; a pin update is a reviewed change, and docs/LAB.md says how.",
-  "sidecar-mismatch": "The published checksum is not the pin's; a pin update is a reviewed change, and docs/LAB.md says how.",
+  "size-mismatch": "omakit lab setup: Omarchy changed the object at the versioned URL since the release was read, and setup reads it again.",
+  "sidecar-mismatch": "omakit lab setup: Omarchy republished the release while setup ran, and setup reads it again.",
   "key-mismatch": "The packaged signing key is not the one the pin names: reinstall omakit from the registry (`omakit upgrade`).",
+  "release-unavailable": "omakit lab inspect names the newest release and why the newer ones were passed over; run it again once Omarchy has published the ISO, its .sha256 and its .sig.",
+  "signer-changed": "omakit upgrade: a newer omakit carries Omarchy's new key once it is verified. Until then the lab keeps the base it has.",
   "toolchain-missing": "omakit lab inspect prints the one command that prepares the toolchain.",
   "toolchain-mismatch": "omakit lab inspect prints the one command that prepares the toolchain.",
-  "guest-mismatch": "omakit lab prune removes the staged base; a pin update is a reviewed change, and docs/LAB.md says how.",
+  "guest-mismatch": "omakit lab prune removes the staged base; an ISO that installs another release's omarchy package is not used as that release.",
   "build-failed": "Read build.log under the lab's staging directory, then omakit lab prune and omakit lab setup again.",
   "qemu-failed": "Read qemu.log in the run directory; omakit lab inspect names what the host lacks.",
   "overlay-failed": "omakit lab inspect: the base must be ready and the disk must have room for one overlay.",
@@ -674,7 +677,7 @@ async function cmdWeigh(args) {
  */
 async function cmdLab(args) {
   const parsed = checkArgs(args, ACCEPTED.lab)
-  const signature = "omakit lab prove <suite> | inspect [--verify] | setup [--from <file>] [--toolchain <dir>] [--plugins] [--yes] | prune [--keep-iso] [--records] [--yes]"
+  const signature = "omakit lab prove <suite> [--offline] | inspect [--verify] [--offline] | setup [--from <file>] [--toolchain <dir>] [--plugins] [--offline] [--yes] | prune [--keep-iso] [--records] [--yes]"
   if (parsed.offending !== null) fail("usage", `${parsed.reason}. Accepted: ${acceptedWords("lab")}.`, 2, signature)
   const [what, suite] = parsed.positionals
   if (!["prove", "inspect", "setup", "prune"].includes(what || "")) fail("usage", `lab needs one of prove, inspect, setup or prune${what ? `, not ${JSON.stringify(what)}` : ""}.`, 2, signature)
@@ -693,6 +696,13 @@ async function cmdLab(args) {
   }
   const listen = () => { for (const signal of Object.keys(SIGNAL_EXIT)) process.on(signal, interrupt) }
   const unlisten = () => { for (const signal of Object.keys(SIGNAL_EXIT)) process.off(signal, interrupt) }
+  // The newest Omarchy release, read from the release list once per
+  // command, with its own deadline so a network that drops packets costs
+  // at most that; --offline skips it and says so.
+  const offline = parsed.options.has("--offline")
+  const newestRelease = async (seconds = 45) => offline
+    ? { checked: false, code: "offline", reason: "--offline" }
+    : checkNewestRelease({ signal: AbortSignal.any([controller.signal, AbortSignal.timeout(seconds * 1000)]) })
   /** A lab error that stopped for a signal carries the signal, so the exit status follows it. */
   const stopped = (error) => {
     if (error?.code === "interrupted" && !error.signal) error.signal = stoppedBy
@@ -703,8 +713,10 @@ async function cmdLab(args) {
     if (suite) fail("usage", `inspect takes no suite, so ${JSON.stringify(suite)} is one argument more than it takes.`, 2, signature)
     let lab
     try {
+      if (!offline) spinner.phase("looking for the newest Omarchy release")
+      const newest = await newestRelease()
       spinner.phase(parsed.options.has("--verify") ? "hashing the ISO and checking its signature" : "reading the lab")
-      lab = await inspectLab({ verify: parsed.options.has("--verify") })
+      lab = await inspectLab({ newest, verify: parsed.options.has("--verify") })
     } catch (error) {
       spinner.done()
       failFrom(error)
@@ -730,6 +742,7 @@ async function cmdLab(args) {
         repoRoot: ROOT,
         options: { runs },
         signal: controller.signal,
+        checkNewest: () => newestRelease(30),
         onPhase: spinner.phase,
         onLine: (line) => {
           spinner.done()
@@ -767,15 +780,30 @@ async function cmdLab(args) {
       failFrom(error)
     }
     let plan
+    const from = parsed.options.get("--from") || null
     try {
-      plan = planSetup({ from: parsed.options.get("--from") || null, plugins: parsed.options.has("--plugins"), repoRoot: ROOT })
+      // First what no release changes: a host that cannot build is told so
+      // before the network is read. Then the newest release, and the plan
+      // that prepares it.
+      plan = planSetup({ from, plugins: parsed.options.has("--plugins"), repoRoot: ROOT })
+      if (!plan.blockers.length) {
+        if (!offline) spinner.phase("looking for the newest Omarchy release")
+        const newest = await newestRelease()
+        spinner.done()
+        // A newer release signed by a key omakit does not ship is a finding,
+        // not a lookup that failed: the lab cannot be brought current, and
+        // the person has to know, whatever base is there.
+        if (!newest.checked && newest.code === "signer-changed") failFrom(Object.assign(new Error(newest.reason), { code: "signer-changed", remedy: "omakit upgrade: a newer omakit carries the new key once it is verified" }))
+        plan = planSetup({ newest, from, plugins: parsed.options.has("--plugins"), repoRoot: ROOT })
+      }
     } catch (error) {
+      spinner.done()
       failFrom(error)
     }
     // The plan is narrated before the question, so the record says what
     // was agreed to; a plan that cannot run is the failure, on stderr.
     if (plan.blockers.length) {
-      refuse(args, plan, (colour) => renderSetupPlan(plan, { colour }), { code: "lab-blocked", message: `setup cannot start: ${plan.blockers.join("; ")}` })
+      refuse(args, plan, (colour) => renderSetupPlan(plan, { colour }), { code: "lab-blocked", message: `setup cannot start: ${plan.blockers.map((item) => item.what).join("; ")} missing` })
       return
     }
     if (!plan.steps.length) return succeed(args, plan, (colour) => renderSetupPlan(plan, { colour }))

package/tools/marketplace/doctor.mjs

@@ -68,6 +68,7 @@ import { pathHint } from "./path-hint.mjs"
 import { completionStatus } from "./completion-check.mjs"
 import { inspectLab } from "../lab/inspect.mjs"
 import { labDoctorChecks } from "../lab/report.mjs"
+import { checkNewestRelease } from "../lab/release.mjs"
 
 export function tool(repoRoot) {
   try {
@@ -278,11 +279,12 @@ export function pinFreshness(identity, head, comparison = null, { upgrade = null
  * @param {{ repoRoot: string, offline?: boolean, env?: object, npmPrefix?: () => string|null,
  *           resolveHead?: typeof defaultBranchHead, latest?: typeof registryLatest, compare?: typeof comparePin }} options
  *   `env` and `npmPrefix` are injectable for tests of the PATH check;
- *   `resolveHead`, `latest` and `compare` for tests of the two checks that
- *   read the network, whose defaults are the tool's one HEAD resolver, its
- *   one registry read and the pin comparison above.
+ *   `resolveHead`, `latest`, `compare` and `newestRelease` for tests of the
+ *   checks that read the network, whose defaults are the tool's one HEAD
+ *   resolver, its one registry read, the pin comparison above and the
+ *   lab's read of Omarchy's release list (tools/lab/release.mjs).
  */
-export async function doctor({ repoRoot, offline = false, onPhase, env = process.env, npmPrefix, resolveHead = defaultBranchHead, latest: latestVersion = registryLatest, compare = comparePin }) {
+export async function doctor({ repoRoot, offline = false, onPhase, env = process.env, npmPrefix, resolveHead = defaultBranchHead, latest: latestVersion = registryLatest, compare = comparePin, newestRelease = checkNewestRelease }) {
   // Optional: told what is being read while the network answers. Never
   // affects the result.
   const phase = onPhase || (() => {})
@@ -431,9 +433,15 @@ export async function doctor({ repoRoot, offline = false, onPhase, env = process
   // the base, each with its measured reason, every one advice and never a
   // problem, because the lab is optional and doctor installs nothing.
   // Read-only: inspectLab creates no directory, verifies nothing online
-  // and starts nothing.
+  // and starts nothing. The one read is Omarchy's release list, so the
+  // lab says when a newer release is out; --offline skips it.
+  let newest = { checked: false, code: "offline", reason: "--offline" }
+  if (!offline) {
+    phase("looking for the newest Omarchy release")
+    newest = await newestRelease({ signal: AbortSignal.timeout(45_000) })
+  }
   phase("reading the lab")
-  for (const check of labDoctorChecks(await inspectLab({ env }))) checks.push(check)
+  for (const check of labDoctorChecks(await inspectLab({ env, newest }))) checks.push(check)
 
   return { checks, problems: checks.filter((check) => check.state === "problem").length }
 }

package/tools/marketplace/github.mjs

@@ -119,7 +119,7 @@ export const CREDENTIAL_HOST = "api.github.com"
  */
 export const GET_DEADLINE_MS = 20_000
 
-async function get(url, { accept, signal, rangeFrom = 0 } = {}) {
+async function get(url, { accept, signal, rangeFrom = 0, rangeEnd = null } = {}) {
   const { host } = new URL(url)
   // The credential is GitHub's and goes to GitHub's API and nowhere else.
   // Measured before this held: `omakit upgrade` and `doctor` sent the gh
@@ -136,7 +136,9 @@ async function get(url, { accept, signal, rangeFrom = 0 } = {}) {
   // A resumed download asks for the rest of the object; the lab's ISO
   // fetch is the one caller, and a server that ignores the range answers
   // 200 from the start, which the caller handles by starting over.
-  if (rangeFrom > 0) headers.range = `bytes=${rangeFrom}-`
+  // The lab's release search asks for the first byte alone (`rangeEnd` 0)
+  // to read the ISO's size from Content-Range without fetching the image.
+  if (rangeFrom > 0 || rangeEnd !== null) headers.range = `bytes=${rangeFrom}-${rangeEnd ?? ""}`
   let response
   try {
     response = await fetch(url, { method: "GET", headers, redirect: "follow", signal: signal || AbortSignal.timeout(GET_DEADLINE_MS) })
@@ -144,8 +146,12 @@ async function get(url, { accept, signal, rangeFrom = 0 } = {}) {
     // Node reports every transport failure as "fetch failed" with the real
     // reason in `cause`. A person needs the reason, and the CLI keys its
     // remedy on the code, so both are carried out of here.
-    const cause = error?.name === "TimeoutError" ? `no answer within ${GET_DEADLINE_MS / 1000} s` : error?.cause?.code || error?.cause?.message || error?.message || "fetch failed"
     const { host, pathname } = new URL(url)
+    // The caller stopped it (SIGINT, SIGTERM): that is an interrupt, not a
+    // network that did not answer, and the caller has to be able to tell.
+    if (signal?.aborted && signal.reason?.name !== "TimeoutError") throw new GitHubError("interrupted", `interrupted while reading ${pathname} from ${host}`)
+    // A caller's own deadline is the caller's figure; only the default is 20 s.
+    const cause = error?.name === "TimeoutError" ? (signal ? "no answer before the caller's deadline" : `no answer within ${GET_DEADLINE_MS / 1000} s`) : error?.cause?.code || error?.cause?.message || error?.message || "fetch failed"
     throw new GitHubError("network-unavailable", `${host} did not answer (${cause}) while reading ${pathname}`)
   }
   if (!response.ok) {
@@ -178,8 +184,8 @@ export async function getText(url, accept) {
  * same literal method, and the credential stays with api.github.com; the
  * ISO origin (iso.omarchy.org) never sees it.
  */
-export async function getStream(url, { rangeFrom = 0, signal } = {}) {
-  return get(url, { accept: "application/octet-stream", signal, rangeFrom })
+export async function getStream(url, { rangeFrom = 0, rangeEnd = null, signal } = {}) {
+  return get(url, { accept: "application/octet-stream", signal, rangeFrom, rangeEnd })
 }
 
 /** Parse a marketplace issue URL into its parts. */

package/tools/marketplace/options.mjs

@@ -31,7 +31,7 @@ export const ACCEPTED = Object.freeze({
   inspect: Object.freeze({ valued: ["--out"], flags: ["--full", "--json", "--offline", "--allow-dirty"], positionals: 1 }),
   add: Object.freeze({ valued: [], flags: ["--update", "--json"], positionals: 2 }),
   weigh: Object.freeze({ valued: ["--runs", "--window", "--settle", "--out"], flags: ["--all", "--list", "--json", "--yes"], positionals: 1 }),
-  lab: Object.freeze({ valued: ["--runs", "--from", "--toolchain", "--out"], flags: ["--json", "--yes", "--verify", "--plugins", "--keep-iso", "--records"], positionals: 2 }),
+  lab: Object.freeze({ valued: ["--runs", "--from", "--toolchain", "--out"], flags: ["--json", "--yes", "--verify", "--plugins", "--keep-iso", "--records", "--offline"], positionals: 2 }),
 })
 
 /** The accepted options of a command in the words a refusal prints: `--runs N, --all, ...`. */

package/tools/marketplace/usage.mjs

@@ -111,26 +111,29 @@ export const COMMANDS = Object.freeze([
   },
   {
     signature: [
-      "omakit lab prove <suite> [--runs <n>] [--json] [--out <file>]",
-      "omakit lab inspect [--verify] [--json] [--out <file>]",
+      "omakit lab prove <suite> [--runs <n>] [--offline] [--json] [--out <file>]",
+      "omakit lab inspect [--verify] [--offline] [--json] [--out <file>]",
       "omakit lab setup [--from <file>] [--toolchain <dir>] [--plugins] [--yes]",
       "omakit lab prune [--keep-iso] [--records] [--yes] [--json]",
     ],
     lines: [
-      "Prove a suite in a disposable Omarchy guest, never on the desktop: the",
-      "pinned 4.0.3 release booted from an immutable verified base, a fresh",
-      "overlay per run, the guest's installed omarchy package read and printed",
-      "before the suite, the document written with that identity. `prove` boots",
-      "nothing until the base, the host and the suite's files are there, and",
-      "names what is missing, what it takes, and the one command; it fetches",
-      "nothing. `inspect` is read-only: the pinned release, its exact size,",
-      "digest and signer, what is on disk and verified, what the host lacks.",
-      "`setup` is the only path that fetches bytes: one consent naming the",
-      "exact size and destination (--yes for an agent), a resumable GET of",
-      "the pinned URL or a copy of --from, verified against the pinned SHA-256",
-      "and the Omarchy signature before anything boots it, then one base built",
-      "by the pinned omarchy-iso toolchain, whose checkout --toolchain records",
-      "and which setup never fetches. `prune` frees the lab cache and says how",
+      "Prove a suite in a disposable Omarchy guest, never on the desktop: an",
+      "Omarchy release booted from an immutable verified base, a fresh overlay",
+      "per run, the guest's installed omarchy package read and printed before",
+      "the suite, the document written with that identity. Every action but",
+      "prune reads Omarchy's release list and says when a newer release is out",
+      "(--offline skips it). `prove` boots nothing until the base, the host",
+      "and the suite's files are there, and names what is missing, what it",
+      "takes, and the one command; it runs the base there, behind or not.",
+      "`inspect` writes nothing: the newest release, its size, digest and",
+      "signer, what is on disk and verified, what the host lacks. `setup` is",
+      "the only path that fetches bytes: it prepares the newest release, with",
+      "one consent naming the exact size and destination (--yes for an agent),",
+      "a resumable GET or a copy of --from, verified against the published",
+      "SHA-256 and the Omarchy signature omakit ships before anything boots it,",
+      "then one base built by the pinned omarchy-iso toolchain, whose checkout",
+      "--toolchain records and which setup never fetches; the old base stays",
+      "until the new one verifies. `prune` frees the lab cache and says how",
       "much. docs/LAB.md is the contract. Suites: run, store, weigh,",
       "weigh-evidence.",
     ],