omakit 0.5.1 → 0.6.1

package/tools/lab/prune.mjs

@@ -0,0 +1,68 @@
+// `omakit lab prune`: the explicit owner of lab-cache deletion. It
+// inventories what the lab owns under its own roots, prints each target
+// with its allocated bytes and the exact total, asks once (or takes
+// --yes), refuses while a run holds the lab or a QEMU still answers on a
+// staged socket, and afterwards reports what was recovered and what
+// remains. It never follows a symlink out of the lab, never touches the
+// marketplace pin or a checkout, and leaves run records alone unless
+// --runs names them.
+
+import { existsSync, lstatSync, readdirSync } from "node:fs"
+import { join } from "node:path"
+import { bytesBoth, labPin } from "./pin.mjs"
+import { allocatedBytes, labLayout, removeFromLab } from "./paths.mjs"
+import { inspectBase, inspectLock, inspectStaging } from "./inspect.mjs"
+import { LabError } from "./run.mjs"
+
+/**
+ * What prune would remove. `keepIso` leaves the verified download (the
+ * expensive fetch); `runs` adds the run records under the state root.
+ */
+export async function planPrune({ env = process.env, pin = labPin(), keepIso = false, runs = false } = {}) {
+  const layout = labLayout(env)
+  const targets = []
+  const add = (root, relative, what) => {
+    const path = join(root, relative)
+    if (!existsSync(path)) return
+    if (lstatSync(path).isSymbolicLink()) throw new LabError("prune-refused", `${path} is a symbolic link; the lab wrote none, so nothing under it is removed`)
+    targets.push({ root, relative, path, what, bytes: allocatedBytes(path) })
+  }
+  const lock = await inspectLock(layout)
+  const staging = await inspectStaging(layout)
+  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}`)
+  if (existsSync(layout.downloads)) {
+    for (const digest of readdirSync(layout.downloads)) {
+      const dir = join(layout.downloads, digest)
+      const verified = digest === pin.release.sha256 && existsSync(join(dir, "verified.json")) && existsSync(join(dir, pin.release.fileName))
+      if (verified && keepIso) {
+        add(layout.cache, `downloads/${digest}/${pin.release.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)})`)
+    }
+  }
+  const base = inspectBase(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")
+  if (lock.held && !lock.alive) add(layout.cache, "lab.lock", `a stale lock from ${lock.record?.runId || "an unknown run"}`)
+  if (runs && existsSync(layout.runs)) add(layout.state, "runs", "every run record and document under the state root")
+  const total = targets.reduce((sum, target) => sum + target.bytes, 0)
+  return { layout, targets, total, blockers, remaining: { cache: existsSync(layout.cache) ? allocatedBytes(layout.cache) : 0, runs: existsSync(layout.runs) ? allocatedBytes(layout.runs) : 0 } }
+}
+
+/** Remove exactly the plan's targets, after the caller's consent; report recovered and remaining bytes. */
+export function prune(plan) {
+  if (plan.blockers.length) throw new LabError("lab-busy", `prune refuses while ${plan.blockers.join("; ")}`, { remedy: "wait for the run, or `omakit lab inspect` to see it" })
+  const removed = []
+  for (const target of plan.targets) {
+    removeFromLab(target.root, target.relative)
+    removed.push(target)
+  }
+  const recovered = removed.reduce((sum, target) => sum + target.bytes, 0)
+  const remaining = { cache: existsSync(plan.layout.cache) ? allocatedBytes(plan.layout.cache) : 0, runs: existsSync(plan.layout.runs) ? allocatedBytes(plan.layout.runs) : 0 }
+  return { removed, recovered, remaining, words: `recovered ${bytesBoth(recovered)}; ${bytesBoth(remaining.cache)} remain in the lab cache and ${bytesBoth(remaining.runs)} in run records` }
+}

package/tools/lab/qemu.mjs

@@ -0,0 +1,153 @@
+// The guest's machine: QEMU's argument list, built pure so a test can read
+// it, and the QMP socket, spoken to from Node so a run needs no socat.
+//
+// What the argument list guarantees, and tests/unit/lab.test.mjs holds it
+// to: the base disk is the overlay's backing file, opened by QEMU read-only
+// because the overlay is what is written; the firmware variables are the
+// run's own copy, never the base's template (docs/history/2026-09-18-lab-
+// inventory.md P15: the template's mtime moved with every run); no display,
+// no host directory, no host socket and no host device reaches the guest;
+// the one network device is user-mode with SSH forwarded on 127.0.0.1 and
+// nothing else forwarded.
+
+import { spawn } from "node:child_process"
+import { connect } from "node:net"
+import { OVMF_CODE } from "./host.mjs"
+
+/**
+ * @param {{ overlay: string, vars: string, memoryMiB: number, cpus: number, sshPort: number, qmpSocket: string, serialLog: string, pidFile: string, ovmfCode?: string }} options
+ */
+export function qemuArgs({ overlay, vars, memoryMiB, cpus, sshPort, qmpSocket, serialLog, pidFile, ovmfCode = OVMF_CODE }) {
+  if (!Number.isInteger(sshPort) || sshPort < 1024 || sshPort > 65535) throw new Error(`lab: the SSH port must be an unprivileged port, not ${sshPort}`)
+  return [
+    "-cpu", "host", "-enable-kvm", "-machine", "q35,accel=kvm",
+    "-smp", String(cpus),
+    "-m", String(memoryMiB),
+    "-drive", `if=pflash,format=raw,readonly=on,file=${ovmfCode}`,
+    "-drive", `if=pflash,format=raw,file=${vars}`,
+    "-drive", `file=${overlay},format=qcow2,if=none,id=drive0`,
+    "-device", "virtio-blk-pci,drive=drive0,bootindex=1",
+    "-device", "virtio-vga",
+    "-display", "none",
+    "-usb", "-device", "usb-tablet",
+    "-netdev", `user,id=net0,hostfwd=tcp:127.0.0.1:${sshPort}-:22`,
+    "-device", "virtio-net-pci,netdev=net0",
+    "-qmp", `unix:${qmpSocket},server,nowait`,
+    "-serial", `file:${serialLog}`,
+    "-pidfile", pidFile,
+  ]
+}
+
+/**
+ * Start QEMU as a child of this process, not daemonised: the lifetime is
+ * the run's, and the exit handlers in run.mjs end it on every path. The
+ * child's stdio goes to the run's log so a QEMU that refuses to start
+ * says why.
+ */
+export function startQemu(args, { log, binary = "qemu-system-x86_64" } = {}) {
+  const child = spawn(binary, args, { stdio: ["ignore", log, log] })
+  return child
+}
+
+/**
+ * One QMP session: the capabilities handshake, then `execute` per
+ * command. A command's answer is the first `return` or `error` object
+ * after it, events in between are dropped. The socket is opened per
+ * command, as the toolchain's socat did; QMP allows one client and a
+ * held-open socket would block a diagnostic connection.
+ */
+export function qmpExecute(socket, command, args = undefined, { timeoutMs = 5000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const client = connect(socket)
+    let buffer = ""
+    let stage = 0
+    let settled = false
+    const timer = setTimeout(() => finish(new Error(`QMP ${command} did not answer within ${timeoutMs} ms`)), timeoutMs)
+    const finish = (error, value) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      client.destroy()
+      if (error) reject(error)
+      else resolve(value)
+    }
+    client.on("error", (error) => finish(Object.assign(new Error(`QMP socket ${socket}: ${error.code || error.message}`), { code: "qmp-unavailable" })))
+    client.on("data", (chunk) => {
+      buffer += chunk.toString("utf8")
+      let index
+      while ((index = buffer.indexOf("\n")) >= 0) {
+        const line = buffer.slice(0, index)
+        buffer = buffer.slice(index + 1)
+        let message
+        try {
+          message = JSON.parse(line)
+        } catch {
+          continue
+        }
+        if (stage === 0 && message.QMP) {
+          stage = 1
+          client.write(`${JSON.stringify({ execute: "qmp_capabilities" })}\n`)
+        } else if (stage === 1 && "return" in message) {
+          stage = 2
+          client.write(`${JSON.stringify({ execute: command, ...(args ? { arguments: args } : {}) })}\n`)
+        } else if (stage === 2 && "return" in message) {
+          finish(null, message.return)
+        } else if (stage === 2 && message.error) {
+          finish(Object.assign(new Error(`QMP ${command}: ${message.error.desc || message.error.class}`), { code: "qmp-error" }))
+        }
+      }
+    })
+  })
+}
+
+/** Whether a QEMU answers on this socket: the cross-namespace liveness question prune and the lock ask. */
+export async function qmpAlive(socket) {
+  try {
+    const status = await qmpExecute(socket, "query-status", undefined, { timeoutMs: 2000 })
+    return { alive: true, status: status?.status || null }
+  } catch {
+    return { alive: false, status: null }
+  }
+}
+
+/**
+ * The qcode for one character, as the toolchain's `type_text` mapped it.
+ * Only what a login needs is typed by the lab (the guest password), but
+ * the table is the toolchain's whole one so a suite that asks for more
+ * gets the same keys.
+ */
+const SHIFTED = {
+  "_": "minus", ":": "semicolon", "@": "2", "|": "backslash", '"': "apostrophe", "+": "equal", "%": "5", "&": "7", "*": "8",
+  "(": "9", ")": "0", "<": "comma", ">": "dot", "!": "1", "#": "3", "$": "4", "?": "slash", "~": "grave_accent", "{": "bracket_left", "}": "bracket_right",
+}
+const PLAIN = { " ": "spc", ".": "dot", ",": "comma", "-": "minus", "/": "slash", ";": "semicolon", "'": "apostrophe", "=": "equal", "\\": "backslash", "[": "bracket_left", "]": "bracket_right" }
+
+export function qcodesFor(text) {
+  const chords = []
+  for (const ch of String(text)) {
+    if (/^[a-z0-9]$/.test(ch)) chords.push([ch])
+    else if (/^[A-Z]$/.test(ch)) chords.push(["shift", ch.toLowerCase()])
+    else if (ch in PLAIN) chords.push([PLAIN[ch]])
+    else if (ch in SHIFTED) chords.push(["shift", SHIFTED[ch]])
+    else throw new Error(`lab: no qcode for ${JSON.stringify(ch)}`)
+  }
+  return chords
+}
+
+/** Press one chord: `["ctrl","alt","f3"]`, or `["ret"]`. */
+export async function press(socket, chord) {
+  await qmpExecute(socket, "send-key", { keys: chord.map((key) => ({ type: "qcode", data: key })) })
+}
+
+/** Type text one chord at a time, 50 ms apart as the toolchain did. */
+export async function typeText(socket, text) {
+  for (const chord of qcodesFor(text)) {
+    await press(socket, chord)
+    await new Promise((resolve) => setTimeout(resolve, 50))
+  }
+}
+
+/** A screendump to a PPM file; the caller converts it if it has `magick`. */
+export async function screendump(socket, file) {
+  await qmpExecute(socket, "screendump", { filename: file })
+}

package/tools/lab/qmp-cli.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// QMP from a shell: `node tools/lab/qmp-cli.mjs <socket> screendump <file>`,
+// `... status`, `... press <chord>`. The harness's capture_console is the
+// one caller; it exists so a suite needs no socat.
+
+import { press, qmpExecute, screendump } from "./qemu.mjs"
+
+const [socket, command, argument] = process.argv.slice(2)
+if (!socket || !command) {
+  process.stderr.write("usage: qmp-cli.mjs <socket> screendump <file> | status | press <chord>\n")
+  process.exit(2)
+}
+try {
+  if (command === "screendump") await screendump(socket, argument)
+  else if (command === "status") process.stdout.write(`${JSON.stringify(await qmpExecute(socket, "query-status"))}\n`)
+  else if (command === "press") await press(socket, String(argument).split("-"))
+  else throw new Error(`unknown command ${command}`)
+} catch (error) {
+  process.stderr.write(`${error.message}\n`)
+  process.exit(1)
+}

package/tools/lab/report.mjs

@@ -0,0 +1,183 @@
+// What the lab commands print for a person: palette roles only, the
+// shared marks, fields and actions from style.mjs, every path under the
+// home directory abbreviated the way a shell takes it. The documents
+// themselves (`--json`) keep every path absolute.
+
+import { action, colourEnabled, field, GUTTER, labelled, mark, section, styler, verdict, wrap } from "../marketplace/style.mjs"
+import { withHomeAbbreviated } from "../marketplace/paths.mjs"
+import { bytesBoth, durationWords, gbBoth, shortId } from "./pin.mjs"
+import { disclosureLines } from "./setup.mjs"
+
+const state = (ok) => (ok ? "pass" : "advisory")
+
+/** The lab's lines for `omakit doctor`, in doctor's check shape; every one advice, never a problem, because the lab is optional. */
+export function labDoctorChecks(lab) {
+  const checks = []
+  const add = (id, ok, detail, remedy = null, evidence = null) => checks.push({ id, state: ok ? "ok" : "advice", detail, action: ok ? null : remedy, ...(evidence ? { evidence } : {}) })
+  for (const line of lab.host.run) {
+    if (line.name === "cpus" || line.name === "memory") continue
+    add(`lab.${line.name}`, line.state === "ok", line.reason, line.remedy)
+  }
+  // MemTotal alone: MemAvailable moves between two runs of doctor, and
+  // doctor's bytes are held to being the same twice (tests/unit/cli.test.mjs).
+  const memory = lab.host.run.find((line) => line.name === "memory")
+  if (memory) add("lab.memory", memory.state === "ok", memory.reason.replace(/, \d+ MiB available/, ""), memory.remedy)
+  for (const line of lab.host.verify) add(`lab.${line.name}`, line.state === "ok", line.reason, line.remedy)
+  const enough = lab.free.bytes >= lab.pin.measured.preparedLabBytes
+  // The free figure alone, no path: the lab cache's path can be wider than
+  // a terminal, and doctor's one wide line is the pin's; `omakit lab
+  // inspect` prints the path and the cache's own size.
+  // 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 })
+  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
+}
+
+/** `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))
+  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))
+  out.push(`${mark(state(lab.download.verified), c)}${c("name", "iso")}`)
+  out.push(...wrap(home(`${lab.download.present ? `${bytesBoth(lab.download.bytes)} at ${lab.download.iso}: ` : ""}${lab.download.reason}`), { indent: GUTTER }, c))
+  out.push(`${mark(state(lab.base.state === "ready"), c)}${c("name", `base (${lab.base.state})`)}`)
+  out.push(...wrap(home(lab.base.reason), { indent: GUTTER }, c))
+  if (lab.base.manifest) out.push(...labelled("disk sha256", lab.base.manifest.disk.sha256, c), ...labelled("origin", home(lab.base.manifest.build?.origin || "unknown"), c))
+  out.push(`${mark(state(lab.toolchain.state === "ready"), c)}${c("name", `toolchain (${lab.toolchain.state})`)}`)
+  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))
+  }
+  if (lab.lock.held) {
+    out.push(`${mark(lab.lock.alive ? "info" : "advisory", c)}${c("name", "lock")}`)
+    out.push(...wrap(lab.lock.alive ? `held by run ${lab.lock.record?.runId || "unknown"} (pid ${lab.lock.record?.pid || "?"})` : `stale, from ${lab.lock.record?.runId || "an unknown run"}`, { indent: GUTTER }, c))
+  }
+  out.push(...field("lab cache", `${bytesBoth(lab.totals.cacheBytes)} at ${home(lab.layout.cache)}: downloads ${gbBoth(lab.totals.downloadsBytes)}, base ${gbBoth(lab.totals.baseBytes)}, staging ${gbBoth(lab.totals.stagingBytes)}, plugins ${gbBoth(lab.totals.pluginsBytes)}`, c))
+  out.push(...field("runs", `${lab.runs.length} record${lab.runs.length === 1 ? "" : "s"}, ${bytesBoth(lab.totals.runsBytes)} at ${home(lab.layout.runs)}${lab.runs.length ? `; newest ${lab.runs.at(-1)}` : ""}`, c))
+  out.push(...field("free", `${bytesBoth(lab.free.bytes)} at ${home(lab.free.path)}`, c))
+  out.push("")
+  out.push(...section("the host", c))
+  for (const line of [...lab.host.run, ...lab.host.verify, ...lab.host.build]) {
+    out.push(`${mark(state(line.state === "ok"), c)}${c("name", line.name)}`)
+    out.push(...wrap(line.reason, { indent: GUTTER }, 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) {
+      out.push(`${mark("advisory", c)}${c("name", item.what)}`)
+      out.push(...labelled("costs", home(item.cost), c))
+      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))
+  } else {
+    out.push(...verdict("pass", "PREPARED", `verified ${release.name}, a ready base, the host can run it; nothing was fetched or written.`, c))
+  }
+  return out.join("\n")
+}
+
+/** The setup disclosure, and what happened. */
+export function renderSetupPlan(plan, { colour = colourEnabled(), env = process.env } = {}) {
+  const c = styler(colour)
+  const out = []
+  if (plan.blockers.length) {
+    out.push(...section(`\`omakit lab setup\` cannot start: ${plan.blockers.length} missing`, c))
+    for (const item of plan.blockers) {
+      out.push(`${mark("fail", c)}${c("name", item.what)}`)
+      out.push(...labelled("costs", withHomeAbbreviated(item.cost, env), c))
+      if (item.command) out.push(...action(withHomeAbbreviated(item.command, env), c))
+    }
+    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))
+    return out.join("\n")
+  }
+  out.push(...section("what setup will do, once you say yes", c))
+  for (const [key, value] of disclosureLines(plan)) out.push(...field(key, withHomeAbbreviated(value, env), c))
+  return out.join("\n")
+}
+
+export function renderSetupResult(result, { colour = colourEnabled(), env = process.env } = {}) {
+  const c = styler(colour)
+  const out = []
+  if (result.nothingToDo) return verdict("pass", "PREPARED", "nothing to acquire; the lab was already prepared.", c).join("\n")
+  for (const step of result.done) {
+    if (step.kind === "download") out.push(`${mark("pass", c)}downloaded ${bytesBoth(step.bytes)} in ${durationWords(step.milliseconds)}`)
+    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 === "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))
+  return out.join("\n")
+}
+
+/** The identity block before a suite, and the verdict after. */
+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("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))
+  return out.join("\n")
+}
+
+export function renderRunResult(record, { colour = colourEnabled(), env = process.env } = {}) {
+  const c = styler(colour)
+  const out = []
+  out.push(...field("duration", durationWords(record.durationMs || 0), c))
+  if (record.overlayBytes !== null) out.push(...field("overlay", `${bytesBoth(record.overlayBytes)} allocated by the run, removed`, c))
+  out.push(...field("base", record.baseUnchanged ? "unchanged (size, mtime and inode of the disk and the template)" : "CHANGED: the base or its template differs from before the run", c))
+  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))
+  else out.push(...verdict("fail", "NOT PROVED", `${record.suite}: ${record.assertion?.reason || record.error || `the suite exited ${record.suiteStatus}`}.`, c))
+  return out.join("\n")
+}
+
+/** `omakit lab prune`: the targets, the total, the question's subject. */
+export function renderPrunePlan(plan, { colour = colourEnabled(), env = process.env } = {}) {
+  const c = styler(colour)
+  const out = []
+  if (plan.blockers.length) {
+    for (const line of plan.blockers) out.push(`${mark("fail", c)}${line}`)
+    return out.join("\n")
+  }
+  if (!plan.targets.length) return verdict("pass", "NOTHING TO PRUNE", `the lab cache holds ${bytesBoth(plan.remaining.cache)} and every byte of it is in use or kept; run records ${bytesBoth(plan.remaining.runs)} (--records removes them).`, c).join("\n")
+  out.push(...section("what prune removes", c))
+  for (const target of plan.targets) {
+    out.push(`${mark("advisory", c)}${c("name", withHomeAbbreviated(target.path, env))}`)
+    out.push(...wrap(`${bytesBoth(target.bytes)}: ${target.what}`, { indent: GUTTER }, c))
+  }
+  out.push(...field("total", bytesBoth(plan.total), c))
+  return out.join("\n")
+}
+
+export function renderPruneResult(result, { colour = colourEnabled() } = {}) {
+  const c = styler(colour)
+  return verdict("pass", "PRUNED", `${result.words}.`, c).join("\n")
+}