omakit 0.5.0 → 0.6.1

package/tools/lab/suites/weigh.sh

@@ -0,0 +1,196 @@
+#!/usr/bin/bash
+# `omakit weigh` against a real shell, in the guest, never on a desktop:
+# the command restarts a shell, and the lab is the only shell that is
+# anyone's to restart unasked.
+#
+#   omakit_lab_suite <mode> <runs> <plugins-dir> [listed-id...]
+#
+# `smoke` proves what no unit test can, in about a minute after the guest
+# is up: a real shell restarts on a written configuration, the real /proc
+# is read (a Pss, ticks that move), the document follows the contract,
+# shell.json comes back byte for byte, and an interrupt mid-measurement
+# restores it and exits 130. Two fixtures at one run, a 2 s settle and a
+# 3 s window, three restarts, then a second measurement interrupted.
+# `evidence` is the five-run gate over the four fixtures and the three
+# listed plugins, forty restarts at the default 30 s settle and 15 s
+# window, about forty minutes, and the only mode whose document belongs
+# under docs/evidence/weigh/. The listed plugins come staged from the
+# lab's plugin cache, fetched once by `omakit lab setup --plugins` at the
+# exact commit the pinned catalog records as validated; this suite fetches
+# nothing.
+#
+# Runs through tools/lab/harness.sh, which defines the helpers used here.
+
+omakit_lab_suite() {
+  local mode="$1" runs="$2" plugins_dir="$3"
+  shift 3
+  local -a reals=("$@") fixtures timing ids
+  local fixtures_dir="$OMAKIT_DIR/tests/fixtures/weigh"
+  local name real real_dir md5_before md5_after count restarts status ids_json
+  # Node in the guest comes through mise, the way a stock Omarchy has it.
+  local guest_path='PATH=$HOME/.local/share/mise/shims:$PATH'
+
+  if [[ $mode == evidence ]]; then
+    fixtures=(clean timer-180ms poller idle-panel)
+    timing=()
+  else
+    runs=1
+    reals=()
+    fixtures=(clean timer-180ms)
+    timing=(--settle 2 --window 3)
+  fi
+  ids=("${fixtures[@]/#/fixture.}" "${reals[@]}")
+  count=${#ids[@]}
+  restarts=$(( (1 + count) * runs ))
+  ids_json=$(jq -c -n '$ARGS.positional' --args "${ids[@]}")
+
+  # One detached measurement in the guest: the shell it restarts is the
+  # session's, so it must not hang off the ssh call.
+  guest_weigh() {
+    local tag="$1" limit="$2"; shift 2
+    guest_job "weigh-$tag" "$limit" "$guest_path node /tmp/omakit/bin/omakit weigh $* --yes --out /tmp/omakit-weigh-$tag.json" || return 1
+    guest_file "/tmp/omakit-weigh-$tag.json" "omakit-weigh-$tag.json" || true
+  }
+  # shell.json is byte for byte what it was, no backup is left, the shell answers.
+  assert_restored() {
+    md5_after=$(ssh_session "md5sum < \"\$HOME/.config/omarchy/shell.json\"")
+    log "shell.json after $1: $md5_after"
+    [[ $md5_after == "$md5_before" ]] || { echo "shell.json changed ($1)" >&2; return 1; }
+    ssh_session "test -z \"\$(ls \"\$HOME/.config/omarchy/\" | grep omakit-backup)\"" || { echo "a backup was left behind ($1)" >&2; return 1; }
+    ssh_session "omarchy-shell shell ping | grep -qx ok" || { echo "the shell does not answer ($1)" >&2; return 1; }
+  }
+
+  log "Checking that the guest has node"
+  ssh_session "$guest_path node --version" || { echo "no node in the guest (mise shims)" >&2; return 1; }
+
+  log "Staging omakit, the ${#fixtures[@]} fixtures and ${#reals[@]} listed plugins in the guest"
+  ssh_guest "rm -rf /tmp/omakit" || return 1
+  stage_paths "$OMAKIT_DIR" /tmp/omakit bin tools package.json || return 1
+  for name in "${fixtures[@]}"; do stage_plugin "$fixtures_dir/$name" "/tmp/omakit-fixtures/$name" || return 1; done
+  for real in "${reals[@]}"; do
+    real_dir="$plugins_dir/$real"
+    log "$real at $(git -C "$real_dir" rev-parse HEAD), the commit the pinned catalog lists as validated"
+    stage_plugin "$real_dir" "/tmp/omakit-real/$real" || return 1
+  done
+  for name in "${fixtures[@]}"; do ssh_session "omarchy-plugin-add /tmp/omakit-fixtures/$name --enable --yes" || return 1; done
+  for real in "${reals[@]}"; do ssh_session "omarchy-plugin-add /tmp/omakit-real/$real --enable --yes" || return 1; done
+  wait_for_guest_state "the $count plugins are installed and enabled" 60 ssh_session \
+    "omarchy-plugin-list --json | jq -e --argjson want '$ids_json' '
+       . as \$list | all(\$want[]; . as \$id | any(\$list[]; .id == \$id and .enabled == true))'" || return 1
+  capture_console "success-weigh-01-installed"
+
+  md5_before=$(ssh_session "md5sum < \"\$HOME/.config/omarchy/shell.json\"")
+  [[ -n $md5_before ]] || return 1
+  log "shell.json before: $md5_before"
+
+  # The plan, refused: without --yes in a pipe the command prints the count
+  # and touches nothing. Exit 2 is the expected outcome.
+  ssh_session "$guest_path node /tmp/omakit/bin/omakit weigh --all --runs $runs ${timing[*]} </dev/null; test \$? -eq 2" || { echo "the unconfirmed run did not refuse with exit 2" >&2; return 1; }
+  [[ $(ssh_session "md5sum < \"\$HOME/.config/omarchy/shell.json\"") == "$md5_before" ]] || { echo "the refused run touched shell.json" >&2; return 1; }
+
+  if [[ $mode == evidence ]]; then
+    log "Running omakit weigh --all --runs $runs in the guest ($restarts restarts, the default 30 s settle and 15 s window)"
+    guest_weigh evidence 3600 --all --runs "$runs" || return 1
+    status=$(guest_job_status weigh-evidence)
+    # The shell's own journal over the run, for C2: a rescan or a bar rebuild between two levels.
+    ssh_session "journalctl --user -t omarchy-shell --no-pager -o short-iso --since '-2 hours'" > "$RUN_DIR/omarchy-shell.journal" 2>/dev/null || true
+    ssh_session "ls \$XDG_RUNTIME_DIR/omarchy/plugin-runtime/" > "$RUN_DIR/plugin-runtime-generations.txt" 2>/dev/null || true
+    cat "$RUN_DIR/weigh-evidence.log" > "$RUN_DIR/omakit-weigh.log" && cat "$RUN_DIR/omakit-weigh-evidence.json" > "$RUN_DIR/omakit-weigh.json" || return 1
+  else
+    log "Running omakit weigh --all --runs 1 --settle 2 --window 3 in the guest ($restarts restarts)"
+    guest_weigh smoke 300 --all --runs 1 "${timing[@]}" || return 1
+    status=$(guest_job_status weigh-smoke)
+    cat "$RUN_DIR/weigh-smoke.log" > "$RUN_DIR/omakit-weigh.log" && cat "$RUN_DIR/omakit-weigh-smoke.json" > "$RUN_DIR/omakit-weigh.json" || return 1
+  fi
+  [[ $status == 0 ]] || { echo "omakit weigh exited $status" >&2; tail -n 40 "$RUN_DIR/omakit-weigh.log" >&2; return 1; }
+  assert_restored "the measurement" || return 1
+  capture_console "success-weigh-02-restored"
+
+  # The document follows the contract, on the host, with the tool's own validator.
+  node "$OMAKIT_DIR/tools/weigh/contract.mjs" "$RUN_DIR/omakit-weigh.json" || return 1
+
+  if [[ $mode == smoke ]]; then
+    # Every configuration produced a sample from the real /proc: a Pss and a
+    # VmRSS in kB, ticks that did not go backwards, and a trace; nothing
+    # failed and nothing was read as zero in a gone shell's place.
+    jq -e --arg before "${md5_before%% *}" --argjson count "$count" '
+      (.failedRuns | length) == 0
+      and (.plugins | length) == $count
+      and all(.plugins[]; .runsCompleted == 1)
+      and ([.baseline.runs[], .plugins[].runs[]] | length) == ($count + 1)
+      and all([.baseline.runs[], .plugins[].runs[]][];
+            (.shell.pssKb | type) == "number" and .shell.pssKb > 0
+            and (.shell.rssKb | type) == "number" and .shell.rssKb > 0
+            and .shell.cpuTicksEnd >= .shell.cpuTicksStart
+            and (.shell.trace | length) >= 2
+            and .readyAfterSeconds >= 0)
+      and .config.restored == true
+      and .config.md5Before == $before and .config.md5After == $before' "$RUN_DIR/omakit-weigh.json" || {
+      jq -c '{failedRuns, config, plugins: [.plugins[] | {id, runsCompleted}]}' "$RUN_DIR/omakit-weigh.json" >&2
+      return 1
+    }
+    grep -q "^▒ WEIGHED" "$RUN_DIR/omakit-weigh.log" || { echo "a one-run measurement does not close with the question mark" >&2; return 1; }
+
+    # The recovery path, against the real shell: a measurement interrupted
+    # inside its settle restores shell.json, restarts the shell once more,
+    # removes the backup and exits 130 (docs/WEIGH.md, the shell.json
+    # mutation). The signal goes to the recorded pid, the way Ctrl-C would
+    # reach the command at a terminal. `set -m` because a background job
+    # under a non-interactive bash inherits SIGINT ignored (measured: a
+    # `kill -INT` to such a job did nothing).
+    log "Interrupting a second measurement inside its settle"
+    ssh_session "rm -f /tmp/omakit-weigh-interrupted.done /tmp/omakit-weigh-interrupted.log /tmp/omakit-weigh-interrupted.json /tmp/omakit-weigh-interrupted.pid; \
+      setsid bash -c 'set -m; $guest_path node /tmp/omakit/bin/omakit weigh fixture.clean --runs 2 --settle 8 --window 5 --yes --out /tmp/omakit-weigh-interrupted.json \
+        > /tmp/omakit-weigh-interrupted.log 2>&1 & echo \$! > /tmp/omakit-weigh-interrupted.pid; wait \$!; echo \$? > /tmp/omakit-weigh-interrupted.done' >/dev/null 2>&1 < /dev/null &" || return 1
+    wait_for_guest_state "the interrupted measurement has backed shell.json up" 60 ssh_guest "grep -q 'backed up to' /tmp/omakit-weigh-interrupted.log" || return 1
+    # The first restart takes about a second in the guest and the settle is
+    # 8 s, so five seconds after the backup line the run is inside its
+    # settle, or still waiting for the shell; both paths restore.
+    sleep 5
+    ssh_guest "kill -INT \$(cat /tmp/omakit-weigh-interrupted.pid)" || { echo "no measurement to interrupt" >&2; return 1; }
+    wait_for_guest_state "the interrupted measurement has exited" 120 ssh_guest "test -f /tmp/omakit-weigh-interrupted.done" || {
+      ssh_guest "tail -n 40 /tmp/omakit-weigh-interrupted.log" || true
+      return 1
+    }
+    guest_file /tmp/omakit-weigh-interrupted.log omakit-weigh-interrupted.log || true
+    status=$(ssh_guest "cat /tmp/omakit-weigh-interrupted.done")
+    [[ $status == 130 ]] || { echo "the interrupted measurement exited $status, not 130" >&2; tail -n 40 "$RUN_DIR/omakit-weigh-interrupted.log" >&2; return 1; }
+    grep -q "interrupted: restoring shell.json before exiting" "$RUN_DIR/omakit-weigh-interrupted.log" || { echo "the interrupt was not announced" >&2; return 1; }
+    grep -q "restored and verified" "$RUN_DIR/omakit-weigh-interrupted.log" || { echo "the restore after the interrupt did not verify" >&2; return 1; }
+    grep -q "NOT WEIGHED  interrupted before the measurement completed" "$RUN_DIR/omakit-weigh-interrupted.log" || { echo "the interrupt did not close as NOT WEIGHED" >&2; return 1; }
+    ssh_guest "test ! -f /tmp/omakit-weigh-interrupted.json" || { echo "an interrupted measurement wrote a document" >&2; return 1; }
+    assert_restored "the interrupt" || return 1
+    capture_console "success-weigh-03-interrupt-restored"
+    guest_shell_healthy || return 1
+    printf 'ok - omakit weigh smoke: %d measured restarts and a restore weighed two fixtures from the real /proc and put shell.json back byte for byte, the document follows docs/WEIGH.md, and an interrupted measurement restored it and exited 130\n' "$restarts"
+    return 0
+  fi
+
+  # The acceptance line: the busy fixture is above noise on CPU; the clean
+  # fixture is within noise on both and the report says so in words; every
+  # plugin completed every run; the md5s in the document match the guest's.
+  jq -e --arg before "${md5_before%% *}" --argjson runs "$runs" --argjson count "$count" '
+    (.plugins[] | select(.id == "fixture.clean")) as $clean
+    | (.plugins[] | select(.id == "fixture.timer-180ms")) as $busy
+    | all(.plugins[]; .runsCompleted == $runs)
+      and $busy.verdict.cpu == "above-noise"
+      and $clean.verdict.cpu == "within-noise"
+      and $clean.verdict.memory == "within-noise"
+      and $clean.verdict.summary == "no measurable CPU"
+      and .config.restored == true
+      and .config.md5Before == $before and .config.md5After == $before
+      and (.plugins | length) == $count' "$RUN_DIR/omakit-weigh.json" || {
+    jq -c '.noiseFloor' "$RUN_DIR/omakit-weigh.json" >&2
+    jq -c '.plugins[] | {id, runsCompleted, shellPssMb, shellCpuPercent, verdict}' "$RUN_DIR/omakit-weigh.json" >&2
+    return 1
+  }
+  grep -Eq "^▁ ok +fixture\.clean " "$RUN_DIR/omakit-weigh.log" || { echo "the report does not mark fixture.clean ok" >&2; return 1; }
+  grep -A1 -E "ok +fixture\.clean " "$RUN_DIR/omakit-weigh.log" | grep -q "no measurable CPU" || { echo "the report does not say no measurable CPU for fixture.clean" >&2; return 1; }
+  grep -q "^memory        within the shell's own startup variance" "$RUN_DIR/omakit-weigh.log" || { echo "the header does not label memory as the shell's" >&2; return 1; }
+  grep -q "^for the README" "$RUN_DIR/omakit-weigh.log" || { echo "no README sentence" >&2; return 1; }
+
+  jq -r '.noiseFloor | "noise floor: Pss \(.pssMb) MB and VmRSS \(.rssMb) MB at the end of the window, Pss \(.pssMbSettled) MB at the settle, CPU \(.cpuPercent)%"' "$RUN_DIR/omakit-weigh.json"
+  jq -r '.plugins[] | [.id, (.shellPssMb.median * 100 | round / 100), (.shellPssMb.spread * 100 | round / 100), (.shellCpuPercent.median * 100 | round / 100), (.shellCpuPercent.spread * 100 | round / 100), (.childRssMb.median * 100 | round / 100), (.childCpuPercent.median * 100 | round / 100), .childSpawns.median, .verdict.summary] | @tsv' "$RUN_DIR/omakit-weigh.json"
+  guest_shell_healthy || return 1
+  printf 'ok - omakit weigh measured %d plugins over %d runs each, told the 180 ms timer from the clean fixture, said within noise in words, restored shell.json byte for byte, and the document follows docs/WEIGH.md\n' "$count" "$runs"
+}

