omakit 0.5.0 → 0.6.1

package/tests/lab/store/suite.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/bash
+# The lab suite for the Store block: every hostile condition the contract
+# refuses, planted in a throwaway HOME, and the block run against it in a
+# separate quickshell instance (systemd-run --user --scope -p MemoryMax=768M,
+# setsid when the user manager is not reachable), never in omarchy-shell.
+# Per scenario the driver prepares HOME, starts the harness with that HOME,
+# waits for its results, then records what the filesystem looks like
+# afterwards; tests/lab/store/report.py asserts the states and those facts.
+#
+#   bash tests/lab/store/suite.sh [out-dir]       default /tmp/omakit-storelab
+#   RUNLAB_BLOCKS=<dir>                           the blocks/ directory to test
+set -u
+here="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+repo="$(cd -- "$here/../../.." && pwd)"
+blocks="${RUNLAB_BLOCKS:-$repo/blocks}"
+out="${1:-/tmp/omakit-storelab}"
+scenarios=(plain symlink-directory symlink-parent symlink-file swap oversized group-writable foreign-owner invalid crash concurrent outside-home fifo short-write non-ascii)
+plugin=lab.store.fixture
+
+for tool in /usr/bin/python3 /usr/bin/quickshell; do [[ -x $tool ]] || { echo "not ok - $tool is missing" >&2; exit 1; }; done
+[[ -n ${WAYLAND_DISPLAY:-} ]] || { echo "not ok - no WAYLAND_DISPLAY" >&2; exit 1; }
+rm -rf "$out" && mkdir -p "$out/runs" "$out/harness/omakit" "$out/homes" || exit 1
+cp "$here/harness/shell.qml" "$out/harness/" && cp "$blocks"/run/Run.qml "$blocks"/run/run-supervisor.py "$blocks"/store/Store.qml "$blocks"/store/store-helper.py "$out/harness/omakit/" || exit 1
+scope_ok=0; systemd-run --user --scope --quiet -p MemoryMax=768M -- /usr/bin/true >/dev/null 2>&1 && scope_ok=1
+sudo_ok=0; sudo -n /usr/bin/chown --version >/dev/null 2>&1 && sudo_ok=1
+echo "# scope: $([[ $scope_ok == 1 ]] && echo systemd-run || echo setsid); sudo for the foreign owner: $([[ $sudo_ok == 1 ]] && echo yes || echo no)"
+
+count_ev() { grep -o 'STORELAB {.*}' "$log" | grep -c "\"ev\":\"$1\""; }
+waitev() { local n=0; while [[ $(count_ev "$1") -lt 1 ]]; do sleep 0.05; n=$((n+1)); [[ $n -gt $(( $2 * 20 )) ]] && return 1; done; return 0; }
+
+prepare() {
+  # A fresh HOME, 0700, with the state and cache bases; the victim outside it.
+  local scen=$1 home=$2 dir=$2/.local/state/$plugin
+  mkdir -m 0700 "$home" && mkdir -p -m 0700 "$home/.local" "$home/.local/state" "$home/.cache" || return 1
+  mkdir -p "$out/victims" && printf 'untouched\n' > "$out/victims/$scen"
+  case $scen in
+    symlink-directory) ln -s "$out/victims" "$dir" ;;
+    symlink-parent) rm -rf "$home/.local/state" && ln -s "$out/victims" "$home/.local/state" ;;
+    symlink-file) mkdir -m 0700 "$dir" && ln -s "$out/victims/$scen" "$dir/memory.json" ;;
+    swap) mkdir -m 0700 "$dir" && printf '{"version":1,"themes":{}}\n' > "$dir/memory.json" ;;
+    oversized) mkdir -p -m 0700 "$home/.cache/$plugin" && /usr/bin/head -c 2097152 /dev/zero | tr '\0' 'x' > "$home/.cache/$plugin/catalog.json" ;;
+    group-writable) mkdir -m 0700 "$dir" && printf '{"version":1,"themes":{}}\n' > "$dir/memory.json" && chmod 0660 "$dir/memory.json" ;;
+    foreign-owner) mkdir -m 0700 "$dir" && printf '{"version":1,"themes":{}}\n' > "$dir/memory.json" && { [[ $sudo_ok == 0 ]] || sudo -n chown root "$dir/memory.json"; } ;;
+    invalid) mkdir -m 0700 "$dir" && printf '{"version":"one","themes":{}}\n' > "$dir/memory.json" ;;
+    crash) mkdir -m 0700 "$dir" && printf '{"version":1,"themes":{}}\n' > "$dir/memory.json" \
+      && printf '{"version":9' > "$dir/.store-99999-0123456789abcdef.tmp" && touch -d '-1 hour' "$dir/.store-99999-0123456789abcdef.tmp" \
+      && printf '{"version":9' > "$dir/.store-99998-fedcba9876543210.tmp" ;;
+    # 0.2.0 (docs/evidence/blocks/2026-09-18-review.json): a FIFO where the file should be; a
+    # write that cannot complete (RLIMIT_FSIZE 6000 bytes on the instance, see below); a file that
+    # is mostly non-ASCII, within the cap, whose escaped form would not be.
+    fifo) mkdir -m 0700 "$dir" && mkfifo -m 0600 "$dir/memory.json" ;;
+    short-write) mkdir -m 0700 "$dir" && printf '{"version":1,"themes":{}}\n' > "$dir/memory.json" ;;
+    non-ascii) mkdir -p -m 0700 "$home/.cache/$plugin" && /usr/bin/python3 -c 'import json,sys; sys.stdout.write(json.dumps({"names": ["\u00e9\u00e8\u00ea\u20ac\U0001F600" * 20] * 3000}, ensure_ascii=False))' > "$home/.cache/$plugin/catalog.json" ;;
+  esac
+}
+
+one() {
+  local scen=$1 home=$out/homes/$scen tag=$1
+  log=$out/runs/$tag.log; local meta=$out/runs/$tag.meta
+  : > "$log"; : > "$meta"
+  prepare "$scen" "$home" || { echo "prepare failed" >>"$meta"; return 1; }
+  echo "victim_dir_before=$(ls -A "$out/victims" | wc -l)" >>"$meta"
+  # The session's own XDG bases point into the real HOME; the instance gets
+  # the throwaway one and the defaults below it, unless the scenario sets one.
+  local -a env=(-u XDG_STATE_HOME -u XDG_CACHE_HOME STORELAB_SCENARIO="$scen" HOME="$home")
+  [[ $scen == outside-home ]] && env+=(XDG_STATE_HOME="$out/victims")
+  [[ $scen == foreign-owner && $sudo_ok == 0 ]] && echo "foreign_owner=not-simulated" >>"$meta"
+  [[ $scen == foreign-owner && $sudo_ok == 1 ]] && echo "foreign_owner=root" >>"$meta"
+  local unit=storelab-$tag-$$
+  if [[ $scope_ok == 1 ]]; then
+    systemd-run --user --scope --quiet -p MemoryMax=768M --unit="$unit" -- /usr/bin/env "${env[@]}" /usr/bin/quickshell -p "$out/harness" >"$log" 2>&1 &
+  else
+    /usr/bin/setsid /usr/bin/env "${env[@]}" /usr/bin/quickshell -p "$out/harness" >"$log" 2>&1 < /dev/null &
+  fi
+  local runner=$! swapper=""
+  waitev ready 30 || { echo "no ready line" >>"$meta"; kill -KILL -- -"$runner" 2>/dev/null; systemctl --user stop "$unit.scope" 2>/dev/null; return 1; }
+  if [[ $scen == short-write ]]; then
+    # RLIMIT_FSIZE 6000 bytes on the instance once it is up (its own startup
+    # writes are larger), inherited by the helper: the 9 KiB staging write
+    # comes up short and the next write raises EFBIG.
+    local qspid; qspid=$(grep -o 'STORELAB {.*}' "$log" | sed 's/^STORELAB //' | /usr/bin/python3 -c 'import json,sys; print(json.loads(sys.stdin.readline())["pid"])')
+    /usr/bin/prlimit --pid "$qspid" --fsize=6000 && echo "fsize_limit=6000 pid=$qspid" >>"$meta"
+  fi
+  if [[ $scen == swap ]]; then
+    # A hostile neighbour swaps the file between a regular file and a link to the victim while the block reads and writes.
+    ( local d=$home/.local/state/$plugin; while [[ -d $d ]]; do ln -sfn "$out/victims/swap" "$d/memory.json.lnk" && mv -T "$d/memory.json.lnk" "$d/memory.json" 2>/dev/null; printf '{"version":1,"themes":{}}\n' > "$d/memory.json.new" && mv -T "$d/memory.json.new" "$d/memory.json" 2>/dev/null; done ) &
+    swapper=$!
+  fi
+  waitev all-done 120 || echo "no all-done within 120 s" >>"$meta"
+  [[ -n $swapper ]] && { kill "$swapper" 2>/dev/null; wait "$swapper" 2>/dev/null; }
+  sleep 1
+  local dir=$home/.local/state/$plugin
+  { echo "victim=$(cat "$out/victims/$scen" 2>/dev/null)"
+    echo "victim_dir_after=$(ls -A "$out/victims" | wc -l)"
+    [[ -e $dir ]] && echo "dir_mode=$(stat -c %a "$dir")" && echo "dir_type=$(stat -c %F "$dir")"
+    [[ -e $dir/memory.json ]] && echo "file_mode=$(stat -c %a "$dir/memory.json")" && echo "file_type=$(stat -c %F "$dir/memory.json")" && echo "file_content=$(tr -d '\n ' < "$dir/memory.json" | head -c 200)"
+    [[ -d $dir ]] && echo "staging_left=$(ls -A "$dir" | grep -c '^\.store-')" && echo "entries=$(ls -A "$dir" | tr '\n' ' ')"
+  } >>"$meta" 2>/dev/null
+  if [[ $scope_ok == 1 ]]; then systemctl --user stop "$unit.scope" 2>/dev/null; else kill -KILL -- -"$runner" 2>/dev/null; fi
+  wait "$runner" 2>/dev/null
+  [[ $scen == foreign-owner && $sudo_ok == 1 ]] && sudo -n chown "$(id -u)" "$dir/memory.json" 2>/dev/null
+  return 0
+}
+
+for scen in "${scenarios[@]}"; do
+  one "$scen" || echo "not ok - $scen did not run" >&2
+  echo "# done $scen $(grep -o '"state":"[a-z-]*"' "$out/runs/$scen.log" | sort | uniq -c | tr '\n' ' ')"
+done
+/usr/bin/python3 "$here/report.py" "$out" "$blocks"