package/tools/lab/suites.mjs

@@ -0,0 +1,142 @@
+// The suites `omakit lab prove` knows, as data: what each stages, what it
+// runs, which document it writes, and what that document must say for the
+// gate to pass. The host-side body of each is a bash file under
+// tools/lab/suites/, run through tools/lab/harness.sh; the in-guest
+// content (a suite that also runs on the desktop, its reader, its harness
+// QML, the weigh fixtures) lives with the tests, under tests/lab/ and
+// tests/fixtures/weigh/, and ships in the package too (package.json
+// `files`), so an installed omakit proves a suite without a checkout.
+// Measured on 2026-09-19 by a first user: the packaged `lab prove` refused
+// for files that were repository-only, with a remedy that cloned the
+// repository and then ran the global package again (docs/evidence/ux/
+// 2026-09-19-first-user-test.json, finding 5). A suite whose content is
+// missing is still named, not guessed at, and the remedy names the tree's
+// own entry point.
+
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import { LAB_DIR } from "./pin.mjs"
+import { marketplacePinDir } from "../marketplace/pin.mjs"
+
+/** The listed plugins the weigh evidence gate weighs beside the fixtures, by id; their repositories and commits are the pinned catalog's to say. */
+export const WEIGH_LISTED = Object.freeze(["io.github.calebhat.weather", "omaplug", "io.github.pablo-merino.altswitch"])
+export const WEIGH_FIXTURES = Object.freeze(["clean", "timer-180ms", "poller", "idle-panel"])
+
+const BLOCK_PLUMBING = ["tests/lab/run/suite.sh", "tests/lab/run/report.py", "tests/lab/run/harness/shell.qml", "blocks/run/Run.qml", "blocks/run/run-supervisor.py"]
+
+export const SUITES = Object.freeze({
+  run: Object.freeze({
+    name: "run",
+    title: "the Run block's lab scenarios on the stock guest",
+    host: join(LAB_DIR, "suites/run.sh"),
+    needs: Object.freeze(BLOCK_PLUMBING),
+    document: "runlab.json",
+    evidence: "run-lab-guest",
+    timeoutSeconds: 1200,
+    args: () => ["1"],
+    /** `ok` over 19 summary entries (one per scenario, keyed by name), the count tests/lab/run/suite.sh names in its scenario list. */
+    assert: (document) => {
+      const summary = document?.summary
+      const count = Array.isArray(summary) ? summary.length : summary && typeof summary === "object" ? Object.keys(summary).length : 0
+      if (document?.ok !== true || count !== 19) return { ok: false, reason: `the document says ok=${document?.ok} over ${count} scenarios; the gate is ok over 19` }
+      return { ok: true, reason: `ok over ${count} scenarios` }
+    },
+  }),
+  store: Object.freeze({
+    name: "store",
+    title: "the Store block's lab scenarios on the stock guest, the foreign owner simulated",
+    host: join(LAB_DIR, "suites/store.sh"),
+    needs: Object.freeze([...BLOCK_PLUMBING, "tests/lab/store/suite.sh", "tests/lab/store/report.py", "tests/lab/store/harness/shell.qml", "blocks/store/Store.qml", "blocks/store/store-helper.py"]),
+    document: "storelab.json",
+    evidence: "store-lab-guest",
+    timeoutSeconds: 1200,
+    args: () => [],
+    /** `ok` over 15 scenarios with `foreign-owner` not skipped: the chown happened. */
+    assert: (document) => {
+      const scenarios = Array.isArray(document?.scenarios) ? document.scenarios : []
+      const foreign = scenarios.find((row) => row?.scenario === "foreign-owner")
+      if (document?.ok !== true || scenarios.length !== 15) return { ok: false, reason: `the document says ok=${document?.ok} over ${scenarios.length} scenarios; the gate is ok over 15` }
+      if (!foreign || foreign.skipped != null) return { ok: false, reason: "the foreign-owner scenario was skipped; the gate needs it simulated" }
+      return { ok: true, reason: `ok over ${scenarios.length} scenarios, the foreign owner simulated` }
+    },
+  }),
+  weigh: Object.freeze({
+    name: "weigh",
+    title: "omakit weigh against the stock shell: the smoke check, about a minute after the guest is up",
+    host: join(LAB_DIR, "suites/weigh.sh"),
+    needs: Object.freeze(["bin/omakit", "tools/weigh/contract.mjs", "tests/fixtures/weigh/clean/manifest.json", "tests/fixtures/weigh/timer-180ms/manifest.json"]),
+    document: "omakit-weigh.json",
+    evidence: null,
+    timeoutSeconds: 1500,
+    args: (options, layout) => ["smoke", "1", layout.plugins],
+    assert: (document) => (document?.config?.restored === true ? { ok: true, reason: "the document says the shell configuration was restored" } : { ok: false, reason: "the document does not say the shell configuration was restored" }),
+  }),
+  "weigh-evidence": Object.freeze({
+    name: "weigh-evidence",
+    title: "omakit weigh against the stock shell: five runs over four fixtures and three listed plugins, about forty minutes",
+    host: join(LAB_DIR, "suites/weigh.sh"),
+    needs: Object.freeze(["bin/omakit", "tools/weigh/contract.mjs", ...WEIGH_FIXTURES.map((name) => `tests/fixtures/weigh/${name}/manifest.json`)]),
+    document: "omakit-weigh.json",
+    evidence: "weigh-lab",
+    timeoutSeconds: 4200,
+    plugins: WEIGH_LISTED,
+    args: (options, layout) => ["evidence", String(options.runs || 5), layout.plugins, ...WEIGH_LISTED],
+    assert: (document) => (document?.config?.restored === true ? { ok: true, reason: "the document says the shell configuration was restored" } : { ok: false, reason: "the document does not say the shell configuration was restored" }),
+  }),
+})
+
+export function suiteNames() {
+  return Object.keys(SUITES)
+}
+
+/**
+ * What a suite is missing on this host, before any guest boots: the
+ * repository files it stages, and for the evidence gate the listed
+ * plugins in the lab's plugin cache at their validated commits.
+ */
+export function suitePreflight(suite, { repoRoot, layout, pinDir = marketplacePinDir(repoRoot) }) {
+  const missing = []
+  for (const relative of suite.needs) {
+    if (!existsSync(join(repoRoot, relative))) missing.push({ what: relative, cost: `a file this omakit ships (${repoRoot}) and does not have; the tree is incomplete`, command: existsSync(join(repoRoot, ".git")) ? `git -C ${repoRoot} checkout -- ${relative} && ${join(repoRoot, "bin/omakit")} lab prove ${suite.name}` : "npm i -g omakit, then run it again" })
+  }
+  if (suite.plugins) {
+    for (const id of suite.plugins) {
+      const listing = listedPlugin(pinDir, id)
+      if (!listing.ok) {
+        missing.push({ what: `${id} in the pinned catalog`, cost: listing.reason, command: "omakit pin" })
+        continue
+      }
+      const dir = join(layout.plugins, id)
+      const head = existsSync(join(dir, ".git")) ? readHead(dir) : null
+      if (head !== listing.commit) missing.push({ what: `${id} at ${listing.commit.slice(0, 12)} in ${dir}`, cost: `one shallow fetch of ${listing.repo} at that commit`, command: "omakit lab setup --plugins" })
+    }
+  }
+  return missing
+}
+
+/** `<repo> <commit>` for a listed id, from the pinned catalog; never written here. */
+export function listedPlugin(pinDir, id) {
+  let catalog
+  try {
+    catalog = JSON.parse(readFileSync(join(pinDir, "site/catalog.json"), "utf8"))
+  } catch {
+    return { ok: false, reason: "the pinned catalog is not readable; the marketplace pin is not in place" }
+  }
+  const plugin = (catalog.plugins || []).find((entry) => entry && entry.id === id)
+  const commit = plugin?.listingValidatedCommit
+  if (!plugin || !/^[0-9a-f]{40}$/.test(String(commit || "")) || !/^https:\/\/github\.com\/[^/]+\/[^/]+$/.test(String(plugin.repo || ""))) {
+    return { ok: false, reason: `${id} is not listed with a validated commit and a github.com repository in the pinned catalog` }
+  }
+  return { ok: true, repo: plugin.repo, commit }
+}
+
+function readHead(dir) {
+  try {
+    const head = readFileSync(join(dir, ".git/HEAD"), "utf8").trim()
+    if (/^[0-9a-f]{40}$/.test(head)) return head
+    const ref = head.match(/^ref: (.+)$/)?.[1]
+    return ref ? readFileSync(join(dir, ".git", ref), "utf8").trim() : null
+  } catch {
+    return null
+  }
+}