package/tests/parity/corpus.mjs

@@ -34,9 +34,14 @@ function registrySources(pinDir) {
 }
 
 export function strataSizes(count) {
-  const needsFixes = Math.ceil(count / 8)
-  const reviewRequired = Math.ceil(count / 4)
-  return { "needs-fixes": needsFixes, "review-required": reviewRequired, passed: Math.max(0, count - needsFixes - reviewRequired) }
+  // ceil for the two non-passed strata, so a small corpus still has one of
+  // each, and never more repositories than were asked for: at --count 1
+  // the two ceilings alone made two (measured on 2026-09-19, "identical
+  // 2/2" after --count 1). The 30-repository corpus is unchanged: 4, 8, 18.
+  const total = Math.max(0, Math.floor(count))
+  const needsFixes = Math.min(Math.ceil(total / 8), total)
+  const reviewRequired = Math.min(Math.ceil(total / 4), total - needsFixes)
+  return { "needs-fixes": needsFixes, "review-required": reviewRequired, passed: total - needsFixes - reviewRequired }
 }
 
 function sample(list, count, offset) {

package/tests/parity/run.mjs

@@ -26,7 +26,7 @@ import { parityOutput } from "../../tools/marketplace/parity-output.mjs"
 function shallowClone(cacheDir, repoUrl, commit) {
   const dir = join(cacheDir, subjectSlug(repoUrl))
   mkdirSync(dir, { recursive: true })
-  const run = (args) => execFileSync("git", ["-C", dir, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })
+  const run = (args) => execFileSync("git", ["-C", dir, ...args], { timeout: 120_000, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })
   try {
     run(["rev-parse", commit + "^{commit}"])
     return dir
@@ -35,7 +35,7 @@ function shallowClone(cacheDir, repoUrl, commit) {
   }
   // Test for the clone's own .git instead of relying on an outer repository.
   if (!existsSync(join(dir, ".git"))) {
-    execFileSync("git", ["init", "-q", dir], { encoding: "utf8" })
+    execFileSync("git", ["init", "-q", dir], { timeout: 120_000, encoding: "utf8" })
     run(["remote", "add", "origin", repoUrl])
   }
   run(["fetch", "-q", "--depth", "1", "origin", commit])
@@ -59,7 +59,7 @@ function digest(result) {
 
 function pinCommit(dir) {
   try {
-    return execFileSync("git", ["-C", dir, "rev-parse", "HEAD"], { encoding: "utf8" }).trim()
+    return execFileSync("git", ["-C", dir, "rev-parse", "HEAD"], { timeout: 120_000, encoding: "utf8" }).trim()
   } catch {
     return "unknown"
   }
@@ -67,7 +67,7 @@ function pinCommit(dir) {
 
 function generatorIdentity(repoRoot) {
   try {
-    return { omakitCommit: execFileSync("git", ["-C", repoRoot, "rev-parse", "HEAD"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() }
+    return { omakitCommit: execFileSync("git", ["-C", repoRoot, "rev-parse", "HEAD"], { timeout: 120_000, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() }
   } catch {
     const pkg = JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8"))
     return { omakitPackage: `${pkg.name}@${pkg.version}` }

package/tools/audit/audit.mjs

@@ -136,7 +136,7 @@ export async function auditInstalled(options = {}) {
   try {
     installed = readers.installed({ env })
   } catch (error) {
-    throw new AuditError(error?.code || "shell-not-running", error?.message || String(error))
+    throw new AuditError(error?.code || "shell-not-running", error?.message || String(error), error?.remedy || null)
   }
   let live
   try {
@@ -197,7 +197,16 @@ export async function auditInstalled(options = {}) {
       updateRouteError = error?.message || String(error)
     }
   }
-  const drift = rows.filter((row) => row.state !== "validated")
+  // Three kinds of row: validated, drift (a comparison that was made and
+  // found the installed commit off the validated one, or a listing without
+  // one to compare against, or no listing), and unknown (a comparison that
+  // could not be made: no source directory, not a checkout, a Git question
+  // that failed). Unknown is never counted as drift and never said to be.
+  // Measured on 2026-09-19: every one of 19 rows was unknown because the
+  // catalog named no source directory, and the close said all 19 "run one
+  // it never saw" (docs/evidence/ux/2026-09-19-acceptance.json, finding 4).
+  const drift = rows.filter((row) => row.state !== "validated" && row.state !== "unknown")
+  const unknown = rows.filter((row) => row.state === "unknown")
   return {
     command: "audit",
     catalog: {
@@ -212,12 +221,14 @@ export async function auditInstalled(options = {}) {
       selected: figure(selected.length, options.target ? "target selection" : "omarchy plugin list --json length"),
       firstPartyExcluded: figure(firstPartyCount, "sourceType builtin or omarchy plugin list --json firstParty"),
       audited: figure(rows.length, "audited row count"),
-      validated: figure(rows.length - drift.length, "rows whose state is validated"),
-      drift: figure(drift.length, "rows whose state is not validated"),
+      validated: figure(rows.length - drift.length - unknown.length, "rows whose state is validated"),
+      drift: figure(drift.length, "rows whose state is ahead, diverged, unverified or unlisted"),
+      unknown: figure(unknown.length, "rows whose state is unknown: a comparison that could not be made"),
     },
-    rows: options.drift ? drift : rows,
+    unknownReasons: [...new Set(unknown.map((row) => row.fact))],
+    rows: options.drift ? rows.filter((row) => row.state !== "validated") : rows,
     updateRoute,
     updateRouteError,
-    ok: drift.length === 0,
+    ok: drift.length === 0 && unknown.length === 0,
   }
 }

package/tools/audit/git.mjs

@@ -4,7 +4,7 @@
 import { spawnSync } from "node:child_process"
 
 function runGit(sourceDir, args, env = process.env) {
-  const result = spawnSync("git", ["-C", sourceDir, ...args], {
+  const result = spawnSync("git", ["-C", sourceDir, ...args], { timeout: 60_000,
     encoding: "utf8",
     env: { ...env, GIT_NO_LAZY_FETCH: "1" },
     stdio: ["ignore", "pipe", "pipe"],
@@ -27,7 +27,7 @@ export function readCheckout(sourceDir, { env = process.env } = {}) {
 
 /** A missing object is a local-history fact, not a failed ancestry check. */
 export function hasCommit(sourceDir, commit, { env = process.env } = {}) {
-  const result = spawnSync("git", ["-C", sourceDir, "cat-file", "-e", commit], {
+  const result = spawnSync("git", ["-C", sourceDir, "cat-file", "-e", commit], { timeout: 60_000,
     encoding: "utf8",
     env: { ...env, GIT_NO_LAZY_FETCH: "1" },
     stdio: ["ignore", "pipe", "pipe"],
@@ -44,7 +44,7 @@ export function isShallow(sourceDir, { env = process.env } = {}) {
 
 /** Is a recorded commit an ancestor of the running checkout? */
 export function ancestorOf(sourceDir, commit, { env = process.env } = {}) {
-  const result = spawnSync("git", ["-C", sourceDir, "merge-base", "--is-ancestor", commit, "HEAD"], {
+  const result = spawnSync("git", ["-C", sourceDir, "merge-base", "--is-ancestor", commit, "HEAD"], { timeout: 60_000,
     encoding: "utf8",
     env: { ...env, GIT_NO_LAZY_FETCH: "1" },
     stdio: ["ignore", "pipe", "pipe"],

package/tools/audit/report.mjs

@@ -1,4 +1,8 @@
 import { action, AUDIT_VERDICTS, colourEnabled, field, GUTTER, mark, styler, verdict, wrap } from "../marketplace/style.mjs"
+import { withHomeAbbreviated } from "../marketplace/paths.mjs"
+
+/** The checkout directory as a shell takes it: `~/...` when it has no whitespace, quoted and absolute otherwise, the way every other command prints a path under the home directory. */
+const shellPath = (dir) => (/\s/.test(dir) ? JSON.stringify(dir) : withHomeAbbreviated(dir))
 
 const short = (value) => value ? String(value).slice(0, 8) : "unrecorded"
 const flagText = (flags) => flags.length ? `; ${flags.join(", ")}` : ""
@@ -16,6 +20,31 @@ function catalogText(catalog) {
   return `pin ${short(catalog.commit.value)}${catalog.offline ? " (offline)" : ""}`
 }
 
+/**
+ * The closing sentence, the same one the envelope carries as the error's
+ * message when the exit is 1: what was compared and found validated, what
+ * was compared and found off (drift), and what could not be compared, with
+ * why, each clause only when its count is not zero. A row that could not
+ * be compared is never said to run a commit the marketplace "never saw".
+ */
+export function auditSummary(document) {
+  const total = document.counts.audited.value
+  const good = document.counts.validated.value
+  const drift = document.counts.drift.value
+  const unknown = document.counts.unknown?.value ?? 0
+  if (total === 0) return "no third-party plugin to audit."
+  const parts = [`${good} of ${total} run a commit the marketplace validated`]
+  if (drift) parts.push(`${drift} run one it never saw`)
+  if (unknown) parts.push(`${unknown} could not be compared (${(document.unknownReasons || []).join("; ") || "the source directory could not be read"})`)
+  return `${parts.join("; ")}.`
+}
+
+/** The closing word: AUDITED when every row was compared and validated, DRIFT when a compared row is off, NOT AUDITED when rows could not be compared and none drifted. */
+export function auditVerdict(document) {
+  if (document.ok) return AUDIT_VERDICTS.validated
+  return document.counts.drift.value > 0 ? AUDIT_VERDICTS.drift : AUDIT_VERDICTS.unavailable
+}
+
 /** A terminal report made only from the shared style vocabulary. */
 export function renderAudit(document, { colour = colourEnabled() } = {}) {
   const c = styler(colour)
@@ -35,13 +64,10 @@ export function renderAudit(document, { colour = colourEnabled() } = {}) {
     out.push(`${mark(markFor(row), c)}${c("name", row.id)}`)
     out.push(...wrap(detail, { indent: GUTTER }, c))
     if ((row.state === "ahead" || row.state === "diverged") && validated) {
-      out.push(...action(`git -C ${JSON.stringify(row.sourceDir)} checkout ${validated}`, c))
+      out.push(...action(`git -C ${shellPath(row.sourceDir)} checkout ${validated}`, c))
     }
     out.push("")
   }
-  const total = document.counts.audited.value
-  const good = document.counts.validated.value
-  const drift = document.counts.drift.value
   if (document.updateRoute) {
     out.push(...action(`To validate a newer commit: ${document.updateRoute.url}`, c))
     out.push(...wrap(`${document.updateRoute.name}; choose ${JSON.stringify(document.updateRoute.choice)}.`, { indent: GUTTER }, c))
@@ -51,6 +77,6 @@ export function renderAudit(document, { colour = colourEnabled() } = {}) {
     out.push(...wrap(`Verification route unavailable: ${document.updateRouteError}; run omakit pin.`, { indent: GUTTER }, c))
     out.push("")
   }
-  out.push(...verdict(document.ok ? "pass" : "fail", document.ok ? AUDIT_VERDICTS.validated : AUDIT_VERDICTS.drift, `${good} of ${total} run a commit the marketplace validated; ${drift} run one it never saw.`, c))
+  out.push(...verdict(document.ok ? "pass" : "fail", auditVerdict(document), auditSummary(document), c))
   return out.join("\n")
 }

package/tools/blocks/add.mjs

@@ -0,0 +1,138 @@
+// `omakit add <block> [plugin-dir] [--update]`: copy a shipped block's
+// files into <plugin-dir>/omakit/ and write omakit/NOTICE, and nothing
+// else. This is the one code path in omakit that writes into a plugin
+// tree, so it is held tighter than the rest (tests/unit/self-containment
+// .test.mjs and tests/unit/blocks.test.mjs): the file names come from the
+// block registry and are checked against the agent-control list before a
+// byte is written; an existing file is never overwritten without --update;
+// with --update a copy whose body is not one omakit shipped is refused,
+// before anything is written, because a modified block is the author's;
+// and every decision is made over every file first, so a refusal leaves
+// the directory as it was.
+
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
+import { execFileSync } from "node:child_process"
+import { join, resolve } from "node:path"
+import { findAgentControl } from "../marketplace/agent-control.mjs"
+import { blockClosure, bodySha256, parseHeader, renderNotice, shippedBlock, shippedBlocks, shippedHistory, withBodySha256, withSourceCommit } from "./registry.mjs"
+import { recordedCommit } from "./record-commit.mjs"
+
+export class AddError extends Error {
+  constructor(code, message, remedy = null) {
+    super(message)
+    this.name = "AddError"
+    this.code = code
+    this.remedy = remedy
+  }
+}
+
+/** The directory a block lands in, inside the plugin. */
+export const BLOCK_DIR = "omakit"
+
+/**
+ * The omakit commit the files come from: the checkout's HEAD when omakit
+ * runs from a Git checkout, else the commit the release workflow recorded
+ * in tools/blocks/commit.json before it packed (record-commit.mjs), else
+ * the `gitHead` npm records at publish, else null. Null is a refusal in
+ * `add`, never a blank in a header: a header that cannot name its commit
+ * is a bug (docs/evidence/ux/2026-09-19-first-user-test.json, finding 2).
+ */
+export function sourceCommit(repoRoot) {
+  if (existsSync(join(repoRoot, ".git"))) {
+    try {
+      return execFileSync("git", ["-C", repoRoot, "rev-parse", "HEAD"], { timeout: 60_000, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim()
+    } catch {
+      // fall through to the package's record
+    }
+  }
+  const recorded = recordedCommit(repoRoot)
+  if (recorded) return recorded
+  try {
+    const pkg = JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8"))
+    if (/^[0-9a-f]{40}$/.test(String(pkg.gitHead || ""))) return pkg.gitHead
+  } catch {
+    // no package.json to read
+  }
+  return null
+}
+
+/** The text `add` writes for one shipped file: the header stamped with the commit, the body untouched. */
+export function stampedText(entry, commit) {
+  return withSourceCommit(withBodySha256(entry.text, entry.sha256), commit)
+}
+
+/**
+ * What would happen to one file: `write` when it is not there, `current`
+ * when it is there with the shipped body, `update` when it is there with
+ * a body omakit shipped before (any version) and --update was passed, and
+ * a refusal otherwise.
+ */
+function decide(target, entry, { update }) {
+  if (!existsSync(target)) return { state: "write" }
+  if (!statSync(target).isFile()) throw new AddError("not-a-file", `${target} exists and is not a regular file`, "Move it out of the way; omakit does not replace directories or links.")
+  const existing = readFileSync(target, "utf8")
+  const parsed = parseHeader(existing)
+  if (parsed && bodySha256(parsed.body) === entry.sha256) {
+    if (parsed.version === entry.version) return { state: "current", version: parsed.version }
+    // The shipped body under an older header: a version bump that did not
+    // touch this file (measured on 0.2.1: Run.qml's body was 0.2.0's, and
+    // `--update` left its header at 0.2.0 beside a 0.2.1 supervisor, so
+    // inspect read one block as two versions). The header moves with --update.
+    if (!update) throw new AddError("exists", `${target} has the shipped body under a ${parsed.version} header; omakit ships ${entry.version}, and --update moves the header`, "omakit add <block> [plugin-dir] --update")
+    return { state: "update", version: parsed.version }
+  }
+  if (!update) throw new AddError("exists", `${target} is already there; pass --update to replace an unmodified copy`, "omakit add <block> [plugin-dir] --update")
+  if (!parsed) throw new AddError("modified", `${target} is not an omakit block file (no block header), so it is the plugin's own and is not replaced`, "Move or rename the file, then run add again.")
+  const older = shippedHistory().find((row) => row.block === entry.block && row.file === entry.file && row.sha256 === bodySha256(parsed.body))
+  if (!older) throw new AddError("modified", `${target} carries a block header but its body is not one omakit shipped, so it was modified and is the plugin's own; it is not replaced`, "Keep your copy, or move it aside and run add again; omakit/NOTICE is where modifications are listed.")
+  return { state: "update", version: older.version }
+}
+
+/**
+ * @param {{ repoRoot: string, block: string, dir?: string, update?: boolean, cwd?: string }} options
+ * @returns {{ block: string, version: string, dir: string, commit: string, files: Array<{ path: string, state: "written"|"updated"|"current", sha256: string, from: string|null }>, notice: { path: string, state: "written"|"updated"|"current" } }}
+ */
+export function addBlock({ repoRoot, block, dir = ".", update = false, cwd = process.cwd() }) {
+  const shipped = shippedBlock(block)
+  if (!shipped) throw new AddError("unknown-block", `${block} is not a block omakit ships; it ships ${shippedBlocks().map((entry) => entry.name).join(", ")}`, "omakit add run [plugin-dir], or omakit add store [plugin-dir]")
+  // A block that uses another one (store uses run) brings it along: the
+  // required block's files first, then its own, one decision list.
+  const closure = blockClosure(block).map((name) => shippedBlock(name))
+  const pluginDir = resolve(cwd, dir)
+  if (!existsSync(pluginDir) || !statSync(pluginDir).isDirectory()) throw new AddError("plugin-dir-not-found", `${pluginDir} is not a directory`, "Pass the plugin's directory, the one with its manifest.json.")
+  if (!existsSync(join(pluginDir, "manifest.json"))) throw new AddError("not-a-plugin", `${pluginDir} has no manifest.json, so it is not a plugin directory`, "Pass the plugin's directory, the one with its manifest.json.")
+  // The names that will be written, checked against the agent-control list
+  // before any decision: a block can never carry an instruction file along.
+  const control = findAgentControl([...closure.flatMap((entry) => entry.files), { file: "NOTICE" }].map((entry) => ({ path: `${BLOCK_DIR}/${entry.file}`, type: "blob" })))
+  if (control.length) throw new AddError("agent-control", `${control.map((entry) => entry.path).join(", ")}: an agent-control file is never written into a plugin`)
+  const blockDir = join(pluginDir, BLOCK_DIR)
+  // Every decision first; the first refusal stops everything, unwritten.
+  const decisions = closure.flatMap((one) => one.files.map((entry) => ({ entry: { ...entry, block: one.name }, target: join(blockDir, entry.file), ...decide(join(blockDir, entry.file), { ...entry, block: one.name }, { update }) })))
+  const commit = sourceCommit(repoRoot)
+  if (!commit) throw new AddError("no-source-commit", `this omakit names no source commit: it runs from neither a Git checkout nor a package the release workflow stamped (tools/blocks/commit.json is empty and package.json has no gitHead), and a block header that cannot name the commit it came from is not written`, "Install omakit from the npm registry (`npm i -g omakit`), or run it from a checkout of the repository.")
+  mkdirSync(blockDir, { recursive: true })
+  const files = []
+  for (const { entry, target, state, version } of decisions) {
+    if (state !== "current") {
+      const blockFile = target
+      writeFileSync(blockFile, stampedText(entry, commit))
+    }
+    files.push({ path: join(BLOCK_DIR, entry.file), block: entry.block, state: state === "write" ? "written" : state === "update" ? "updated" : "current", sha256: entry.sha256, from: version && version !== shippedBlock(entry.block).version ? version : null })
+  }
+  // NOTICE lists every block present in omakit/ after the write, recognised
+  // by the headers of the files that are there.
+  const present = shippedBlocks().filter((candidate) => candidate.files.every((entry) => existsSync(join(blockDir, entry.file)) && parseHeader(readFileSync(join(blockDir, entry.file), "utf8"))?.name === candidate.name))
+  const noticeText = renderNotice(present, commit)
+  const noticePath = join(blockDir, "NOTICE")
+  const noticeBefore = existsSync(noticePath) ? readFileSync(noticePath, "utf8") : null
+  let noticeState = "current"
+  // A NOTICE already there stays when nothing was written: the commit it
+  // names is the one the files came from, not the one add ran at.
+  const untouched = files.every((entry) => entry.state === "current") && noticeBefore !== null
+  if (!untouched && noticeBefore !== noticeText) {
+    const blockFile = noticePath
+    writeFileSync(blockFile, noticeText)
+    noticeState = noticeBefore === null ? "written" : "updated"
+  }
+  return { block: shipped.name, version: shipped.version, requires: closure.filter((one) => one.name !== shipped.name).map((one) => `${one.name} ${one.version}`), dir: pluginDir, commit, files, notice: { path: join(BLOCK_DIR, "NOTICE"), state: noticeState } }
+}

package/tools/blocks/commit.json

@@ -0,0 +1,5 @@
+{
+  "commit": "d3bd117d9fa0650c8dd5968fa5c94f7369162d40",
+  "recordedAt": "2026-09-19T16:44:26.025Z",
+  "how": "Written by `node tools/blocks/record-commit.mjs` in the release workflow before `npm pack`, so a packaged omakit, which has no Git checkout, still names the commit its block files come from. In a checkout this file is null and `git rev-parse HEAD` is the source; a package with null here was packed without the release step, and `omakit add` refuses to stamp a header it cannot name."
+}

package/tools/blocks/record-commit.mjs

@@ -0,0 +1,77 @@
+// Release tool: write the checkout's HEAD into tools/blocks/commit.json so
+// the packaged omakit names the commit its block files come from. Run by
+// .github/workflows/release.yml before `npm pack`, never by a user, and
+// never at install time (there is no lifecycle hook; tests/unit/
+// self-containment.test.mjs holds package.json to none). Measured on
+// 2026-09-19 by a first user of the packaged product: every stamped
+// header, the NOTICE and `add`'s output said `commit unknown`, because
+// the package has no .git and `npm pack` records no gitHead in the
+// tarball's package.json (docs/evidence/ux/2026-09-19-first-user-test.json,
+// finding 2).
+//
+//   node tools/blocks/record-commit.mjs            # writes the checkout's HEAD
+//   node tools/blocks/record-commit.mjs --check    # exits 1 when the file names a commit other than HEAD, or none
+//   node tools/blocks/record-commit.mjs --clear    # puts the checkout's null back, after a local `npm run pack:release`
+//
+// `npm run pack:release` is the release step run by hand: record, check,
+// pack, clear, so the tarball a person tests is the tarball the workflow
+// publishes, and the checkout is left as it was. A raw `npm pack` names no
+// commit, and the package it makes refuses `add` (measured on 2026-09-19 by
+// an acceptance tester whose candidate said no-source-commit; docs/evidence/
+// ux/2026-09-19-acceptance.json, finding 7).
+
+import { execFileSync } from "node:child_process"
+import { readFileSync, writeFileSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { fileURLToPath, pathToFileURL } from "node:url"
+
+export const COMMIT_FILE = "tools/blocks/commit.json"
+
+/** The recorded commit in a tree, or null: the file's `commit` when it is a 40-character sha. */
+export function recordedCommit(root) {
+  try {
+    const record = JSON.parse(readFileSync(join(root, COMMIT_FILE), "utf8"))
+    return /^[0-9a-f]{40}$/.test(String(record.commit || "")) ? record.commit : null
+  } catch {
+    return null
+  }
+}
+
+/** The one write: the record with `commit` and `recordedAt` set, the file's own explanation kept. */
+function writeRecord(root, commit, recordedAt) {
+  const file = join(root, COMMIT_FILE)
+  const record = JSON.parse(readFileSync(file, "utf8"))
+  const commitFile = file
+  writeFileSync(commitFile, `${JSON.stringify({ ...record, commit, recordedAt }, null, 2)}\n`)
+}
+
+/** Write `commit` into the tree's record, keeping the file's own explanation. */
+export function recordCommit(root, commit, { now = new Date() } = {}) {
+  if (!/^[0-9a-f]{40}$/.test(String(commit || ""))) throw new Error(`record-commit: not a 40-character commit: ${commit}`)
+  writeRecord(root, commit, now.toISOString())
+  return commit
+}
+
+/** Put the checkout's null back: what a checkout carries, where git is the source. */
+export function clearCommit(root) {
+  writeRecord(root, null, null)
+}
+
+const invoked = process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href
+if (invoked) {
+  const root = resolve(dirname(fileURLToPath(import.meta.url)), "../..")
+  const head = execFileSync("git", ["-C", root, "rev-parse", "HEAD"], { timeout: 60_000, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim()
+  if (process.argv.includes("--check")) {
+    const recorded = recordedCommit(root)
+    if (recorded !== head) {
+      process.stderr.write(`${COMMIT_FILE} names ${recorded || "no commit"}; HEAD is ${head}\n`)
+      process.exit(1)
+    }
+    process.stdout.write(`${COMMIT_FILE} names HEAD ${head}\n`)
+  } else if (process.argv.includes("--clear")) {
+    clearCommit(root)
+    process.stdout.write(`${COMMIT_FILE} is null again; git is the source in a checkout\n`)
+  } else {
+    process.stdout.write(`recorded ${recordCommit(root, head)} in ${COMMIT_FILE}\n`)
+  }
+}