package/tools/lab/verify.mjs

@@ -0,0 +1,134 @@
+// 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 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 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.
+
+import { createHash } from "node:crypto"
+import { spawnSync } from "node:child_process"
+import { closeSync, openSync, readFileSync, readSync, statSync } from "node:fs"
+import { join } from "node:path"
+import { LAB_DIR, labPin } from "./pin.mjs"
+import { labDir, removeFromLab } from "./paths.mjs"
+
+/**
+ * SHA-256 of a file, streamed in 4 MiB reads. Measured on the 6.26 GB
+ * 4.0.3 ISO on the reference host, page-cached: 5.2 s in Node, 5.1 s in
+ * `sha256sum` (docs/MEASUREMENTS.md M14), so there is no reason to shell
+ * out. `onProgress(read, total)` at most once per read.
+ */
+export function sha256File(file, { onProgress } = {}) {
+  const total = statSync(file).size
+  const hash = createHash("sha256")
+  const buffer = Buffer.alloc(4 * 1024 * 1024)
+  const fd = openSync(file, "r")
+  let read = 0
+  try {
+    for (;;) {
+      const n = readSync(fd, buffer, 0, buffer.length, null)
+      if (n <= 0) break
+      hash.update(buffer.subarray(0, n))
+      read += n
+      if (onProgress) onProgress(read, total)
+    }
+  } finally {
+    closeSync(fd)
+  }
+  return { sha256: hash.digest("hex"), bytes: read }
+}
+
+/** The packaged key, checked against its pinned digest before it is trusted with anything. */
+export function packagedKey(pin = labPin(), dir = LAB_DIR) {
+  const file = join(dir, pin.release.signingKey)
+  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" })
+  }
+  return file
+}
+
+/**
+ * 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.
+ */
+export function verifySignature({ file, signature, keyFile, stagingRoot, run = spawnSync }) {
+  const home = labDir(stagingRoot, `gnupg-${process.pid}`)
+  const env = { ...process.env, GNUPGHOME: home }
+  try {
+    const imported = run("gpg", ["--batch", "--quiet", "--import", keyFile], { env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 60_000 })
+    if (imported.error || imported.status !== 0) {
+      return { state: "gpg-failed", fingerprint: null, detail: String(imported.stderr || imported.error?.message || "").trim().split("\n")[0] || "gpg could not import the packaged key" }
+    }
+    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() }
+  } finally {
+    removeFromLab(stagingRoot, `gnupg-${process.pid}`)
+  }
+}
+
+/**
+ * The whole judgement over a file on disk against the pin: 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).
+ */
+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 }
+  let st
+  try {
+    st = statSync(file)
+  } catch {
+    verdict.reason = `${file} is not there`
+    return verdict
+  }
+  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`
+    return verdict
+  }
+  verdict.sha256 = sha256File(file, { onProgress }).sha256
+  verdict.sha256Match = verdict.sha256 === pin.release.sha256
+  if (checksum) {
+    try {
+      verdict.sidecarSha256 = readFileSync(checksum, "utf8").trim().split(/\s+/)[0].toLowerCase()
+      verdict.sidecarMatch = verdict.sidecarSha256 === pin.release.sha256
+    } catch {
+      verdict.sidecarSha256 = null
+      verdict.sidecarMatch = null
+    }
+  }
+  if (!verdict.sha256Match) {
+    verdict.reason = `${file} has digest ${verdict.sha256}, the pin says ${pin.release.sha256}`
+    return verdict
+  }
+  if (!signature) {
+    verdict.reason = "no detached signature beside the file"
+    return verdict
+  }
+  const signed = verifySignature({ file, signature, keyFile, stagingRoot, run })
+  verdict.signature = signed
+  if (signed.state !== "valid") {
+    verdict.reason = `the signature did not verify: ${signed.detail}`
+    return verdict
+  }
+  if (signed.fingerprint !== pin.release.signingFingerprint) {
+    verdict.reason = `the signature is by ${signed.fingerprint}, the pin says ${pin.release.signingFingerprint}`
+    return verdict
+  }
+  verdict.ok = true
+  verdict.reason = `${st.size.toLocaleString("en-US")} B, sha256 ${verdict.sha256}, signed by ${signed.fingerprint}`
+  return verdict
+}

package/tools/marketplace/README.md

@@ -31,7 +31,8 @@ local commit through the transport seam the marketplace tests itself
 | `update-check.mjs` | A passive npm-release notice during normal terminal use, throttled to one check per day with a one-second network budget. Stores only installed/latest version metadata and time under XDG_STATE_HOME/omakit. Offline, JSON, pipes, help and CI skip it; DISABLE_UPDATE_NOTIFIER disables it. Version precedence and the registry GET are shared with doctor/upgrade. |
 | `path-hint.mjs` | Is `omakit` reachable as a bare command, and if not, the one line that makes it so for the install that is here: a symlink for a clone, the npm prefix's `bin` on PATH for a package, said for the shell in `$SHELL`. `setup` and `doctor` print it; nothing writes an rc file. |
 | `usage.mjs` | The help text, as data. |
-| `options.mjs` | Every option every command accepts, in one table, and the parser that reads a command line against it before anything runs; `tests/unit/options.test.mjs` holds the help signatures, and through them the completion scripts, to the table. |
+| `options.mjs` | Every option every command accepts, in one table, and the parser that reads a command line against it before anything runs: an option the command does not know, an option without its value or given twice, an empty argument, or one positional too many is refused by name; `tests/unit/options.test.mjs` holds the help signatures, and through them the completion scripts, to the table. |
+| `outcome.mjs` | The one contract every command leaves through: the exit status (0 success, 1 a refusal or failure the tool means, 2 usage, 128 plus the signal for an interrupt), the `--json` envelope `{ command, ok, error, ...document }` with `error.remedy` never null, the text on stdout on exit 0 and on stderr otherwise, and `--out` written on every outcome. `conclude()` is the call; `tests/unit/json-outcomes.test.mjs` holds it per command and per outcome. |
 | `completion.mjs` | A completion script for bash, zsh or fish, derived from the help data and the pin's form: the subcommands and flags are read out of `COMMANDS`, the categories and tags out of the pinned submission form, and the script says which pin it came from. `setup` installs it for the shell in `$SHELL`, the one file this tool writes outside its own checkout. |
 | `completion-check.mjs` | Whether tab completion actually works: a frozen probe per shell run interactively, asking the loader to load `omakit` the way TAB does; the one marked block `setup` may append to an rc file after a yes, looked for by its marker first; the installed script's version and pin read from its first line; `doctor`'s `omakit.completion`; and the once-a-day stale notice. |
 | `banner.mjs` | The wordmark, on a bare `omakit` and in `setup` only. |
@@ -74,6 +75,29 @@ the tree, no verdict:
 | `inspect/contract.mjs` | The JSON contract of docs/INSPECT.md as a validator, run by the unit tests over every fixture document. |
 | `inspect/report.mjs` | The report for a person, drawn with `style.mjs` only: `░ info` for a fact, `▒ ?` for one that could not be read, `▓ note` for a pattern row, `▔ skip` under `--offline`, and the closing word `INSPECTED`. |
 
+`tools/lab/` is `omakit lab`, the fourth job (docs/LAB.md): a suite proven
+in a disposable Omarchy guest, never on the desktop, the guest identified
+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/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/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/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/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`. |
+
 ```text
 omakit pin
 omakit inspect /path/to/plugin-repo                      # what the tree does, as observations; --json for the document
@@ -127,3 +151,16 @@ beyond fetching a reviewer-mode subject, and `tests/parity/offline.mjs` proves
 it.
 
 `watch --list` discovers the signed-in account's open marketplace issues through `github.mjs`; `--user` bypasses the account lookup. `watch --all` runs the existing single-issue watch with four workers and shared repository HEAD promises, preserving each read failure. A bare terminal invocation uses `ask.mjs` to choose one or several issues. `report.mjs` composes the list and batch views; all options remain in `options.mjs` and `usage.mjs`, which also generate completion. The batch JSON retains complete single-issue reports; `current` compares commits and never substitutes for review or publication.
+
+## tools/blocks/
+
+`tools/blocks/` is the Run block's plumbing on omakit's side: the block
+itself is `blocks/run/`, files a plugin copies (docs/BLOCKS.md).
+
+| Module | What it does |
+| --- | --- |
+| `blocks/registry.mjs` | The shipped blocks read from `blocks/<name>/`: each file's header (block, version, licence, source, body sha256) and body hash; `recogniseBlockFile` for inspect and `add`; `blocks/history.json` for every hash ever shipped; the NOTICE renderer. |
+| `blocks/add.mjs` | `omakit add <block> [plugin-dir]`: the one code path that writes into a plugin tree, held to the registry's names under `omakit/`, checked against the agent-control list first, never over a file without `--update`, never over a modified copy. |
+| `blocks/stamp.mjs` | Maintainer's tool after editing a block: rewrites each header's sha256 to its body's, regenerates NOTICE and appends to history.json, under this checkout's `blocks/` only. |
+| `blocks/record-commit.mjs`, `blocks/commit.json` | The release tool: HEAD written into the record before `npm pack`, so an installed package names the commit its block files come from; null in a checkout, where git is the source. Never a lifecycle hook. |
+

package/tools/marketplace/banner.mjs

@@ -194,6 +194,25 @@ export function frame(layout, band, revealed = band, { colour = true } = {}) {
   })
 }
 
+/**
+ * The tagline as the lines drawn under the wordmark: one when it fits the
+ * wordmark's width, else the narrowest wrap that takes two lines, and the
+ * text on one line when no width under its own length does.
+ *
+ * @param {string} text
+ * @param {number} width the wordmark's width in cells
+ * @returns {string[]}
+ */
+export function taglineLines(text, width) {
+  const plain = String(text)
+  if ([...plain].length <= width) return [plain]
+  for (let columns = width; columns < [...plain].length; columns += 1) {
+    const lines = wrap(plain, { width: columns })
+    if (lines.length <= 2) return lines
+  }
+  return [plain]
+}
+
 /**
  * @param {{ word?: string, tagline?: string, stream?: NodeJS.WriteStream,
  *           enabled?: boolean, animate?: boolean, shines?: number,
@@ -217,9 +236,11 @@ export async function banner(options = {}) {
   // The tagline is centred under the wordmark, not set flush left: the rule
   // is exactly as wide as the letters, so a shorter line starting at column
   // 0 reads as slid to the left. The padding is spaces, no escape, so the
-  // line is centred under NO_COLOR and in a pipe alike.
+  // line is centred under NO_COLOR and in a pipe alike. A tagline wider
+  // than the wordmark is wrapped as narrow as two lines allow, so it sits
+  // under the letters instead of running past them.
   const tagline = options.tagline
-    ? " ".repeat(Math.max(0, Math.floor((width - [...String(options.tagline)].length) / 2))) + c(code("prose"), options.tagline)
+    ? taglineLines(options.tagline, width).map((line) => " ".repeat(Math.max(0, Math.floor((width - [...line].length) / 2))) + c(code("prose"), line)).join("\n")
     : null
 
   // Nothing at all when it is not a terminal. There is no plain-text substitute